feat: add Convex RAG tools and calendar tool tests

- Introduced Convex RAG tools including:
  - `convexChunker`: A tool for processing document content and storing chunk embeddings in ConvexVector with configurable chunking strategies and embedding generation.
  - `convexGraphQueryTool`: A graph-based retrieval augmented generation tool using ConvexVector for semantic search.
  - `convexVectorQueryTool`: A similarity search tool for semantic content retrieval and question answering using ConvexVector.
  - `convexRerankerTool`: A tool for reranking initial ConvexVector search results using a semantic reranker with configurable weights.

- Implemented input and output schemas for each tool using Zod for validation.
- Added logging and tracing capabilities for better observability during tool execution.
- Created tests for the calendar tool to ensure functionality:
  - Validated default source selection based on platform.
  - Checked explicit source overrides.
  - Parsed events from ICS calendar exports.
  - Loaded events from an ICS file on Linux.
  - Ensured an ICS file is required when falling back to the ICS source on Linux.

Co-authored-by: Copilot <copilot@github.com>

Author: ssdeanx

.agents/skills/convex-create-component/agents/openai.yaml

@@ -0,0 +1,10 @@
+interface:
+  display_name: "Convex Create Component"
+  short_description: "Design and build reusable Convex components with clear boundaries."
+  icon_small: "./assets/icon.svg"
+  icon_large: "./assets/icon.svg"
+  brand_color: "#14B8A6"
+  default_prompt: "Help me create a Convex component for this feature. First check that a component is actually justified, then design the tables, API surface, and app-facing wrappers before implementing it."
+
+policy:
+  allow_implicit_invocation: true

.agents/skills/convex-migration-helper/agents/openai.yaml

@@ -0,0 +1,10 @@
+interface:
+  display_name: "Convex Migration Helper"
+  short_description: "Plan and run safe Convex schema and data migrations."
+  icon_small: "./assets/icon.svg"
+  icon_large: "./assets/icon.svg"
+  brand_color: "#8B5CF6"
+  default_prompt: "Help me plan and execute this Convex migration safely. Start by identifying the schema change, the existing data shape, and the widen-migrate-narrow path before making edits."
+
+policy:
+  allow_implicit_invocation: true

.agents/skills/convex-performance-audit/agents/openai.yaml

@@ -0,0 +1,10 @@
+interface:
+  display_name: "Convex Performance Audit"
+  short_description: "Audit slow Convex reads, subscriptions, OCC conflicts, and limits."
+  icon_small: "./assets/icon.svg"
+  icon_large: "./assets/icon.svg"
+  brand_color: "#EF4444"
+  default_prompt: "Audit this Convex app for performance issues. Start with the strongest signal available, identify the problem class, and suggest the smallest high-impact fix before proposing bigger structural changes."
+
+policy:
+  allow_implicit_invocation: true

.agents/skills/convex-quickstart/agents/openai.yaml

@@ -0,0 +1,10 @@
+interface:
+  display_name: "Convex Quickstart"
+  short_description: "Start a new Convex app or add Convex to an existing frontend."
+  icon_small: "./assets/icon.svg"
+  icon_large: "./assets/icon.svg"
+  brand_color: "#F97316"
+  default_prompt: "Set up Convex for this project as fast as possible. First decide whether this is a new app or an existing app, then scaffold or integrate Convex and verify the setup works."
+
+policy:
+  allow_implicit_invocation: true

.agents/skills/convex-setup-auth/agents/openai.yaml

@@ -0,0 +1,10 @@
+interface:
+  display_name: "Convex Setup Auth"
+  short_description: "Set up Convex auth, user identity mapping, and access control."
+  icon_small: "./assets/icon.svg"
+  icon_large: "./assets/icon.svg"
+  brand_color: "#2563EB"
+  default_prompt: "Set up authentication for this Convex app. Figure out the provider first, then wire up the user model, identity mapping, and access control with the smallest solid implementation."
+
+policy:
+  allow_implicit_invocation: true

AGENTS.md

