Merge pull request #26 from BjornMelin/feat/agent-registry-research-mcp

feat: agent registry research mcp + tools

Author: BjornMelin

.github/dependabot.yml

@@ -10,6 +10,14 @@ updates:
       # Keep typings aligned with Node LTS (we target Node 24.x).
       - dependency-name: "@types/node"
         update-types: ["version-update:semver-major"]
+      # ESLint v10 is not yet supported by our lint plugin stack (jsdoc/tsdoc +
+      # typescript-eslint utils). Keep us on v9 until upstream support lands.
+      - dependency-name: "eslint"
+        update-types: ["version-update:semver-major"]
+        versions: [">=10.0.0"]
+      - dependency-name: "@eslint/js"
+        update-types: ["version-update:semver-major"]
+        versions: [">=10.0.0"]
     groups:
       dependencies:
         patterns:

.gitignore

@@ -29,6 +29,7 @@ build/
 
 # Coverage
 coverage/
+coverage_tmp_*/
 *.lcov
 
 # Logs

bun.lock

@@ -1,40 +1,41 @@
 ---
 ADR: 0008
 Title: Web research: Exa + Firecrawl with citations
-Status: Accepted
-Version: 0.2
-Date: 2026-01-30
+Status: Implemented
+Version: 0.4
+Date: 2026-02-07
 Supersedes: []
 Superseded-by: []
 Related: [ADR-0006, ADR-0013]
 Tags: [research, architecture]
 References:
