@sema-agent/core 7.57.0 → 7.59.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +1161 -0
- package/README.md +6 -4
- package/dist/agents/cc-peer-directory.js +8 -8
- package/dist/agents/child-model-seat.d.ts +4 -2
- package/dist/agents/child-model-seat.js +5 -3
- package/dist/agents/peer-directory.d.ts +9 -0
- package/dist/agents/peer-directory.js +6 -2
- package/dist/agents/send-message-tool.js +21 -12
- package/dist/agents/subagent-steps.js +2 -4
- package/dist/agents/subagent.js +33 -34
- package/dist/brain/anthropic.js +161 -45
- package/dist/brain/errors.d.ts +9 -3
- package/dist/brain/errors.js +7 -1
- package/dist/brain/failover.js +2 -1
- package/dist/brain/open-responses.js +3 -3
- package/dist/brain/openai.js +103 -53
- package/dist/brain/provider-dialect.d.ts +11 -0
- package/dist/brain/provider-dialect.js +5 -2
- package/dist/brain/reasoning-request.js +5 -4
- package/dist/brain/reasoning.d.ts +19 -0
- package/dist/brain/reasoning.js +17 -2
- package/dist/brain/request-route.d.ts +4 -1
- package/dist/brain/request-route.js +4 -1
- package/dist/brain/route-adjudicator.d.ts +84 -18
- package/dist/brain/route-adjudicator.js +89 -22
- package/dist/brain/route-conformance.js +1 -1
- package/dist/brain/stream-engine.js +84 -49
- package/dist/brain/stream-shared.d.ts +30 -0
- package/dist/brain/stream-shared.js +34 -1
- package/dist/brain/timeout.d.ts +62 -5
- package/dist/brain/timeout.js +93 -6
- package/dist/core/a2a.d.ts +2 -1
- package/dist/core/a2a.js +23 -10
- package/dist/core/account-row.d.ts +61 -0
- package/dist/core/account-row.js +51 -0
- package/dist/core/advisor-verdict.d.ts +2 -1
- package/dist/core/advisor-verdict.js +1 -1
- package/dist/core/allow-entry.d.ts +20 -7
- package/dist/core/allow-entry.js +18 -9
- package/dist/core/approval-object.d.ts +29 -15
- package/dist/core/approval-object.js +47 -19
- package/dist/core/ask-origin.d.ts +21 -2
- package/dist/core/ask-origin.js +5 -1
- package/dist/core/auto-compaction.d.ts +4 -0
- package/dist/core/auto-compaction.js +2 -2
- package/dist/core/auto-mode-directive.d.ts +29 -5
- package/dist/core/auto-mode-directive.js +38 -8
- package/dist/core/background-agent-store.d.ts +16 -3
- package/dist/core/checkpoint-requirements.d.ts +19 -1
- package/dist/core/checkpoint-requirements.js +5 -1
- package/dist/core/checkpoint-store.d.ts +85 -23
- package/dist/core/checkpoint-store.js +31 -9
- package/dist/core/child-clamp-seats.d.ts +29 -0
- package/dist/core/child-clamp-seats.js +56 -1
- package/dist/core/compliance.d.ts +2 -2
- package/dist/core/compliance.js +1 -1
- package/dist/core/effective-path-target.d.ts +8 -2
- package/dist/core/effective-path-target.js +8 -3
- package/dist/core/engine-notice.d.ts +99 -9
- package/dist/core/engine-notice.js +19 -5
- package/dist/core/fs-write-gate-policy.d.ts +4 -2
- package/dist/core/fs-write-gate-policy.js +7 -3
- package/dist/core/gate-fold.js +7 -4
- package/dist/core/gate-lanes.js +19 -6
- package/dist/core/gate-outcome.d.ts +32 -3
- package/dist/core/gate-outcome.js +19 -1
- package/dist/core/git-worktree-env.d.ts +53 -11
- package/dist/core/git-worktree-env.js +96 -12
- package/dist/core/governance-codes.d.ts +9 -1
- package/dist/core/governance-codes.js +13 -0
- package/dist/core/hooks.d.ts +35 -4
- package/dist/core/hooks.js +17 -11
- package/dist/core/human-input-projection.d.ts +1 -0
- package/dist/core/human-input-projection.js +3 -0
- package/dist/core/image-admission.d.ts +6 -5
- package/dist/core/image-admission.js +18 -14
- package/dist/core/locked-config.d.ts +20 -3
- package/dist/core/locked-config.js +40 -3
- package/dist/core/mailbox-store.d.ts +45 -1
- package/dist/core/mailbox-store.js +53 -9
- package/dist/core/mcp-call-meta.d.ts +66 -0
- package/dist/core/mcp-call-meta.js +103 -0
- package/dist/core/mcp-connection-pool.d.ts +3 -1
- package/dist/core/mcp-connection-pool.js +3 -1
- package/dist/core/mcp-failure.d.ts +117 -15
- package/dist/core/mcp-failure.js +71 -3
- package/dist/core/mcp-probe.d.ts +4 -0
- package/dist/core/mcp-probe.js +1 -1
- package/dist/core/mcp-server-link.d.ts +27 -3
- package/dist/core/mcp-server-link.js +25 -1
- package/dist/core/mcp-server-spec.d.ts +46 -18
- package/dist/core/mcp-server-spec.js +1 -18
- package/dist/core/mcp.d.ts +16 -20
- package/dist/core/mcp.js +112 -55
- package/dist/core/memory-engine/consolidation-driver.d.ts +2 -4
- package/dist/core/memory-engine/consolidation-driver.js +3 -3
- package/dist/core/memory-engine/consolidation.d.ts +4 -0
- package/dist/core/memory-engine/consolidation.js +1 -0
- package/dist/core/memory-engine/delegation-settlement.js +5 -12
- package/dist/core/memory-engine/distiller.js +2 -2
- package/dist/core/memory-engine/dual-root.d.ts +50 -1
- package/dist/core/memory-engine/dual-root.js +44 -1
- package/dist/core/memory-engine/engine.d.ts +67 -14
- package/dist/core/memory-engine/engine.js +384 -212
- package/dist/core/memory-engine/export-bundle.d.ts +23 -0
- package/dist/core/memory-engine/export-bundle.js +23 -4
- package/dist/core/memory-engine/file-backend.d.ts +128 -55
- package/dist/core/memory-engine/file-backend.js +290 -117
- package/dist/core/memory-engine/index.d.ts +1 -1
- package/dist/core/memory-engine/layout.d.ts +59 -11
- package/dist/core/memory-engine/layout.js +190 -40
- package/dist/core/memory-engine/memory-backend-contract.d.ts +1 -1
- package/dist/core/memory-engine/memory-backend-contract.js +39 -2
- package/dist/core/memory-engine/scope-contract.d.ts +45 -4
- package/dist/core/memory-engine/scope-contract.js +80 -11
- package/dist/core/memory-engine/sync-client.d.ts +9 -1
- package/dist/core/memory-engine/sync-client.js +31 -8
- package/dist/core/memory-engine/sync.d.ts +5 -0
- package/dist/core/memory-engine/types.d.ts +6 -0
- package/dist/core/mode-policy.d.ts +8 -5
- package/dist/core/mode-policy.js +5 -4
- package/dist/core/mods/classic-events.d.ts +5 -1
- package/dist/core/mods/host.js +1 -1
- package/dist/core/mods/kernel/dispatch.d.ts +3 -0
- package/dist/core/mods/kernel/dispatch.js +12 -9
- package/dist/core/mods/kernel/events.d.ts +6 -1
- package/dist/core/mods/kernel/events.js +2 -2
- package/dist/core/mods/kernel/registration.d.ts +9 -1
- package/dist/core/mods/kernel/registration.js +3 -0
- package/dist/core/mods/kernel/site-rules.d.ts +3 -0
- package/dist/core/mods/kernel/site-rules.js +10 -0
- package/dist/core/mods/package.d.ts +23 -0
- package/dist/core/mods/package.js +118 -0
- package/dist/core/mods/stations.d.ts +33 -12
- package/dist/core/mods/stations.js +45 -11
- package/dist/core/mods/tool-call.d.ts +5 -1
- package/dist/core/mods/tool-call.js +13 -4
- package/dist/core/parent-spec-seat.d.ts +8 -3
- package/dist/core/parent-spec-seat.js +2 -0
- package/dist/core/park-selfcheck.js +6 -0
- package/dist/core/path-guard-rows.d.ts +20 -0
- package/dist/core/path-guard-rows.js +11 -0
- package/dist/core/peer-seat.d.ts +248 -0
- package/dist/core/peer-seat.js +439 -0
- package/dist/core/permission-rule-consent.js +10 -4
- package/dist/core/permission-rule-model.d.ts +16 -0
- package/dist/core/permission-rule-model.js +1 -1
- package/dist/core/present-plan-tool.d.ts +20 -3
- package/dist/core/present-plan-tool.js +48 -4
- package/dist/core/protocol-http-auth.d.ts +40 -29
- package/dist/core/protocol-http-auth.js +30 -32
- package/dist/core/redaction-marks.d.ts +16 -0
- package/dist/core/redaction-marks.js +16 -0
- package/dist/core/redaction-passes.js +8 -9
- package/dist/core/resume-startup-cause.js +1 -0
- package/dist/core/retention.d.ts +41 -15
- package/dist/core/retention.js +59 -12
- package/dist/core/rewrite-rejudge.d.ts +38 -0
- package/dist/core/rewrite-rejudge.js +42 -2
- package/dist/core/roles.d.ts +34 -2
- package/dist/core/roles.js +43 -4
- package/dist/core/run-origin.d.ts +40 -0
- package/dist/core/run-origin.js +37 -0
- package/dist/core/runner/advertised-writable-dirs.d.ts +57 -38
- package/dist/core/runner/advertised-writable-dirs.js +126 -0
- package/dist/core/runner/announce-once-ledger.d.ts +5 -4
- package/dist/core/runner/announce-once-ledger.js +4 -2
- package/dist/core/runner/call-hook-stations.js +2 -2
- package/dist/core/runner/compaction-restate.d.ts +15 -6
- package/dist/core/runner/compaction-restate.js +28 -2
- package/dist/core/runner/contracts.d.ts +33 -21
- package/dist/core/runner/credential-origin-seat.js +4 -3
- package/dist/core/runner/cwd-alignment-probe.d.ts +20 -0
- package/dist/core/runner/cwd-alignment-probe.js +21 -0
- package/dist/core/runner/decide-continuation.d.ts +2 -2
- package/dist/core/runner/gate-exit.d.ts +30 -8
- package/dist/core/runner/gate-exit.js +15 -8
- package/dist/core/runner/image-removed-seat.d.ts +12 -0
- package/dist/core/runner/image-removed-seat.js +19 -0
- package/dist/core/runner/inline-image.js +1 -1
- package/dist/core/runner/memory-consolidation-driver.js +3 -3
- package/dist/core/runner/park-commit.d.ts +1 -1
- package/dist/core/runner/park-commit.js +3 -0
- package/dist/core/runner/prepare-ask-lane.d.ts +1 -1
- package/dist/core/runner/prepare-ask-lane.js +2 -1
- package/dist/core/runner/prepare-boundary-parks.js +2 -2
- package/dist/core/runner/prepare-caps-and-workflow.d.ts +5 -5
- package/dist/core/runner/prepare-caps-and-workflow.js +3 -1
- package/dist/core/runner/prepare-config-doors.d.ts +8 -5
- package/dist/core/runner/prepare-config-doors.js +14 -10
- package/dist/core/runner/prepare-context-lane.js +2 -0
- package/dist/core/runner/prepare-delegation-surface.d.ts +8 -0
- package/dist/core/runner/prepare-delegation-surface.js +16 -18
- package/dist/core/runner/prepare-gate-stations.js +1 -1
- package/dist/core/runner/prepare-hands-readface.d.ts +11 -3
- package/dist/core/runner/prepare-hands-readface.js +9 -1
- package/dist/core/runner/prepare-inherited-gate.d.ts +1 -3
- package/dist/core/runner/prepare-inherited-gate.js +14 -27
- package/dist/core/runner/prepare-memory.d.ts +3 -0
- package/dist/core/runner/prepare-memory.js +26 -37
- package/dist/core/runner/prepare-park-ask.d.ts +1 -1
- package/dist/core/runner/prepare-park-ask.js +2 -1
- package/dist/core/runner/prepare-policy-chain.d.ts +7 -7
- package/dist/core/runner/prepare-policy-chain.js +18 -15
- package/dist/core/runner/prepare-project-context.d.ts +2 -2
- package/dist/core/runner/prepare-project-context.js +2 -2
- package/dist/core/runner/prepare-prompt-inputs.d.ts +1 -1
- package/dist/core/runner/prepare-prompt-inputs.js +8 -19
- package/dist/core/runner/prepare-protocol-tools.d.ts +4 -2
- package/dist/core/runner/prepare-protocol-tools.js +11 -3
- package/dist/core/runner/prepare-run-refs.d.ts +2 -3
- package/dist/core/runner/prepare-run-refs.js +4 -1
- package/dist/core/runner/prepare-suspend-saga.d.ts +2 -0
- package/dist/core/runner/prepare-suspend-saga.js +2 -1
- package/dist/core/runner/prepare-task.js +28 -13
- package/dist/core/runner/prepare-wiring-manifest.d.ts +2 -1
- package/dist/core/runner/prepare-wiring-manifest.js +4 -3
- package/dist/core/runner/prepare-workspace-restore.d.ts +3 -0
- package/dist/core/runner/prepare-workspace-restore.js +4 -4
- package/dist/core/runner/reply-pricing.d.ts +30 -0
- package/dist/core/runner/reply-pricing.js +19 -0
- package/dist/core/runner/resume-admission.js +5 -3
- package/dist/core/runner/resume-apply.js +6 -1
- package/dist/core/runner/resume-checkpoint-screen.js +2 -0
- package/dist/core/runner/resume-policy-outcome.js +5 -5
- package/dist/core/runner/role-seat-defaulted.d.ts +44 -0
- package/dist/core/runner/role-seat-defaulted.js +40 -0
- package/dist/core/runner/run-brain-sinks.js +2 -0
- package/dist/core/runner/run-harness-handlers.d.ts +3 -4
- package/dist/core/runner/run-harness-handlers.js +1 -8
- package/dist/core/runner/run-identity-wiring.d.ts +2 -5
- package/dist/core/runner/run-identity-wiring.js +6 -4
- package/dist/core/runner/run-leg.d.ts +2 -0
- package/dist/core/runner/run-leg.js +42 -29
- package/dist/core/runner/run-notification-lane.js +3 -0
- package/dist/core/runner/run-stop-and-final-verify.js +2 -2
- package/dist/core/runner/run-terminal-adoption.d.ts +2 -5
- package/dist/core/runner/run-terminal-adoption.js +9 -3
- package/dist/core/runner/run-turn-boundary.js +77 -70
- package/dist/core/runner/runtask.d.ts +1 -1
- package/dist/core/runner/runtask.js +2 -2
- package/dist/core/runner/side-call-account.d.ts +1 -1
- package/dist/core/runner/side-call-account.js +3 -18
- package/dist/core/runner/sub-agent-deny-lists.d.ts +24 -0
- package/dist/core/runner/sub-agent-deny-lists.js +10 -0
- package/dist/core/runner/terminal-account.js +3 -3
- package/dist/core/runner/tool-end-body.js +2 -1
- package/dist/core/runner/tool-occurrence.d.ts +5 -2
- package/dist/core/runner/tool-occurrence.js +4 -3
- package/dist/core/runner/turn-attachments.d.ts +26 -22
- package/dist/core/runner/turn-attachments.js +24 -26
- package/dist/core/runner/write-protection-station.d.ts +8 -2
- package/dist/core/runner/write-protection-station.js +2 -0
- package/dist/core/runner-deps.d.ts +3 -3
- package/dist/core/secret-env.d.ts +32 -2
- package/dist/core/secret-env.js +65 -3
- package/dist/core/sensitive-path-policy.js +9 -10
- package/dist/core/session-log-transfer.d.ts +24 -0
- package/dist/core/session-log-transfer.js +166 -0
- package/dist/core/session-policy-store.d.ts +3 -1
- package/dist/core/session-policy-store.js +13 -9
- package/dist/core/session-store.d.ts +86 -24
- package/dist/core/session-store.js +162 -24
- package/dist/core/session.d.ts +92 -1
- package/dist/core/shell-read-silence.js +1 -0
- package/dist/core/side-query.d.ts +11 -1
- package/dist/core/side-query.js +9 -0
- package/dist/core/skill-grant-binding.d.ts +31 -2
- package/dist/core/skill-grant-binding.js +31 -1
- package/dist/core/skill-grant.d.ts +8 -5
- package/dist/core/skill-grant.js +6 -6
- package/dist/core/steer-replay.d.ts +4 -2
- package/dist/core/steer-replay.js +2 -1
- package/dist/core/store-contracts/background-agent-store-contract.js +27 -0
- package/dist/core/store-contracts/checkpoint-store-contract.js +20 -2
- package/dist/core/store-contracts/mailbox-store-contract.js +31 -1
- package/dist/core/store-contracts/session-repo-contract.js +112 -5
- package/dist/core/store-contracts/session-store-contract.d.ts +4 -1
- package/dist/core/store-contracts/session-store-contract.js +236 -2
- package/dist/core/synthetic-read-verdict.js +2 -1
- package/dist/core/task-event.d.ts +92 -8
- package/dist/core/task-notification.js +16 -10
- package/dist/core/task-registry-agent.js +1 -0
- package/dist/core/task-registry-shared.d.ts +7 -1
- package/dist/core/task-spec.d.ts +49 -1
- package/dist/core/task-stream.d.ts +2 -1
- package/dist/core/terminal-cause.d.ts +11 -1
- package/dist/core/tool-catalog-entries.js +1 -0
- package/dist/core/tool-check-reading.d.ts +1 -0
- package/dist/core/tool-check-reading.js +3 -3
- package/dist/core/tool-policy.d.ts +16 -0
- package/dist/core/tool-result-store.d.ts +17 -10
- package/dist/core/tool-result-store.js +3 -1
- package/dist/core/tool-roster.d.ts +112 -5
- package/dist/core/tool-roster.js +42 -1
- package/dist/core/tool-spec.d.ts +3 -1
- package/dist/core/types.d.ts +3 -3
- package/dist/core/types.js +1 -1
- package/dist/core/untrusted-egress.d.ts +0 -2
- package/dist/core/untrusted-egress.js +10 -14
- package/dist/core/user-attachment.js +1 -1
- package/dist/core/wiring-manifest.d.ts +18 -6
- package/dist/core/wiring-manifest.js +4 -3
- package/dist/core/workspace-snapshot.d.ts +44 -0
- package/dist/core/workspace-snapshot.js +34 -0
- package/dist/core/write-protect.d.ts +43 -3
- package/dist/core/write-protect.js +43 -16
- package/dist/engine/compaction/compaction.js +29 -3
- package/dist/engine/execution-env/node-execution-env.d.ts +4 -3
- package/dist/engine/execution-env/node-execution-env.js +24 -23
- package/dist/engine/execution-env/symlink-chain.d.ts +7 -5
- package/dist/engine/harness/agent-harness.d.ts +30 -2
- package/dist/engine/harness/agent-harness.js +43 -12
- package/dist/engine/harness/messages.d.ts +3 -1
- package/dist/engine/harness/messages.js +3 -2
- package/dist/engine/harness/types.d.ts +56 -7
- package/dist/engine/harness/types.js +5 -1
- package/dist/engine/llm/rejected-images.d.ts +46 -0
- package/dist/engine/llm/rejected-images.js +54 -0
- package/dist/engine/llm/tool-turns.d.ts +2 -1
- package/dist/engine/llm/types.d.ts +30 -10
- package/dist/engine/llm/types.js +1 -1
- package/dist/engine/loop/agent-loop.d.ts +8 -0
- package/dist/engine/loop/agent-loop.js +52 -15
- package/dist/engine/loop/types.d.ts +3 -1
- package/dist/engine/session/import-validate.js +3 -0
- package/dist/engine/session/memory-repo.d.ts +17 -9
- package/dist/engine/session/memory-repo.js +44 -34
- package/dist/engine/session/path-to-root.d.ts +38 -0
- package/dist/engine/session/path-to-root.js +39 -0
- package/dist/engine/session/repo-utils.d.ts +22 -4
- package/dist/engine/session/repo-utils.js +49 -1
- package/dist/engine/session/storage-base.d.ts +10 -1
- package/dist/engine/session/storage-base.js +11 -22
- package/dist/index.d.ts +29 -16
- package/dist/index.js +21 -11
- package/dist/internal/harness-types.d.ts +2 -2
- package/dist/internal/harness.d.ts +3 -2
- package/dist/internal/harness.js +2 -2
- package/dist/internal/llm.d.ts +1 -0
- package/dist/orchestration/workflow-observe.d.ts +17 -1
- package/dist/orchestration/workflow-observe.js +20 -0
- package/dist/orchestration/workflow-types.d.ts +32 -7
- package/dist/orchestration/workflow.js +739 -489
- package/dist/shell/counting-pass.d.ts +50 -0
- package/dist/shell/counting-pass.js +502 -0
- package/dist/shell/lex.d.ts +4 -2
- package/dist/shell/lex.js +93 -34
- package/dist/shell/shell-words.d.ts +1 -1
- package/dist/shell/shell-words.js +7 -6
- package/dist/stores/file/index.d.ts +4 -1
- package/dist/stores/file/index.js +4 -1
- package/dist/stores/file/mailbox-store.js +6 -10
- package/dist/stores/file/session-store.d.ts +15 -8
- package/dist/stores/file/session-store.js +28 -13
- package/dist/tools/fs/fs-bash.d.ts +6 -0
- package/dist/tools/fs/fs-bash.js +6 -3
- package/dist/tools/fs/fs-write.d.ts +6 -3
- package/dist/tools/fs/fs-write.js +8 -7
- package/dist/tools/fs/index.d.ts +3 -0
- package/dist/tools/fs/index.js +7 -3
- package/dist/tools/fs/program-read-model.d.ts +13 -0
- package/dist/tools/fs/program-read-model.js +15 -0
- package/dist/tools/fs/program-read-model.rows.js +1 -1
- package/dist/tools/fs/read-deny.d.ts +13 -10
- package/dist/tools/fs/read-deny.js +25 -5
- package/dist/tools/fs/read-floor.d.ts +19 -0
- package/dist/tools/fs/read-floor.js +23 -0
- package/dist/tools/fs/safety.js +40 -8
- package/dist/tools/fs/search.js +6 -24
- package/dist/tools/fs/shell-read-check.d.ts +9 -2
- package/dist/tools/fs/shell-read-check.js +61 -16
- package/dist/tools/fs/shell-read-establish.js +2 -1
- package/dist/tools/fs/shell-read-identity.js +1 -1
- package/dist/tools/fs/shell-read-judge.d.ts +26 -9
- package/dist/tools/fs/shell-read-judge.js +10 -6
- package/dist/tools/fs/shell-read-plan.d.ts +6 -1
- package/dist/tools/fs/shell-read-plan.js +22 -15
- package/dist/tools/fs/shell-read-start.js +1 -0
- package/dist/tools/fs/shell-reentry-text.d.ts +15 -1
- package/dist/tools/fs/shell-reentry-text.js +25 -3
- package/dist/tools/monitor.d.ts +4 -0
- package/dist/tools/monitor.js +2 -0
- package/dist/tools/worktree.d.ts +42 -15
- package/dist/tools/worktree.js +60 -32
- package/package.json +5 -2
- package/test/export-surface.snapshot.json +149 -1
- package/wire-changes/core-stores-sql@7.58.0.json +29 -0
- package/wire-changes/core-stores-sql@7.59.0.json +29 -0
- package/wire-changes/core@7.58.0.json +2188 -0
- package/wire-changes/core@7.59.0.json +2459 -0
- package/wire-changes/mods-kernel@7.58.0.json +81 -0
- package/wire-changes/mods-kernel@7.59.0.json +29 -0
- package/wire-changes/primitives@7.58.0.json +29 -0
- package/wire-changes/primitives@7.59.0.json +29 -0
- package/dist/primitives/credential-ref.d.ts +0 -89
- package/dist/primitives/credential-ref.js +0 -125
- package/dist/primitives/index.d.ts +0 -2
- package/dist/primitives/index.js +0 -1
|
@@ -2,6 +2,8 @@
|
|
|
2
2
|
* lease/expiry cycles (a re-leased message keeps its number — dedup/ordering key). */
|
|
3
3
|
export interface MailboxMessage {
|
|
4
4
|
seq: number;
|
|
5
|
+
/** The identity the PRODUCER gave this record ({@link MailboxAppendMessage.id}); absent = it stated none. */
|
|
6
|
+
id?: string;
|
|
5
7
|
/** Sender display name, when the sender had one (SendMessage `senderName` — display only). */
|
|
6
8
|
from?: string;
|
|
7
9
|
content: string;
|
|
@@ -181,7 +183,7 @@ export declare const MAILBOX_TOMBSTONED_RECIPIENT_CODE = "mailbox.recipient_tomb
|
|
|
181
183
|
* A backend may raise the same code with a plain `Error` carrying `.code`; consumers branch on the
|
|
182
184
|
* string, not on this class (a cross-process/out-of-repo store cannot hand back an instance).
|
|
183
185
|
*/
|
|
184
|
-
export type MailboxStoreErrorCode = typeof MAILBOX_TOMBSTONED_RECIPIENT_CODE | typeof MAILBOX_INVALID_PEER_META_CODE | typeof MAILBOX_CROSS_PROCESS_UNSAFE_CODE | typeof MAILBOX_INVALID_DECISION_MOVE_CODE;
|
|
186
|
+
export type MailboxStoreErrorCode = typeof MAILBOX_TOMBSTONED_RECIPIENT_CODE | typeof MAILBOX_INVALID_PEER_META_CODE | typeof MAILBOX_CROSS_PROCESS_UNSAFE_CODE | typeof MAILBOX_INVALID_DECISION_MOVE_CODE | typeof MAILBOX_INVALID_RECORD_ID_CODE | typeof MAILBOX_DUPLICATE_RECORD_ID_CODE;
|
|
185
187
|
export declare class MailboxStoreError extends Error {
|
|
186
188
|
readonly code: MailboxStoreErrorCode;
|
|
187
189
|
constructor(code: MailboxStoreErrorCode, message: string);
|
|
@@ -195,6 +197,14 @@ export interface MailboxLease {
|
|
|
195
197
|
/** REF-D18: one appended mailbox message — the SINGLE shape the interface method and both the
|
|
196
198
|
* In-Memory and File implementations reference. */
|
|
197
199
|
export interface MailboxAppendMessage {
|
|
200
|
+
/**
|
|
201
|
+
* The record's identity, minted by its producer — a re-park of the same message carries the same
|
|
202
|
+
* one. While the box HOLDS a record under this id, an append under it is that record: identical on
|
|
203
|
+
* every {@link MAILBOX_REPLAY_FACETS} facet ⇒ the held `seq`, nothing written; any facet different ⇒
|
|
204
|
+
* refused with {@link MAILBOX_DUPLICATE_RECORD_ID_CODE}. Absent = the producer states no identity and
|
|
205
|
+
* every append is a new record (its `seq` is all it is known by). Validated by {@link readMailboxRecordId}.
|
|
206
|
+
*/
|
|
207
|
+
id?: string;
|
|
198
208
|
from?: string;
|
|
199
209
|
content: string;
|
|
200
210
|
sentAt: number;
|
|
@@ -203,6 +213,33 @@ export interface MailboxAppendMessage {
|
|
|
203
213
|
/** design/385 — see {@link MailboxMessage.peerMeta}; validated by {@link readMailboxPeerMeta}. */
|
|
204
214
|
peerMeta?: MailboxPeerMeta;
|
|
205
215
|
}
|
|
216
|
+
/** An `id` that is not a non-empty string of at most {@link MAILBOX_RECORD_ID_MAX_CHARS} characters. */
|
|
217
|
+
export declare const MAILBOX_INVALID_RECORD_ID_CODE = "mailbox.invalid_record_id";
|
|
218
|
+
/** An append under an `id` the box holds, whose record differs from the held one. */
|
|
219
|
+
export declare const MAILBOX_DUPLICATE_RECORD_ID_CODE = "mailbox.duplicate_record_id";
|
|
220
|
+
export declare const MAILBOX_RECORD_ID_MAX_CHARS = 1024;
|
|
221
|
+
/**
|
|
222
|
+
* What a record SAYS — the facets a repeat under one id is compared on. `sentAt` is not one of them: it
|
|
223
|
+
* is when a write happened, and a re-park of the same message happens later. Closed, in refusal order.
|
|
224
|
+
*/
|
|
225
|
+
export declare const MAILBOX_REPLAY_FACETS: readonly ["from", "content", "hopChain", "peerMeta"];
|
|
226
|
+
export type MailboxReplayFacet = (typeof MAILBOX_REPLAY_FACETS)[number];
|
|
227
|
+
/** Validate a record id at `append`, before any side effect. `undefined` = no identity stated. */
|
|
228
|
+
export declare function readMailboxRecordId(raw: unknown): string | undefined;
|
|
229
|
+
/**
|
|
230
|
+
* ONE read of a caller's append: every member read once, validated (`peerMeta`, then `id`) and detached.
|
|
231
|
+
* A backend judges and persists THIS snapshot — never the caller's object again — so an accessor, or a
|
|
232
|
+
* mutation while the append waits for its lock, cannot make the record judged differ from the record stored.
|
|
233
|
+
*/
|
|
234
|
+
export declare function readMailboxAppend(msg: MailboxAppendMessage): MailboxAppendMessage;
|
|
235
|
+
/**
|
|
236
|
+
* THE append-by-identity judgment, the one every backend runs inside its write critical section
|
|
237
|
+
* (with `msg` already validated: `id` by {@link readMailboxRecordId}, `peerMeta` by {@link readMailboxPeerMeta}).
|
|
238
|
+
* Returns the held record's `seq` when `msg` replays it (the caller writes nothing), `undefined` when the
|
|
239
|
+
* box holds no record under `msg.id` (the caller appends), and throws {@link MAILBOX_DUPLICATE_RECORD_ID_CODE}
|
|
240
|
+
* naming the facets when a different record claims the id. A third-party backend calls this function too.
|
|
241
|
+
*/
|
|
242
|
+
export declare function judgeMailboxAppendById(held: readonly MailboxMessage[], msg: MailboxAppendMessage): number | undefined;
|
|
206
243
|
/**
|
|
207
244
|
* The pluggable mailbox seam (design/151 §7.1). Contract notes for implementations (file/pg):
|
|
208
245
|
* - `append` is durable-first (a returned seq means the message survives a crash); seq is monotonic
|
|
@@ -250,6 +287,13 @@ export interface MailboxAppendMessage {
|
|
|
250
287
|
* and a malformed value is REFUSED with `"mailbox.invalid_peer_meta"` before any side effect
|
|
251
288
|
* (`readMailboxPeerMeta` is the one validator; bundled backends call it first). T1 cases in
|
|
252
289
|
* `mailboxStoreContract` cover the pass trip, the refusal and the aliasing.
|
|
290
|
+
* - RECORD IDENTITY (every backend): `append` takes an optional producer-minted `id`, persists
|
|
291
|
+
* it and hands it back on `claimLease`. While the box holds a record under that id, an append under
|
|
292
|
+
* it is answered by {@link judgeMailboxAppendById} — the held `seq` for an identical record (nothing
|
|
293
|
+
* written), `"mailbox.duplicate_record_id"` for a different one — atomically with the seq allocation;
|
|
294
|
+
* a malformed id is refused with `"mailbox.invalid_record_id"` before any side effect. This is what
|
|
295
|
+
* makes re-asking a store whose reply was lost safe: a rejected append is not proof that nothing was
|
|
296
|
+
* written. The box answers for what it HOLDS — once a record is acked its id is free again.
|
|
253
297
|
* - CROSS-PROCESS SAFETY (design/385, optional capability declared on the store): the session-box
|
|
254
298
|
* drain shares ONE box between several OS processes. A backend that is correct under that sharing —
|
|
255
299
|
* seq minted once across processes, lease/ack never crossing, one process's housekeeping never
|
|
@@ -150,6 +150,54 @@ export class MailboxStoreError extends Error {
|
|
|
150
150
|
this.name = "MailboxStoreError";
|
|
151
151
|
}
|
|
152
152
|
}
|
|
153
|
+
export const MAILBOX_INVALID_RECORD_ID_CODE = "mailbox.invalid_record_id";
|
|
154
|
+
export const MAILBOX_DUPLICATE_RECORD_ID_CODE = "mailbox.duplicate_record_id";
|
|
155
|
+
export const MAILBOX_RECORD_ID_MAX_CHARS = 1024;
|
|
156
|
+
export const MAILBOX_REPLAY_FACETS = Object.freeze(["from", "content", "hopChain", "peerMeta"]);
|
|
157
|
+
export function readMailboxRecordId(raw) {
|
|
158
|
+
if (raw === undefined)
|
|
159
|
+
return undefined;
|
|
160
|
+
if (typeof raw !== "string" || raw === "" || raw.length > MAILBOX_RECORD_ID_MAX_CHARS) {
|
|
161
|
+
throw new MailboxStoreError(MAILBOX_INVALID_RECORD_ID_CODE, `MailboxStore.append: id must be a non-empty string of at most ${MAILBOX_RECORD_ID_MAX_CHARS} characters`);
|
|
162
|
+
}
|
|
163
|
+
return raw;
|
|
164
|
+
}
|
|
165
|
+
export function readMailboxAppend(msg) {
|
|
166
|
+
const peerMeta = readMailboxPeerMeta(msg.peerMeta);
|
|
167
|
+
const id = readMailboxRecordId(msg.id);
|
|
168
|
+
const from = msg.from;
|
|
169
|
+
const content = msg.content;
|
|
170
|
+
const sentAt = msg.sentAt;
|
|
171
|
+
const hopChain = msg.hopChain;
|
|
172
|
+
return {
|
|
173
|
+
...(id !== undefined ? { id } : {}),
|
|
174
|
+
...(from !== undefined ? { from } : {}),
|
|
175
|
+
content,
|
|
176
|
+
sentAt,
|
|
177
|
+
...(hopChain !== undefined ? { hopChain: [...hopChain] } : {}),
|
|
178
|
+
...(peerMeta !== undefined ? { peerMeta } : {}),
|
|
179
|
+
};
|
|
180
|
+
}
|
|
181
|
+
function facetSpelling(v) {
|
|
182
|
+
if (v === undefined || v === null)
|
|
183
|
+
return "-";
|
|
184
|
+
if (typeof v !== "object")
|
|
185
|
+
return JSON.stringify(v);
|
|
186
|
+
if (Array.isArray(v))
|
|
187
|
+
return `[${Array.from(v, facetSpelling).join(",")}]`;
|
|
188
|
+
return `{${Object.keys(v).filter((k) => v[k] !== undefined).sort().map((k) => `${JSON.stringify(k)}:${facetSpelling(v[k])}`).join(",")}}`;
|
|
189
|
+
}
|
|
190
|
+
export function judgeMailboxAppendById(held, msg) {
|
|
191
|
+
if (msg.id === undefined)
|
|
192
|
+
return undefined;
|
|
193
|
+
const prior = held.find((m) => m.id === msg.id);
|
|
194
|
+
if (prior === undefined)
|
|
195
|
+
return undefined;
|
|
196
|
+
const differs = MAILBOX_REPLAY_FACETS.filter((f) => facetSpelling(prior[f]) !== facetSpelling(msg[f]));
|
|
197
|
+
if (differs.length === 0)
|
|
198
|
+
return prior.seq;
|
|
199
|
+
throw new MailboxStoreError(MAILBOX_DUPLICATE_RECORD_ID_CODE, `MailboxStore.append: the box already holds a different record under this id (it differs in: ${differs.join(", ")}) — a new message takes a new id; an identical repeat would have been a replay`);
|
|
200
|
+
}
|
|
153
201
|
export function mailboxCrossProcessMountVerdict(store) {
|
|
154
202
|
const declared = store.crossProcessSafe;
|
|
155
203
|
if (declared === true)
|
|
@@ -199,17 +247,13 @@ export class InMemoryMailboxStore {
|
|
|
199
247
|
async append(scope, handle, msg) {
|
|
200
248
|
if (scope === undefined || scope === "")
|
|
201
249
|
throw new Error("MailboxStore.append: refusing a message without a scope");
|
|
202
|
-
const
|
|
250
|
+
const record = readMailboxAppend(msg);
|
|
203
251
|
const b = this.box(scope, handle);
|
|
252
|
+
const held = judgeMailboxAppendById(b.messages, record);
|
|
253
|
+
if (held !== undefined)
|
|
254
|
+
return held;
|
|
204
255
|
const seq = b.nextSeq++;
|
|
205
|
-
b.messages.push({
|
|
206
|
-
seq,
|
|
207
|
-
...(msg.from !== undefined ? { from: msg.from } : {}),
|
|
208
|
-
content: msg.content,
|
|
209
|
-
sentAt: msg.sentAt,
|
|
210
|
-
...(msg.hopChain !== undefined ? { hopChain: [...msg.hopChain] } : {}),
|
|
211
|
-
...(peerMeta !== undefined ? { peerMeta } : {}),
|
|
212
|
-
});
|
|
256
|
+
b.messages.push({ seq, ...record });
|
|
213
257
|
return seq;
|
|
214
258
|
}
|
|
215
259
|
async claimLease(scope, handle, owner, ttlMs, now = Date.now()) {
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
/** The `_meta` key carrying the executing call's id. */
|
|
2
|
+
export declare const MCP_TOOL_USE_ID_META_KEY = "sema/toolUseId";
|
|
3
|
+
/** The `_meta` key carrying the request meta the call's `tool.call` chain handed on. */
|
|
4
|
+
export declare const MCP_REQUEST_META_KEY = "sema/requestMeta";
|
|
5
|
+
/** The most UTF-8 bytes a request meta may hold, its keys and values together (the reference's bound on its values: 262144). */
|
|
6
|
+
export declare const MCP_REQUEST_META_MAX_BYTES = 262144;
|
|
7
|
+
/** A request meta as it rides: string members only. */
|
|
8
|
+
export type McpRequestMeta = Readonly<Record<string, string>>;
|
|
9
|
+
/** A judged request meta: the copy that rides (undefined when there is none, or it has no member), or why it cannot ride. */
|
|
10
|
+
export type RequestMetaReading = {
|
|
11
|
+
readonly meta: McpRequestMeta | undefined;
|
|
12
|
+
} | {
|
|
13
|
+
readonly problem: string;
|
|
14
|
+
};
|
|
15
|
+
/**
|
|
16
|
+
* The request meta `value` stands for. It can ride when it is a plain record (the ordinary prototype, or none) whose own members
|
|
17
|
+
* are all enumerable string-keyed data properties holding strings, at most {@link MCP_REQUEST_META_MAX_BYTES} UTF-8 bytes of keys
|
|
18
|
+
* and values together; what rides is a frozen copy of those members with no prototype (an own `__proto__` key stays a key).
|
|
19
|
+
*/
|
|
20
|
+
export declare function judgeRequestMeta(value: unknown): RequestMetaReading;
|
|
21
|
+
/** The request meta a handler handed on in `payload`: its OWN `requestMeta` data member (one inherited from a prototype is not
|
|
22
|
+
* handed on, and an accessor is never run), judged by {@link judgeRequestMeta}. */
|
|
23
|
+
export declare function readHandedRequestMeta(payload: object): RequestMetaReading;
|
|
24
|
+
/** The most characters a declared session key may have. */
|
|
25
|
+
export declare const MCP_SESSION_META_KEY_MAX_CHARS = 128;
|
|
26
|
+
/** A judged session key: the key that rides (undefined when none is declared), or why it cannot. */
|
|
27
|
+
export type SessionMetaKeyReading = {
|
|
28
|
+
readonly key: string | undefined;
|
|
29
|
+
} | {
|
|
30
|
+
readonly problem: string;
|
|
31
|
+
};
|
|
32
|
+
/**
|
|
33
|
+
* The one judge of a declared `sessionMetaKey` ({@link import("./mcp-server-spec.js").McpServerSpec.sessionMetaKey}). It can ride when it is
|
|
34
|
+
* a non-empty string of at most {@link MCP_SESSION_META_KEY_MAX_CHARS} characters in the MCP `_meta` key-name format (an optional
|
|
35
|
+
* prefix of dot-separated labels and a slash, then a name — the format is what a conforming server accepts, and it keeps out names such
|
|
36
|
+
* as `__proto__` that the SDK's own request parse drops) that names no `_meta` member of anyone else's: not the SDK's `progressToken`,
|
|
37
|
+
* not a key under the engine's `sema/` namespace, not under a prefix MCP reserves (the prefix is the text before the first `/`; its
|
|
38
|
+
* labels are DNS labels, so the second one is compared with case folded). Every refusal names the key; the key is the declaration's own
|
|
39
|
+
* text, bounded in the sentence.
|
|
40
|
+
*/
|
|
41
|
+
export declare function judgeSessionMetaKey(value: unknown): SessionMetaKeyReading;
|
|
42
|
+
/**
|
|
43
|
+
* The `_meta` of one request the engine sends a server — a `tools/call` (the executing call's id, when it has one, and the request meta,
|
|
44
|
+
* when there is one: the judge answers none for a record with no member, so whatever it hands here rides) or a `resources/read` (neither) —
|
|
45
|
+
* and, when the server declared a session key, the leg's own session id under it. THE one mint: the key was judged where the declaration
|
|
46
|
+
* was ({@link judgeSessionMetaKey}), so it never lands on another member; no session id (a dial with no leg) rides nothing.
|
|
47
|
+
*/
|
|
48
|
+
export declare function mcpCallMeta(toolUseId: string | undefined, requestMeta: McpRequestMeta | undefined, sessionMetaKey?: string, sessionId?: string): Record<string, unknown> | undefined;
|
|
49
|
+
/**
|
|
50
|
+
* The carrier from a call's `tool.call` chain bottom to the MCP tool's `execute`, one per leg. A tool's `execute` takes the call id
|
|
51
|
+
* and no per-call context, so the request meta rides the body's own async chain: {@link McpRequestMetaSeat.of} answers it only to
|
|
52
|
+
* an `execute` that runs inside that body, for the same call id, on the same leg's seat, while the body has not settled. Two calls
|
|
53
|
+
* in flight (even under one id), a child leg's calls (its own seat), a direct `execute` outside any body and a timer the body left
|
|
54
|
+
* behind never read each other's.
|
|
55
|
+
*/
|
|
56
|
+
export interface McpRequestMetaSeat {
|
|
57
|
+
/** Run `body` with `meta` standing for the call `toolCallId` names, on this body's async chain; it stops standing when it settles. */
|
|
58
|
+
hold<T>(toolCallId: string, meta: McpRequestMeta | undefined, body: () => Promise<T>): Promise<T>;
|
|
59
|
+
/** What stands for the call `toolCallId` names, read from inside its body. */
|
|
60
|
+
of(toolCallId: string): McpRequestMeta | undefined;
|
|
61
|
+
/** The leg's own session id: what a server that declared a session key is sent ({@link mcpCallMeta}). Absent for a seat made without one. */
|
|
62
|
+
readonly sessionId?: string;
|
|
63
|
+
}
|
|
64
|
+
/** What the MCP materialization reads of its leg's seat: the request meta standing for a call, and the leg's session id. */
|
|
65
|
+
export type McpLegMetaReader = Pick<McpRequestMetaSeat, "of" | "sessionId">;
|
|
66
|
+
export declare function createMcpRequestMetaSeat(sessionId?: string): McpRequestMetaSeat;
|
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
import { AsyncLocalStorage } from "node:async_hooks";
|
|
2
|
+
import { types } from "node:util";
|
|
3
|
+
import { isPlainRecord } from "./mods/kernel/receive.js";
|
|
4
|
+
import { dataKind } from "./mcp-server-spec.js";
|
|
5
|
+
export const MCP_TOOL_USE_ID_META_KEY = "sema/toolUseId";
|
|
6
|
+
export const MCP_REQUEST_META_KEY = "sema/requestMeta";
|
|
7
|
+
export const MCP_REQUEST_META_MAX_BYTES = 262_144;
|
|
8
|
+
const kindOf = (v) => v === null ? "null" : Array.isArray(v) ? "a list" : typeof v === "object" ? (types.isProxy(v) ? "a Proxy" : "an object that is not a plain record") : `a ${typeof v}`;
|
|
9
|
+
const named = (key) => JSON.stringify(key.length > 60 ? `${key.slice(0, 60)}…` : key);
|
|
10
|
+
export function judgeRequestMeta(value) {
|
|
11
|
+
if (value === undefined)
|
|
12
|
+
return { meta: undefined };
|
|
13
|
+
if (typeof value === "object" && value !== null && types.isProxy(value))
|
|
14
|
+
return { problem: "requestMeta is a Proxy; it takes a plain record of strings" };
|
|
15
|
+
if (!isPlainRecord(value))
|
|
16
|
+
return { problem: `requestMeta is ${kindOf(value)}; it takes a plain record of strings` };
|
|
17
|
+
const descriptors = Object.getOwnPropertyDescriptors(value);
|
|
18
|
+
if (Object.getOwnPropertySymbols(descriptors).length > 0)
|
|
19
|
+
return { problem: "requestMeta has a symbol-keyed member; its members are string keys holding strings" };
|
|
20
|
+
const copy = Object.create(null);
|
|
21
|
+
let bytes = 0;
|
|
22
|
+
let members = 0;
|
|
23
|
+
for (const key of Object.getOwnPropertyNames(descriptors)) {
|
|
24
|
+
const d = descriptors[key];
|
|
25
|
+
if (!Object.hasOwn(d, "value") || d.enumerable !== true)
|
|
26
|
+
return { problem: `requestMeta's member ${named(key)} is not an enumerable data property (a getter is never run)` };
|
|
27
|
+
const v = d.value;
|
|
28
|
+
if (typeof v !== "string")
|
|
29
|
+
return { problem: `requestMeta's member ${named(key)} is ${kindOf(v)}, not a string` };
|
|
30
|
+
bytes += Buffer.byteLength(key, "utf8") + Buffer.byteLength(v, "utf8");
|
|
31
|
+
Object.defineProperty(copy, key, { value: v, enumerable: true, writable: false, configurable: false });
|
|
32
|
+
members += 1;
|
|
33
|
+
}
|
|
34
|
+
if (bytes > MCP_REQUEST_META_MAX_BYTES)
|
|
35
|
+
return { problem: `requestMeta is ${bytes} bytes of keys and values; the most is ${MCP_REQUEST_META_MAX_BYTES}` };
|
|
36
|
+
return { meta: members === 0 ? undefined : Object.freeze(copy) };
|
|
37
|
+
}
|
|
38
|
+
export function readHandedRequestMeta(payload) {
|
|
39
|
+
const d = Object.getOwnPropertyDescriptor(payload, "requestMeta");
|
|
40
|
+
if (d === undefined)
|
|
41
|
+
return { meta: undefined };
|
|
42
|
+
if (!Object.hasOwn(d, "value"))
|
|
43
|
+
return { problem: "requestMeta is an accessor (a getter is never run); it takes a plain record of strings" };
|
|
44
|
+
return judgeRequestMeta(d.value);
|
|
45
|
+
}
|
|
46
|
+
const SDK_PROGRESS_TOKEN_KEY = "progressToken";
|
|
47
|
+
const ENGINE_META_NAMESPACE = "sema/";
|
|
48
|
+
export const MCP_SESSION_META_KEY_MAX_CHARS = 128;
|
|
49
|
+
const MCP_RESERVED_LABELS = ["modelcontextprotocol", "mcp"];
|
|
50
|
+
const META_LABEL = /^[A-Za-z](?:[A-Za-z0-9-]*[A-Za-z0-9])?$/;
|
|
51
|
+
const META_NAME = /^(?:[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?)?$/;
|
|
52
|
+
export function judgeSessionMetaKey(value) {
|
|
53
|
+
if (value === undefined)
|
|
54
|
+
return { key: undefined };
|
|
55
|
+
if (typeof value !== "string")
|
|
56
|
+
return { problem: `sessionMetaKey is ${dataKind(value)}; it takes a non-empty string` };
|
|
57
|
+
if (value === "")
|
|
58
|
+
return { problem: "sessionMetaKey is the empty string; it takes a non-empty string" };
|
|
59
|
+
if (value.length > MCP_SESSION_META_KEY_MAX_CHARS)
|
|
60
|
+
return { problem: `sessionMetaKey ${named(value)} is ${value.length} characters; the most is ${MCP_SESSION_META_KEY_MAX_CHARS}` };
|
|
61
|
+
const slash = value.indexOf("/");
|
|
62
|
+
const labels = slash === -1 ? [] : value.slice(0, slash).split(".");
|
|
63
|
+
if (!labels.every((label) => META_LABEL.test(label)))
|
|
64
|
+
return { problem: `sessionMetaKey ${named(value)} has a prefix that is not dot-separated labels (a label starts with a letter, ends with a letter or digit, and holds letters, digits and hyphens) followed by a slash` };
|
|
65
|
+
if (!META_NAME.test(value.slice(slash + 1)))
|
|
66
|
+
return { problem: `sessionMetaKey ${named(value)} has a name that does not begin and end with a letter or digit, or holds a character other than letters, digits, hyphen, underscore and dot` };
|
|
67
|
+
if (value === SDK_PROGRESS_TOKEN_KEY)
|
|
68
|
+
return { problem: `sessionMetaKey ${named(value)} is the key the MCP SDK writes for its own progress token` };
|
|
69
|
+
if (value.startsWith(ENGINE_META_NAMESPACE))
|
|
70
|
+
return { problem: `sessionMetaKey ${named(value)} is under the engine's own "${ENGINE_META_NAMESPACE}" namespace` };
|
|
71
|
+
const second = labels[1]?.toLowerCase();
|
|
72
|
+
if (second !== undefined && MCP_RESERVED_LABELS.includes(second))
|
|
73
|
+
return { problem: `sessionMetaKey ${named(value)} is under a prefix MCP reserves (second label "${second}")` };
|
|
74
|
+
return { key: value };
|
|
75
|
+
}
|
|
76
|
+
export function mcpCallMeta(toolUseId, requestMeta, sessionMetaKey, sessionId) {
|
|
77
|
+
const meta = {
|
|
78
|
+
...(typeof toolUseId === "string" && toolUseId !== "" ? { [MCP_TOOL_USE_ID_META_KEY]: toolUseId } : {}),
|
|
79
|
+
...(requestMeta !== undefined ? { [MCP_REQUEST_META_KEY]: requestMeta } : {}),
|
|
80
|
+
...(sessionMetaKey !== undefined && typeof sessionId === "string" && sessionId !== "" ? { [sessionMetaKey]: sessionId } : {}),
|
|
81
|
+
};
|
|
82
|
+
return Object.keys(meta).length === 0 ? undefined : meta;
|
|
83
|
+
}
|
|
84
|
+
const store = new AsyncLocalStorage();
|
|
85
|
+
export function createMcpRequestMetaSeat(sessionId) {
|
|
86
|
+
const seat = {};
|
|
87
|
+
return {
|
|
88
|
+
sessionId,
|
|
89
|
+
async hold(toolCallId, meta, body) {
|
|
90
|
+
const held = { seat, toolCallId, meta, live: true };
|
|
91
|
+
try {
|
|
92
|
+
return await store.run(held, body);
|
|
93
|
+
}
|
|
94
|
+
finally {
|
|
95
|
+
held.live = false;
|
|
96
|
+
}
|
|
97
|
+
},
|
|
98
|
+
of(toolCallId) {
|
|
99
|
+
const held = store.getStore();
|
|
100
|
+
return held !== undefined && held.live && held.seat === seat && held.toolCallId === toolCallId ? held.meta : undefined;
|
|
101
|
+
},
|
|
102
|
+
};
|
|
103
|
+
}
|
|
@@ -14,7 +14,9 @@
|
|
|
14
14
|
* a revived one), so the DECLARATION stays the one source of truth — no handle is ever recorded anywhere.
|
|
15
15
|
*
|
|
16
16
|
* THE KEY is the server's declaration as the dial reads it (name and transport) and the principal the task runs under: a
|
|
17
|
-
* different principal is a different identity at the server.
|
|
17
|
+
* different principal is a different identity at the server. The transport holds no value (a declaration carries at most an
|
|
18
|
+
* opaque credential reference, so two references that differ never share a connection); the pieces a request carries are the
|
|
19
|
+
* peer seat's, asked under this same identity, so every holder of a connection sends what the one seat answers for it. A server that opted in to elicitation never enters the pool — the
|
|
18
20
|
* answer to its questions belongs to the leg that is waiting on it.
|
|
19
21
|
*/
|
|
20
22
|
import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { canonicalize } from "./canonical-json.js";
|
|
2
2
|
import { ConnectionListing } from "./mcp-server-link.js";
|
|
3
|
+
import { carrierOf } from "./peer-seat.js";
|
|
3
4
|
export class McpConnectionPool {
|
|
4
5
|
entries = new Map();
|
|
5
6
|
dialing = new Map();
|
|
@@ -19,7 +20,8 @@ export class McpConnectionPool {
|
|
|
19
20
|
if (this.shut)
|
|
20
21
|
return undefined;
|
|
21
22
|
opts?.signal?.throwIfAborted();
|
|
22
|
-
|
|
23
|
+
const held = this.entries.get(key);
|
|
24
|
+
if (opts?.fresh === true || (held !== undefined && carrierOf(held.client)?.expired() === true))
|
|
23
25
|
this.detach(key);
|
|
24
26
|
let entry = this.entries.get(key);
|
|
25
27
|
if (entry === undefined || entry.closed) {
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import type { AssertAllKeysHandled } from "./ask-origin.js";
|
|
2
|
+
import type { AnnouncedMcpFailure } from "../internal/harness.js";
|
|
2
3
|
/**
|
|
3
4
|
* The closed set of failure classes ({@link McpFailure.kind}):
|
|
4
5
|
* · `connect_refused` — a connect-phase errno (ECONNREFUSED / ENOTFOUND / EAI_AGAIN / EHOSTUNREACH /
|
|
@@ -9,8 +10,14 @@ import type { AssertAllKeysHandled } from "./ask-origin.js";
|
|
|
9
10
|
* · `connection_closed` — the SDK reported the transport closed (`McpError` `ConnectionClosed`): in
|
|
10
11
|
* flight the fate is unknowable, and for a server already known dead the
|
|
11
12
|
* request was never attempted — the two are told apart by `delivered`;
|
|
12
|
-
* · `
|
|
13
|
-
* (
|
|
13
|
+
* · `unauthorized` — the principal must authorize this server before it serves them: the endpoint
|
|
14
|
+
* answered 401 (after the peer seat was asked once more), or 403 whose
|
|
15
|
+
* challenge says `insufficient_scope`, or the deployment's peer seat answered
|
|
16
|
+
* that the principal is not authorized here. `authorization` carries which
|
|
17
|
+
* ({@link McpAuthorization}); the next step is the user's, not an outage's;
|
|
18
|
+
* · `http_status` — the HTTP endpoint answered with any other status instead of an MCP response
|
|
19
|
+
* (`httpStatus` carries the number: 5xx = down, a 403 without a scope
|
|
20
|
+
* challenge = refused by policy);
|
|
14
21
|
* · `not_mcp_response` — the HTTP endpoint answered something that is not an MCP payload and no status;
|
|
15
22
|
* · `spawn_failed` — a stdio server process could not be started (a missing/unexecutable command);
|
|
16
23
|
* · `timeout` — the request timed out (the SDK's per-call timer, the total ceiling, or the
|
|
@@ -19,10 +26,41 @@ import type { AssertAllKeysHandled } from "./ask-origin.js";
|
|
|
19
26
|
* capability, an ordinary `-32603`): the exchange happened;
|
|
20
27
|
* · `invalid_config` — the declaration itself could not be dialed (a malformed `url`): a fault to
|
|
21
28
|
* fix in the spec, never an outage to wait out;
|
|
29
|
+
* · `credential_unavailable` — the deployment's peer seat did not furnish the request (it threw, did not
|
|
30
|
+
* answer in time, or answered something the engine cannot carry): that request
|
|
31
|
+
* was not sent — a fault for the deployment to fix, not an outage of the server;
|
|
22
32
|
* · `unknown` — the thrown value carried no structure this table reads.
|
|
23
33
|
*/
|
|
24
|
-
export declare const MCP_FAILURE_KINDS: readonly ["connect_refused", "connection_failed", "connection_closed", "http_status", "not_mcp_response", "spawn_failed", "timeout", "protocol", "invalid_config", "unknown"];
|
|
34
|
+
export declare const MCP_FAILURE_KINDS: readonly ["connect_refused", "connection_failed", "connection_closed", "unauthorized", "http_status", "not_mcp_response", "spawn_failed", "timeout", "protocol", "invalid_config", "credential_unavailable", "unknown"];
|
|
25
35
|
export type McpFailureKind = (typeof MCP_FAILURE_KINDS)[number];
|
|
36
|
+
/**
|
|
37
|
+
* Why a server is `unauthorized` ({@link McpAuthorization.reason}), closed:
|
|
38
|
+
* · `rejected` — the HTTP endpoint answered 401: the request's credential (or its absence) was refused, and asking the peer seat once
|
|
39
|
+
* more did not answer a credential that passed;
|
|
40
|
+
* · `scope` — the HTTP endpoint answered 403 with a Bearer challenge whose `error` is `insufficient_scope` (RFC 6750 §3.1): the
|
|
41
|
+
* credential is good and does not cover this request;
|
|
42
|
+
* · `none` — the deployment's peer seat answered `unauthorized`: it holds no credential for this principal and this server, so
|
|
43
|
+
* nothing was sent.
|
|
44
|
+
*/
|
|
45
|
+
export declare const MCP_AUTHORIZATION_REASONS: readonly ["rejected", "scope", "none"];
|
|
46
|
+
export type McpAuthorizationReason = (typeof MCP_AUTHORIZATION_REASONS)[number];
|
|
47
|
+
/**
|
|
48
|
+
* The authorization fact an `unauthorized` failure carries — one record, read whole by every face (the status record, the wiring
|
|
49
|
+
* manifest row, the thrown request error's `details`, the `mcp.authorization_required` notice, the model's needs-authorization line).
|
|
50
|
+
* The two URLs are separate members because their trust differs:
|
|
51
|
+
* · `authorizeUrl` comes ONLY from the deployment's peer seat (its `unauthorized` answer, to the send or to the re-ask after a 401) —
|
|
52
|
+
* TRUSTED; the engine never makes one up;
|
|
53
|
+
* · `resourceMetadataUrl` comes ONLY from the endpoint's own `WWW-Authenticate` challenge (`resource_metadata`, RFC 9728) — the
|
|
54
|
+
* REMOTE's claim, UNTRUSTED, and never rendered to the model by the engine.
|
|
55
|
+
* Both are read by one URL law at the point they arrive (`authorizationUrlOf`, peer-seat.ts): an absolute http(s) URL within
|
|
56
|
+
* {@link import("./peer-seat.js").AUTHORIZATION_URL_MAX} code units, kept as the URL parser serializes it (percent-encoded: no
|
|
57
|
+
* whitespace, no markup); the seat's URL that breaks the law refuses its answer, the remote's is dropped.
|
|
58
|
+
*/
|
|
59
|
+
export interface McpAuthorization {
|
|
60
|
+
reason: McpAuthorizationReason;
|
|
61
|
+
authorizeUrl?: string;
|
|
62
|
+
resourceMetadataUrl?: string;
|
|
63
|
+
}
|
|
26
64
|
/** The closed set of delivery verdicts ({@link McpFailure.delivered}). */
|
|
27
65
|
export declare const MCP_DELIVERY_VERDICTS: readonly ["yes", "no", "unknown"];
|
|
28
66
|
export type McpDelivered = (typeof MCP_DELIVERY_VERDICTS)[number];
|
|
@@ -37,12 +75,14 @@ export declare const DELIVERED_BY_KIND: {
|
|
|
37
75
|
readonly connect_refused: "no";
|
|
38
76
|
readonly connection_failed: "unknown";
|
|
39
77
|
readonly connection_closed: "unknown";
|
|
78
|
+
readonly unauthorized: "unknown";
|
|
40
79
|
readonly http_status: "unknown";
|
|
41
80
|
readonly not_mcp_response: "unknown";
|
|
42
81
|
readonly spawn_failed: "no";
|
|
43
82
|
readonly timeout: "unknown";
|
|
44
83
|
readonly protocol: "yes";
|
|
45
84
|
readonly invalid_config: "no";
|
|
85
|
+
readonly credential_unavailable: "no";
|
|
46
86
|
readonly unknown: "unknown";
|
|
47
87
|
};
|
|
48
88
|
/** The fence over the delivery table: `never` while every kind has a verdict. */
|
|
@@ -98,27 +138,30 @@ export declare const LIVENESS_BY_FAILURE_KIND: {
|
|
|
98
138
|
readonly connect_refused: "unreachable";
|
|
99
139
|
readonly connection_failed: "unreachable";
|
|
100
140
|
readonly connection_closed: "unreachable";
|
|
141
|
+
readonly unauthorized: "unknown";
|
|
101
142
|
readonly http_status: "unknown";
|
|
102
143
|
readonly not_mcp_response: "unknown";
|
|
103
144
|
readonly spawn_failed: "unreachable";
|
|
104
145
|
readonly timeout: "unreachable";
|
|
105
146
|
readonly protocol: "reachable";
|
|
106
147
|
readonly invalid_config: undefined;
|
|
148
|
+
readonly credential_unavailable: undefined;
|
|
107
149
|
readonly unknown: "unknown";
|
|
108
150
|
};
|
|
109
151
|
/** The fence over the liveness table: `never` while every kind has a verdict. */
|
|
110
152
|
export type LivenessTableCoversEveryMcpFailureKind = AssertAllKeysHandled<Exclude<McpFailureKind, keyof typeof LIVENESS_BY_FAILURE_KIND>>;
|
|
111
153
|
/**
|
|
112
|
-
* What ONE exchange with a server tells the liveness record: the CLASS of the failure it ended in,
|
|
113
|
-
* `"completed"` when it finished
|
|
114
|
-
*
|
|
115
|
-
*
|
|
154
|
+
* What ONE exchange with a server tells the liveness record: the CLASS of the failure it ended in,
|
|
155
|
+
* `"completed"` when it finished, or `"unsent"` when the engine's own seat refused to send it (nothing
|
|
156
|
+
* was attempted, whatever the class — see {@link readMcpFailure}). Every round trip the engine makes — a
|
|
157
|
+
* dial, a tool call, a resource read, a listing, a refresh — reports exactly this, so the engine needs no
|
|
158
|
+
* second vocabulary and no per-site judgment about which failures "count".
|
|
116
159
|
*/
|
|
117
|
-
export type McpExchangeOutcome = McpFailureKind | "completed";
|
|
160
|
+
export type McpExchangeOutcome = McpFailureKind | "completed" | "unsent";
|
|
118
161
|
/** The liveness observation an exchange supports, or `undefined` when the outcome is not an observation
|
|
119
|
-
* at all (see {@link LIVENESS_BY_FAILURE_KIND}: a declaration that could never be dialed
|
|
120
|
-
* mint of the record — no two sites can disagree about the word, about
|
|
121
|
-
* `errorCode`, or about what a completed exchange proves. */
|
|
162
|
+
* at all (see {@link LIVENESS_BY_FAILURE_KIND}: a declaration that could never be dialed; a request the
|
|
163
|
+
* engine never sent). THE single mint of the record — no two sites can disagree about the word, about
|
|
164
|
+
* which words may carry `errorCode`, or about what a completed exchange proves. */
|
|
122
165
|
export declare function livenessOf(outcome: McpExchangeOutcome, observedAt: number): McpServerLiveness | undefined;
|
|
123
166
|
/** A request over an established connection; `session` when the request carried the session id the server issued at the handshake. */
|
|
124
167
|
export type McpRequestSite = {
|
|
@@ -133,7 +176,7 @@ export type McpFailureSite = {
|
|
|
133
176
|
} | McpRequestSite;
|
|
134
177
|
/**
|
|
135
178
|
* The one MCP failure record. Both fields are always present; `httpStatus` rides only with
|
|
136
|
-
* `kind === "http_status"`.
|
|
179
|
+
* `kind === "http_status"`, `authorization` only with `kind === "unauthorized"`.
|
|
137
180
|
*/
|
|
138
181
|
export interface McpFailure {
|
|
139
182
|
/**
|
|
@@ -165,7 +208,23 @@ export interface McpFailure {
|
|
|
165
208
|
delivered: McpDelivered;
|
|
166
209
|
/** The HTTP status the endpoint answered with; present iff `kind === "http_status"`. */
|
|
167
210
|
httpStatus?: number;
|
|
211
|
+
/** @contract mcp.failure.authorization — why the principal must authorize, and where ({@link McpAuthorization}); present iff
|
|
212
|
+
* `kind === "unauthorized"`. */
|
|
213
|
+
authorization?: McpAuthorization;
|
|
214
|
+
}
|
|
215
|
+
/**
|
|
216
|
+
* The failure record as a row carries it, spread flat: {@link McpFailure.kind} as `errorCode` beside `delivered`, and the class's own
|
|
217
|
+
* members (`httpStatus`, `authorization`). Every row that carries the record — the per-server status, the wiring manifest's `mcp[]`
|
|
218
|
+
* row — is written by {@link failureFields}, so a member the record gains rides every row without a second spelling.
|
|
219
|
+
*/
|
|
220
|
+
export interface McpFailureFields {
|
|
221
|
+
errorCode: McpFailureKind;
|
|
222
|
+
delivered: McpDelivered;
|
|
223
|
+
httpStatus?: number;
|
|
224
|
+
authorization?: McpAuthorization;
|
|
168
225
|
}
|
|
226
|
+
/** {@link McpFailureFields} of a record, or of a row that already carries them (`errorCode` absent ⇒ none) — fresh objects, never aliased. */
|
|
227
|
+
export declare function failureFields(of: McpFailure | Partial<McpFailureFields>): Partial<McpFailureFields>;
|
|
169
228
|
/**
|
|
170
229
|
* The first errno-shaped / undici-shaped `code` on an error's cause chain (`E[A-Z_]+`, `UND_ERR_*`,
|
|
171
230
|
* Node's `ERR_*`). `fetch` reports every network failure as a bare `TypeError: fetch failed` with the
|
|
@@ -174,12 +233,16 @@ export interface McpFailure {
|
|
|
174
233
|
* DNS-temporary-failure errno is literally `EAI_AGAIN`.
|
|
175
234
|
*/
|
|
176
235
|
export declare function networkErrorCode(err: unknown, depth?: number): string | undefined;
|
|
177
|
-
/** What a row reads OFF the thrown value: the failure's class,
|
|
178
|
-
*
|
|
179
|
-
*
|
|
236
|
+
/** What a row reads OFF the thrown value: the failure's class, the status the `http_status` class carries, the authorization fact
|
|
237
|
+
* the `unauthorized` class carries, and `unsent` — the thrown value is the engine's OWN refusal to send (the peer seat did not
|
|
238
|
+
* furnish the request: {@link PeerSeatFailure}), a structural fact about our side of the exchange that makes the verdict `"no"`
|
|
239
|
+
* whatever the class. A row does NOT write the delivery verdict — that follows from the kind, `unsent` and the SITE, in one place
|
|
240
|
+
* ({@link DELIVERED_BY_KIND} + {@link classifyMcpFailure}), so a row cannot spell it wrong. */
|
|
180
241
|
export type McpFailureClass = {
|
|
181
242
|
kind: McpFailureKind;
|
|
182
243
|
httpStatus?: number;
|
|
244
|
+
authorization?: McpAuthorization;
|
|
245
|
+
unsent?: true;
|
|
183
246
|
};
|
|
184
247
|
/** One row of the classifier: `when` reads structure only; `reads` names the class it saw. */
|
|
185
248
|
export interface McpFailureRule {
|
|
@@ -203,6 +266,45 @@ export declare const FAILURE_CLASSIFIER: ReadonlyArray<McpFailureRule>;
|
|
|
203
266
|
* Total: every input maps to a record.
|
|
204
267
|
*/
|
|
205
268
|
export declare function classifyMcpFailure(err: unknown, at: McpFailureSite): McpFailure;
|
|
269
|
+
/**
|
|
270
|
+
* One failure, read once: the record ({@link classifyMcpFailure}) and what the exchange tells the liveness record
|
|
271
|
+
* ({@link McpExchangeOutcome} — `"unsent"` for the engine's own refusal to send, else the class). A refusal of our own is `"no"` at every
|
|
272
|
+
* site and is no observation about the server; at the dial every other class but those minted from an answer is `"no"`
|
|
273
|
+
* ({@link CONNECT_KEEPS_THE_TABLE_VERDICT}); elsewhere the table says.
|
|
274
|
+
*/
|
|
275
|
+
export declare function readMcpFailure(err: unknown, at: McpFailureSite): {
|
|
276
|
+
failure: McpFailure;
|
|
277
|
+
exchange: McpExchangeOutcome;
|
|
278
|
+
};
|
|
279
|
+
/**
|
|
280
|
+
* A failed server as the `mcp_unavailable` frame tells it: the session's told-record identity pair (`name`, `error` — the ledger judges
|
|
281
|
+
* telling by the pair, announce-once-ledger.ts) and, for an `unauthorized` failure, the record's own `authorization` — what the frame's
|
|
282
|
+
* needs-authorization arm renders. The told record keeps the pair only (`settleMcpUnavailable`): the pair already differs when the
|
|
283
|
+
* failure does.
|
|
284
|
+
*/
|
|
285
|
+
export interface McpUnavailableEntry extends AnnouncedMcpFailure {
|
|
286
|
+
authorization?: McpAuthorization;
|
|
287
|
+
}
|
|
288
|
+
/** Where the user authorizes, as every model-facing line names it: the seat's URL, or the deployment's connector settings. */
|
|
289
|
+
export declare function whereToAuthorize(authorizeUrl: string | undefined): string;
|
|
290
|
+
/**
|
|
291
|
+
* The `mcp_unavailable` frame's needs-authorization arm — the servers among `entries` whose failure record carries `authorization`, or
|
|
292
|
+
* `undefined` when there are none. CC 2.1.309's arm, minted as `needsAuthMcpServers` (cli309.js:265582), read back as `needsAuthMcpServers` (cli309.js:267398),
|
|
293
|
+
* worded (cli309.js:267399) "The following MCP servers require authentication before their tools can be used" — ahead of the
|
|
294
|
+
* failed-to-connect arm; this engine never runs an authorization flow itself, so it is always the reference's cannot-start-the-flow form.
|
|
295
|
+
* `<where>` is the deployment seat's `authorizeUrl` when it gave one (listed beside the server), else the connector settings; no error
|
|
296
|
+
* text rides it (the fact is the record's). At most `max` servers are named, the rest counted.
|
|
297
|
+
*/
|
|
298
|
+
export declare function needsAuthorizationArm(entries: readonly McpUnavailableEntry[], max: number): string | undefined;
|
|
299
|
+
/**
|
|
300
|
+
* The model's line for a request refused as `unauthorized` — the call-time twin of the needs-authorization arm the `mcp_unavailable`
|
|
301
|
+
* frame carries for a server that could not mount (turn-attachments.ts): who must act (the user), where ({@link whereToAuthorize}: the
|
|
302
|
+
* seat's URL only), what not to ask for, and the delivery tail (`writeTail`, the caller's write-class sentence) the verdict owes. A 401
|
|
303
|
+
* after which the deployment answered another credential that no request has carried yet (`renewed`: the first attempt, not sent again)
|
|
304
|
+
* may pass on a new call: the line says so, and that only a refusal of that call too is the user's — a seat that answers a fresh
|
|
305
|
+
* credential every time still reaches the user. A re-send refused again is the plain line.
|
|
306
|
+
*/
|
|
307
|
+
export declare function unauthorizedLine(what: string, serverLabel: string, a: McpAuthorization, renewed: boolean, writeTail: string): string;
|
|
206
308
|
/**
|
|
207
309
|
* What a transport-level HTTP failure can be said to be, in words for a model-facing line: the
|
|
208
310
|
* condition to name, and the delivery verdict. `undefined` for every failure that is NOT of the HTTP
|