feat(mcp): loopKey support for MCP-wrapped tools

[LukasParke]

Summary

Stacked on #73 (feat/doom-loop-detector). Closes the review finding that MCP tools had no way to declare a doom-loop loopKey — the entire MCP surface was stuck on whole-arguments identity.

What's added

Two declaration channels, both landing on tool.function.loopKey via markMcp's injection point (shipped in #73):

1. Client config — loopKeys on createMCPTools / rehydrateMCPTools, keyed by the tool's unprefixed MCP name. Accepts any ToolLoopKey form:

const handle = await createMCPTools({
  url: 'https://mcp.example.com',
  toolNamePrefix: 'svc_',
  loopKeys: {
    run_command: ['command', 'cwd'],   // field list — the bash identity
    web_search: (args) => String(args.query).toLowerCase(), // function
    poll_job: false,                    // exempt — repetition is its job
  },
});

2. Server-advertised — _meta['openrouter/loopKey'] on the MCP tool definition: a field-name array or false. Data-only by design (functions can't cross the wire); unknown shapes ignored. Captured in listToolDefs, carried on McpToolDef.loopKey, and round-tripped through cache snapshots (SerializedMCPToolDef.loopKey), so rehydrated tool sets keep their identities without a listTools() round-trip.

Client config takes precedence over the server declaration. Both wrap branches (regular + emitProgress generator) get the same wiring.

Tests

10 new tests (tests/unit/loop-key.test.ts): all three client-config forms, unprefixed-name keying, server-advertised pickup, client-over-server precedence, generator-tool coverage, absent-by-default, buildTools plumbing, and cache serialize → JSON round-trip for both field-list and false declarations.

Verification

• pnpm test (mcp): 10 files, 49 passed (10 new)
• pnpm typecheck, pnpm lint: clean

Surface changes

• CreateMCPToolsOptions.loopKeys / RehydrateMCPToolsOptions.loopKeys
• McpToolDef.loopKey, WrapToolOptions.loopKeys, BuildToolsOptions.loopKeys
• SerializedMCPToolDef.loopKey (additive within snapshot version 1)
• Changeset: minor (@openrouter/mcp)

---

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

[cortex-github-agent]

Summary

Update resolves the coverage gaps flagged in the prior pass: server-advertised loopKey parsing (advertisedLoopKey/listToolDefs) is now directly unit-tested against invalid/missing _meta shapes, and cache-types.ts gained loopKey shape validation in isSerializedToolDef so a corrupted/malformed cached loopKey now fails isSerializedMCPServer instead of being silently trusted. Core wiring (client-config precedence over server-advertised, markMcp injection, cache round-trip) is unchanged from the previous revision and remains correct.

Findings (1)

⚪ nit · packages/mcp/src/cache/cache-types.ts:64
isJsonSchemaObject(value) is evaluated twice (once for the loopKey extraction, once in the final return's boolean chain) — harmless but slightly redundant.

[cortex-github-agent]

Summary

This update replaces the options.loopKeys?.[def.name] ?? def.loopKey precedence lookup in tool-wrapper.ts with an Object.hasOwn()-guarded lookup, fixing a real (if narrow) correctness bug: bracket access on a plain object follows the prototype chain, so an MCP tool literally named toString/constructor/valueOf/etc. would previously pick up the inherited Object.prototype method as its loopKey even when the caller's loopKeys map was empty or didn't mention that tool — silently discarding any server-advertised declaration. The fix is now covered by a dedicated regression test. No other logic changed; prior findings stand as noted below.

Findings (1)

⚪ nit · packages/mcp/src/cache/cache-types.ts:64
isJsonSchemaObject(value) is still evaluated twice in isSerializedToolDef (once for the loopKey extraction, once in the final conjunction) — unchanged from the prior revision, still just cosmetic.

[cortex-github-agent]

Summary

This update closes a real latent gap: loopKeys was missing from FORWARDED_REHYDRATE_KEYS, so with caching enabled the warm (cache-hit) path silently dropped client-configured doom-loop identities while cold connects honored them. The fix adds the key to the type-checked allowlist (create-mcp-tools.ts:47), documents the drop-on-omission hazard, and adds an end-to-end regression test that drives createMCPTools through the cache hit and asserts loopKey lands on the rehydrated tool. No new issues; only a cosmetic nit remains.

Findings (1)

⚪ nit · packages/mcp/src/cache/cache-types.ts:63-72
Unchanged from prior revisions: isJsonSchemaObject(value) is evaluated twice in isSerializedToolDef (once to extract loopKey, once in the return conjunction). Cosmetic only.

[cortex-github-agent]

Summary

Only change since the last head is the isSerializedToolDef refactor in packages/mcp/src/cache/cache-types.ts:62-76: it early-returns on a non-object value and reads loopKey once, which resolves the standing cosmetic nit about the duplicated isJsonSchemaObject(value) call with identical accept/reject semantics. No functional changes elsewhere and no new issues; all prior findings are now closed.

✅ No findings.

[devin-ai-integration]

Re-review at c3ce7b4c

Verified locally at this head: pnpm typecheck, pnpm lint clean; full suite 702 tests across 61 files (643 agent + 59 mcp).

c3ce7b4c is a merge of the base branch, and it carries exactly 68eb0bc (#73's advisor: false fix — 11 lines of doom-loop.ts plus 39 lines of tests) with no conflict resolution of its own: git diff c3ce7b4c^1 c3ce7b4c is that commit verbatim. This PR's own diff against its base is unchanged apart from 6e5148c.

6e5148c is a strict improvement over what I suggested. The early return doesn't just deduplicate isJsonSchemaObject(value) — it removes the trap that the ternary created, where a non-object value produced loopKey === undefined and therefore hasValidLoopKey === true, a local asserting validity about a value that was never inspected. Harmless before only because the conjunction re-checked object-ness; now it's not load-bearing. The added comment recording why each accepted shape is accepted (absent = optional, false = exempt, string[] = field list, everything else = poisoned or stale snapshot) is the part that will keep the guard honest when someone widens SerializedMCPToolDef later.

One standing item, same as on #73: .changeset/mcp-loop-key.md has no fenced code block, and loopKeys on createMCPTools/rehydrateMCPTools plus McpToolDef.loopKey are public API — .agents/skills/public-api-examples/SKILL.md requires the example in the changeset. The loopKeys: { run_command: ['command', 'cwd'], poll_job: false } snippet from the PR description is exactly what's missing there.

Verdict: ✅ LGTM. Merge order matters — this lands after #73.

[cortex-github-agent]

Base switched to main — the effective diff is no longer the MCP change alone.

Previous passes (heads e45973f → 6e5148c) reviewed 9–11 files, all in packages/mcp, against base feat/doom-loop-detector. This head (c1b0c02) targets main, so the PR now carries the entire stacked #73/#75 surface as its own change: 34 files, including packages/agent/src/lib/doom-loop.ts (+1088), model-result.ts (+878/-38), the escalate ladder, run cancellation (signal on callModel, dispatchRequestOptions), three new changesets for @openrouter/agent, and ~4,700 lines of new agent tests. The GitHub diff is truncated at 200 KB, so part of it is not inspectable in this pass.

The MCP portion is byte-identical to the head I approved and I have no new findings there. What changed is what an approval means: it would now bless the @openrouter/agent minor release surface too, under a PR titled feat(mcp) whose body still says "Stacked on #73" and lists only MCP surface changes.

Two possibilities:

• feat(agent): doom-loop detection for the tool-execution loop #73 is still meant to merge first → re-target this PR at feat/doom-loop-detector and the diff collapses back to the MCP subset (already approved).
• The stack is being collapsed deliberately → please update the title/body to describe the full surface, and point me at where the doom-loop/cancellation code was reviewed so this PR isn't the first review of record for it.

Advisory notes on the newly-in-scope code, from what is visible:

• packages/agent/src/lib/model-result.ts:2985 — AbortSignal.any(...) requires Node ≥ 20.3 and globalThis.crypto.subtle (doom-loop.ts:520) requires Node ≥ 19, but packages/agent/package.json declares no engines field. Consumers on Node 18 get a runtime TypeError only when they opt into signal/doomLoop. Worth declaring the floor.
• packages/agent/src/lib/model-result.ts:2981 — this.options.client._options.timeoutMs reads an underscore-prefixed SDK internal. If @openrouter/sdk renames it, the client-level timeout silently stops applying on the composed-signal path (no type error, no test failure unless one pins it). A narrow accessor or a documented dependency would make that breakage loud.

[cortex-github-agent]

Summary

The MCP loopKey code is unchanged from the head I approved (6e5148c) and remains clean — all prior findings stay resolved. What changed is the base: retargeting from feat/doom-loop-detector to main pulled the whole stacked doom-loop/escalation/cancellation surface (~5,000 new lines across packages/agent, plus three @openrouter/agent changesets) into this PR's own diff, which is also truncated at 200 KB, so I can neither review it here nor approve it as if I had.

Findings (4)

🟠 major · packages/agent/src/lib/doom-loop.ts:1-1088
Base switch to main expanded this PR from 9 MCP files to 34, adding ~5,000 lines of agent-engine code (doom-loop detector, escalate ladder, run cancellation) plus three @openrouter/agent changesets, none of which the PR title/body describes and none of which was in scope for the four prior review passes. Either re-target at feat/doom-loop-detector (diff collapses to the already-approved MCP subset) or update the description and point to where this engine code was reviewed.

🟡 minor · packages/agent/src/lib/model-result.ts:2985
AbortSignal.any (Node >= 20.3) and globalThis.crypto.subtle in doom-loop.ts:520 (Node >= 19) raise the effective runtime floor, but packages/agent/package.json declares no engines field — Node 18 consumers hit a runtime TypeError only once they opt into signal/doomLoop.

🟡 minor · packages/agent/src/lib/model-result.ts:2981
this.options.client._options.timeoutMs reads an underscore-prefixed SDK internal; an upstream rename would silently drop the client-level timeout on the composed-signal path with no type error or failing test.

⚪ nit · packages/agent/src/inner-loop/call-model.ts:140-169
The option assembly was rewritten to a Record<string, unknown> plus a delete-undefined loop and a double cast (as unknown as GetResponseOptions), trading the previous compile-time checking of each forwarded key for runtime pruning — a future renamed option would no longer fail typecheck.

[LukasParke]

CI note on c1b0c02: structural-gate is failing, and the attribution is worth stating precisely because it is not what the red X suggests.

The failing criterion is complex functions 9 → 10 — not coupling (this PR is a different case from #86, which fails on coupling against a much older 0.43 / 133-edge baseline).

What the evidence says:

• The gate only ran on c1b0c02, which is a changeset-only commit (.changeset/mcp-loop-key.md, +29 lines of markdown). It cannot add a complex function.
• My other commit here, 6e5148c, converts a ternary + conjunction into an early return — that reduces branching, and its diff is 8 insertions in one guard function.
• feat(agent): doom-loop detection for the tool-execution loop #73 passes this gate on its own — 68eb0bc is green with the identical 0.4739 / 9 complex fn baseline.

So the +1 appears only when #73's code is combined with this branch's, via the dae91464 merge. Neither PR trips it alone. That is a composition effect, not a regression introduced by either changeset.

I am not touching the gate config or thresholds, and I am not restructuring working code to chase a metric that neither PR moved on its own. Two reasonable paths, and this is a human call:

1. Merge feat(agent): doom-loop detection for the tool-execution loop #73 first (devin's note on this PR says the same: "Merge order matters — this lands after feat(agent): doom-loop detection for the tool-execution loop #73"). Once feat(agent): doom-loop detection for the tool-execution loop #73 is on main, its function is baseline, and re-running this gate should measure only this PR's own delta.
2. Refresh the baseline on main, which is the same underlying ask as on feat(mcp)!: support both MCP protocol revisions (2025-11-25 and 2026-07-28) #86 — the committed baseline is stale there too, and there is precedent in fcbf9aa.

All review threads here are resolved and Devin Review is green at this head.

[devin-ai-integration]

Re-review — c1b0c02

The changeset example is correct — it compiles against this branch (loopKeys keyed by unprefixed name, cache: { store }, handle.tools into doomLoop: true), and it covers the changed surface rather than adjacent code. But two things need to happen before this merges, one of which contradicts the triage of the failing check.

1. structural-gate ❌ is this PR's own regression, not inherited drift

Reproduced with sentrux 0.5.7 (the version CI pins) and isolated by file. Reverting packages/mcp/src/rehydrate.ts to main while keeping the rest of the PR clears it; keeping only that file and reverting everything else reintroduces it; and removing the single added hunk

...(options.loopKeys !== undefined && {
  loopKeys: options.loopKeys,
}),

from toCreateOptions clears it. toCreateOptions sat at cc=15 — the max_cc in .sentrux/rules.toml — so the 15th conditional spread is one over the ceiling.

You already fixed this exact function on #86 (6a87464). Porting the same shape here — a as const satisfies readonly (keyof RehydrateMCPToolsOptions & keyof CreateMCPToolsOptions)[] key list plus one copy loop, mirroring forwardedRehydrateOptions — gives, verified locally: ✓ No degradation detected, tsc --noEmit clean, 59/59 mcp unit tests passing.

Both PRs edit toCreateOptions, so whichever lands second must add loopKeys to the key list rather than re-adding a spread.

2. loopKey: [] collapses a tool's entire identity — and this PR makes it server-controllable

advertisedLoopKey accepts an empty array ([].every(...) is vacuously true), isSerializedToolDef accepts it through the cache, and resolveLoopKeyMaterial([]) returns an empty subset as key material. So every call of that tool hashes to one fingerprint. Verified:

const a = resolveLoopKeyMaterial([], { command: 'ls', cwd: '/a' });
const b = resolveLoopKeyMaterial([], { command: 'rm -rf /', cwd: '/b' });
await fingerprintToolCall('run_command', a.keyMaterial)
  === await fingerprintToolCall('run_command', b.keyMaterial); // true

Before this PR that required a local typo. After it, a server can put _meta['openrouter/loopKey']: [] on a tool definition and drive a client's run to block/stop on its 2nd or 3rd unrelated call to that tool — remote input deciding that someone else's agent is looping. The codebase already treats identity collapse as a bug for the function form: a loopKey returning undefined falls back to full arguments with a warning, on the stated grounds that treating it as key material "would collide every call of the tool onto one fingerprint". An empty field list is the same failure with the same reasoning, so it should get the same treatment.

The cheapest choke point is resolveLoopKeyMaterial — one guard covers the server channel, the cache channel, and the client loopKeys map — but that file is on main now, so it's either a small follow-up or an addition here plus validation in advertisedLoopKey / isSerializedToolDef.

3. Review surface (not blocking)

This branch is still stacked on the pre-merge feat/doom-loop-detector, and #73 was squash-merged, so the merge base predates it: GitHub's three-dot diff shows 34 files / +8145 with all of doom-loop, escalation, and run-cancellation re-presented as new. git diff origin/main HEAD is the real change — 11 files / +559. Merging main in collapses the diff to what actually wants reviewing.

[perry-the-pr-reviewer]

Perry's Review

Verdict: 💬 Comments / questions
Risk: 🟡 Medium

Details

Re-reviewing after c1b0c02 (changeset example fix). All prior review threads are resolved, cortex approved, and the loopKey implementation is clean: server-advertised _meta parsing, client-side loopKeys map with Object.hasOwn precedence, cache snapshot validation in isSerializedToolDef, and the FORWARDED_REHYDRATE_KEYS fix for cache hits. The changeset now includes the required API example.

CI: structural-gate FAILURE (complex functions 9 to 10). The effective diff against main is only 11 files / 559 insertions (the gh pr diff includes merge history from the merged doom-loop PR). The one additional complex function is in the new loopKey code. Whether this is acceptable is a human judgment call — it's a single function crossing the sentrux threshold, not a structural regression across the codebase.

One cross-PR concern worth flagging: this PR still imports from the v1 MCP SDK and uses the three-argument callTool signature with the undefined middle parameter. PR #86 migrates to the v2 SDK and removes that middle argument. When whichever merges first lands, the other will need a follow-up to reconcile the import and callTool signature. This isn't a defect in either PR individually, but the merge order matters.

[LukasParke]

Head is now 6f9f3c1 (main merged in). Both of Devin's blockers addressed.

structural-gate. Ported the key-list + copy-loop from 6a87464 on the dual-protocol branch exactly as suggested — PASS_THROUGH_CREATE_KEYS with as const satisfies readonly (keyof RehydrateMCPToolsOptions & keyof CreateMCPToolsOptions)[], so a key that isn't valid on both types fails to compile instead of silently dropping. loopKeys is in the list. Noting your cross-PR point: whichever of #74 / #86 lands second inherits the other's list, and since both now carry it the merge is a no-op either way.

loopKey: [] collapsing tool identity. Confirmed and fixed. Traced it end to end: advertisedLoopKey (handle.ts:41) accepts [] because [].every(...) is vacuously true, and resolveLoopKeyMaterial (doom-loop.ts:459) then builds an empty subset, so identity is constant and a detector armed to block a repeat refuses the second unrelated call. Both degenerate shapes now warn and fall back to full arguments, mirroring the function form's existing warns-and-falls-back behavior:

• empty field list → kind: 'fallback' + warning
• every declared field absent from the arguments → same (the same collapse by another route, which your comment didn't mention but has identical impact)

false remains the documented way to exempt a tool. Guarded in resolveLoopKeyMaterial as you preferred, so it covers the wire path and local declarations together.

Three tests added, including empty field array does not collapse two unrelated calls to one identity asserting ls and rm -rf / no longer fingerprint the same. Mutation-verified: replacing the guard condition with if (false) fails exactly one test.

Verification: 646 agent + 59 mcp tests pass, typecheck and lint clean.

Non-blocking note you raised: the branch is still stacked on the pre-merge base, so GitHub shows inflated file/line counts.

[devin-ai-integration]

Devin Review found 2 new potential issues.

[devin-ai-integration]

🔍 Server-advertised loopKey is trusted unconditionally, including false

advertisedLoopKey accepts false (full exemption) and any string array straight off _meta['openrouter/loopKey'], and wrapMcpTool applies it whenever the client hasn't configured an override (packages/mcp/src/tool-wrapper.ts:101-104). The agent-side guard added in this PR only protects against the degenerate empty list (packages/agent/src/lib/doom-loop.ts:469-476); a server can still fully disable doom-loop detection for its own tools by advertising false, or collapse all its calls onto one identity by advertising a field that is constant across calls (e.g. ['api_version']), which bypasses both new guards since the subset is non-empty. Worth deciding whether server declarations should be opt-in (e.g. a trustServerLoopKeys flag) rather than honored by default.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[LukasParke]

Both of these are the same finding at two severities, and I'm escalating rather than deciding it — it's a question about this feature's trust model, not a defect in its implementation.

Verified the mechanism at head. advertisedLoopKey (handle.ts:35-46) returns false or a string array verbatim, and wrapMcpTool (tool-wrapper.ts:101-104) applies it whenever the client hasn't set loopKeys[name]. So server declarations are honored by default, and:

• false → resolveLoopKeyMaterial returns {kind:'exempt'}, disabling detection for that tool entirely.
• ['api_version'] (or any field constant across calls) → a non-empty subset, so it passes both guards I added in 6f9f3c1 while still collapsing every call onto one identity.

You're right that my guards don't cover these. They were scoped to the degenerate shapes — empty list, all-fields-absent — where no legitimate intent exists. A constant-valued field is indistinguishable from a correct narrow key without knowing the tool's semantics, and false is a legitimate declaration that a tool repeats by design. Neither can be fixed by validating the value.

The real question is the default, and there are three answers:

1. trustServerLoopKeys defaulting to false (your suggestion). Servers can advertise; clients opt in. Safest, but it makes the feature inert out of the box, which may defeat the point of wire advertisement.
2. Honor field lists, ignore false. A server can narrow its identity but never exempt itself. Keeps most of the value; removes the total-bypass case.
3. Keep it as-is, document the trust boundary. Defensible if MCP servers are already trusted — they execute arbitrary tool calls, so a hostile server has far worse options than weakening a loop detector.

My read is (2), because it's the only one that removes the sharp edge without making the feature opt-in — but it's a judgment about how much an MCP server is trusted, which belongs to whoever owns that boundary. Leaving both threads open.

Worth noting for whoever decides: loopKey is a safety control, not a security boundary. It bounds wasted spend on a looping agent. A hostile server neutralizing it costs money, not integrity — which argues this is lower severity than the 🟨 marking suggests, though still worth a deliberate default.

[devin-ai-integration]

🟨 Remote MCP server can disable doom-loop detection for its own tools

A tool definition fetched from a remote MCP server can now declare _meta['openrouter/loopKey'] and that value is trusted verbatim (advertisedLoopKey at packages/mcp/src/handle.ts:35-46, applied at packages/mcp/src/tool-wrapper.ts:101-104). A hostile or compromised server can send false, which makes the wrapped tool statically exempt from doom-loop detection (resolveLoopKeyMaterial returns {kind:'exempt'} for false, packages/agent/src/lib/doom-loop.ts:454-458), or a field list naming a constant/absent-in-practice field to collapse many distinct calls onto one identity. The agent-side guard added in this PR only catches the empty-array and all-fields-absent degenerate cases, not false or a constant single-field list, so the server-controlled path can still neutralize a client-side safety control the operator explicitly enabled via doomLoop.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[LukasParke]

Both of these are the same finding at two severities, and I'm escalating rather than deciding it — it's a question about this feature's trust model, not a defect in its implementation.

Verified the mechanism at head. advertisedLoopKey (handle.ts:35-46) returns false or a string array verbatim, and wrapMcpTool (tool-wrapper.ts:101-104) applies it whenever the client hasn't set loopKeys[name]. So server declarations are honored by default, and:

• false → resolveLoopKeyMaterial returns {kind:'exempt'}, disabling detection for that tool entirely.
• ['api_version'] (or any field constant across calls) → a non-empty subset, so it passes both guards I added in 6f9f3c1 while still collapsing every call onto one identity.

You're right that my guards don't cover these. They were scoped to the degenerate shapes — empty list, all-fields-absent — where no legitimate intent exists. A constant-valued field is indistinguishable from a correct narrow key without knowing the tool's semantics, and false is a legitimate declaration that a tool repeats by design. Neither can be fixed by validating the value.

The real question is the default, and there are three answers:

1. trustServerLoopKeys defaulting to false (your suggestion). Servers can advertise; clients opt in. Safest, but it makes the feature inert out of the box, which may defeat the point of wire advertisement.
2. Honor field lists, ignore false. A server can narrow its identity but never exempt itself. Keeps most of the value; removes the total-bypass case.
3. Keep it as-is, document the trust boundary. Defensible if MCP servers are already trusted — they execute arbitrary tool calls, so a hostile server has far worse options than weakening a loop detector.

My read is (2), because it's the only one that removes the sharp edge without making the feature opt-in — but it's a judgment about how much an MCP server is trusted, which belongs to whoever owns that boundary. Leaving both threads open.

Worth noting for whoever decides: loopKey is a safety control, not a security boundary. It bounds wasted spend on a looping agent. A hostile server neutralizing it costs money, not integrity — which argues this is lower severity than the 🟨 marking suggests, though still worth a deliberate default.