-  - [Exa tool registry](https://ai-sdk.dev/tools-registry/exa)
-  - [Firecrawl tool registry](https://ai-sdk.dev/tools-registry/firecrawl)
+  - [Exa Search API](https://docs.exa.ai/reference/search)
+  - [Firecrawl Node SDK](https://docs.firecrawl.dev/sdks/node)
+  - [OWASP SSRF Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Server_Side_Request_Forgery_Prevention_Cheat_Sheet.html)
 ---
 
 ## Status
 
-Accepted — 2026-01-30.
+Implemented — 2026-02-07.
 
 ## Description
 
-Use Exa for search and Firecrawl for page extraction, enforcing citation capture per claim.
+Use Exa for search and Firecrawl for page extraction, enforcing citation capture per claim with strict budgets, caching, and SSRF guardrails.
 
 ## Context
 
-Market validation and competitive research require up-to-date web information. We need reliable search results plus robust extraction to get clean content for summarization. Both Exa and Firecrawl have AI SDK tools, reducing custom integration code.
+Market validation and competitive research require up-to-date web information. We need reliable search results plus robust extraction to get clean content for summarization.
 
 ## Decision Drivers
 
 - High-quality search
 - Reliable extraction
 - Citation enforcement
-- AI SDK tool ecosystem
+- Low maintenance surface area (thin wrappers + caching)
 
 ## Alternatives
 
-- A: Exa + Firecrawl — Pros: purpose-built; AI SDK tools. Cons: two vendors.
+- A: Exa + Firecrawl — Pros: purpose-built; thin, typed adapters. Cons: two vendors.
 - B: Only search (no extraction) — Pros: simpler. Cons: low quality grounding.
 - C: Scrape manually — Pros: control. Cons: high maintenance and fragility.
 
@@ -53,11 +54,15 @@ Market validation and competitive research require up-to-date web information. W
 
 We will adopt **Exa** for search and **Firecrawl** for content extraction, capturing source URLs and minimal excerpts for citations.
 
+Implementation detail: Exa calls use a small REST wrapper (AbortController + timeouts) rather than the Exa SDK to guarantee deterministic cancellation under load.[^exa-search]
+
 ## Constraints
 
 - Respect robots and provider terms.
 - Do not store full copyrighted articles; store snippets + summaries.
 - Enforce max URLs per step and cache results.
+- Enforce SSRF guardrails for outbound extraction URLs.[^owasp-ssrf]
+- SSRF validation is defense-in-depth and intentionally does not perform DNS resolution; hostnames that resolve to private IPs or DNS rebinding attacks are out of scope and must be mitigated via provider-side protections or egress controls.
 
 ## High-Level Architecture
 
@@ -92,14 +97,17 @@ flowchart LR
 
 ### Architecture Overview
 
-- `src/lib/ai/tools/web-search.ts` wraps Exa queries.
-- `src/lib/ai/tools/firecrawl.ts` wraps Firecrawl extract.
-- Cache by `(url, extractProfile)` in Upstash Redis.
+- `src/lib/ai/tools/web-search.server.ts` wraps Exa queries.
+- `src/lib/ai/tools/web-extract.server.ts` wraps Firecrawl extraction.
+- `src/lib/net/fetch-with-timeout.server.ts` enforces AbortController timeouts for upstream requests.
+- `src/lib/security/url-safety.server.ts` blocks known-unsafe URLs (SSRF defense-in-depth).
+- Cache by `(tool, params)` in Upstash Redis.
 
 ### Implementation Details
 
 - Store citations as `{url, title, publishedAt?, accessedAt, excerpt}`.
-- Render citations in UI as footnotes per message/section.
+- Link citations to artifacts (not chat messages) for auditing/export.
+- Render citations in artifact markdown via `citation:n` links.
 
 ## Testing
 
@@ -131,9 +139,14 @@ flowchart LR
 
 ### Dependencies
 
-- **Added**: @exa/ai-sdk, firecrawl-aisdk (or official package)
+- **Added**: `@mendable/firecrawl-js`
 
 ## Changelog
 
 - **0.1 (2026-01-29)**: Initial version.
 - **0.2 (2026-01-30)**: Updated for current repo baseline (Bun, `src/` layout, CI).
+- **0.3 (2026-02-07)**: Implemented with server wrappers, caching, budgets, and artifact-linked citations.
+- **0.4 (2026-02-07)**: Hardened adapters with deterministic timeouts and SSRF guardrails; removed unused Exa SDK dependency.
+
+[^exa-search]: See References: Exa Search API
+[^owasp-ssrf]: See References: OWASP SSRF Prevention Cheat Sheet

docs/architecture/adr/ADR-0008-web-research-exa-firecrawl-with-citations.md

@@ -1,9 +1,9 @@
 ---
 ADR: 0012
 Title: MCP + dynamic tools: Context7 via MCP + dynamicTool
-Status: Accepted
-Version: 0.2
-Date: 2026-01-30
+Status: Implemented
+Version: 0.4
+Date: 2026-02-07
 Supersedes: []
 Superseded-by: []
 Related: [ADR-0006, ADR-0008, ADR-0013]
@@ -16,7 +16,7 @@ References:
 
 ## Status
 
-Accepted — 2026-01-30.
+Implemented — 2026-02-07.
 
 ## Description
 
@@ -52,7 +52,7 @@ Library APIs change quickly. Instead of hardcoding doc content into prompts, we
 
 ## Decision
 
-We will use **MCP tools** via `createMCPClient` and expose them to agents using `dynamicTool()` so only the required doc tools are in context for a given step.
+We will use **MCP tools** via `createMCPClient` and only expose them to agents when the selected agent mode allowlists them (default deny).
 
 ## Constraints
 
@@ -64,8 +64,8 @@ We will use **MCP tools** via `createMCPClient` and expose them to agents using
 
 ```mermaid
 flowchart LR
-  Agent --> Dynamic[dynamicTool()]
-  Dynamic --> MCPClient[createMCPClient]
+  Agent --> Toolset[Mode-scoped toolset]
+  Toolset --> MCPClient[createMCPClient]
   MCPClient --> Context7[(Context7 MCP server)]
 ```
 
@@ -91,13 +91,18 @@ flowchart LR
 
 ### Architecture Overview
 
-- MCP client configured as stdio transport.
+- MCP client configured as HTTP transport.
 - Tools: resolve library id, query docs.
 
 ### Implementation Details
 
-- Add `src/lib/ai/tools/mcp.ts` that provides a `getMcpTools()` factory.
-- Use `dynamicTool()` to inject only when step requires.
+- `src/lib/ai/tools/mcp-context7.server.ts` wraps Context7 MCP tools (cached + size-bounded).
+- Tool calls are time-bounded and abortable:
+  - Budget: `budgets.context7TimeoutMs` in `src/lib/config/budgets.server.ts`
+  - Enforcement: AbortController timeout in `src/lib/ai/tools/mcp-context7.server.ts`
+  - Propagation: `options.abortSignal` is passed from `ToolExecutionOptions.abortSignal` in `src/workflows/chat/steps/context7.step.ts`
+- `src/lib/ai/tools/factory.server.ts` injects Context7 tools only for allowlisted modes.
+- `src/workflows/chat/steps/context7.step.ts` enforces per-turn budgets for Context7 calls.
 
 ## Testing
 
@@ -126,9 +131,11 @@ flowchart LR
 
 ### Dependencies
 
-- **Added**: @modelcontextprotocol/sdk, context7 tools
+- **Added**: `@ai-sdk/mcp` (MCP client transport)
 
 ## Changelog
 
 - **0.1 (2026-01-29)**: Initial version.
 - **0.2 (2026-01-30)**: Updated for current repo baseline (Bun, `src/` layout, CI).
+- **0.3 (2026-02-07)**: Implemented with mode-scoped tool injection, Redis caching, and budgets.
+- **0.4 (2026-02-07)**: Documented abortable, time-bounded MCP calls (`context7TimeoutMs`) and the workflow abort propagation path.

docs/architecture/adr/ADR-0012-mcp-dynamic-tools-context7-via-mcp-dynamictool.md

@@ -2,8 +2,8 @@
 ADR: 0013
 Title: Caching + cost controls: Next.js caching + Upstash Redis + budgets
 Status: Implemented
-Version: 0.5
-Date: 2026-02-06
+Version: 0.6
+Date: 2026-02-07
 Supersedes: []
 Superseded-by: []
 Related: [ADR-0004, ADR-0005, ADR-0007]
@@ -108,6 +108,10 @@ flowchart LR
 
 - Define budgets in `src/lib/config/budgets.server.ts`.
 - Persist per-step usage, enforce max tokens and tool calls.
+- Enforce upstream timeouts for external providers to avoid hung requests:
+  - Exa search: `src/lib/ai/tools/web-search.server.ts` via `src/lib/net/fetch-with-timeout.server.ts` using `budgets.webSearchTimeoutMs`.
+  - Firecrawl extraction: `src/lib/ai/tools/web-extract.server.ts` using `budgets.webExtractTimeoutMs`.
+  - Context7 MCP: `src/lib/ai/tools/mcp-context7.server.ts` using `budgets.context7TimeoutMs`.
 - Standardize cache tags in `src/lib/cache/tags.ts` and apply to server loaders
   using `'use cache'` + `cacheTag`.
 - Apply server-side search rate limiting with Upstash Ratelimit in
@@ -161,3 +165,4 @@ flowchart LR
 - **0.3 (2026-02-03)**: Linked to SPEC-0021 as the cross-cutting finalization spec.
 - **0.4 (2026-02-06)**: Marked implemented; added Cache Components/tag invalidation implementation details and concrete file references.
 - **0.5 (2026-02-06)**: Added ownership-scoped search + Upstash Ratelimit implementation details for `/api/search`.
+- **0.6 (2026-02-07)**: Documented upstream timeouts as part of budgets and cost controls for external tool calls.

docs/architecture/adr/ADR-0013-caching-cost-controls-next-js-caching-upstash-redis-budgets.md

@@ -1,10 +1,10 @@
 ---
 spec: SPEC-0004
 title: Chat + retrieval augmentation
-version: 0.3.0
-date: 2026-02-03
+version: 0.4.0
+date: 2026-02-07
 owners: ["Bjorn Melin"]
-status: Proposed
+status: Implemented
 related_requirements: ["FR-008", "FR-009", "FR-019", "PR-001", "PR-002"]
 related_adrs: ["ADR-0006", "ADR-0004", "ADR-0011"]
 notes: "Defines chat UX, persistence, and RAG behavior for grounded responses."
@@ -106,6 +106,9 @@ Requirement IDs are defined in [docs/specs/requirements.md](/docs/specs/requirem
 
 - `src/app/(app)/projects/[projectId]/chat/page.tsx`: UI for streaming chat and message history.
 - `src/app/api/chat/route.ts`: server streaming endpoint; must persist messages/tool calls.
+- `src/app/api/chat/[runId]/route.ts`: resume endpoint for durable chat sessions.
+- `src/lib/data/chat.server.ts`: chat threads + messages DAL (Neon + Drizzle).
+- `src/workflows/chat/project-chat.workflow.ts`: durable chat workflow orchestration and persistence.
 - `src/lib/ai/tools/retrieval.server.ts`: retrieval tools (uploads + artifacts);
   must enforce project scoping and top-k bounds.
 - `src/lib/upstash/vector.server.ts`: vector query interface with metadata filters.
@@ -121,7 +124,7 @@ Requirement IDs are defined in [docs/specs/requirements.md](/docs/specs/requirem
 
 - Chat streams responses and persists message history
 - RAG tool returns cited sources for grounded answers
-- Agent modes can be switched per message
+- Agent mode is selected per thread and persisted; tool allowlists follow mode
 
 ## Testing
 

docs/architecture/spec/SPEC-0004-chat-retrieval-augmentation.md

@@ -1,13 +1,13 @@
 ---
 spec: SPEC-0006
 title: Agent registry & orchestration patterns
-version: 0.3.0
-date: 2026-02-01
+version: 0.4.0
+date: 2026-02-07
 owners: ["Bjorn Melin"]
-status: Proposed
+status: Implemented
 related_requirements: ["FR-009", "FR-033", "NFR-011", "NFR-013", "NFR-015"]
 related_adrs: ["ADR-0006", "ADR-0012", "ADR-0024"]
-notes: "Defines agent modes, tool allowlists, and orchestration patterns."
+notes: "Defines agent modes, tool allowlists, and orchestration patterns (implemented for project chat + research)."
 ---
 
 ## Summary
@@ -18,9 +18,8 @@ Defines:
 - which tools each mode can access (least privilege)
 - orchestration patterns for multi-agent workflows
 
-The system uses AI SDK v6 agents and dynamic tools to reduce context bloat
-(see [AI SDK Agents](https://ai-sdk.dev/docs/agents/overview) and
-[dynamicTool](https://ai-sdk.dev/docs/reference/ai-sdk-core/dynamic-tool)).
+The system uses AI SDK v6 agents and tool allowlisting to reduce context bloat
+(see [AI SDK Agents](https://ai-sdk.dev/docs/agents/overview)).
 
 ## Context
 
@@ -87,15 +86,18 @@ Requirement IDs are defined in [docs/specs/requirements.md](/docs/specs/requirem
 
 ### File-level contracts
 
-- `src/lib/ai/agents/*`: agent definitions (ToolLoopAgent configs) per mode.
-- `src/lib/ai/tools/*`: tool implementations and wrappers (typed schemas).
-- `src/lib/ai/registry.ts`: canonical registry mapping mode → agent/tools.
+- `src/lib/ai/agents/agent-mode.ts`: shared agent mode types.
+- `src/lib/ai/agents/modes/*`: mode definitions (system prompt + model + budgets + tool allowlist).
+- `src/lib/ai/agents/registry.ts`: canonical registry mapping modeId → mode definition.
+- `src/lib/ai/agents/registry.server.ts`: server-facing registry (env gates + enabled modes).
+- `src/lib/ai/tools/tool-ids.ts`: canonical tool IDs for allowlists.
+- `src/lib/ai/tools/factory.server.ts`: tool factory enforcing allowlists (default deny).
 
 ### Configuration
 
 - Tool allowlists must be enforced at agent construction time (not by “prompt
   instructions” alone).
-- Dynamic tools (MCP/Context7) must be sandboxed/guarded and bounded by budgets.
+- Dynamic tools (MCP/Context7) must be guarded and bounded by budgets.
 
 ## Agent modes