@sema-agent/core 7.56.0 → 7.58.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 +926 -0
- package/LICENSE +1 -1
- package/dist/agents/org-delivery-gate.js +3 -4
- package/dist/agents/peer-held-queue.d.ts +69 -49
- package/dist/agents/peer-held-queue.js +255 -106
- package/dist/agents/peer-session-drain.js +63 -43
- package/dist/agents/send-message-tool.js +3 -2
- package/dist/agents/subagent-steps.js +2 -4
- package/dist/agents/subagent.js +8 -8
- package/dist/brain/anthropic.js +16 -8
- package/dist/brain/open-responses.js +10 -8
- package/dist/brain/openai.js +11 -9
- package/dist/brain/provider-dialect.d.ts +3 -2
- package/dist/brain/provider-dialect.js +2 -2
- package/dist/brain/request-params.d.ts +6 -0
- package/dist/brain/request-params.js +14 -1
- package/dist/brain/route-adjudicator.js +2 -1
- package/dist/brain/stream-engine.d.ts +9 -0
- package/dist/brain/stream-engine.js +24 -10
- package/dist/brain/stream-shared.d.ts +5 -4
- package/dist/brain/stream-shared.js +4 -4
- package/dist/core/a2a.d.ts +2 -1
- package/dist/core/a2a.js +23 -10
- package/dist/core/allow-entry.d.ts +5 -11
- package/dist/core/allow-entry.js +19 -26
- package/dist/core/approval-object.d.ts +21 -5
- package/dist/core/approval-object.js +44 -17
- package/dist/core/ask-origin.d.ts +23 -4
- package/dist/core/ask-origin.js +5 -1
- package/dist/core/auto-compaction.d.ts +75 -6
- package/dist/core/auto-compaction.js +43 -27
- 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 +6 -2
- package/dist/core/background-agent-store.js +1 -1
- package/dist/core/checkpoint-requirements.d.ts +13 -1
- package/dist/core/checkpoint-requirements.js +4 -0
- package/dist/core/checkpoint-store.d.ts +44 -40
- package/dist/core/checkpoint-store.js +32 -14
- package/dist/core/cross-boundary-taint.js +4 -2
- package/dist/core/engine-notice.d.ts +4 -3
- package/dist/core/engine-notice.js +6 -0
- package/dist/core/file-history-store.d.ts +14 -8
- package/dist/core/file-history-store.js +14 -4
- 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 +6 -3
- package/dist/core/gate-lanes.js +13 -5
- package/dist/core/git-worktree-env.d.ts +53 -11
- package/dist/core/git-worktree-env.js +96 -12
- package/dist/core/hooks.d.ts +6 -3
- package/dist/core/hooks.js +12 -5
- package/dist/core/human-input-projection.d.ts +1 -0
- package/dist/core/human-input-projection.js +3 -0
- package/dist/core/locked-config.d.ts +15 -1
- package/dist/core/locked-config.js +38 -2
- package/dist/core/mailbox-store.d.ts +62 -1
- package/dist/core/mailbox-store.js +59 -0
- 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 +7 -1
- package/dist/core/mcp-failure.js +10 -0
- package/dist/core/mcp-name-judge.d.ts +46 -0
- package/dist/core/mcp-name-judge.js +61 -0
- package/dist/core/mcp-probe.d.ts +5 -1
- package/dist/core/mcp-probe.js +3 -6
- package/dist/core/mcp-server-link.d.ts +5 -2
- 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 +6 -14
- package/dist/core/mcp.js +85 -65
- package/dist/core/memory-engine/consolidation-driver.js +4 -3
- package/dist/core/memory-engine/distiller.js +26 -17
- package/dist/core/memory-engine/layout.js +5 -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/mode-policy.d.ts +8 -5
- package/dist/core/mode-policy.js +5 -4
- 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 +10 -8
- package/dist/core/mods/kernel/events.d.ts +5 -1
- package/dist/core/mods/kernel/events.js +1 -1
- package/dist/core/mods/kernel/registration.d.ts +5 -1
- 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 +2 -2
- package/dist/core/mods/stations.js +1 -1
- package/dist/core/mods/tool-call.d.ts +5 -1
- package/dist/core/mods/tool-call.js +12 -3
- package/dist/core/park-selfcheck.js +2 -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 +186 -0
- package/dist/core/peer-seat.js +307 -0
- package/dist/core/permission-rule-consent.d.ts +5 -3
- package/dist/core/permission-rule-consent.js +20 -15
- package/dist/core/permission-rule-model.d.ts +43 -2
- package/dist/core/permission-rule-model.js +52 -8
- package/dist/core/permission-rule-org.js +1 -1
- package/dist/core/present-plan-tool.d.ts +10 -1
- package/dist/core/present-plan-tool.js +46 -2
- package/dist/core/protocol-http-auth.d.ts +56 -31
- package/dist/core/protocol-http-auth.js +71 -42
- package/dist/core/protocol-naming.d.ts +20 -0
- package/dist/core/protocol-naming.js +20 -3
- package/dist/core/read-only-shell.d.ts +20 -5
- package/dist/core/read-only-shell.js +29 -14
- 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/remote-env.d.ts +37 -1
- package/dist/core/remote-env.js +11 -0
- package/dist/core/resume-startup-cause.d.ts +24 -2
- package/dist/core/resume-startup-cause.js +20 -1
- package/dist/core/retention.d.ts +41 -15
- package/dist/core/retention.js +59 -12
- package/dist/core/rewrite-rejudge.d.ts +37 -0
- package/dist/core/rewrite-rejudge.js +40 -0
- package/dist/core/roles.js +50 -7
- 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/compact-session.d.ts +10 -0
- package/dist/core/runner/compact-session.js +202 -0
- package/dist/core/runner/compaction-call-options.d.ts +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/compaction-seams.d.ts +21 -1
- package/dist/core/runner/compaction-seams.js +11 -8
- package/dist/core/runner/contracts.d.ts +36 -21
- package/dist/core/runner/derived-route-fallback.d.ts +13 -0
- package/dist/core/runner/derived-route-fallback.js +6 -0
- package/dist/core/runner/env-capability-census.d.ts +3 -2
- package/dist/core/runner/env-capability-census.js +9 -3
- package/dist/core/runner/gate-exit.d.ts +18 -4
- package/dist/core/runner/gate-exit.js +5 -1
- package/dist/core/runner/permission-rule-lanes.d.ts +7 -7
- package/dist/core/runner/permission-rule-lanes.js +17 -11
- package/dist/core/runner/prepare-acquire-reconcile.d.ts +3 -0
- package/dist/core/runner/prepare-acquire-reconcile.js +2 -1
- package/dist/core/runner/prepare-caps-and-workflow.d.ts +2 -0
- package/dist/core/runner/prepare-caps-and-workflow.js +1 -1
- package/dist/core/runner/prepare-config-doors.d.ts +14 -5
- package/dist/core/runner/prepare-config-doors.js +16 -13
- package/dist/core/runner/prepare-delegation-surface.d.ts +4 -0
- package/dist/core/runner/prepare-delegation-surface.js +15 -18
- package/dist/core/runner/prepare-gate-stations.js +1 -1
- package/dist/core/runner/prepare-hands-readface.d.ts +10 -4
- package/dist/core/runner/prepare-hands-readface.js +6 -1
- package/dist/core/runner/prepare-memory.d.ts +3 -0
- package/dist/core/runner/prepare-memory.js +19 -23
- package/dist/core/runner/prepare-park-ask.d.ts +2 -0
- package/dist/core/runner/prepare-park-ask.js +2 -2
- package/dist/core/runner/prepare-policy-chain.d.ts +4 -4
- package/dist/core/runner/prepare-policy-chain.js +4 -6
- package/dist/core/runner/prepare-protocol-tools.d.ts +4 -2
- package/dist/core/runner/prepare-protocol-tools.js +3 -3
- 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.d.ts +4 -1
- package/dist/core/runner/prepare-task.js +46 -37
- package/dist/core/runner/prepare-tool-disclosure-mount.d.ts +13 -0
- package/dist/core/runner/prepare-tool-disclosure-mount.js +13 -7
- package/dist/core/runner/prepare-wiring-manifest.d.ts +1 -0
- package/dist/core/runner/prepare-wiring-manifest.js +2 -2
- 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/resume-admission.js +1 -1
- package/dist/core/runner/resume-checkpoint-screen.js +2 -0
- package/dist/core/runner/rewind-files.d.ts +2 -5
- package/dist/core/runner/rewind-files.js +9 -51
- 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.js +1 -0
- package/dist/core/runner/run-leg.js +15 -22
- package/dist/core/runner/run-notification-lane.d.ts +2 -0
- package/dist/core/runner/run-notification-lane.js +5 -2
- package/dist/core/runner/run-recovery-lanes.js +3 -4
- package/dist/core/runner/run-settle-and-teardown.js +5 -11
- package/dist/core/runner/run-terminal-adoption.js +3 -4
- package/dist/core/runner/run-turn-boundary.js +3 -5
- package/dist/core/runner/runtask.d.ts +8 -1
- package/dist/core/runner/runtask.js +28 -34
- package/dist/core/runner/send-message-continuation.js +1 -1
- package/dist/core/runner/session-verb-doors.d.ts +28 -0
- package/dist/core/runner/session-verb-doors.js +48 -0
- package/dist/core/runner/session-write-ledger.d.ts +30 -0
- package/dist/core/runner/session-write-ledger.js +101 -0
- package/dist/core/runner/stream-settle-backstop.js +11 -14
- package/dist/core/runner/sub-agent-deny-lists.d.ts +25 -3
- package/dist/core/runner/sub-agent-deny-lists.js +21 -10
- package/dist/core/runner/teardown-bounded.d.ts +1 -0
- package/dist/core/runner/teardown-bounded.js +1 -0
- package/dist/core/runner/terminal-account.js +3 -3
- package/dist/core/runner/tool-end-body.js +1 -0
- package/dist/core/runner/tool-occurrence.d.ts +4 -1
- package/dist/core/runner/tool-occurrence.js +2 -1
- 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 +4 -4
- package/dist/core/secret-env.d.ts +4 -0
- package/dist/core/secret-env.js +3 -0
- package/dist/core/sensitive-path-policy.js +6 -7
- 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 +7 -2
- package/dist/core/session-policy-store.js +1 -1
- package/dist/core/session-store.d.ts +84 -19
- 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/shell-wrapper-projection.d.ts +1 -1
- 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 +1 -0
- package/dist/core/store-contracts/checkpoint-store-contract.js +19 -1
- package/dist/core/store-contracts/file-history-store-contract.js +9 -0
- package/dist/core/store-contracts/mailbox-store-contract.js +49 -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/task-event.d.ts +68 -8
- package/dist/core/task-registry-agent.d.ts +8 -4
- package/dist/core/task-registry-agent.js +14 -8
- package/dist/core/task-registry-shared.d.ts +36 -6
- package/dist/core/task-registry-shared.js +11 -0
- package/dist/core/task-registry.d.ts +1 -1
- package/dist/core/task-registry.js +1 -1
- package/dist/core/task-spec.d.ts +37 -0
- package/dist/core/task-stream.d.ts +2 -1
- package/dist/core/terminal-cause.d.ts +1 -1
- package/dist/core/tool-catalog-entries.d.ts +6 -0
- package/dist/core/tool-catalog-entries.js +2 -0
- package/dist/core/tool-name-aliases.d.ts +32 -2
- package/dist/core/tool-name-aliases.js +23 -0
- package/dist/core/tool-name-readings.d.ts +4 -0
- package/dist/core/tool-name-readings.js +1 -0
- package/dist/core/tool-policy.d.ts +10 -6
- package/dist/core/tool-policy.js +4 -7
- package/dist/core/tool-result-store.d.ts +17 -10
- package/dist/core/tool-result-store.js +3 -1
- package/dist/core/trace.d.ts +4 -1
- package/dist/core/trace.js +2 -1
- package/dist/core/types.d.ts +1 -1
- package/dist/core/untrusted-egress.d.ts +18 -0
- package/dist/core/untrusted-egress.js +82 -12
- package/dist/core/wiring-manifest.d.ts +12 -3
- 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/execution-env/node-execution-env.js +15 -11
- package/dist/engine/execution-env/symlink-chain.d.ts +7 -5
- package/dist/engine/harness/agent-harness.d.ts +12 -5
- package/dist/engine/harness/agent-harness.js +13 -2
- package/dist/engine/harness/types.d.ts +48 -7
- package/dist/engine/harness/types.js +5 -1
- package/dist/engine/llm/types.d.ts +12 -3
- package/dist/engine/llm/types.js +1 -1
- package/dist/engine/loop/agent-loop.d.ts +1 -4
- package/dist/engine/loop/agent-loop.js +26 -4
- 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/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 +7 -1
- package/dist/index.d.ts +23 -11
- package/dist/index.js +15 -6
- package/dist/internal/harness-types.d.ts +1 -1
- package/dist/internal/harness.d.ts +4 -3
- package/dist/internal/harness.js +3 -2
- package/dist/stores/file/checkpoint-store.d.ts +0 -4
- package/dist/stores/file/checkpoint-store.js +0 -1
- package/dist/stores/file/file-history-store.js +12 -4
- package/dist/stores/file/index.d.ts +4 -1
- package/dist/stores/file/index.js +4 -1
- package/dist/stores/file/mailbox-store.d.ts +2 -1
- package/dist/stores/file/mailbox-store.js +26 -1
- package/dist/stores/file/session-store.d.ts +15 -8
- package/dist/stores/file/session-store.js +28 -13
- package/dist/tools/fs/bash-readonly-classifier.d.ts +15 -19
- package/dist/tools/fs/bash-readonly-classifier.js +5 -10
- package/dist/tools/fs/fs-bash.js +10 -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 +1 -1
- package/dist/tools/fs/pattern-kill-guard.d.ts +3 -2
- package/dist/tools/fs/pattern-kill-guard.js +68 -36
- 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 +18 -1
- package/dist/tools/fs/shell-read-check.js +66 -16
- package/dist/tools/fs/shell-read-establish.js +2 -1
- package/dist/tools/fs/shell-read-identity.d.ts +12 -9
- package/dist/tools/fs/shell-read-identity.js +10 -5
- package/dist/tools/fs/shell-read-judge.d.ts +10 -1
- package/dist/tools/web.js +9 -7
- package/dist/tools/worktree.d.ts +42 -15
- package/dist/tools/worktree.js +60 -32
- package/package.json +4 -2
- package/test/export-surface.snapshot.json +141 -3
- package/wire-changes/core-stores-sql@7.57.0.json +29 -0
- package/wire-changes/core-stores-sql@7.58.0.json +29 -0
- package/wire-changes/core@7.57.0.json +1487 -0
- package/wire-changes/core@7.58.0.json +2188 -0
- package/wire-changes/mods-kernel@7.57.0.json +29 -0
- package/wire-changes/mods-kernel@7.58.0.json +81 -0
- package/wire-changes/primitives@7.57.0.json +245 -0
- package/wire-changes/primitives@7.58.0.json +29 -0
|
@@ -18,7 +18,56 @@ export interface MailboxMessage {
|
|
|
18
18
|
* ABSENT = a pre-385 or foreign record (same semantics as an absent `hopChain`): the drain treats it
|
|
19
19
|
* as foreign, never retro-admits it. Validated at `append` ({@link readMailboxPeerMeta}). */
|
|
20
20
|
peerMeta?: MailboxPeerMeta;
|
|
21
|
+
/** The record's HOLD DECISION ({@link MailboxDecision}): absent = never held. Never appended — it
|
|
22
|
+
* starts absent and moves only through {@link MailboxStore.moveDecision}; every lease snapshot
|
|
23
|
+
* carries it, so every consumer of the box reads the same decision. */
|
|
24
|
+
decision?: MailboxDecision;
|
|
21
25
|
}
|
|
26
|
+
/**
|
|
27
|
+
* A parked record's hold decision — the durable answer about a record a recipient's setting put on
|
|
28
|
+
* hold, kept ON the record so every consumer of the box (another terminal, another process, the session's
|
|
29
|
+
* next run) reads the same answer. `held` — waiting for a person; `approved` — a person approved it, not yet
|
|
30
|
+
* handed over; `delivered` — a consumer holding the lease took the move and handed it over (a later
|
|
31
|
+
* answer about it learns that instead of claiming a decision); `denied` / `expired` / `refused` /
|
|
32
|
+
* `dropped` — final: the record is never delivered and only waits for the ack that removes it.
|
|
33
|
+
*/
|
|
34
|
+
export declare const MAILBOX_DECISIONS: readonly ["held", "approved", "delivered", "denied", "expired", "refused", "dropped"];
|
|
35
|
+
export type MailboxDecision = (typeof MAILBOX_DECISIONS)[number];
|
|
36
|
+
/** A stored decision word as a reader takes it: a word this engine does not know (a newer engine's) reads
|
|
37
|
+
* as `held` — never delivered on a guess, and left for a person (or that newer engine) to decide. */
|
|
38
|
+
export declare function readStoredMailboxDecision(raw: unknown): MailboxDecision | undefined;
|
|
39
|
+
/** The refusal code of a malformed {@link MailboxStore.moveDecision} call (a word outside the
|
|
40
|
+
* closed set, a non-positive seq, or an edge the decision law does not allow). */
|
|
41
|
+
export declare const MAILBOX_INVALID_DECISION_MOVE_CODE = "mailbox.invalid_decision_move";
|
|
42
|
+
export declare function isMailboxDecision(value: unknown): value is MailboxDecision;
|
|
43
|
+
/** Final states: the record is never delivered again, by any consumer. */
|
|
44
|
+
export declare function isMailboxDecisionFinal(state: MailboxDecision | undefined): boolean;
|
|
45
|
+
/** Deliverable states: a consumer holding the lease delivers the record (a setting that now refuses still wins). */
|
|
46
|
+
export declare function isMailboxDecisionDeliverable(state: MailboxDecision | undefined): boolean;
|
|
47
|
+
/**
|
|
48
|
+
* THE decision law — a decision only moves forward, and every hand-over of a held record is itself a move:
|
|
49
|
+
* absent → `held`; `held` → `approved` / `delivered` / `denied` / `expired` / `refused`; `approved` →
|
|
50
|
+
* `delivered` or a final state; `delivered` → `dropped` (the handed-over frame was refused by policy inside a lease-holding pass) only;
|
|
51
|
+
* a final state never moves.
|
|
52
|
+
*/
|
|
53
|
+
export declare function mailboxDecisionEdgeAllowed(from: MailboxDecision | undefined, to: MailboxDecision): boolean;
|
|
54
|
+
/** What {@link MailboxStore.moveDecision} answers: the move happened, or the record's actual state
|
|
55
|
+
* (`unset` = never held, `gone` = no such record any more — acked, reaped or dropped). */
|
|
56
|
+
export type MailboxDecisionOutcome = {
|
|
57
|
+
readonly ok: true;
|
|
58
|
+
} | {
|
|
59
|
+
readonly ok: false;
|
|
60
|
+
readonly current: MailboxDecision | "unset" | "gone";
|
|
61
|
+
};
|
|
62
|
+
/**
|
|
63
|
+
* THE caller-side reading of {@link MailboxStore.moveDecision}: a fault can arrive AFTER the move
|
|
64
|
+
* committed (a lock release that failed, a reply lost on the wire), so a call that throws is asked once
|
|
65
|
+
* more, and a store that already holds `next` answers the first call's success. A second fault throws.
|
|
66
|
+
* Every engine-side decision move goes through this one function.
|
|
67
|
+
*/
|
|
68
|
+
export declare function moveMailboxDecision(store: Pick<MailboxStore, "moveDecision">, scope: string, handle: string, seq: number, expect: MailboxDecision | undefined, next: MailboxDecision): Promise<MailboxDecisionOutcome>;
|
|
69
|
+
/** The one validator every backend runs BEFORE touching storage: a malformed call has zero side effects. */
|
|
70
|
+
export declare function assertMailboxDecisionMove(seq: unknown, expect: unknown, next: unknown): void;
|
|
22
71
|
/** design/385 — the typed peer-metadata record on a parked message. ONE optional object, one-time
|
|
23
72
|
* contract extension; every field optional. Bundled backends persist it verbatim and hand back a
|
|
24
73
|
* detached copy. */
|
|
@@ -132,7 +181,7 @@ export declare const MAILBOX_TOMBSTONED_RECIPIENT_CODE = "mailbox.recipient_tomb
|
|
|
132
181
|
* A backend may raise the same code with a plain `Error` carrying `.code`; consumers branch on the
|
|
133
182
|
* string, not on this class (a cross-process/out-of-repo store cannot hand back an instance).
|
|
134
183
|
*/
|
|
135
|
-
export type MailboxStoreErrorCode = typeof MAILBOX_TOMBSTONED_RECIPIENT_CODE | typeof MAILBOX_INVALID_PEER_META_CODE | typeof MAILBOX_CROSS_PROCESS_UNSAFE_CODE;
|
|
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;
|
|
136
185
|
export declare class MailboxStoreError extends Error {
|
|
137
186
|
readonly code: MailboxStoreErrorCode;
|
|
138
187
|
constructor(code: MailboxStoreErrorCode, message: string);
|
|
@@ -241,6 +290,17 @@ export interface MailboxStore {
|
|
|
241
290
|
* Implementations report `{acked:true}` only when they actually consumed the prefix.
|
|
242
291
|
*/
|
|
243
292
|
ack(scope: string, handle: string, owner: string, upToSeq: number): Promise<MailboxAckResult>;
|
|
293
|
+
/**
|
|
294
|
+
* Move one record's hold decision from `expect` (absent = never held) to `next`, atomically
|
|
295
|
+
* against every other transition and against `ack` — the compare-and-set every decision about a held
|
|
296
|
+
* record goes through. NOT fenced by the lease: a person answers from whichever process shows the
|
|
297
|
+
* record, whether or not it holds the box. A state that is not `expect` answers `{ ok: false, current }`
|
|
298
|
+
* and changes nothing; a record no longer in the box answers `current: "gone"`. A malformed call (see
|
|
299
|
+
* {@link assertMailboxDecisionMove}) is refused with {@link MAILBOX_INVALID_DECISION_MOVE_CODE}
|
|
300
|
+
* before any side effect. The state is durable like the record, and `ack` / `reap` / `drop` remove it
|
|
301
|
+
* with the record.
|
|
302
|
+
*/
|
|
303
|
+
moveDecision(scope: string, handle: string, seq: number, expect: MailboxDecision | undefined, next: MailboxDecision): Promise<MailboxDecisionOutcome>;
|
|
244
304
|
releaseLease(scope: string, handle: string, owner: string): Promise<void>;
|
|
245
305
|
/** Observation face (the "N pending" receipt figure) — count of currently-visible messages. */
|
|
246
306
|
peekCount(scope: string, handle: string): Promise<number>;
|
|
@@ -291,6 +351,7 @@ export declare class InMemoryMailboxStore implements MailboxStore {
|
|
|
291
351
|
append(scope: string, handle: string, msg: MailboxAppendMessage): Promise<number>;
|
|
292
352
|
claimLease(scope: string, handle: string, owner: string, ttlMs: number, now?: number): Promise<MailboxLease | null>;
|
|
293
353
|
ack(scope: string, handle: string, owner: string, upToSeq: number): Promise<MailboxAckResult>;
|
|
354
|
+
moveDecision(scope: string, handle: string, seq: number, expect: MailboxDecision | undefined, next: MailboxDecision): Promise<MailboxDecisionOutcome>;
|
|
294
355
|
releaseLease(scope: string, handle: string, owner: string): Promise<void>;
|
|
295
356
|
peekCount(scope: string, handle: string): Promise<number>;
|
|
296
357
|
drop(scope: string, handle: string): Promise<void>;
|
|
@@ -1,4 +1,53 @@
|
|
|
1
1
|
import { assertRetentionPolicy } from "./retention-policy.js";
|
|
2
|
+
export const MAILBOX_DECISIONS = Object.freeze(["held", "approved", "delivered", "denied", "expired", "refused", "dropped"]);
|
|
3
|
+
export function readStoredMailboxDecision(raw) {
|
|
4
|
+
if (raw === undefined)
|
|
5
|
+
return undefined;
|
|
6
|
+
return isMailboxDecision(raw) ? raw : "held";
|
|
7
|
+
}
|
|
8
|
+
export const MAILBOX_INVALID_DECISION_MOVE_CODE = "mailbox.invalid_decision_move";
|
|
9
|
+
export function isMailboxDecision(value) {
|
|
10
|
+
return typeof value === "string" && MAILBOX_DECISIONS.includes(value);
|
|
11
|
+
}
|
|
12
|
+
export function isMailboxDecisionFinal(state) {
|
|
13
|
+
return state === "denied" || state === "expired" || state === "refused" || state === "dropped";
|
|
14
|
+
}
|
|
15
|
+
export function isMailboxDecisionDeliverable(state) {
|
|
16
|
+
return state === "approved" || state === "delivered";
|
|
17
|
+
}
|
|
18
|
+
export function mailboxDecisionEdgeAllowed(from, to) {
|
|
19
|
+
if (from === undefined)
|
|
20
|
+
return to === "held";
|
|
21
|
+
if (from === "held")
|
|
22
|
+
return to === "approved" || to === "delivered" || to === "denied" || to === "expired" || to === "refused";
|
|
23
|
+
if (from === "approved")
|
|
24
|
+
return to === "delivered" || isMailboxDecisionFinal(to);
|
|
25
|
+
if (from === "delivered")
|
|
26
|
+
return to === "dropped";
|
|
27
|
+
return false;
|
|
28
|
+
}
|
|
29
|
+
export async function moveMailboxDecision(store, scope, handle, seq, expect, next) {
|
|
30
|
+
try {
|
|
31
|
+
return await store.moveDecision(scope, handle, seq, expect, next);
|
|
32
|
+
}
|
|
33
|
+
catch {
|
|
34
|
+
const again = await store.moveDecision(scope, handle, seq, expect, next);
|
|
35
|
+
return !again.ok && again.current === next ? { ok: true } : again;
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
export function assertMailboxDecisionMove(seq, expect, next) {
|
|
39
|
+
const refuse = (why) => {
|
|
40
|
+
throw new MailboxStoreError(MAILBOX_INVALID_DECISION_MOVE_CODE, `MailboxStore.moveDecision: ${why}`);
|
|
41
|
+
};
|
|
42
|
+
if (typeof seq !== "number" || !Number.isInteger(seq) || seq < 1)
|
|
43
|
+
refuse(`seq must be a positive integer (got ${String(seq)})`);
|
|
44
|
+
if (expect !== undefined && !isMailboxDecision(expect))
|
|
45
|
+
refuse(`expect must be absent or one of ${MAILBOX_DECISIONS.join("|")}`);
|
|
46
|
+
if (!isMailboxDecision(next))
|
|
47
|
+
refuse(`next must be one of ${MAILBOX_DECISIONS.join("|")}`);
|
|
48
|
+
if (!mailboxDecisionEdgeAllowed(expect, next))
|
|
49
|
+
refuse(`${String(expect ?? "unset")} → ${String(next)} is not a decision move (a decision only moves forward)`);
|
|
50
|
+
}
|
|
2
51
|
export const MAILBOX_PEER_FROM_MODES = Object.freeze(["bypass", "prompting"]);
|
|
3
52
|
export const MAILBOX_PEER_RECORD_KINDS = Object.freeze(["peer_message", "idle_notice", "delivery_notice", "idle_subscription", "engine_frame"]);
|
|
4
53
|
export const MAILBOX_PEER_NOTICE_STATES = Object.freeze(["held", "denied", "expired", "delivered", "refused", "dropped", "idle", "exited", "unavailable"]);
|
|
@@ -184,6 +233,16 @@ export class InMemoryMailboxStore {
|
|
|
184
233
|
b.lease = undefined;
|
|
185
234
|
return { acked: true };
|
|
186
235
|
}
|
|
236
|
+
async moveDecision(scope, handle, seq, expect, next) {
|
|
237
|
+
assertMailboxDecisionMove(seq, expect, next);
|
|
238
|
+
const m = this.boxes.get(this.key(scope, handle))?.messages.find((x) => x.seq === seq);
|
|
239
|
+
if (m === undefined)
|
|
240
|
+
return { ok: false, current: "gone" };
|
|
241
|
+
if (m.decision !== expect)
|
|
242
|
+
return { ok: false, current: m.decision ?? "unset" };
|
|
243
|
+
m.decision = next;
|
|
244
|
+
return { ok: true };
|
|
245
|
+
}
|
|
187
246
|
async releaseLease(scope, handle, owner) {
|
|
188
247
|
const b = this.boxes.get(this.key(scope, handle));
|
|
189
248
|
if (b?.lease?.owner === owner)
|
|
@@ -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) {
|
|
@@ -19,9 +19,13 @@ import type { AssertAllKeysHandled } from "./ask-origin.js";
|
|
|
19
19
|
* capability, an ordinary `-32603`): the exchange happened;
|
|
20
20
|
* · `invalid_config` — the declaration itself could not be dialed (a malformed `url`): a fault to
|
|
21
21
|
* fix in the spec, never an outage to wait out;
|
|
22
|
+
* · `credential_unavailable` — the deployment's peer seat did not furnish the request (it threw, did not
|
|
23
|
+
* answer in time, answered something the engine cannot carry, or answered that
|
|
24
|
+
* the principal is not authorized): that request was not sent — a fault for the
|
|
25
|
+
* deployment to fix, not an outage of the server;
|
|
22
26
|
* · `unknown` — the thrown value carried no structure this table reads.
|
|
23
27
|
*/
|
|
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"];
|
|
28
|
+
export declare const MCP_FAILURE_KINDS: readonly ["connect_refused", "connection_failed", "connection_closed", "http_status", "not_mcp_response", "spawn_failed", "timeout", "protocol", "invalid_config", "credential_unavailable", "unknown"];
|
|
25
29
|
export type McpFailureKind = (typeof MCP_FAILURE_KINDS)[number];
|
|
26
30
|
/** The closed set of delivery verdicts ({@link McpFailure.delivered}). */
|
|
27
31
|
export declare const MCP_DELIVERY_VERDICTS: readonly ["yes", "no", "unknown"];
|
|
@@ -43,6 +47,7 @@ export declare const DELIVERED_BY_KIND: {
|
|
|
43
47
|
readonly timeout: "unknown";
|
|
44
48
|
readonly protocol: "yes";
|
|
45
49
|
readonly invalid_config: "no";
|
|
50
|
+
readonly credential_unavailable: "no";
|
|
46
51
|
readonly unknown: "unknown";
|
|
47
52
|
};
|
|
48
53
|
/** The fence over the delivery table: `never` while every kind has a verdict. */
|
|
@@ -104,6 +109,7 @@ export declare const LIVENESS_BY_FAILURE_KIND: {
|
|
|
104
109
|
readonly timeout: "unreachable";
|
|
105
110
|
readonly protocol: "reachable";
|
|
106
111
|
readonly invalid_config: undefined;
|
|
112
|
+
readonly credential_unavailable: undefined;
|
|
107
113
|
readonly unknown: "unknown";
|
|
108
114
|
};
|
|
109
115
|
/** The fence over the liveness table: `never` while every kind has a verdict. */
|
package/dist/core/mcp-failure.js
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import { McpError, ErrorCode } from "@modelcontextprotocol/sdk/types.js";
|
|
2
2
|
import { StreamableHTTPError } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
|
|
3
3
|
import { proxyTunnelRefusedSentence, readConnectFailure } from "../brain/errors.js";
|
|
4
|
+
import { PeerSeatFailure } from "./peer-seat.js";
|
|
4
5
|
export const MCP_FAILURE_KINDS = Object.freeze([
|
|
5
6
|
"connect_refused",
|
|
6
7
|
"connection_failed",
|
|
@@ -11,6 +12,7 @@ export const MCP_FAILURE_KINDS = Object.freeze([
|
|
|
11
12
|
"timeout",
|
|
12
13
|
"protocol",
|
|
13
14
|
"invalid_config",
|
|
15
|
+
"credential_unavailable",
|
|
14
16
|
"unknown",
|
|
15
17
|
]);
|
|
16
18
|
export const MCP_DELIVERY_VERDICTS = Object.freeze(["yes", "no", "unknown"]);
|
|
@@ -24,6 +26,7 @@ export const DELIVERED_BY_KIND = {
|
|
|
24
26
|
timeout: "unknown",
|
|
25
27
|
protocol: "yes",
|
|
26
28
|
invalid_config: "no",
|
|
29
|
+
credential_unavailable: "no",
|
|
27
30
|
unknown: "unknown",
|
|
28
31
|
};
|
|
29
32
|
export const MCP_LIVENESS_STATES = Object.freeze(["reachable", "unreachable", "unknown"]);
|
|
@@ -37,6 +40,7 @@ export const LIVENESS_BY_FAILURE_KIND = {
|
|
|
37
40
|
timeout: "unreachable",
|
|
38
41
|
protocol: "reachable",
|
|
39
42
|
invalid_config: undefined,
|
|
43
|
+
credential_unavailable: undefined,
|
|
40
44
|
unknown: "unknown",
|
|
41
45
|
};
|
|
42
46
|
export function livenessOf(outcome, observedAt) {
|
|
@@ -74,6 +78,11 @@ export function networkErrorCode(err, depth = 0) {
|
|
|
74
78
|
const isNodeErrCode = (code) => code.startsWith("ERR_");
|
|
75
79
|
const isDeclarationFault = (code) => code === "ERR_INVALID_URL" || (typeof code === "string" && code.startsWith("config."));
|
|
76
80
|
export const FAILURE_CLASSIFIER = [
|
|
81
|
+
{
|
|
82
|
+
name: "peer seat did not furnish the request",
|
|
83
|
+
when: (err) => err instanceof PeerSeatFailure,
|
|
84
|
+
reads: () => ({ kind: "credential_unavailable" }),
|
|
85
|
+
},
|
|
77
86
|
{
|
|
78
87
|
name: "sdk connection closed",
|
|
79
88
|
when: (err) => err instanceof McpError && err.code === ErrorCode.ConnectionClosed,
|
|
@@ -180,6 +189,7 @@ export function describeHttpTransportFailure(err, at = { phase: "request" }) {
|
|
|
180
189
|
case "timeout":
|
|
181
190
|
case "protocol":
|
|
182
191
|
case "invalid_config":
|
|
192
|
+
case "credential_unavailable":
|
|
183
193
|
case "unknown":
|
|
184
194
|
return undefined;
|
|
185
195
|
}
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* One declared server, as far as its names go: `McpServerSpec` fits as it is. `tools` are the server's REMOTE tool names the asker
|
|
3
|
+
* already knows (a listing, a host's reading of one — never the minted `mcp__…` names); absent means none are known.
|
|
4
|
+
*/
|
|
5
|
+
export interface McpNameSetServer {
|
|
6
|
+
readonly name: string;
|
|
7
|
+
readonly tools?: readonly string[];
|
|
8
|
+
}
|
|
9
|
+
/**
|
|
10
|
+
* One contention: `names` are the two sources, the earlier one first (server names for `server_name`; the remote tool names for
|
|
11
|
+
* `tool_name`, where `server` says whose); `shared` is the name they mint — the prefix for `server_name`, the wire name for `tool_name`.
|
|
12
|
+
*/
|
|
13
|
+
export type McpNameConflict = {
|
|
14
|
+
readonly kind: "server_name";
|
|
15
|
+
readonly names: readonly [string, string];
|
|
16
|
+
readonly shared: string;
|
|
17
|
+
} | {
|
|
18
|
+
readonly kind: "tool_name";
|
|
19
|
+
readonly server: string;
|
|
20
|
+
readonly names: readonly [string, string];
|
|
21
|
+
readonly shared: string;
|
|
22
|
+
};
|
|
23
|
+
/** The judge's answer: `ok`, or EVERY contention in the set — server rows first, then tool rows, each in declaration order; never empty. */
|
|
24
|
+
export type McpNameVerdict = {
|
|
25
|
+
readonly ok: true;
|
|
26
|
+
} | {
|
|
27
|
+
readonly ok: false;
|
|
28
|
+
readonly conflicts: readonly [McpNameConflict, ...McpNameConflict[]];
|
|
29
|
+
};
|
|
30
|
+
/** Judge a declared set. Pure: reads nothing but the names it is handed; a malformed set is refused (`config.invalid_argument`), never read as clean. */
|
|
31
|
+
export declare function judgeMcpNames(servers: readonly McpNameSetServer[]): McpNameVerdict;
|
|
32
|
+
/**
|
|
33
|
+
* The sentence that says why a tool of one server is not mounted under its own name: `heldBy` is the raw name that took the wire
|
|
34
|
+
* name `minted` first, `tool` the raw name that came after. TWO FACTS, TWO SENTENCES (a fixed label must not head more than one
|
|
35
|
+
* cause): the same raw name listed again, where namespacing folded nothing, and two different raw names that fold onto one name.
|
|
36
|
+
* It carries no raw name — the caller's own field says which tool.
|
|
37
|
+
*/
|
|
38
|
+
export declare function mcpToolDropReason(minted: string, heldBy: string, tool: string): string;
|
|
39
|
+
/** One row as a sentence — the one the engine refuses a run with (`server_name`) or discloses a drop with (`tool_name`). Names are quoted single-line and bounded. */
|
|
40
|
+
export declare function describeMcpNameConflict(conflict: McpNameConflict): string;
|
|
41
|
+
/**
|
|
42
|
+
* The refusal of a declared set whose server names do not each own a namespace domain — thrown by the mount and by the no-run probe,
|
|
43
|
+
* so one set is refused with one code and one sentence wherever it is asked. It takes the NAMES only (a run's refusal reads no
|
|
44
|
+
* tool list); the FIRST `server_name` row speaks, naming both raw spellings.
|
|
45
|
+
*/
|
|
46
|
+
export declare function refuseCollidingMcpServerNames(serverNames: readonly string[]): void;
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
import { MCP_NAMESPACE } from "./protocol-table.js";
|
|
2
|
+
import { createToolNameClaims, findNamespacePrefixCollisions } from "./protocol-naming.js";
|
|
3
|
+
import { inlineUntrusted } from "./untrusted-text.js";
|
|
4
|
+
function refuseArgument(problem) {
|
|
5
|
+
throw Object.assign(new Error(problem), { code: "config.invalid_argument" });
|
|
6
|
+
}
|
|
7
|
+
function readNameSet(servers) {
|
|
8
|
+
if (!Array.isArray(servers))
|
|
9
|
+
refuseArgument("judgeMcpNames takes a list of declared servers; what was passed is not a list.");
|
|
10
|
+
return Array.from(servers, (server, index) => {
|
|
11
|
+
if (typeof server !== "object" || server === null)
|
|
12
|
+
refuseArgument(`judgeMcpNames: entry ${index} is not a server declaration (an object with a "name").`);
|
|
13
|
+
const { name, tools } = server;
|
|
14
|
+
if (typeof name !== "string")
|
|
15
|
+
refuseArgument(`judgeMcpNames: entry ${index} has no string "name".`);
|
|
16
|
+
if (tools === undefined)
|
|
17
|
+
return { name };
|
|
18
|
+
const listed = Array.isArray(tools) ? Array.from(tools) : [undefined];
|
|
19
|
+
if (listed.some((tool) => typeof tool !== "string")) {
|
|
20
|
+
refuseArgument(`judgeMcpNames: entry ${index} ("${inlineUntrusted(name, 120)}") names its tools as something other than a list of strings.`);
|
|
21
|
+
}
|
|
22
|
+
return { name, tools: listed };
|
|
23
|
+
});
|
|
24
|
+
}
|
|
25
|
+
export function judgeMcpNames(servers) {
|
|
26
|
+
const set = readNameSet(servers);
|
|
27
|
+
const conflicts = findNamespacePrefixCollisions(MCP_NAMESPACE, set.map((s) => s.name)).map((c) => ({ kind: "server_name", names: c.peers, shared: c.prefix }));
|
|
28
|
+
for (const server of set) {
|
|
29
|
+
const claim = createToolNameClaims(MCP_NAMESPACE, server.name);
|
|
30
|
+
for (const tool of server.tools ?? []) {
|
|
31
|
+
const { minted, heldBy } = claim(tool);
|
|
32
|
+
if (heldBy !== undefined)
|
|
33
|
+
conflicts.push({ kind: "tool_name", server: server.name, names: [heldBy, tool], shared: minted });
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
const [first, ...rest] = conflicts;
|
|
37
|
+
return first === undefined ? { ok: true } : { ok: false, conflicts: [first, ...rest] };
|
|
38
|
+
}
|
|
39
|
+
export function mcpToolDropReason(minted, heldBy, tool) {
|
|
40
|
+
return heldBy === tool
|
|
41
|
+
? `this server listed this tool name more than once in one listing; the first entry is mounted as "${minted}" and the repeat is dropped (one name cannot denote two tools)`
|
|
42
|
+
: `name collides with an earlier tool of this server: both mount as "${minted}" after namespacing (only [a-zA-Z0-9_-] survives), and one name cannot denote two tools`;
|
|
43
|
+
}
|
|
44
|
+
export function describeMcpNameConflict(conflict) {
|
|
45
|
+
const [a, b] = conflict.names;
|
|
46
|
+
if (conflict.kind === "tool_name") {
|
|
47
|
+
return `MCP server "${inlineUntrusted(conflict.server, 120)}", tool "${inlineUntrusted(b, 120)}": ${mcpToolDropReason(conflict.shared, a, b)}`;
|
|
48
|
+
}
|
|
49
|
+
return a === b
|
|
50
|
+
? `MCP server "${inlineUntrusted(a, 120)}" is declared twice — each server needs its own name (both mount under "${conflict.shared}", so their tools would shadow each other and a refresh of one would unmount the other's).`
|
|
51
|
+
: `MCP server names "${inlineUntrusted(a, 120)}" and "${inlineUntrusted(b, 120)}" both mount under "${conflict.shared}" — the namespaced tool name keeps only [a-zA-Z0-9_-], so they are the same domain to this engine (their tools would shadow each other and a refresh of one would unmount the other's). Rename one.`;
|
|
52
|
+
}
|
|
53
|
+
export function refuseCollidingMcpServerNames(serverNames) {
|
|
54
|
+
const verdict = judgeMcpNames(serverNames.map((name) => ({ name })));
|
|
55
|
+
if (verdict.ok)
|
|
56
|
+
return;
|
|
57
|
+
const row = verdict.conflicts.find((c) => c.kind === "server_name");
|
|
58
|
+
if (row === undefined)
|
|
59
|
+
return;
|
|
60
|
+
throw Object.assign(new Error(describeMcpNameConflict(row)), { code: "config.mcp_server_name_collision" });
|
|
61
|
+
}
|
package/dist/core/mcp-probe.d.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { type McpFailureKind } from "./mcp-failure.js";
|
|
2
2
|
import type { McpServerSpec, OnElicit } from "./mcp-server-spec.js";
|
|
3
|
+
import type { PeerSeat } from "./peer-seat.js";
|
|
3
4
|
import type { WiringManifestMcpEntry } from "./wiring-manifest.js";
|
|
4
5
|
/** One server's probe reading, beside its manifest row. `connectMs` is wall time this probe measured
|
|
5
6
|
* for THIS server's dial — the spawn/handshake, the initial `tools/list` walk and the intake, ending
|
|
@@ -56,6 +57,9 @@ export interface McpProbeOptions {
|
|
|
56
57
|
signal?: AbortSignal;
|
|
57
58
|
/** The elicitation seat, for a caller that has a human behind it. Default: decline everything. */
|
|
58
59
|
onElicit?: OnElicit;
|
|
60
|
+
/** The peer seat a prepared leg dials with (`RunnerDeps.peerSeat`): what each request carries. Absent ⇒ nothing is carried, and a
|
|
61
|
+
* server whose declaration names `credentials` reads `failed` (`invalid_config`, `config.peer_seat_missing`). */
|
|
62
|
+
peerSeat?: PeerSeat;
|
|
59
63
|
/** Abort reading, stated once: the call rejects with the signal's own reason when that reason is an
|
|
60
64
|
* Error (a bare `abort()` supplies a DOMException named `AbortError`) and with this module's own
|
|
61
65
|
* `AbortError` otherwise — a face that throws a string is a face no `catch` can read. A condition
|
|
@@ -93,7 +97,7 @@ export interface McpProbeOptions {
|
|
|
93
97
|
* FAILURE IS PER SERVER, REFUSAL IS NOT. A server that cannot be dialed, that answers a status, or that
|
|
94
98
|
* outlives `timeoutMs` takes its verdict in its own row and the walk continues. What DOES reject is the
|
|
95
99
|
* declaration set the materialization itself refuses — two names that mount under one namespace prefix
|
|
96
|
-
* are refused before any transport is touched, by
|
|
100
|
+
* are refused before any transport is touched, by the judge the mount asks, so the probe answers a colliding
|
|
97
101
|
* configuration exactly as a task would rather than showing two healthy-looking rows for a pair the
|
|
98
102
|
* engine would never mount.
|
|
99
103
|
*
|
package/dist/core/mcp-probe.js
CHANGED
|
@@ -2,8 +2,7 @@ import { ErrorCode, McpError } from "@modelcontextprotocol/sdk/types.js";
|
|
|
2
2
|
import { snapshotMcpEntries } from "./locked-config.js";
|
|
3
3
|
import { classifyMcpFailure, livenessOf } from "./mcp-failure.js";
|
|
4
4
|
import { MCP_ENV_MS_MAX, materializeMcpTools } from "./mcp.js";
|
|
5
|
-
import {
|
|
6
|
-
import { MCP_NAMESPACE } from "./protocol-table.js";
|
|
5
|
+
import { refuseCollidingMcpServerNames } from "./mcp-name-judge.js";
|
|
7
6
|
import { mcpManifestEntries } from "./runner/prepare-wiring-manifest.js";
|
|
8
7
|
const DECLINE_EVERY_ELICITATION = async () => ({ action: "decline" });
|
|
9
8
|
function wholeInRange(name, value, min, max) {
|
|
@@ -66,9 +65,7 @@ export async function probeMcpServers(specs, opts = {}) {
|
|
|
66
65
|
const concurrency = wholeInRange("concurrency", opts.concurrency, 1, Number.MAX_SAFE_INTEGER) ?? 1;
|
|
67
66
|
const onElicit = opts.onElicit ?? DECLINE_EVERY_ELICITATION;
|
|
68
67
|
const signal = opts.signal;
|
|
69
|
-
|
|
70
|
-
await materializeMcpTools(declared, opts.principal, onElicit);
|
|
71
|
-
}
|
|
68
|
+
refuseCollidingMcpServerNames(declared.map((e) => e.name));
|
|
72
69
|
const statuses = [];
|
|
73
70
|
const servers = new Array(declared.length);
|
|
74
71
|
const teardowns = [];
|
|
@@ -77,7 +74,7 @@ export async function probeMcpServers(specs, opts = {}) {
|
|
|
77
74
|
const entry = declared[i];
|
|
78
75
|
const started = performance.now();
|
|
79
76
|
const elapsed = () => Math.round(performance.now() - started);
|
|
80
|
-
const dial = materializeMcpTools([entry], opts.principal, onElicit);
|
|
77
|
+
const dial = materializeMcpTools([entry], opts.principal, onElicit, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, opts.peerSeat);
|
|
81
78
|
const verdict = await raceDial(dial, timeoutMs, signal);
|
|
82
79
|
if (verdict.kind === "settled") {
|
|
83
80
|
const found = verdict.handle.statuses.find((s) => s.name === entry.name);
|
|
@@ -131,8 +131,11 @@ export interface McpLiveConnection {
|
|
|
131
131
|
export interface McpServerLink {
|
|
132
132
|
/** The connection the materialization holds for the server now; `undefined` while it holds none (a re-dial's old one is gone and the new one has not landed, or the last dial failed). */
|
|
133
133
|
live(): McpLiveConnection | undefined;
|
|
134
|
-
/**
|
|
135
|
-
|
|
134
|
+
/** Replace `lost`: join the re-dial running for the server, or start one while `lost` is still the live connection. Settles when there
|
|
135
|
+
* is nothing left to wait for. `cause`: the server dropped the session (`session`, the default), or the peer seat's pieces the
|
|
136
|
+
* connection was started with expired (`expired`: the calls in flight on it settle before it is closed, and the run tree's pooled
|
|
137
|
+
* connection is replaced once for all its holders). */
|
|
138
|
+
recover(lost: McpLiveConnection, cause?: "session" | "expired"): Promise<unknown>;
|
|
136
139
|
}
|
|
137
140
|
/** Why a tool may not be sent on a live connection: its listing mints the tool another gate or none (`changed`), or no listing of the connection has reached it (`unreached`). */
|
|
138
141
|
export type McpListingRefusal = "changed" | "unreached";
|