@sema-agent/core 7.58.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 +776 -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.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 +87 -21
- 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/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 +18 -6
- package/dist/core/allow-entry.js +16 -8
- package/dist/core/approval-object.d.ts +29 -15
- package/dist/core/approval-object.js +47 -19
- package/dist/core/auto-compaction.js +1 -1
- package/dist/core/background-agent-store.d.ts +16 -3
- package/dist/core/checkpoint-requirements.d.ts +13 -1
- package/dist/core/checkpoint-requirements.js +3 -1
- package/dist/core/checkpoint-store.d.ts +58 -12
- package/dist/core/checkpoint-store.js +18 -6
- 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 +98 -8
- package/dist/core/engine-notice.js +19 -5
- package/dist/core/gate-fold.js +1 -1
- package/dist/core/gate-lanes.js +8 -4
- package/dist/core/gate-outcome.d.ts +32 -3
- package/dist/core/gate-outcome.js +19 -1
- package/dist/core/governance-codes.d.ts +9 -1
- package/dist/core/governance-codes.js +13 -0
- package/dist/core/hooks.d.ts +31 -3
- package/dist/core/hooks.js +5 -6
- package/dist/core/image-admission.d.ts +6 -5
- package/dist/core/image-admission.js +18 -14
- package/dist/core/locked-config.d.ts +5 -2
- package/dist/core/locked-config.js +2 -1
- package/dist/core/mailbox-store.d.ts +45 -1
- package/dist/core/mailbox-store.js +53 -9
- package/dist/core/mcp-failure.d.ts +114 -18
- package/dist/core/mcp-failure.js +63 -5
- package/dist/core/mcp-server-link.d.ts +22 -1
- package/dist/core/mcp-server-link.js +25 -1
- package/dist/core/mcp.d.ts +12 -8
- package/dist/core/mcp.js +42 -25
- 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/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/mods/classic-events.d.ts +5 -1
- package/dist/core/mods/kernel/dispatch.js +2 -1
- package/dist/core/mods/kernel/events.d.ts +2 -1
- package/dist/core/mods/kernel/events.js +2 -2
- package/dist/core/mods/kernel/registration.d.ts +4 -0
- package/dist/core/mods/kernel/registration.js +3 -0
- package/dist/core/mods/stations.d.ts +31 -10
- package/dist/core/mods/stations.js +44 -10
- package/dist/core/mods/tool-call.js +1 -1
- 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/peer-seat.d.ts +70 -8
- package/dist/core/peer-seat.js +143 -11
- 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 +11 -3
- package/dist/core/present-plan-tool.js +2 -2
- package/dist/core/resume-startup-cause.js +1 -0
- package/dist/core/rewrite-rejudge.d.ts +1 -0
- package/dist/core/rewrite-rejudge.js +2 -2
- package/dist/core/roles.d.ts +34 -2
- package/dist/core/roles.js +43 -4
- 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/contracts.d.ts +20 -16
- 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 +12 -4
- package/dist/core/runner/gate-exit.js +10 -7
- 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 +3 -5
- package/dist/core/runner/prepare-caps-and-workflow.js +2 -0
- package/dist/core/runner/prepare-config-doors.js +2 -0
- package/dist/core/runner/prepare-context-lane.js +2 -0
- package/dist/core/runner/prepare-delegation-surface.d.ts +4 -0
- package/dist/core/runner/prepare-delegation-surface.js +1 -0
- package/dist/core/runner/prepare-hands-readface.d.ts +4 -0
- package/dist/core/runner/prepare-hands-readface.js +5 -0
- 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.js +10 -17
- 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 +3 -3
- package/dist/core/runner/prepare-policy-chain.js +16 -13
- 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.js +9 -1
- 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-task.js +4 -2
- package/dist/core/runner/prepare-wiring-manifest.d.ts +1 -1
- package/dist/core/runner/prepare-wiring-manifest.js +2 -1
- 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 +4 -2
- package/dist/core/runner/resume-apply.js +6 -1
- 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-identity-wiring.d.ts +2 -5
- package/dist/core/runner/run-identity-wiring.js +5 -4
- package/dist/core/runner/run-leg.d.ts +2 -0
- package/dist/core/runner/run-leg.js +37 -28
- 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/tool-end-body.js +2 -2
- package/dist/core/runner/tool-occurrence.d.ts +1 -1
- package/dist/core/runner/tool-occurrence.js +2 -2
- package/dist/core/runner/turn-attachments.d.ts +26 -22
- package/dist/core/runner/turn-attachments.js +24 -26
- package/dist/core/runner-deps.d.ts +1 -1
- package/dist/core/secret-env.d.ts +32 -2
- package/dist/core/secret-env.js +65 -3
- package/dist/core/sensitive-path-policy.js +3 -3
- 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 +2 -5
- 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/store-contracts/background-agent-store-contract.js +27 -0
- package/dist/core/store-contracts/checkpoint-store-contract.js +3 -2
- package/dist/core/store-contracts/mailbox-store-contract.js +31 -1
- package/dist/core/synthetic-read-verdict.js +2 -1
- package/dist/core/task-event.d.ts +32 -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 +5 -0
- package/dist/core/task-spec.d.ts +12 -1
- package/dist/core/terminal-cause.d.ts +10 -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-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 +2 -2
- package/dist/core/types.js +1 -1
- package/dist/core/user-attachment.js +1 -1
- package/dist/core/wiring-manifest.d.ts +6 -3
- 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 +9 -12
- package/dist/engine/harness/agent-harness.d.ts +25 -2
- package/dist/engine/harness/agent-harness.js +41 -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 +8 -0
- 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 +18 -7
- 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/path-to-root.d.ts +38 -0
- package/dist/engine/session/path-to-root.js +39 -0
- package/dist/engine/session/storage-base.js +4 -21
- package/dist/index.d.ts +16 -10
- package/dist/index.js +11 -7
- package/dist/internal/harness-types.d.ts +1 -1
- package/dist/internal/harness.d.ts +1 -0
- 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/mailbox-store.js +6 -10
- package/dist/tools/fs/fs-bash.d.ts +6 -0
- package/dist/tools/fs/fs-bash.js +6 -3
- package/dist/tools/fs/index.js +6 -2
- 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/shell-read-check.d.ts +1 -1
- package/dist/tools/fs/shell-read-check.js +2 -1
- package/dist/tools/fs/shell-read-judge.d.ts +16 -8
- 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/package.json +3 -2
- package/test/export-surface.snapshot.json +87 -1
- package/wire-changes/core-stores-sql@7.59.0.json +29 -0
- package/wire-changes/core@7.59.0.json +2459 -0
- package/wire-changes/mods-kernel@7.59.0.json +29 -0
- package/wire-changes/primitives@7.59.0.json +29 -0
|
@@ -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
|
|
@@ -20,13 +27,40 @@ import type { AssertAllKeysHandled } from "./ask-origin.js";
|
|
|
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;
|
|
22
29
|
* · `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
|
|
24
|
-
*
|
|
25
|
-
* deployment to fix, not an outage of the server;
|
|
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;
|
|
26
32
|
* · `unknown` — the thrown value carried no structure this table reads.
|
|
27
33
|
*/
|
|
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"];
|
|
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"];
|
|
29
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
|
+
}
|
|
30
64
|
/** The closed set of delivery verdicts ({@link McpFailure.delivered}). */
|
|
31
65
|
export declare const MCP_DELIVERY_VERDICTS: readonly ["yes", "no", "unknown"];
|
|
32
66
|
export type McpDelivered = (typeof MCP_DELIVERY_VERDICTS)[number];
|
|
@@ -41,6 +75,7 @@ export declare const DELIVERED_BY_KIND: {
|
|
|
41
75
|
readonly connect_refused: "no";
|
|
42
76
|
readonly connection_failed: "unknown";
|
|
43
77
|
readonly connection_closed: "unknown";
|
|
78
|
+
readonly unauthorized: "unknown";
|
|
44
79
|
readonly http_status: "unknown";
|
|
45
80
|
readonly not_mcp_response: "unknown";
|
|
46
81
|
readonly spawn_failed: "no";
|
|
@@ -103,6 +138,7 @@ export declare const LIVENESS_BY_FAILURE_KIND: {
|
|
|
103
138
|
readonly connect_refused: "unreachable";
|
|
104
139
|
readonly connection_failed: "unreachable";
|
|
105
140
|
readonly connection_closed: "unreachable";
|
|
141
|
+
readonly unauthorized: "unknown";
|
|
106
142
|
readonly http_status: "unknown";
|
|
107
143
|
readonly not_mcp_response: "unknown";
|
|
108
144
|
readonly spawn_failed: "unreachable";
|
|
@@ -115,16 +151,17 @@ export declare const LIVENESS_BY_FAILURE_KIND: {
|
|
|
115
151
|
/** The fence over the liveness table: `never` while every kind has a verdict. */
|
|
116
152
|
export type LivenessTableCoversEveryMcpFailureKind = AssertAllKeysHandled<Exclude<McpFailureKind, keyof typeof LIVENESS_BY_FAILURE_KIND>>;
|
|
117
153
|
/**
|
|
118
|
-
* What ONE exchange with a server tells the liveness record: the CLASS of the failure it ended in,
|
|
119
|
-
* `"completed"` when it finished
|
|
120
|
-
*
|
|
121
|
-
*
|
|
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".
|
|
122
159
|
*/
|
|
123
|
-
export type McpExchangeOutcome = McpFailureKind | "completed";
|
|
160
|
+
export type McpExchangeOutcome = McpFailureKind | "completed" | "unsent";
|
|
124
161
|
/** The liveness observation an exchange supports, or `undefined` when the outcome is not an observation
|
|
125
|
-
* at all (see {@link LIVENESS_BY_FAILURE_KIND}: a declaration that could never be dialed
|
|
126
|
-
* mint of the record — no two sites can disagree about the word, about
|
|
127
|
-
* `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. */
|
|
128
165
|
export declare function livenessOf(outcome: McpExchangeOutcome, observedAt: number): McpServerLiveness | undefined;
|
|
129
166
|
/** A request over an established connection; `session` when the request carried the session id the server issued at the handshake. */
|
|
130
167
|
export type McpRequestSite = {
|
|
@@ -139,7 +176,7 @@ export type McpFailureSite = {
|
|
|
139
176
|
} | McpRequestSite;
|
|
140
177
|
/**
|
|
141
178
|
* The one MCP failure record. Both fields are always present; `httpStatus` rides only with
|
|
142
|
-
* `kind === "http_status"`.
|
|
179
|
+
* `kind === "http_status"`, `authorization` only with `kind === "unauthorized"`.
|
|
143
180
|
*/
|
|
144
181
|
export interface McpFailure {
|
|
145
182
|
/**
|
|
@@ -171,7 +208,23 @@ export interface McpFailure {
|
|
|
171
208
|
delivered: McpDelivered;
|
|
172
209
|
/** The HTTP status the endpoint answered with; present iff `kind === "http_status"`. */
|
|
173
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;
|
|
174
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>;
|
|
175
228
|
/**
|
|
176
229
|
* The first errno-shaped / undici-shaped `code` on an error's cause chain (`E[A-Z_]+`, `UND_ERR_*`,
|
|
177
230
|
* Node's `ERR_*`). `fetch` reports every network failure as a bare `TypeError: fetch failed` with the
|
|
@@ -180,12 +233,16 @@ export interface McpFailure {
|
|
|
180
233
|
* DNS-temporary-failure errno is literally `EAI_AGAIN`.
|
|
181
234
|
*/
|
|
182
235
|
export declare function networkErrorCode(err: unknown, depth?: number): string | undefined;
|
|
183
|
-
/** What a row reads OFF the thrown value: the failure's class,
|
|
184
|
-
*
|
|
185
|
-
*
|
|
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. */
|
|
186
241
|
export type McpFailureClass = {
|
|
187
242
|
kind: McpFailureKind;
|
|
188
243
|
httpStatus?: number;
|
|
244
|
+
authorization?: McpAuthorization;
|
|
245
|
+
unsent?: true;
|
|
189
246
|
};
|
|
190
247
|
/** One row of the classifier: `when` reads structure only; `reads` names the class it saw. */
|
|
191
248
|
export interface McpFailureRule {
|
|
@@ -209,6 +266,45 @@ export declare const FAILURE_CLASSIFIER: ReadonlyArray<McpFailureRule>;
|
|
|
209
266
|
* Total: every input maps to a record.
|
|
210
267
|
*/
|
|
211
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;
|
|
212
308
|
/**
|
|
213
309
|
* What a transport-level HTTP failure can be said to be, in words for a model-facing line: the
|
|
214
310
|
* condition to name, and the delivery verdict. `undefined` for every failure that is NOT of the HTTP
|
package/dist/core/mcp-failure.js
CHANGED
|
@@ -1,11 +1,12 @@
|
|
|
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
|
+
import { PeerAuthorizationRefused, PeerSeatFailure } from "./peer-seat.js";
|
|
5
5
|
export const MCP_FAILURE_KINDS = Object.freeze([
|
|
6
6
|
"connect_refused",
|
|
7
7
|
"connection_failed",
|
|
8
8
|
"connection_closed",
|
|
9
|
+
"unauthorized",
|
|
9
10
|
"http_status",
|
|
10
11
|
"not_mcp_response",
|
|
11
12
|
"spawn_failed",
|
|
@@ -15,11 +16,13 @@ export const MCP_FAILURE_KINDS = Object.freeze([
|
|
|
15
16
|
"credential_unavailable",
|
|
16
17
|
"unknown",
|
|
17
18
|
]);
|
|
19
|
+
export const MCP_AUTHORIZATION_REASONS = Object.freeze(["rejected", "scope", "none"]);
|
|
18
20
|
export const MCP_DELIVERY_VERDICTS = Object.freeze(["yes", "no", "unknown"]);
|
|
19
21
|
export const DELIVERED_BY_KIND = {
|
|
20
22
|
connect_refused: "no",
|
|
21
23
|
connection_failed: "unknown",
|
|
22
24
|
connection_closed: "unknown",
|
|
25
|
+
unauthorized: "unknown",
|
|
23
26
|
http_status: "unknown",
|
|
24
27
|
not_mcp_response: "unknown",
|
|
25
28
|
spawn_failed: "no",
|
|
@@ -34,6 +37,7 @@ export const LIVENESS_BY_FAILURE_KIND = {
|
|
|
34
37
|
connect_refused: "unreachable",
|
|
35
38
|
connection_failed: "unreachable",
|
|
36
39
|
connection_closed: "unreachable",
|
|
40
|
+
unauthorized: "unknown",
|
|
37
41
|
http_status: "unknown",
|
|
38
42
|
not_mcp_response: "unknown",
|
|
39
43
|
spawn_failed: "unreachable",
|
|
@@ -46,12 +50,25 @@ export const LIVENESS_BY_FAILURE_KIND = {
|
|
|
46
50
|
export function livenessOf(outcome, observedAt) {
|
|
47
51
|
if (outcome === "completed")
|
|
48
52
|
return { state: "reachable", observedAt };
|
|
53
|
+
if (outcome === "unsent")
|
|
54
|
+
return undefined;
|
|
49
55
|
const state = LIVENESS_BY_FAILURE_KIND[outcome];
|
|
50
56
|
if (state === undefined)
|
|
51
57
|
return undefined;
|
|
52
58
|
return state === "unreachable" ? { state, observedAt, errorCode: outcome } : { state, observedAt };
|
|
53
59
|
}
|
|
54
|
-
const CONNECT_KEEPS_THE_TABLE_VERDICT = new Set(["protocol", "http_status"]);
|
|
60
|
+
const CONNECT_KEEPS_THE_TABLE_VERDICT = new Set(["protocol", "http_status", "unauthorized"]);
|
|
61
|
+
export function failureFields(of) {
|
|
62
|
+
const kind = "kind" in of ? of.kind : of.errorCode;
|
|
63
|
+
if (kind === undefined)
|
|
64
|
+
return {};
|
|
65
|
+
return {
|
|
66
|
+
errorCode: kind,
|
|
67
|
+
...(of.delivered !== undefined ? { delivered: of.delivered } : {}),
|
|
68
|
+
...(of.httpStatus !== undefined ? { httpStatus: of.httpStatus } : {}),
|
|
69
|
+
...(of.authorization !== undefined ? { authorization: { ...of.authorization } } : {}),
|
|
70
|
+
};
|
|
71
|
+
}
|
|
55
72
|
const NETWORK_CODES_NEVER_DELIVERED = new Set([
|
|
56
73
|
"ECONNREFUSED",
|
|
57
74
|
"ENOTFOUND",
|
|
@@ -78,10 +95,15 @@ export function networkErrorCode(err, depth = 0) {
|
|
|
78
95
|
const isNodeErrCode = (code) => code.startsWith("ERR_");
|
|
79
96
|
const isDeclarationFault = (code) => code === "ERR_INVALID_URL" || (typeof code === "string" && code.startsWith("config."));
|
|
80
97
|
export const FAILURE_CLASSIFIER = [
|
|
98
|
+
{
|
|
99
|
+
name: "peer seat answered the principal is not authorized",
|
|
100
|
+
when: (err) => err instanceof PeerSeatFailure && err.reason === "unauthorized",
|
|
101
|
+
reads: (err) => ({ kind: "unauthorized", authorization: authorizationOf("none", err.authorizeUrl, undefined), unsent: true }),
|
|
102
|
+
},
|
|
81
103
|
{
|
|
82
104
|
name: "peer seat did not furnish the request",
|
|
83
105
|
when: (err) => err instanceof PeerSeatFailure,
|
|
84
|
-
reads: () => ({ kind: "credential_unavailable" }),
|
|
106
|
+
reads: () => ({ kind: "credential_unavailable", unsent: true }),
|
|
85
107
|
},
|
|
86
108
|
{
|
|
87
109
|
name: "sdk connection closed",
|
|
@@ -98,6 +120,13 @@ export const FAILURE_CLASSIFIER = [
|
|
|
98
120
|
when: (err) => err instanceof McpError,
|
|
99
121
|
reads: () => ({ kind: "protocol" }),
|
|
100
122
|
},
|
|
123
|
+
{
|
|
124
|
+
name: "http endpoint refused the authorization",
|
|
125
|
+
when: (err) => err instanceof StreamableHTTPError && (err.code === 401 || err instanceof PeerAuthorizationRefused),
|
|
126
|
+
reads: (err) => err instanceof PeerAuthorizationRefused
|
|
127
|
+
? { kind: "unauthorized", authorization: authorizationOf(err.reason, err.authorizeUrl, err.resourceMetadataUrl) }
|
|
128
|
+
: { kind: "unauthorized", authorization: { reason: "rejected" } },
|
|
129
|
+
},
|
|
101
130
|
{
|
|
102
131
|
name: "http endpoint answered a status",
|
|
103
132
|
when: (err) => err instanceof StreamableHTTPError && typeof err.code === "number" && err.code > 0,
|
|
@@ -151,9 +180,37 @@ export const FAILURE_CLASSIFIER = [
|
|
|
151
180
|
},
|
|
152
181
|
];
|
|
153
182
|
export function classifyMcpFailure(err, at) {
|
|
154
|
-
|
|
183
|
+
return readMcpFailure(err, at).failure;
|
|
184
|
+
}
|
|
185
|
+
export function readMcpFailure(err, at) {
|
|
186
|
+
const { unsent, ...read } = classOf(err, at);
|
|
155
187
|
const dialled = at.phase === "connect" && !CONNECT_KEEPS_THE_TABLE_VERDICT.has(read.kind);
|
|
156
|
-
return { ...read, delivered: dialled ? "no" : DELIVERED_BY_KIND[read.kind] };
|
|
188
|
+
return { failure: { ...read, delivered: unsent === true || dialled ? "no" : DELIVERED_BY_KIND[read.kind] }, exchange: unsent === true ? "unsent" : read.kind };
|
|
189
|
+
}
|
|
190
|
+
function authorizationOf(reason, authorizeUrl, resourceMetadataUrl) {
|
|
191
|
+
return { reason, ...(authorizeUrl !== undefined ? { authorizeUrl } : {}), ...(resourceMetadataUrl !== undefined ? { resourceMetadataUrl } : {}) };
|
|
192
|
+
}
|
|
193
|
+
export function whereToAuthorize(authorizeUrl) {
|
|
194
|
+
return authorizeUrl !== undefined ? `at ${authorizeUrl}` : "through the deployment's connector settings";
|
|
195
|
+
}
|
|
196
|
+
export function needsAuthorizationArm(entries, max) {
|
|
197
|
+
const named = entries.filter((f) => f.authorization !== undefined);
|
|
198
|
+
if (named.length === 0)
|
|
199
|
+
return undefined;
|
|
200
|
+
const withUrl = named.filter((f) => f.authorization?.authorizeUrl !== undefined).length;
|
|
201
|
+
const where = withUrl === named.length ? "at the address listed beside it" : withUrl === 0 ? whereToAuthorize(undefined) : `at the address listed beside it, or, for a server listed without one, ${whereToAuthorize(undefined)}`;
|
|
202
|
+
const lines = named.slice(0, max).map((f) => `${f.name}${f.authorization?.authorizeUrl !== undefined ? ` — authorize ${whereToAuthorize(f.authorization.authorizeUrl)}` : ""}`);
|
|
203
|
+
return (`The following MCP servers require authentication before their tools can be used:\n${lines.join("\n")}${named.length > max ? `\n…and ${named.length - max} more` : ""}\n\n` +
|
|
204
|
+
`You cannot start the authorization flow yourself. If the user's request depends on one of these servers (even if they didn't name it explicitly), ` +
|
|
205
|
+
`or they ask about it, tell them that it needs to be authorized — ${where} — and that the capability is unavailable until they do. ` +
|
|
206
|
+
`Otherwise carry on with the request and do not mention these servers. Do not ask the user for authorization codes, tokens, or callback URLs.`);
|
|
207
|
+
}
|
|
208
|
+
export function unauthorizedLine(what, serverLabel, a, renewed, writeTail) {
|
|
209
|
+
const owed = `The user needs to authorize this server${a.reason === "scope" ? " for the access this request needs" : ""} ${whereToAuthorize(a.authorizeUrl)}; its capability is unavailable until they do. Do not ask the user for authorization codes, tokens, or callback URLs.`;
|
|
210
|
+
if (a.reason === "none")
|
|
211
|
+
return `${what} was not sent to MCP server "${serverLabel}": the deployment holds no authorization of this user for it. ${owed} The request was not delivered, so the server did not execute it.`;
|
|
212
|
+
const refused = `${what} on MCP server "${serverLabel}" was refused ${a.reason === "scope" ? "for insufficient scope (HTTP 403)" : "as unauthorized (HTTP 401)"}`;
|
|
213
|
+
return renewed ? `${refused}; the deployment has since answered another credential, which a new call carries — this call was not sent again. If that call is refused too: ${owed}${writeTail}` : `${refused}. ${owed}${writeTail}`;
|
|
157
214
|
}
|
|
158
215
|
function classOf(err, at) {
|
|
159
216
|
for (const rule of FAILURE_CLASSIFIER)
|
|
@@ -185,6 +242,7 @@ export function describeHttpTransportFailure(err, at = { phase: "request" }) {
|
|
|
185
242
|
case "connection_failed":
|
|
186
243
|
return { condition: `the connection to its HTTP endpoint failed (${networkErrorCode(err)})`, delivered: f.delivered };
|
|
187
244
|
case "connection_closed":
|
|
245
|
+
case "unauthorized":
|
|
188
246
|
case "spawn_failed":
|
|
189
247
|
case "timeout":
|
|
190
248
|
case "protocol":
|
|
@@ -13,7 +13,16 @@
|
|
|
13
13
|
* replacement, so a late 404 never closes a connection other calls have moved to.
|
|
14
14
|
*/
|
|
15
15
|
import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
|
|
16
|
-
import type
|
|
16
|
+
import { type McpAuthorization, type McpExchangeOutcome, type McpFailure, type McpFailureSite } from "./mcp-failure.js";
|
|
17
|
+
/**
|
|
18
|
+
* One request failure, read once and told to the server's two writers: its reach ({@link ServerHealth.observe}) always, and — when
|
|
19
|
+
* `answer` (this failure is the request's answer: the lane sends nothing again) — the authorization the user owes
|
|
20
|
+
* ({@link ServerHealth.owed}). Returns the record.
|
|
21
|
+
*/
|
|
22
|
+
export declare function observedFailure(err: unknown, site: McpFailureSite, health: ServerHealth | undefined, answer: boolean): McpFailure;
|
|
23
|
+
/** A tool call's FINAL failure (the translated error, whose `details` is the record the one reading stamped) tells the server's
|
|
24
|
+
* announcer what the user owes — the call lane's one announcement, made once its attempts are over. */
|
|
25
|
+
export declare function owedByAnswer(err: unknown, health: ServerHealth): void;
|
|
17
26
|
/** Mutable per-server liveness flag, shared between a server's tool closures and its transport-close hook.
|
|
18
27
|
* `pendingElicitations` (RB-199 FO-1 codex review): a live count of in-flight `onElicit` waits on THIS
|
|
19
28
|
* server — the idle watchdog ({@link armMcpIdleWatchdog}) reads it before aborting a call (incremented when the wait starts,
|
|
@@ -37,6 +46,9 @@ export interface ServerHealth {
|
|
|
37
46
|
* outage either, and the in-flight calls it fails belong to a connection we chose to replace.
|
|
38
47
|
*/
|
|
39
48
|
observe?: (outcome: McpExchangeOutcome) => void;
|
|
49
|
+
/** The other thing a request can learn: its ANSWER was a refusal as `unauthorized`, so the user owes this authorization — the
|
|
50
|
+
* materialization's once-per-server announcer, filled by the merge stage beside `observe` (the same lifecycle silence applies). */
|
|
51
|
+
owed?: (authorization: McpAuthorization) => void;
|
|
40
52
|
pendingElicitations: number;
|
|
41
53
|
/** Stamped on EVERY
|
|
42
54
|
* elicitation close (finally, unconditional — not just when the count returns to 0). Closes a race
|
|
@@ -156,6 +168,15 @@ export declare class Resendable {
|
|
|
156
168
|
* {@link McpListingRefusal} answer only a call that was never sent.
|
|
157
169
|
*/
|
|
158
170
|
export declare function callThroughLink<R extends object>(link: McpServerLink, name: string, gate: string, signal: AbortSignal | undefined, send: (on: McpLiveConnection, resent: boolean) => Promise<R | Resendable>, gone: () => never): Promise<R | McpListingRefusal>;
|
|
171
|
+
/** What judges a call a refusal turned away: the live connection's listing, the operator's revocation list, the declaration a tool was mounted with. */
|
|
172
|
+
export type RefusalJudge = "listing" | "revocation" | "declaration";
|
|
173
|
+
/**
|
|
174
|
+
* THE closing sentence of an MCP call refused before it was sent: what the refusal covers (this call) and what judges a later call,
|
|
175
|
+
* never how that call will come out — a host's re-dial, refresh or un-revoke lands between two calls, and the call after it is
|
|
176
|
+
* judged against what it took. The listing's refusal, a revoked server's four outlets and the task-required one end with it; no
|
|
177
|
+
* site words it again. (A server whose transport is gone has its own text, `throwDeadServer`.)
|
|
178
|
+
*/
|
|
179
|
+
export declare function refusalScope(judge: RefusalJudge): string;
|
|
159
180
|
/** The answer to a call {@link reach} refused before it was sent: the pre-send refusal record (`delivered: "no"`; `code` beside `error`, as the revocation refusal's). */
|
|
160
181
|
export declare function listingRefusal(refusal: McpListingRefusal, remoteName: string, server: string): {
|
|
161
182
|
content: Array<{
|
|
@@ -1,5 +1,20 @@
|
|
|
1
|
+
import { readMcpFailure } from "./mcp-failure.js";
|
|
1
2
|
import { UNPROVEN_GATE } from "./mcp-listing-drift.js";
|
|
3
|
+
import { readMember } from "./thrown-value.js";
|
|
2
4
|
import { inlineUntrusted } from "./untrusted-text.js";
|
|
5
|
+
export function observedFailure(err, site, health, answer) {
|
|
6
|
+
const { failure, exchange } = readMcpFailure(err, site);
|
|
7
|
+
health?.observe?.(exchange);
|
|
8
|
+
if (answer && failure.authorization !== undefined)
|
|
9
|
+
health?.owed?.(failure.authorization);
|
|
10
|
+
return failure;
|
|
11
|
+
}
|
|
12
|
+
export function owedByAnswer(err, health) {
|
|
13
|
+
const details = readMember(err, "details");
|
|
14
|
+
const a = readMember(details, "code") === "unauthorized" ? readMember(details, "authorization") : undefined;
|
|
15
|
+
if (typeof a === "object" && a !== null)
|
|
16
|
+
health.owed?.(a);
|
|
17
|
+
}
|
|
3
18
|
export const IDLE_WATCHDOG_ABORT_REASON = Symbol("mcp-idle-watchdog-abort");
|
|
4
19
|
export function armMcpIdleWatchdog(health, idleMs, outerSignal) {
|
|
5
20
|
const idleController = new AbortController();
|
|
@@ -89,11 +104,20 @@ export async function callThroughLink(link, name, gate, signal, send, gone) {
|
|
|
89
104
|
throw again.error;
|
|
90
105
|
return again;
|
|
91
106
|
}
|
|
107
|
+
const REFUSAL_JUDGES = {
|
|
108
|
+
listing: { rule: "each later call to this tool is checked again against the connection's latest listing", standing: "" },
|
|
109
|
+
revocation: { rule: "each later call to this server is checked again against the operator's current revocation list", standing: "This server stays on this run's tool roster. " },
|
|
110
|
+
declaration: { rule: "each later call to this tool is judged by the declaration of the listing it was mounted from, until a refresh or reconnect of the server mints the tool anew", standing: "" },
|
|
111
|
+
};
|
|
112
|
+
export function refusalScope(judge) {
|
|
113
|
+
const j = REFUSAL_JUDGES[judge];
|
|
114
|
+
return `${j.standing}This refusal is for this call only: ${j.rule}.`;
|
|
115
|
+
}
|
|
92
116
|
export function listingRefusal(refusal, remoteName, server) {
|
|
93
117
|
const changed = refusal === "changed";
|
|
94
118
|
const code = changed ? "mcp.tool_declaration_changed" : "mcp.tool_listing_unreached";
|
|
95
119
|
return {
|
|
96
|
-
content: [{ type: "text", text: `The call to tool ${inlineUntrusted(remoteName)} was refused before it was sent: MCP server "${inlineUntrusted(server)}" ${changed ? "no longer declares this tool the way it was mounted (its safety declaration changed, or a complete listing no longer lists it)" : "has not listed this tool since it was reconnected (the re-listing stopped before it reached the tool), so whether the server still declares it the way it was mounted is unknown"}. The server did not execute it.
|
|
120
|
+
content: [{ type: "text", text: `The call to tool ${inlineUntrusted(remoteName)} was refused before it was sent: MCP server "${inlineUntrusted(server)}" ${changed ? "no longer declares this tool the way it was mounted (its safety declaration changed, or a complete listing no longer lists it)" : "has not listed this tool since it was reconnected (the re-listing stopped before it reached the tool), so whether the server still declares it the way it was mounted is unknown"}. The server did not execute it. ${refusalScope("listing")}` }],
|
|
97
121
|
details: { error: code, code, delivered: "no", server },
|
|
98
122
|
terminate: false,
|
|
99
123
|
isError: true,
|
package/dist/core/mcp.d.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { type PeerSeat } from "./peer-seat.js";
|
|
2
2
|
import { type McpInstructionsEntry, type PromptSectionDisposer } from "./prompt-section-seat.js";
|
|
3
3
|
import { McpConnectionPool } from "./mcp-connection-pool.js";
|
|
4
|
-
import { type McpDelivered, type McpFailureKind, type McpServerLiveness } from "./mcp-failure.js";
|
|
4
|
+
import { type McpAuthorization, type McpDelivered, type McpFailureKind, type McpServerLiveness } from "./mcp-failure.js";
|
|
5
5
|
import type { AgentTool } from "../internal/harness-types.js";
|
|
6
6
|
import type { ImageContent, TextContent } from "../internal/llm.js";
|
|
7
7
|
import { type McpImageResizer } from "./image-downsample.js";
|
|
@@ -312,8 +312,8 @@ export interface McpReconnectResult {
|
|
|
312
312
|
* what the run handle's verb forwards to `onError(phase:"mcp")`. One production, two drains. */
|
|
313
313
|
warnings?: string[];
|
|
314
314
|
/** The NEW connect-time status record (also swapped into {@link MaterializedMcp.statuses}), present
|
|
315
|
-
* whenever the dial was attempted: a consumer keys its next action off `errorCode` / `
|
|
316
|
-
* (
|
|
315
|
+
* whenever the dial was attempted: a consumer keys its next action off `errorCode` / `authorization`
|
|
316
|
+
* (an `unauthorized` is the user's authorization door, a `spawn_failed` a missing binary), not off {@link reason}. */
|
|
317
317
|
status?: McpServerStatus;
|
|
318
318
|
/** The re-dial's own `tools/list` walk did not finish — {@link McpRefreshResult.listingIncomplete}
|
|
319
319
|
* minus the retention arm: a re-dial has no previous listing on this connection to retain from. */
|
|
@@ -334,13 +334,16 @@ export interface McpServerStatus {
|
|
|
334
334
|
};
|
|
335
335
|
toolNames?: string[];
|
|
336
336
|
error?: string;
|
|
337
|
-
/** Present iff `status === "failed"` — the connect-time failure record, spread flat
|
|
338
|
-
* as `errorCode`, {@link McpFailure.delivered} as `delivered`,
|
|
339
|
-
* `
|
|
337
|
+
/** Present iff `status === "failed"` — the connect-time failure record, spread flat ({@link import("./mcp-failure.js").failureFields}):
|
|
338
|
+
* {@link McpFailure.kind} as `errorCode`, {@link McpFailure.delivered} as `delivered`, `httpStatus` when the kind is `http_status`,
|
|
339
|
+
* `authorization` when it is `unauthorized`. A consumer keys an action off THESE (an `unauthorized` is the user's authorization door,
|
|
340
340
|
* a `spawn_failed` is a missing binary) instead of parsing the neutralized `error` text. */
|
|
341
341
|
errorCode?: McpFailureKind;
|
|
342
342
|
delivered?: McpDelivered;
|
|
343
343
|
httpStatus?: number;
|
|
344
|
+
/** {@link McpFailure.authorization}: why the principal must authorize this server and where — present iff `errorCode === "unauthorized"`.
|
|
345
|
+
* `authorizeUrl` is the deployment seat's (TRUSTED); `resourceMetadataUrl` is the endpoint's own claim (UNTRUSTED, like `error`). */
|
|
346
|
+
authorization?: McpAuthorization;
|
|
344
347
|
/**
|
|
345
348
|
* Set to `true` once core OBSERVES this server's transport close during the task; absent
|
|
346
349
|
* otherwise (never `false`: absence means "no close was observed", which is not the same as "alive").
|
|
@@ -606,10 +609,11 @@ reminderDisclosure?: {
|
|
|
606
609
|
}, poolOpts?: {
|
|
607
610
|
pool: McpConnectionPool;
|
|
608
611
|
ownsPool?: boolean;
|
|
609
|
-
}, promptSections?: PromptSectionDisposer, dialable?: (spec: McpServerSpec) => boolean, signal?: AbortSignal, hostFloor?: HostFloor, peerSeat?: PeerSeat):
|
|
612
|
+
}, promptSections?: PromptSectionDisposer, dialable?: (spec: McpServerSpec) => boolean, signal?: AbortSignal, hostFloor?: HostFloor, peerSeat?: PeerSeat, // `RunnerDeps.peerSeat` (peer-seat.ts): what each request carries; absent ⇒ nothing, and a declared `credentials` refuses that dial
|
|
613
|
+
onAuthorizationRequired?: (server: string, authorization: McpAuthorization) => void): Promise<MaterializedMcp>;
|
|
610
614
|
/** The runner's materialization of one leg (not index-exported): every minted tool's `tools/call` reads the leg's request-meta seat
|
|
611
615
|
* (`mcp-call-meta.ts`) — the request meta's only source, written only by the `tool.call` station with what its judge passed. */
|
|
612
|
-
export declare function materializeLegMcpTools(seat: McpLegMetaReader | undefined, ...[specs, principal, onElicit, imageResizer, reminderDisclosure, mcpRevocations, poolOpts, promptSections, dialable, signal, hostFloor, peerSeat]: Parameters<typeof materializeMcpTools>): Promise<MaterializedMcp>;
|
|
616
|
+
export declare function materializeLegMcpTools(seat: McpLegMetaReader | undefined, ...[specs, principal, onElicit, imageResizer, reminderDisclosure, mcpRevocations, poolOpts, promptSections, dialable, signal, hostFloor, peerSeat, onAuthorizationRequired]: Parameters<typeof materializeMcpTools>): Promise<MaterializedMcp>;
|
|
613
617
|
/**
|
|
614
618
|
* Fold the caller's AUTHORITATIVE per-tool override (design F: caller = trust root) over the server-hint axis.
|
|
615
619
|
* Unlike server hints, the caller may RAISE or LOWER any axis: `effect` sets the repeat-safety class (lower to
|