fix(mcp): soft-fail stalled package retrievers during search/execute

[kentcdodds]

Summary

Agents were seeing MCP Error: Execution timed out on search (and sometimes execute) after ~1–2s — far below the documented ~90s execute sandbox budget.

Root cause: package retrievers are optional enrichment with short sandbox budgets (previously 1s search / 300ms context). After #551, a single timed-out retriever used Promise.all and failed the entire MCP tool call with the sandbox string "Execution timed out". That matches Sentry KODY-CLOUDFLARE-P / KODY-CLOUDFLARE-12 durations (~1–2s) and "some agents" (those with slow/cold package retrievers).

Fix:

• Soft-fail per retriever again (Promise.allSettled + warning); keep healthy results
• Raise defaults to 3s search / 1s context (max 5s / 3s)
• Do not reintroduce Sentry capture for these optional failures (keeps triage noise down after fix(mcp): stop reporting sandbox execute failures to Sentry #917)
• Document host budgets and fail-soft behavior

Validation

• Unit: packages/worker/src/package-retrievers/service.node.test.ts (soft-fail keeps healthy results)
• Pre-push hooks ran on push (includes e2e)

System recap — extends existing primitives (medium risk)

Mode: recap · Base: main @ dc25e719 · Head: f111178e

Classification: extends — optional package-retriever enrichment no longer fails MCP search / execute when one retriever times out.

Primitives touched

Primitive	Group	Impact
packages	assistant	extends — package retriever runs soft-fail with warnings; default budgets raised
mcp-server	surfaces	composes — search/execute keep working when enrichment stalls

Classifier note: packages/worker/src/package-retrievers/** is not yet under a code root in primitives.yaml; behavior is package-enrichment for MCP tools.

System map

Package retrievers enrich MCP search/execute; a stalled retriever now skips instead of aborting the tool.

Legend: green = composes (wiring only) · amber = extended by this PR · red = new primitive · gray = context.

flowchart LR
	mcpSearch["MCP search / execute"]:::untouched
	retrievers["packages<br/>package retrievers"]:::extended
	sandbox["execute sandbox<br/>short budget"]:::untouched
	mcpSearch -->|"enrichment"| retrievers
	retrievers -->|"timeout/error → warn + skip"| mcpSearch
	retrievers --> sandbox
	classDef touched fill:#1a7f37,color:#fff
	classDef extended fill:#9a6700,color:#fff
	classDef added fill:#cf222e,color:#fff
	classDef untouched fill:#57606a,color:#fff

Loading

Before / after

Before: one retriever "Execution timed out" failed the whole MCP search/execute call (~1–2s wall time).

After: that retriever is skipped with a warning; other retrievers and core search/execute results still return.

Invariants

Retriever runs remain user-scoped (userId on package/source lookups). Soft-fail never substitutes another user's retriever data.

Docs

docs/contributing/packages-and-manifests.md documents host budgets and fail-soft enrichment.

---

Note

Medium Risk
Changes MCP search/execute enrichment behavior and timeout defaults; failures are isolated but agents may see new warnings instead of hard errors when retrievers stall.

Overview
Fixes MCP search and execute failing with Execution timed out when a single optional package retriever stalled under the old short budgets.

runPackageRetrievers now uses Promise.allSettled so one slow or broken retriever is logged, recorded in warnings, and skipped while other retrievers still contribute results. Default host budgets rise to 3s search / 1s context (caps 5s / 3s), and contributor docs describe fail-soft enrichment behavior.

A unit test covers the timeout skip path; per-retriever execution errors are normalized via getErrorMessage before surfacing in warnings.

^{Reviewed by Cursor Bugbot for commit f111178. Bugbot is set up for automated code reviews on this repo. Configure here.}

Summary by CodeRabbit

• New Features

  • Retriever timeouts now allow more time for search and context operations, within defined limits.
  • Failed or timed-out retrievers are skipped with a warning while successful retrievers continue returning results.

• Documentation

  • Updated contributor guidance to explain timeout defaults, limits, and failure behavior.
  • Updated the example retriever timeout setting.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: f4acab0d-8073-40a0-96ba-1a5c2462b066

📥 Commits

Reviewing files that changed from the base of the PR and between dc25e71 and f111178.

📒 Files selected for processing (3)

• docs/contributing/packages-and-manifests.md
• packages/worker/src/package-retrievers/service.node.test.ts
• packages/worker/src/package-retrievers/service.ts

---

📝 Walkthrough

Walkthrough

Package retriever execution now uses updated timeout budgets and soft-fails individual retrievers. Failed retrievers are logged and returned as warnings while successful results remain available. Documentation and tests cover the timeout and failure behavior.

Changes

Package retriever resilience

Layer / File(s)	Summary
Timeout budgets and error normalization packages/worker/src/package-retrievers/service.ts, docs/contributing/packages-and-manifests.md	Retriever timeout defaults and limits are updated, execution errors are normalized, and the documented manifest and failure behavior reflect the new budgets.
Soft-fail retriever aggregation packages/worker/src/package-retrievers/service.ts, packages/worker/src/package-retrievers/service.node.test.ts	runPackageRetrievers uses settled execution results to skip failed retrievers, log failures, accumulate warnings, and retain healthy results; tests cover timeout handling and assertions.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant runPackageRetrievers
  participant RetrieverExecution
  participant consoleError
  runPackageRetrievers->>RetrieverExecution: execute healthy and stalled retrievers
  RetrieverExecution-->>runPackageRetrievers: successful result or timeout error
  runPackageRetrievers->>consoleError: log failed retriever
  runPackageRetrievers-->>runPackageRetrievers: keep healthy results and accumulate warning

Loading

Suggested reviewers: kody-bot

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: making stalled package retrievers soft-fail during search and execute.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch cursor/mcp-retriever-timeout-soft-fail-3db5

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

🔎 Preview deployed: https://kody-pr-920.kody-a99.workers.dev

Worker: kody-pr-920
D1: kody-pr-920-db
KV: kody-pr-920-oauth-kv

Mocks:

• cloudflare: https://kody-pr-920-mock-cloudflare.kody-a99.workers.dev/__mocks (kody-pr-920-mock-cloudflare)