@@ -0,0 +1,7 @@
+<!-- convex-ai-start -->
+This project uses [Convex](https://convex.dev) as its backend.
+
+When working on Convex code, **always read `convex/_generated/ai/guidelines.md` first** for important guidelines on how to correctly use Convex APIs and patterns. The file contains rules that override what you may have learned about Convex from training data.
+
+Convex agent skills for common tasks can be installed by running `npx convex ai-files install`.
+<!-- convex-ai-end -->

convex/_generated/ai/ai-files.state.json

@@ -0,0 +1,14 @@
+{
+  "guidelinesHash": "62d72acb9afcc18f658d88dd772f34b5b1da5fa60ef0402e57a784d97c458e57",
+  "agentsMdSectionHash": "bbf30bd25ceea0aefd279d62e1cb2b4c207fcb712b69adf26f3d02b296ffc7b2",
+  "claudeMdHash": "bbf30bd25ceea0aefd279d62e1cb2b4c207fcb712b69adf26f3d02b296ffc7b2",
+  "agentSkillsSha": "231a67aa8a5b29cc2794cbc8298335a71aaa6d0e",
+  "installedSkillNames": [
+    "convex",
+    "convex-create-component",
+    "convex-migration-helper",
+    "convex-performance-audit",
+    "convex-quickstart",
+    "convex-setup-auth"
+  ]
+}

convex/_generated/ai/guidelines.md

@@ -1,3 +1,30 @@
+# Active Context Update (2026-04-20 - calendar tool cross-platform refactor)
+
+- Refactored `src/mastra/tools/calendar-tool.ts` from a macOS-only AppleScript reader into a platform-aware calendar source selector.
+- Auto-selection now supports `macos-calendar`, `windows-outlook`, and `ics-file` sources via `process.platform` and the `CALENDAR_SOURCE` / `CALENDAR_ICS_PATH` env vars.
+- Added a Linux-compatible ICS fallback reader plus a Windows Outlook PowerShell reader, while preserving the existing macOS Calendar path.
+- Added `src/mastra/tools/tests/calendar-tool.test.ts` covering source selection and ICS parsing; the targeted vitest run passed.
+
+# Active Context Update (2026-04-20 - tools folder crash scan)
+
+- Scanned `src/mastra/tools` for the same unsafe direct `.length` pattern that caused the earlier runtime crash.
+- Hardened additional tool hooks and model-output helpers in `arxiv.tool.ts`, `calendar-tool.ts`, `downsample.tool.ts`, `editor-agent-tool.ts`, `extractLearningsTool.ts`, `git-local.tool.ts`, `github.ts`, `image-tool.ts`, `polygon-tools.ts`, `serpapi-academic-local.tool.ts`, `serpapi-images.tool.ts`, `serpapi-local-maps.tool.ts`, `serpapi-news-trends.tool.ts`, and `url-tool.ts`.
+- The remaining direct `.length` scans in the folder are mostly `messages.length` reads, which are a broader follow-up pass rather than the same output-null crash class.
+
+# Active Context Update (2026-04-20 - weather temperature-unit narrowed)
+
+- Removed the global `temperature-unit` injection from `src/mastra/index.ts` so the shared agent request context no longer carries a celsius/fahrenheit default for every agent.
+- `weatherTool` still defaults to `celsius` locally when the weather request context does not provide a temperature unit, so weather lookups continue to work without exposing the unit globally.
+- `weatherAgent` remains the only agent wired to `weatherTool` in the current codebase.
+- Hardened the weather tool lifecycle hooks so missing `messages` or `output` values cannot crash the callback path.
+
+# Active Context Update (2026-04-20 - SerpAPI googleSearchTool crash fix)
+
+- The repeated Mastra runtime crash was traced to `src/mastra/tools/serpapi-search.tool.ts`, specifically `googleSearchTool.onOutput` dereferencing nested output fields without guards.
+- `googleSearchTool` now accepts SerpAPI's numeric `searchInfo.totalResults` response shape and uses optional chaining for all `onOutput` nested reads.
+- `googleAiOverviewTool.onOutput` was hardened at the same time so a missing output payload cannot trip the same `length` error again.
+- The failing stack traces were coming from generated `.mastra/output/tools/*.mjs` files, but the source fix is in the checked-in SerpAPI tool module.
+
 # Active Context Update (2026-04-18 - Blender MCP / FPV research)
 
 - Blender 5.1 is compatible with the official Blender MCP server page, which requires Blender 5.1 or newer and warns that LLM-generated code executes in Blender without guards.

memory-bank/activeContext.md

@@ -1,3 +1,31 @@
+# Progress Update (2026-04-20 - calendar tool cross-platform refactor)
+
+- Reworked `src/mastra/tools/calendar-tool.ts` to select a calendar source by platform instead of assuming macOS Calendar.
+- Added Windows Outlook support and a Linux-compatible ICS-file fallback, both behind the same tool interface.
+- Exposed `getCalendarSourceKind`, `createCalendarSource`, and `parseIcsCalendarEvents` for unit testing.
+- Added `src/mastra/tools/tests/calendar-tool.test.ts`; targeted vitest run passed (`5 passed, 0 failed`).
+
+# Progress Update (2026-04-20 - tools folder crash scan)
+
+- Confirmed the earlier Mastra crash pattern also appeared in several other tools via direct `.length` reads on optional output payloads.
+- Hardened output handling in the following files: `arxiv.tool.ts`, `calendar-tool.ts`, `downsample.tool.ts`, `editor-agent-tool.ts`, `extractLearningsTool.ts`, `git-local.tool.ts`, `github.ts`, `image-tool.ts`, `polygon-tools.ts`, `serpapi-academic-local.tool.ts`, `serpapi-images.tool.ts`, `serpapi-local-maps.tool.ts`, `serpapi-news-trends.tool.ts`, and `url-tool.ts`.
+- The folder still contains many `messages.length` reads in input hooks; those are a separate broader hardening pass if you want to eliminate that class too.
+
+# Progress Update (2026-04-20 - weather temperature-unit narrowed)
+
+- Removed the shared request-context `temperature-unit` injection from `src/mastra/index.ts` so only the weather tool can fall back to `celsius` locally.
+- Confirmed `weatherTool` is only wired into `weatherAgent` in the current agent set.
+- Cleaned the now-unused `TemperatureUnit` / `TEMPERATURE_UNIT_CONTEXT_KEY` imports from `src/mastra/index.ts`.
+- Hardened `src/mastra/tools/weather-tool.ts` so its input/output hooks use optional chaining and no longer assume `messages` or `output` are always present.
+
+# Progress Update (2026-04-20 - SerpAPI googleSearchTool crash fix)
+
+- Traced the repeated `Cannot read properties of undefined (reading 'length')` error to the Google Search tool generated hook logs.
+- Patched `src/mastra/tools/serpapi-search.tool.ts` so `googleSearchTool.onOutput` no longer assumes nested output fields are always present.
+- Updated the Google Search output schema so `searchInfo.totalResults` accepts the numeric value SerpAPI is returning.
+- Hardened `googleAiOverviewTool.onOutput` with the same defensive pattern to avoid the same crash if an overview payload is missing.
+- Next verification step: re-run the workflow or agent path that was invoking `googleSearchTool` and confirm the error does not reappear.
+
 # Progress Update (2026-04-18 - Blender MCP / FPV research)
 
 - Confirmed the official Blender MCP server supports Blender 5.1+ and found the key safety caveat: it runs LLM-generated code in Blender without guards, so it should be isolated from sensitive data.