@buildanagent/harness 0.0.0-bootstrap.0 → 0.1.0-alpha.28
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/LICENSE +54 -0
- package/LICENSE-APACHE +202 -0
- package/LICENSE-MIT +21 -0
- package/README.md +717 -0
- package/dist/ablation.d.ts +2 -0
- package/dist/ablation.js +3 -0
- package/dist/ablation.js.map +1 -0
- package/dist/completion/check.d.ts +64 -0
- package/dist/completion/check.js +152 -0
- package/dist/completion/check.js.map +1 -0
- package/dist/completion/checks.d.ts +45 -0
- package/dist/completion/checks.js +173 -0
- package/dist/completion/checks.js.map +1 -0
- package/dist/completion/flags.d.ts +25 -0
- package/dist/completion/flags.js +87 -0
- package/dist/completion/flags.js.map +1 -0
- package/dist/completion/index.d.ts +8 -0
- package/dist/completion/index.js +9 -0
- package/dist/completion/index.js.map +1 -0
- package/dist/completion/snapshot.d.ts +33 -0
- package/dist/completion/snapshot.js +83 -0
- package/dist/completion/snapshot.js.map +1 -0
- package/dist/context/cap.d.ts +32 -0
- package/dist/context/cap.js +50 -0
- package/dist/context/cap.js.map +1 -0
- package/dist/context/estimate.d.ts +18 -0
- package/dist/context/estimate.js +20 -0
- package/dist/context/estimate.js.map +1 -0
- package/dist/context/file-spill.d.ts +5 -0
- package/dist/context/file-spill.js +25 -0
- package/dist/context/file-spill.js.map +1 -0
- package/dist/context/index.d.ts +10 -0
- package/dist/context/index.js +10 -0
- package/dist/context/index.js.map +1 -0
- package/dist/context/mask.d.ts +27 -0
- package/dist/context/mask.js +71 -0
- package/dist/context/mask.js.map +1 -0
- package/dist/context/mid-turn.d.ts +40 -0
- package/dist/context/mid-turn.js +82 -0
- package/dist/context/mid-turn.js.map +1 -0
- package/dist/context/policy.d.ts +9 -0
- package/dist/context/policy.js +140 -0
- package/dist/context/policy.js.map +1 -0
- package/dist/context/spill-ledger.d.ts +25 -0
- package/dist/context/spill-ledger.js +54 -0
- package/dist/context/spill-ledger.js.map +1 -0
- package/dist/context/spill.d.ts +6 -0
- package/dist/context/spill.js +14 -0
- package/dist/context/spill.js.map +1 -0
- package/dist/context/summarize.d.ts +53 -0
- package/dist/context/summarize.js +204 -0
- package/dist/context/summarize.js.map +1 -0
- package/dist/context/summary-template.d.ts +29 -0
- package/dist/context/summary-template.js +69 -0
- package/dist/context/summary-template.js.map +1 -0
- package/dist/context/types.d.ts +150 -0
- package/dist/context/types.js +2 -0
- package/dist/context/types.js.map +1 -0
- package/dist/context/write-cap.d.ts +19 -0
- package/dist/context/write-cap.js +41 -0
- package/dist/context/write-cap.js.map +1 -0
- package/dist/create-harness.d.ts +7 -0
- package/dist/create-harness.js +21 -0
- package/dist/create-harness.js.map +1 -0
- package/dist/credentials/addresses.d.ts +14 -0
- package/dist/credentials/addresses.js +144 -0
- package/dist/credentials/addresses.js.map +1 -0
- package/dist/credentials/allowlist.d.ts +34 -0
- package/dist/credentials/allowlist.js +77 -0
- package/dist/credentials/allowlist.js.map +1 -0
- package/dist/credentials/egress-proxy.d.ts +70 -0
- package/dist/credentials/egress-proxy.js +482 -0
- package/dist/credentials/egress-proxy.js.map +1 -0
- package/dist/credentials/index.d.ts +9 -0
- package/dist/credentials/index.js +10 -0
- package/dist/credentials/index.js.map +1 -0
- package/dist/credentials/scrub.d.ts +16 -0
- package/dist/credentials/scrub.js +93 -0
- package/dist/credentials/scrub.js.map +1 -0
- package/dist/errors.d.ts +56 -0
- package/dist/errors.js +63 -0
- package/dist/errors.js.map +1 -0
- package/dist/extensions/compose.d.ts +27 -0
- package/dist/extensions/compose.js +83 -0
- package/dist/extensions/compose.js.map +1 -0
- package/dist/extensions/context-files-node.d.ts +28 -0
- package/dist/extensions/context-files-node.js +74 -0
- package/dist/extensions/context-files-node.js.map +1 -0
- package/dist/extensions/context-files.d.ts +68 -0
- package/dist/extensions/context-files.js +214 -0
- package/dist/extensions/context-files.js.map +1 -0
- package/dist/extensions/digest.d.ts +6 -0
- package/dist/extensions/digest.js +68 -0
- package/dist/extensions/digest.js.map +1 -0
- package/dist/extensions/index.d.ts +10 -0
- package/dist/extensions/index.js +10 -0
- package/dist/extensions/index.js.map +1 -0
- package/dist/extensions/load.d.ts +42 -0
- package/dist/extensions/load.js +211 -0
- package/dist/extensions/load.js.map +1 -0
- package/dist/extensions/lock.d.ts +8 -0
- package/dist/extensions/lock.js +95 -0
- package/dist/extensions/lock.js.map +1 -0
- package/dist/extensions/node.d.ts +10 -0
- package/dist/extensions/node.js +11 -0
- package/dist/extensions/node.js.map +1 -0
- package/dist/extensions/project-dirs.d.ts +24 -0
- package/dist/extensions/project-dirs.js +97 -0
- package/dist/extensions/project-dirs.js.map +1 -0
- package/dist/extensions/skills-node.d.ts +34 -0
- package/dist/extensions/skills-node.js +123 -0
- package/dist/extensions/skills-node.js.map +1 -0
- package/dist/extensions/skills.d.ts +51 -0
- package/dist/extensions/skills.js +175 -0
- package/dist/extensions/skills.js.map +1 -0
- package/dist/extensions/trust-file.d.ts +3 -0
- package/dist/extensions/trust-file.js +62 -0
- package/dist/extensions/trust-file.js.map +1 -0
- package/dist/extensions/trust-store-node.d.ts +10 -0
- package/dist/extensions/trust-store-node.js +33 -0
- package/dist/extensions/trust-store-node.js.map +1 -0
- package/dist/extensions/types.d.ts +42 -0
- package/dist/extensions/types.js +2 -0
- package/dist/extensions/types.js.map +1 -0
- package/dist/harness.d.ts +156 -0
- package/dist/harness.js +2 -0
- package/dist/harness.js.map +1 -0
- package/dist/index.d.ts +4 -0
- package/dist/index.js +5 -0
- package/dist/index.js.map +1 -0
- package/dist/mcp/connection.d.ts +22 -0
- package/dist/mcp/connection.js +267 -0
- package/dist/mcp/connection.js.map +1 -0
- package/dist/mcp/content.d.ts +27 -0
- package/dist/mcp/content.js +177 -0
- package/dist/mcp/content.js.map +1 -0
- package/dist/mcp/errors.d.ts +19 -0
- package/dist/mcp/errors.js +21 -0
- package/dist/mcp/errors.js.map +1 -0
- package/dist/mcp/index.d.ts +10 -0
- package/dist/mcp/index.js +10 -0
- package/dist/mcp/index.js.map +1 -0
- package/dist/mcp/manager.d.ts +7 -0
- package/dist/mcp/manager.js +173 -0
- package/dist/mcp/manager.js.map +1 -0
- package/dist/mcp/record.d.ts +7 -0
- package/dist/mcp/record.js +20 -0
- package/dist/mcp/record.js.map +1 -0
- package/dist/mcp/stdio.d.ts +39 -0
- package/dist/mcp/stdio.js +382 -0
- package/dist/mcp/stdio.js.map +1 -0
- package/dist/mcp/types.d.ts +172 -0
- package/dist/mcp/types.js +2 -0
- package/dist/mcp/types.js.map +1 -0
- package/dist/memory/index.d.ts +2 -0
- package/dist/memory/index.js +3 -0
- package/dist/memory/index.js.map +1 -0
- package/dist/permissions/default-rules.d.ts +7 -0
- package/dist/permissions/default-rules.js +42 -0
- package/dist/permissions/default-rules.js.map +1 -0
- package/dist/permissions/errors.d.ts +11 -0
- package/dist/permissions/errors.js +14 -0
- package/dist/permissions/errors.js.map +1 -0
- package/dist/permissions/index.d.ts +9 -0
- package/dist/permissions/index.js +9 -0
- package/dist/permissions/index.js.map +1 -0
- package/dist/permissions/match.d.ts +33 -0
- package/dist/permissions/match.js +287 -0
- package/dist/permissions/match.js.map +1 -0
- package/dist/permissions/pipeline.d.ts +9 -0
- package/dist/permissions/pipeline.js +235 -0
- package/dist/permissions/pipeline.js.map +1 -0
- package/dist/permissions/rules.d.ts +22 -0
- package/dist/permissions/rules.js +74 -0
- package/dist/permissions/rules.js.map +1 -0
- package/dist/permissions/shadow.d.ts +5 -0
- package/dist/permissions/shadow.js +22 -0
- package/dist/permissions/shadow.js.map +1 -0
- package/dist/permissions/types.d.ts +104 -0
- package/dist/permissions/types.js +2 -0
- package/dist/permissions/types.js.map +1 -0
- package/dist/sandbox/base.d.ts +35 -0
- package/dist/sandbox/base.js +60 -0
- package/dist/sandbox/base.js.map +1 -0
- package/dist/sandbox/docker/index.d.ts +35 -0
- package/dist/sandbox/docker/index.js +448 -0
- package/dist/sandbox/docker/index.js.map +1 -0
- package/dist/sandbox/errors.d.ts +16 -0
- package/dist/sandbox/errors.js +22 -0
- package/dist/sandbox/errors.js.map +1 -0
- package/dist/sandbox/host-files.d.ts +63 -0
- package/dist/sandbox/host-files.js +248 -0
- package/dist/sandbox/host-files.js.map +1 -0
- package/dist/sandbox/index.d.ts +8 -0
- package/dist/sandbox/index.js +8 -0
- package/dist/sandbox/index.js.map +1 -0
- package/dist/sandbox/none.d.ts +17 -0
- package/dist/sandbox/none.js +108 -0
- package/dist/sandbox/none.js.map +1 -0
- package/dist/sandbox/process.d.ts +61 -0
- package/dist/sandbox/process.js +253 -0
- package/dist/sandbox/process.js.map +1 -0
- package/dist/sandbox/spawn-env.d.ts +20 -0
- package/dist/sandbox/spawn-env.js +128 -0
- package/dist/sandbox/spawn-env.js.map +1 -0
- package/dist/sandbox/srt/index.d.ts +35 -0
- package/dist/sandbox/srt/index.js +264 -0
- package/dist/sandbox/srt/index.js.map +1 -0
- package/dist/sandbox/srt/settings.d.ts +48 -0
- package/dist/sandbox/srt/settings.js +31 -0
- package/dist/sandbox/srt/settings.js.map +1 -0
- package/dist/sandbox/types.d.ts +88 -0
- package/dist/sandbox/types.js +6 -0
- package/dist/sandbox/types.js.map +1 -0
- package/dist/server/answers.d.ts +16 -0
- package/dist/server/answers.js +43 -0
- package/dist/server/answers.js.map +1 -0
- package/dist/server/connection.d.ts +99 -0
- package/dist/server/connection.js +309 -0
- package/dist/server/connection.js.map +1 -0
- package/dist/server/dispatcher.d.ts +86 -0
- package/dist/server/dispatcher.js +800 -0
- package/dist/server/dispatcher.js.map +1 -0
- package/dist/server/index.d.ts +13 -0
- package/dist/server/index.js +12 -0
- package/dist/server/index.js.map +1 -0
- package/dist/server/local-transport.d.ts +44 -0
- package/dist/server/local-transport.js +103 -0
- package/dist/server/local-transport.js.map +1 -0
- package/dist/server/outbox.d.ts +31 -0
- package/dist/server/outbox.js +130 -0
- package/dist/server/outbox.js.map +1 -0
- package/dist/server/params.d.ts +25 -0
- package/dist/server/params.js +112 -0
- package/dist/server/params.js.map +1 -0
- package/dist/server/protocol.schema.json +2448 -0
- package/dist/server/rpc-session.d.ts +43 -0
- package/dist/server/rpc-session.js +167 -0
- package/dist/server/rpc-session.js.map +1 -0
- package/dist/server/stdio-streams.d.ts +67 -0
- package/dist/server/stdio-streams.js +218 -0
- package/dist/server/stdio-streams.js.map +1 -0
- package/dist/server/stdio.d.ts +59 -0
- package/dist/server/stdio.js +189 -0
- package/dist/server/stdio.js.map +1 -0
- package/dist/server/websocket.d.ts +106 -0
- package/dist/server/websocket.js +327 -0
- package/dist/server/websocket.js.map +1 -0
- package/dist/session/approvals.d.ts +81 -0
- package/dist/session/approvals.js +217 -0
- package/dist/session/approvals.js.map +1 -0
- package/dist/session/code-call-log.d.ts +42 -0
- package/dist/session/code-call-log.js +63 -0
- package/dist/session/code-call-log.js.map +1 -0
- package/dist/session/code-call-result.d.ts +19 -0
- package/dist/session/code-call-result.js +95 -0
- package/dist/session/code-call-result.js.map +1 -0
- package/dist/session/code-call.d.ts +49 -0
- package/dist/session/code-call.js +345 -0
- package/dist/session/code-call.js.map +1 -0
- package/dist/session/effect-scope.d.ts +11 -0
- package/dist/session/effect-scope.js +10 -0
- package/dist/session/effect-scope.js.map +1 -0
- package/dist/session/errors.d.ts +19 -0
- package/dist/session/errors.js +27 -0
- package/dist/session/errors.js.map +1 -0
- package/dist/session/file-index.d.ts +8 -0
- package/dist/session/file-index.js +70 -0
- package/dist/session/file-index.js.map +1 -0
- package/dist/session/file-key-store.d.ts +16 -0
- package/dist/session/file-key-store.js +169 -0
- package/dist/session/file-key-store.js.map +1 -0
- package/dist/session/file-lock.d.ts +52 -0
- package/dist/session/file-lock.js +324 -0
- package/dist/session/file-lock.js.map +1 -0
- package/dist/session/index.d.ts +22 -0
- package/dist/session/index.js +20 -0
- package/dist/session/index.js.map +1 -0
- package/dist/session/jsonl-store.d.ts +37 -0
- package/dist/session/jsonl-store.js +386 -0
- package/dist/session/jsonl-store.js.map +1 -0
- package/dist/session/jsonl.d.ts +9 -0
- package/dist/session/jsonl.js +10 -0
- package/dist/session/jsonl.js.map +1 -0
- package/dist/session/lock.d.ts +19 -0
- package/dist/session/lock.js +2 -0
- package/dist/session/lock.js.map +1 -0
- package/dist/session/memory-store.d.ts +12 -0
- package/dist/session/memory-store.js +60 -0
- package/dist/session/memory-store.js.map +1 -0
- package/dist/session/migrate.d.ts +41 -0
- package/dist/session/migrate.js +86 -0
- package/dist/session/migrate.js.map +1 -0
- package/dist/session/pointer.d.ts +15 -0
- package/dist/session/pointer.js +22 -0
- package/dist/session/pointer.js.map +1 -0
- package/dist/session/rebuild.d.ts +53 -0
- package/dist/session/rebuild.js +230 -0
- package/dist/session/rebuild.js.map +1 -0
- package/dist/session/resume.d.ts +26 -0
- package/dist/session/resume.js +128 -0
- package/dist/session/resume.js.map +1 -0
- package/dist/session/retention.d.ts +97 -0
- package/dist/session/retention.js +702 -0
- package/dist/session/retention.js.map +1 -0
- package/dist/session/runner.d.ts +156 -0
- package/dist/session/runner.js +656 -0
- package/dist/session/runner.js.map +1 -0
- package/dist/session/scheduler.d.ts +47 -0
- package/dist/session/scheduler.js +85 -0
- package/dist/session/scheduler.js.map +1 -0
- package/dist/session/secret-key-store.d.ts +47 -0
- package/dist/session/secret-key-store.js +79 -0
- package/dist/session/secret-key-store.js.map +1 -0
- package/dist/session/session.d.ts +106 -0
- package/dist/session/session.js +353 -0
- package/dist/session/session.js.map +1 -0
- package/dist/session/sticky.d.ts +48 -0
- package/dist/session/sticky.js +232 -0
- package/dist/session/sticky.js.map +1 -0
- package/dist/session/store.d.ts +108 -0
- package/dist/session/store.js +163 -0
- package/dist/session/store.js.map +1 -0
- package/dist/telemetry/index.d.ts +2 -0
- package/dist/telemetry/index.js +3 -0
- package/dist/telemetry/index.js.map +1 -0
- package/dist/testing/fake-sandbox.d.ts +34 -0
- package/dist/testing/fake-sandbox.js +221 -0
- package/dist/testing/fake-sandbox.js.map +1 -0
- package/dist/testing/index.d.ts +10 -0
- package/dist/testing/index.js +11 -0
- package/dist/testing/index.js.map +1 -0
- package/dist/testing/key-store-conformance.d.ts +22 -0
- package/dist/testing/key-store-conformance.js +97 -0
- package/dist/testing/key-store-conformance.js.map +1 -0
- package/dist/testing/run-cases.d.ts +21 -0
- package/dist/testing/run-cases.js +20 -0
- package/dist/testing/run-cases.js.map +1 -0
- package/dist/testing/sandbox-conformance.d.ts +64 -0
- package/dist/testing/sandbox-conformance.js +361 -0
- package/dist/testing/sandbox-conformance.js.map +1 -0
- package/dist/testing/scheduler-conformance.d.ts +32 -0
- package/dist/testing/scheduler-conformance.js +72 -0
- package/dist/testing/scheduler-conformance.js.map +1 -0
- package/dist/testing/store-conformance.d.ts +21 -0
- package/dist/testing/store-conformance.js +320 -0
- package/dist/testing/store-conformance.js.map +1 -0
- package/dist/tools/errors.d.ts +13 -0
- package/dist/tools/errors.js +17 -0
- package/dist/tools/errors.js.map +1 -0
- package/dist/tools/index.d.ts +8 -0
- package/dist/tools/index.js +8 -0
- package/dist/tools/index.js.map +1 -0
- package/dist/tools/registry.d.ts +3 -0
- package/dist/tools/registry.js +234 -0
- package/dist/tools/registry.js.map +1 -0
- package/dist/tools/tool-search.d.ts +30 -0
- package/dist/tools/tool-search.js +118 -0
- package/dist/tools/tool-search.js.map +1 -0
- package/dist/tools/types.d.ts +106 -0
- package/dist/tools/types.js +2 -0
- package/dist/tools/types.js.map +1 -0
- package/llms.txt +435 -0
- package/package.json +119 -5
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The harness's types: the settings every turn of a harness shares, and the code calls it runs. A turn can override the
|
|
3
|
+
* model, the system prompt and the tools; what it can't override, such as the registry and the permission pipeline, is
|
|
4
|
+
* fixed here. `H` is the type of the per-turn host context, which reaches a tool's `execute` as `ctx.app` and is in no
|
|
5
|
+
* request, event or saved entry. `createHarness()` lives in its own module, because it binds the code-call runner,
|
|
6
|
+
* which imports these types.
|
|
7
|
+
*/
|
|
8
|
+
import type { Model } from "@buildanagent/gateway";
|
|
9
|
+
import type { ApprovalPolicy, PermissionMode, SandboxTier } from "@buildanagent/protocol";
|
|
10
|
+
import type { ApprovalSigner, Interceptors, Observer, SignedPendingRequest, ToolResult } from "@buildanagent/sdk";
|
|
11
|
+
import type { Clock } from "@buildanagent/sdk/testing";
|
|
12
|
+
import type { ContextPolicy } from "./context/types.js";
|
|
13
|
+
import type { Skill } from "./extensions/skills.js";
|
|
14
|
+
import type { ExtensionLoadedRecord } from "./extensions/types.js";
|
|
15
|
+
import type { PermissionPipeline } from "./permissions/types.js";
|
|
16
|
+
import type { Session } from "./session/session.js";
|
|
17
|
+
import type { ToolRegistry, ToolWrapper } from "./tools/types.js";
|
|
18
|
+
/** What the session's `env_stamp` records about where the turns run. */
|
|
19
|
+
export interface HarnessEnv {
|
|
20
|
+
readonly cwd: string;
|
|
21
|
+
readonly permissionMode: PermissionMode;
|
|
22
|
+
readonly approvalPolicy: ApprovalPolicy;
|
|
23
|
+
readonly sandbox: SandboxTier;
|
|
24
|
+
}
|
|
25
|
+
/** The options of `createHarness()`. */
|
|
26
|
+
export interface HarnessOptions<H = unknown> {
|
|
27
|
+
readonly registry: ToolRegistry;
|
|
28
|
+
/** The model a turn uses unless it names another. */
|
|
29
|
+
readonly model: Model;
|
|
30
|
+
/** The system prompt a turn uses unless it names another. */
|
|
31
|
+
readonly system: string;
|
|
32
|
+
/** What `env_stamp` records. A field left out takes `/`, `default`, `on-request` or `none`. */
|
|
33
|
+
readonly env?: Partial<HarnessEnv>;
|
|
34
|
+
/**
|
|
35
|
+
* The tenant a write acts for: one tenant is one user, so a business key never spans two users. Default `local`,
|
|
36
|
+
* for a host that has one user. `effectScope()` puts it in the scope a guarded write takes.
|
|
37
|
+
*/
|
|
38
|
+
readonly tenant?: string;
|
|
39
|
+
/** The harness's version, stamped into each session header. */
|
|
40
|
+
readonly harnessVersion?: string;
|
|
41
|
+
/** A hash of the ablation switches, stamped into each session header. Default `none`. */
|
|
42
|
+
readonly ablationHash?: string;
|
|
43
|
+
/** When set, its gate decides every tool call, and each decision is written to the log. */
|
|
44
|
+
readonly pipeline?: PermissionPipeline;
|
|
45
|
+
/**
|
|
46
|
+
* Hooks that run with the pipeline's gate in every turn, before it for a gate, as `composeInterceptors()` orders
|
|
47
|
+
* them. A code call from `invokeTool()` runs no turn, so they don't see it.
|
|
48
|
+
*/
|
|
49
|
+
readonly interceptors?: Interceptors;
|
|
50
|
+
/** The context layers every turn runs through, from `createContextPolicy()`. Without one a turn sends its whole transcript. */
|
|
51
|
+
readonly context?: ContextPolicy;
|
|
52
|
+
/**
|
|
53
|
+
* The extensions this harness runs, as `recordsOf()` or `loadProjectExtensions()` gives them. A turn writes an
|
|
54
|
+
* `extension_loaded` entry for each the session's log does not hold yet, so a session shows which code ran.
|
|
55
|
+
*/
|
|
56
|
+
readonly extensionRecords?: readonly ExtensionLoadedRecord[];
|
|
57
|
+
/**
|
|
58
|
+
* The skills the system prompt lists, as `discoverSkills()` gives them. When a successful `read` call opens the whole
|
|
59
|
+
* of one's `SKILL.md`, with no `offset` or `limit`, the turn writes a `skill_loaded` entry. Relative paths in the call
|
|
60
|
+
* resolve against `env.cwd`.
|
|
61
|
+
*/
|
|
62
|
+
readonly skills?: readonly Skill[];
|
|
63
|
+
/** Observers that see every event of every turn, after the runner's own. A code call emits no events. */
|
|
64
|
+
readonly observers?: readonly Observer[];
|
|
65
|
+
/** Binds a tool to the turn's host context, such as a write cap. A tool can also read it as `ctx.app`. */
|
|
66
|
+
readonly wrap?: ToolWrapper<H>;
|
|
67
|
+
/** Signs the pauses a turn ends in. */
|
|
68
|
+
readonly signer?: ApprovalSigner;
|
|
69
|
+
}
|
|
70
|
+
/** A tool call that the host's own code makes with `Harness.invokeTool()`, with no model step. */
|
|
71
|
+
export interface CodeCall<H = unknown> {
|
|
72
|
+
/** The tool's name or alias in the registry. */
|
|
73
|
+
readonly tool: string;
|
|
74
|
+
/** The input the tool runs with. It is recorded and hashed as given, so it must have a canonical JSON form. */
|
|
75
|
+
readonly input: unknown;
|
|
76
|
+
/**
|
|
77
|
+
* The host context the tool runs with, as `ctx.app`. A call that asks for a person binds a MAC of it into the signed
|
|
78
|
+
* request, so `Approvals.resolve()` runs the call only when it is given the same host context.
|
|
79
|
+
*/
|
|
80
|
+
readonly hostContext?: H;
|
|
81
|
+
/**
|
|
82
|
+
* The call id of an earlier code call that this one undoes. The earlier call must have run, and this call must reach
|
|
83
|
+
* an effect key of its own. The `code_call` entry records the link.
|
|
84
|
+
*/
|
|
85
|
+
readonly compensates?: string;
|
|
86
|
+
/** Aborts the call. An aborted signal before the call starts writes nothing; the tool receives it as `ctx.signal`. */
|
|
87
|
+
readonly signal?: AbortSignal;
|
|
88
|
+
/** The clock of the entries, the signed request and the tool's `ctx.clock`. Default the system clock. */
|
|
89
|
+
readonly clock?: Clock;
|
|
90
|
+
/** Makes the ids of the entries, the call and the signed request. Default `crypto.randomUUID()`. */
|
|
91
|
+
readonly newId?: () => string;
|
|
92
|
+
}
|
|
93
|
+
/**
|
|
94
|
+
* What a code call ended in.
|
|
95
|
+
*
|
|
96
|
+
* - `done`: the tool ran. `result` is the whole of what it returned, with a write outcome's sentence in front of its
|
|
97
|
+
* content, even when the call's `tool_result` entry holds it capped.
|
|
98
|
+
* - `denied`: the permission pipeline or a person refused the call. The tool never ran.
|
|
99
|
+
* - `awaiting_approval`: a person must answer `pending` through `Approvals.resolve()`. It has no `entryId`.
|
|
100
|
+
*
|
|
101
|
+
* `entryId` is the id of the call's `tool_result` entry. `effectKey` is the call's effect identity: from the tool's
|
|
102
|
+
* business key when it declares one, and otherwise from the call id, which is the id of the call's `code_call` entry.
|
|
103
|
+
*/
|
|
104
|
+
export type CodeCallResult = {
|
|
105
|
+
readonly status: "done";
|
|
106
|
+
readonly callId: string;
|
|
107
|
+
readonly result: ToolResult<unknown>;
|
|
108
|
+
readonly entryId: string;
|
|
109
|
+
readonly effectKey: string;
|
|
110
|
+
} | {
|
|
111
|
+
readonly status: "denied";
|
|
112
|
+
readonly callId: string;
|
|
113
|
+
readonly reason: string;
|
|
114
|
+
readonly entryId: string;
|
|
115
|
+
} | {
|
|
116
|
+
readonly status: "awaiting_approval";
|
|
117
|
+
readonly callId: string;
|
|
118
|
+
readonly pending: SignedPendingRequest;
|
|
119
|
+
readonly effectKey: string;
|
|
120
|
+
};
|
|
121
|
+
/** A harness: its options with the defaults filled in. */
|
|
122
|
+
export interface Harness<H = unknown> extends HarnessOptions<H> {
|
|
123
|
+
readonly env: HarnessEnv;
|
|
124
|
+
readonly tenant: string;
|
|
125
|
+
readonly harnessVersion: string;
|
|
126
|
+
readonly ablationHash: string;
|
|
127
|
+
/**
|
|
128
|
+
* Runs a tool call that the host's own code chose, through the same permission pipeline, signed pause and log as a
|
|
129
|
+
* call the model makes, with no model call. The session must be open with its lock.
|
|
130
|
+
*
|
|
131
|
+
* The call's own entries start with a `code_call` entry, then the pipeline's `permission_decision`. Before them it
|
|
132
|
+
* writes what the session lacks: a new session's header and environment stamp, and a result for each earlier code
|
|
133
|
+
* call a crash left open.
|
|
134
|
+
*
|
|
135
|
+
* The call ends one of three ways:
|
|
136
|
+
*
|
|
137
|
+
* - An allow runs the tool through the harness's `wrap` with `call.hostContext`, writes its `tool_result` and returns
|
|
138
|
+
* `done`. The harness's `context` policy caps the stored result, and the store's entry bound cuts it to fit, with
|
|
139
|
+
* its outcome kept.
|
|
140
|
+
* - A deny writes an error `tool_result` and returns `denied`.
|
|
141
|
+
* - An ask that no sticky allowance covers writes an `approval_requested` entry, signed as `createPendingRequest()`
|
|
142
|
+
* signs it, and returns `awaiting_approval`. `Approvals.resolve()` answers it.
|
|
143
|
+
*
|
|
144
|
+
* A code call runs no turn, so the harness's `interceptors` and `observers` don't see it. Put a guard that must cover
|
|
145
|
+
* code calls in the pipeline's hooks, which see `initiator: "code"`, or in `wrap`.
|
|
146
|
+
*
|
|
147
|
+
* It throws before it writes anything:
|
|
148
|
+
*
|
|
149
|
+
* - `invalid_code_call` for a tool the registry lacks or that runs on the client, an input or host context with no
|
|
150
|
+
* canonical JSON form, a business key that fails, a harness with no permission pipeline, or a compensation that
|
|
151
|
+
* names no code call that ran or would share that call's effect key.
|
|
152
|
+
* - `approval_unavailable` for a harness with no signer.
|
|
153
|
+
* - The signal's reason for a signal aborted before the call starts.
|
|
154
|
+
*/
|
|
155
|
+
invokeTool(this: Harness<H>, session: Session, call: CodeCall<H>): Promise<CodeCallResult>;
|
|
156
|
+
}
|
package/dist/harness.js
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"harness.js","sourceRoot":"","sources":["../src/harness.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * The harness's types: the settings every turn of a harness shares, and the code calls it runs. A turn can override the\n * model, the system prompt and the tools; what it can't override, such as the registry and the permission pipeline, is\n * fixed here. `H` is the type of the per-turn host context, which reaches a tool's `execute` as `ctx.app` and is in no\n * request, event or saved entry. `createHarness()` lives in its own module, because it binds the code-call runner,\n * which imports these types.\n */\nimport type { Model } from \"@buildanagent/gateway\";\nimport type { ApprovalPolicy, PermissionMode, SandboxTier } from \"@buildanagent/protocol\";\nimport type { ApprovalSigner, Interceptors, Observer, SignedPendingRequest, ToolResult } from \"@buildanagent/sdk\";\nimport type { Clock } from \"@buildanagent/sdk/testing\";\nimport type { ContextPolicy } from \"./context/types.js\";\nimport type { Skill } from \"./extensions/skills.js\";\nimport type { ExtensionLoadedRecord } from \"./extensions/types.js\";\nimport type { PermissionPipeline } from \"./permissions/types.js\";\nimport type { Session } from \"./session/session.js\";\nimport type { ToolRegistry, ToolWrapper } from \"./tools/types.js\";\n\n/** What the session's `env_stamp` records about where the turns run. */\nexport interface HarnessEnv {\n readonly cwd: string;\n readonly permissionMode: PermissionMode;\n readonly approvalPolicy: ApprovalPolicy;\n readonly sandbox: SandboxTier;\n}\n\n/** The options of `createHarness()`. */\nexport interface HarnessOptions<H = unknown> {\n readonly registry: ToolRegistry;\n /** The model a turn uses unless it names another. */\n readonly model: Model;\n /** The system prompt a turn uses unless it names another. */\n readonly system: string;\n /** What `env_stamp` records. A field left out takes `/`, `default`, `on-request` or `none`. */\n readonly env?: Partial<HarnessEnv>;\n /**\n * The tenant a write acts for: one tenant is one user, so a business key never spans two users. Default `local`,\n * for a host that has one user. `effectScope()` puts it in the scope a guarded write takes.\n */\n readonly tenant?: string;\n /** The harness's version, stamped into each session header. */\n readonly harnessVersion?: string;\n /** A hash of the ablation switches, stamped into each session header. Default `none`. */\n readonly ablationHash?: string;\n /** When set, its gate decides every tool call, and each decision is written to the log. */\n readonly pipeline?: PermissionPipeline;\n /**\n * Hooks that run with the pipeline's gate in every turn, before it for a gate, as `composeInterceptors()` orders\n * them. A code call from `invokeTool()` runs no turn, so they don't see it.\n */\n readonly interceptors?: Interceptors;\n /** The context layers every turn runs through, from `createContextPolicy()`. Without one a turn sends its whole transcript. */\n readonly context?: ContextPolicy;\n /**\n * The extensions this harness runs, as `recordsOf()` or `loadProjectExtensions()` gives them. A turn writes an\n * `extension_loaded` entry for each the session's log does not hold yet, so a session shows which code ran.\n */\n readonly extensionRecords?: readonly ExtensionLoadedRecord[];\n /**\n * The skills the system prompt lists, as `discoverSkills()` gives them. When a successful `read` call opens the whole\n * of one's `SKILL.md`, with no `offset` or `limit`, the turn writes a `skill_loaded` entry. Relative paths in the call\n * resolve against `env.cwd`.\n */\n readonly skills?: readonly Skill[];\n /** Observers that see every event of every turn, after the runner's own. A code call emits no events. */\n readonly observers?: readonly Observer[];\n /** Binds a tool to the turn's host context, such as a write cap. A tool can also read it as `ctx.app`. */\n readonly wrap?: ToolWrapper<H>;\n /** Signs the pauses a turn ends in. */\n readonly signer?: ApprovalSigner;\n}\n\n/** A tool call that the host's own code makes with `Harness.invokeTool()`, with no model step. */\nexport interface CodeCall<H = unknown> {\n /** The tool's name or alias in the registry. */\n readonly tool: string;\n /** The input the tool runs with. It is recorded and hashed as given, so it must have a canonical JSON form. */\n readonly input: unknown;\n /**\n * The host context the tool runs with, as `ctx.app`. A call that asks for a person binds a MAC of it into the signed\n * request, so `Approvals.resolve()` runs the call only when it is given the same host context.\n */\n readonly hostContext?: H;\n /**\n * The call id of an earlier code call that this one undoes. The earlier call must have run, and this call must reach\n * an effect key of its own. The `code_call` entry records the link.\n */\n readonly compensates?: string;\n /** Aborts the call. An aborted signal before the call starts writes nothing; the tool receives it as `ctx.signal`. */\n readonly signal?: AbortSignal;\n /** The clock of the entries, the signed request and the tool's `ctx.clock`. Default the system clock. */\n readonly clock?: Clock;\n /** Makes the ids of the entries, the call and the signed request. Default `crypto.randomUUID()`. */\n readonly newId?: () => string;\n}\n\n/**\n * What a code call ended in.\n *\n * - `done`: the tool ran. `result` is the whole of what it returned, with a write outcome's sentence in front of its\n * content, even when the call's `tool_result` entry holds it capped.\n * - `denied`: the permission pipeline or a person refused the call. The tool never ran.\n * - `awaiting_approval`: a person must answer `pending` through `Approvals.resolve()`. It has no `entryId`.\n *\n * `entryId` is the id of the call's `tool_result` entry. `effectKey` is the call's effect identity: from the tool's\n * business key when it declares one, and otherwise from the call id, which is the id of the call's `code_call` entry.\n */\nexport type CodeCallResult =\n | {\n readonly status: \"done\";\n readonly callId: string;\n readonly result: ToolResult<unknown>;\n readonly entryId: string;\n readonly effectKey: string;\n }\n | { readonly status: \"denied\"; readonly callId: string; readonly reason: string; readonly entryId: string }\n | {\n readonly status: \"awaiting_approval\";\n readonly callId: string;\n readonly pending: SignedPendingRequest;\n readonly effectKey: string;\n };\n\n/** A harness: its options with the defaults filled in. */\nexport interface Harness<H = unknown> extends HarnessOptions<H> {\n readonly env: HarnessEnv;\n readonly tenant: string;\n readonly harnessVersion: string;\n readonly ablationHash: string;\n /**\n * Runs a tool call that the host's own code chose, through the same permission pipeline, signed pause and log as a\n * call the model makes, with no model call. The session must be open with its lock.\n *\n * The call's own entries start with a `code_call` entry, then the pipeline's `permission_decision`. Before them it\n * writes what the session lacks: a new session's header and environment stamp, and a result for each earlier code\n * call a crash left open.\n *\n * The call ends one of three ways:\n *\n * - An allow runs the tool through the harness's `wrap` with `call.hostContext`, writes its `tool_result` and returns\n * `done`. The harness's `context` policy caps the stored result, and the store's entry bound cuts it to fit, with\n * its outcome kept.\n * - A deny writes an error `tool_result` and returns `denied`.\n * - An ask that no sticky allowance covers writes an `approval_requested` entry, signed as `createPendingRequest()`\n * signs it, and returns `awaiting_approval`. `Approvals.resolve()` answers it.\n *\n * A code call runs no turn, so the harness's `interceptors` and `observers` don't see it. Put a guard that must cover\n * code calls in the pipeline's hooks, which see `initiator: \"code\"`, or in `wrap`.\n *\n * It throws before it writes anything:\n *\n * - `invalid_code_call` for a tool the registry lacks or that runs on the client, an input or host context with no\n * canonical JSON form, a business key that fails, a harness with no permission pipeline, or a compensation that\n * names no code call that ran or would share that call's effect key.\n * - `approval_unavailable` for a harness with no signer.\n * - The signal's reason for a signal aborted before the call starts.\n */\n invokeTool(this: Harness<H>, session: Session, call: CodeCall<H>): Promise<CodeCallResult>;\n}\n"]}
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
/** `@buildanagent/harness`, the buildanagent harness: the session log, context policy, tools, permissions, sandbox and credentials around the SDK's loop. The `memory`, `telemetry` and `ablation` subpaths are stubs that hold their place until their components are built. */
|
|
2
|
+
export { HarnessError, type HarnessErrorCode, isHarnessError } from "./errors.js";
|
|
3
|
+
/** The package's npm name, `@buildanagent/harness`. */
|
|
4
|
+
export declare const PACKAGE_NAME = "@buildanagent/harness";
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
/** `@buildanagent/harness`, the buildanagent harness: the session log, context policy, tools, permissions, sandbox and credentials around the SDK's loop. The `memory`, `telemetry` and `ablation` subpaths are stubs that hold their place until their components are built. */
|
|
2
|
+
export { HarnessError, isHarnessError } from "./errors.js";
|
|
3
|
+
/** The package's npm name, `@buildanagent/harness`. */
|
|
4
|
+
export const PACKAGE_NAME = "@buildanagent/harness";
|
|
5
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,iRAAiR;AACjR,OAAO,EAAE,YAAY,EAAyB,cAAc,EAAE,MAAM,aAAa,CAAC;AAElF,uDAAuD;AACvD,MAAM,CAAC,MAAM,YAAY,GAAG,uBAAuB,CAAC","sourcesContent":["/** `@buildanagent/harness`, the buildanagent harness: the session log, context policy, tools, permissions, sandbox and credentials around the SDK's loop. The `memory`, `telemetry` and `ablation` subpaths are stubs that hold their place until their components are built. */\nexport { HarnessError, type HarnessErrorCode, isHarnessError } from \"./errors.js\";\n\n/** The package's npm name, `@buildanagent/harness`. */\nexport const PACKAGE_NAME = \"@buildanagent/harness\";\n"]}
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
import type { McpConnection, McpServerConfig } from "./types.js";
|
|
2
|
+
/** A server's settings with their defaults, checked. Throws a `HarnessError`, code `invalid_mcp_config`. */
|
|
3
|
+
export declare function checkServerConfig(config: McpServerConfig): {
|
|
4
|
+
connectMs: number;
|
|
5
|
+
probeMs: number;
|
|
6
|
+
requestMs: number;
|
|
7
|
+
maxTools: number;
|
|
8
|
+
};
|
|
9
|
+
/**
|
|
10
|
+
* Connects one server and negotiates its era. A stdio server that exits cleanly after the `server/discover` probe, as
|
|
11
|
+
* servers on some older SDKs do on any request before `initialize`, is started once more and spoken to as a legacy
|
|
12
|
+
* server; a server that crashes runs once. The whole connect, a restart included, takes at most `connectTimeoutMs`.
|
|
13
|
+
* `signal` aborts it, and the server is closed.
|
|
14
|
+
*
|
|
15
|
+
* Throws a `HarnessError`, code `invalid_mcp_config`, for a config that can't be used, and an `McpError`, code
|
|
16
|
+
* `mcp_connect_failed`, when the server does not start, does not finish the handshake within `connectTimeoutMs`, is
|
|
17
|
+
* aborted, or negotiates a revision this harness does not know.
|
|
18
|
+
*/
|
|
19
|
+
export declare function connectMcpServer(config: McpServerConfig, options?: {
|
|
20
|
+
readonly log?: (line: string) => void;
|
|
21
|
+
readonly signal?: AbortSignal;
|
|
22
|
+
}): Promise<McpConnection>;
|
|
@@ -0,0 +1,267 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `connectMcpServer()`: one server behind `McpConnection`, over `@modelcontextprotocol/client` 2.4.0 (ADR 0021). The
|
|
3
|
+
* client negotiates the era per connection: it probes with `server/discover` and falls back to `initialize` when the
|
|
4
|
+
* server gives no sign of the 2026-07-28 revision. This module reads the result through the client's
|
|
5
|
+
* `getProtocolEra()`, and only it imports the client, so the base can change without touching the registry.
|
|
6
|
+
*/
|
|
7
|
+
import { Client } from "@modelcontextprotocol/client";
|
|
8
|
+
import { HarnessError } from "../errors.js";
|
|
9
|
+
import { checkToolList, resultOf, shortText } from "./content.js";
|
|
10
|
+
import { McpError } from "./errors.js";
|
|
11
|
+
import { checkStdioTransport, StdioChannel } from "./stdio.js";
|
|
12
|
+
const MODERN_VERSION = "2026-07-28";
|
|
13
|
+
const DEFAULT_CONNECT_TIMEOUT_MS = 30_000;
|
|
14
|
+
const DEFAULT_PROBE_TIMEOUT_MS = 5_000;
|
|
15
|
+
const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
|
|
16
|
+
const DEFAULT_MAX_TOOLS = 256;
|
|
17
|
+
// The pages a tool list may take. A server whose cursor never ends can't keep the connect busy.
|
|
18
|
+
const MAX_LIST_PAGES = 8;
|
|
19
|
+
// The longest delay a timer takes: a larger one fires at once.
|
|
20
|
+
const MAX_TIMER_MS = 2 ** 31 - 1;
|
|
21
|
+
const SERVER_NAME = /^[A-Za-z0-9][A-Za-z0-9-]{0,31}$/;
|
|
22
|
+
const CLIENT_INFO = { name: "buildanagent-harness", version: "0.0.0" };
|
|
23
|
+
const describe = (error) => shortText(error instanceof Error ? error.message : String(error));
|
|
24
|
+
function timeout(name, value, fallback) {
|
|
25
|
+
if (value === undefined)
|
|
26
|
+
return fallback;
|
|
27
|
+
if (!(Number.isInteger(value) && value >= 1 && value <= MAX_TIMER_MS)) {
|
|
28
|
+
throw new HarnessError("invalid_mcp_config", `${name} must be a whole number of milliseconds from 1 to ${MAX_TIMER_MS}`);
|
|
29
|
+
}
|
|
30
|
+
return value;
|
|
31
|
+
}
|
|
32
|
+
/** A server's settings with their defaults, checked. Throws a `HarnessError`, code `invalid_mcp_config`. */
|
|
33
|
+
export function checkServerConfig(config) {
|
|
34
|
+
if (typeof config?.name !== "string" || !SERVER_NAME.test(config.name)) {
|
|
35
|
+
throw new HarnessError("invalid_mcp_config", `an MCP server name must be 1 to 32 characters from A-Z, a-z, 0-9 and -, starting with a letter or digit, got ${JSON.stringify(config?.name)}`);
|
|
36
|
+
}
|
|
37
|
+
const transport = config.transport;
|
|
38
|
+
if (transport?.kind === "stdio")
|
|
39
|
+
checkStdioTransport(transport);
|
|
40
|
+
else if (transport?.kind !== "in_process" || typeof transport.channel?.send !== "function") {
|
|
41
|
+
throw new HarnessError("invalid_mcp_config", `the MCP server "${config.name}" needs a stdio or in_process transport`);
|
|
42
|
+
}
|
|
43
|
+
const maxTools = config.maxTools ?? DEFAULT_MAX_TOOLS;
|
|
44
|
+
if (!Number.isInteger(maxTools) || maxTools < 1) {
|
|
45
|
+
throw new HarnessError("invalid_mcp_config", "maxTools must be a whole number, 1 or more");
|
|
46
|
+
}
|
|
47
|
+
const connectMs = timeout("connectTimeoutMs", config.connectTimeoutMs, DEFAULT_CONNECT_TIMEOUT_MS);
|
|
48
|
+
// A probe that outlasts the handshake would never let a silent server fall back to legacy, so a probe timeout the
|
|
49
|
+
// config names must be shorter, and the default shrinks to half the handshake when it would not be.
|
|
50
|
+
if (config.probeTimeoutMs !== undefined && config.probeTimeoutMs >= connectMs) {
|
|
51
|
+
throw new HarnessError("invalid_mcp_config", "probeTimeoutMs must be shorter than connectTimeoutMs");
|
|
52
|
+
}
|
|
53
|
+
return {
|
|
54
|
+
connectMs,
|
|
55
|
+
probeMs: timeout("probeTimeoutMs", config.probeTimeoutMs, Math.min(DEFAULT_PROBE_TIMEOUT_MS, Math.ceil(connectMs / 2))),
|
|
56
|
+
requestMs: timeout("requestTimeoutMs", config.requestTimeoutMs, DEFAULT_REQUEST_TIMEOUT_MS),
|
|
57
|
+
maxTools,
|
|
58
|
+
};
|
|
59
|
+
}
|
|
60
|
+
/** Why a call failed, read from what the client library threw. */
|
|
61
|
+
function failureOf(error, signal, closed) {
|
|
62
|
+
if (signal.aborted)
|
|
63
|
+
return "aborted";
|
|
64
|
+
if (closed)
|
|
65
|
+
return "closed";
|
|
66
|
+
const code = error?.code;
|
|
67
|
+
if (code === "REQUEST_TIMEOUT")
|
|
68
|
+
return "timeout";
|
|
69
|
+
if (code === "CONNECTION_CLOSED" || code === "NOT_CONNECTED" || code === "SEND_FAILED")
|
|
70
|
+
return "closed";
|
|
71
|
+
if (code === "UNSUPPORTED_RESULT_TYPE" || code === "INPUT_REQUIRED_ROUNDS_EXCEEDED")
|
|
72
|
+
return "input_required";
|
|
73
|
+
return "server_error";
|
|
74
|
+
}
|
|
75
|
+
const FAILURE_TEXT = {
|
|
76
|
+
closed: "the connection closed before the call finished",
|
|
77
|
+
timeout: "the call timed out",
|
|
78
|
+
aborted: "the call was aborted",
|
|
79
|
+
input_required: "the server asked for input from the user, which this harness does not supply yet",
|
|
80
|
+
server_error: "the server answered with an error",
|
|
81
|
+
};
|
|
82
|
+
class Connection {
|
|
83
|
+
server;
|
|
84
|
+
era;
|
|
85
|
+
protocolVersion;
|
|
86
|
+
#client;
|
|
87
|
+
#channel;
|
|
88
|
+
#settings;
|
|
89
|
+
#closed = false;
|
|
90
|
+
#closing;
|
|
91
|
+
constructor(server, client, channel, settings, era, version) {
|
|
92
|
+
this.server = server;
|
|
93
|
+
this.#client = client;
|
|
94
|
+
this.#channel = channel;
|
|
95
|
+
this.#settings = settings;
|
|
96
|
+
this.era = era;
|
|
97
|
+
this.protocolVersion = version;
|
|
98
|
+
const previous = channel.onclose;
|
|
99
|
+
channel.onclose = () => {
|
|
100
|
+
this.#closed = true;
|
|
101
|
+
previous?.();
|
|
102
|
+
};
|
|
103
|
+
}
|
|
104
|
+
get closed() {
|
|
105
|
+
return this.#closed;
|
|
106
|
+
}
|
|
107
|
+
/**
|
|
108
|
+
* The server's tools, read one page at a time. The walk stops as soon as the list passes `maxTools` or runs past
|
|
109
|
+
* eight pages, so a server can make the harness hold at most one page beyond the limit, each page bounded by the
|
|
110
|
+
* line limit. The client's own walk would gather every page before anything counted them.
|
|
111
|
+
*/
|
|
112
|
+
async listTools() {
|
|
113
|
+
const listed = [];
|
|
114
|
+
let cursor;
|
|
115
|
+
for (let page = 1;; page += 1) {
|
|
116
|
+
const result = await this.#page(cursor);
|
|
117
|
+
const tools = result.tools;
|
|
118
|
+
if (!Array.isArray(tools))
|
|
119
|
+
return checkToolList(this.server, tools, this.#settings.maxTools);
|
|
120
|
+
listed.push(...tools);
|
|
121
|
+
// One past the limit is enough for checkToolList() to refuse, so no later page is asked for.
|
|
122
|
+
if (listed.length > this.#settings.maxTools)
|
|
123
|
+
break;
|
|
124
|
+
const next = result.nextCursor;
|
|
125
|
+
if (typeof next !== "string" || next === "")
|
|
126
|
+
break;
|
|
127
|
+
if (page >= MAX_LIST_PAGES) {
|
|
128
|
+
throw new McpError("mcp_tool_list_refused", this.server, `its tool list was refused, so none of its tools was registered: it runs past ${MAX_LIST_PAGES} pages`);
|
|
129
|
+
}
|
|
130
|
+
cursor = next;
|
|
131
|
+
}
|
|
132
|
+
return checkToolList(this.server, listed, this.#settings.maxTools);
|
|
133
|
+
}
|
|
134
|
+
async #page(cursor) {
|
|
135
|
+
const options = { timeout: this.#settings.requestMs };
|
|
136
|
+
try {
|
|
137
|
+
// The first page goes as a plain request, since the client's listTools() with no cursor walks every page itself.
|
|
138
|
+
return cursor === undefined
|
|
139
|
+
? await this.#client.request({ method: "tools/list" }, options)
|
|
140
|
+
: await this.#client.listTools({ cursor }, options);
|
|
141
|
+
}
|
|
142
|
+
catch (error) {
|
|
143
|
+
throw new McpError("mcp_tool_list_refused", this.server, `its tool list could not be read: ${describe(error)}`, {
|
|
144
|
+
cause: error,
|
|
145
|
+
});
|
|
146
|
+
}
|
|
147
|
+
}
|
|
148
|
+
async callTool(name, args, signal) {
|
|
149
|
+
if (this.#closed) {
|
|
150
|
+
throw new McpError("mcp_call_failed", this.server, FAILURE_TEXT.closed, { failure: "closed" });
|
|
151
|
+
}
|
|
152
|
+
const input = typeof args === "object" && args !== null && !Array.isArray(args) ? args : {};
|
|
153
|
+
try {
|
|
154
|
+
const result = await this.#client.callTool({ name, arguments: input }, { signal, timeout: this.#settings.requestMs });
|
|
155
|
+
return resultOf(result);
|
|
156
|
+
}
|
|
157
|
+
catch (error) {
|
|
158
|
+
const failure = failureOf(error, signal, this.#closed);
|
|
159
|
+
const detail = failure === "server_error" ? `: ${describe(error)}` : "";
|
|
160
|
+
throw new McpError("mcp_call_failed", this.server, `${FAILURE_TEXT[failure]}${detail}`, {
|
|
161
|
+
cause: error,
|
|
162
|
+
failure,
|
|
163
|
+
});
|
|
164
|
+
}
|
|
165
|
+
}
|
|
166
|
+
stderr() {
|
|
167
|
+
return this.#channel instanceof StdioChannel ? this.#channel.stderr : "";
|
|
168
|
+
}
|
|
169
|
+
close() {
|
|
170
|
+
this.#closing ??= (async () => {
|
|
171
|
+
this.#closed = true;
|
|
172
|
+
await this.#client.close().catch(() => { });
|
|
173
|
+
await this.#channel.close().catch(() => { });
|
|
174
|
+
})();
|
|
175
|
+
return this.#closing;
|
|
176
|
+
}
|
|
177
|
+
}
|
|
178
|
+
function channelOf(config, log) {
|
|
179
|
+
return config.transport.kind === "stdio" ? new StdioChannel(config.transport, log) : config.transport.channel;
|
|
180
|
+
}
|
|
181
|
+
/** Connects through `channel`, bounded by `connectMs`, and closes everything when it fails. */
|
|
182
|
+
async function handshake(config, settings, channel, prior, log, deadline) {
|
|
183
|
+
const client = new Client(CLIENT_INFO, {
|
|
184
|
+
capabilities: {},
|
|
185
|
+
versionNegotiation: { mode: "auto", probe: { timeoutMs: settings.probeMs } },
|
|
186
|
+
// A server's request for user input fails the call: whether it may pause a turn waits on the owner.
|
|
187
|
+
inputRequired: { autoFulfill: false },
|
|
188
|
+
listMaxPages: MAX_LIST_PAGES,
|
|
189
|
+
// The harness reads a result's content, not its structured content, so a server's output schema is never compiled:
|
|
190
|
+
// a hostile pattern or reference in it can cost nothing.
|
|
191
|
+
jsonSchemaValidator: {
|
|
192
|
+
getValidator: () => (input) => ({ valid: true, data: input, errorMessage: undefined }),
|
|
193
|
+
},
|
|
194
|
+
});
|
|
195
|
+
// The tool list stays as registered at connect. A changed list is announced, and a later todo diffs it against a pin.
|
|
196
|
+
client.setNotificationHandler("notifications/tools/list_changed", () => {
|
|
197
|
+
log(`the server "${config.name}" says its tool list changed; its tools stay as they were registered`);
|
|
198
|
+
});
|
|
199
|
+
let timer;
|
|
200
|
+
let onAbort;
|
|
201
|
+
const expired = new Promise((_, reject) => {
|
|
202
|
+
timer = setTimeout(() => reject(new Error(`the handshake did not finish in ${settings.connectMs} ms`)), Math.max(1, deadline.ms));
|
|
203
|
+
onAbort = () => reject(new Error("the connect was aborted"));
|
|
204
|
+
if (deadline.signal?.aborted)
|
|
205
|
+
onAbort();
|
|
206
|
+
else
|
|
207
|
+
deadline.signal?.addEventListener("abort", onAbort, { once: true });
|
|
208
|
+
});
|
|
209
|
+
try {
|
|
210
|
+
const connecting = client.connect(channel, {
|
|
211
|
+
timeout: Math.max(1, deadline.ms),
|
|
212
|
+
...(prior === undefined ? {} : { prior: { kind: prior } }),
|
|
213
|
+
});
|
|
214
|
+
connecting.catch(() => { });
|
|
215
|
+
await Promise.race([connecting, expired]);
|
|
216
|
+
const era = client.getProtocolEra();
|
|
217
|
+
const version = client.getNegotiatedProtocolVersion() ?? "";
|
|
218
|
+
if (era === "modern" && version !== MODERN_VERSION) {
|
|
219
|
+
throw new Error(`the server negotiated the revision ${shortText(version, 32)}, which this harness does not know`);
|
|
220
|
+
}
|
|
221
|
+
return new Connection(config.name, client, channel, settings, era === "modern" ? MODERN_VERSION : "legacy", version);
|
|
222
|
+
}
|
|
223
|
+
catch (error) {
|
|
224
|
+
await client.close().catch(() => { });
|
|
225
|
+
await channel.close().catch(() => { });
|
|
226
|
+
throw error;
|
|
227
|
+
}
|
|
228
|
+
finally {
|
|
229
|
+
clearTimeout(timer);
|
|
230
|
+
if (onAbort !== undefined)
|
|
231
|
+
deadline.signal?.removeEventListener("abort", onAbort);
|
|
232
|
+
}
|
|
233
|
+
}
|
|
234
|
+
/**
|
|
235
|
+
* Connects one server and negotiates its era. A stdio server that exits cleanly after the `server/discover` probe, as
|
|
236
|
+
* servers on some older SDKs do on any request before `initialize`, is started once more and spoken to as a legacy
|
|
237
|
+
* server; a server that crashes runs once. The whole connect, a restart included, takes at most `connectTimeoutMs`.
|
|
238
|
+
* `signal` aborts it, and the server is closed.
|
|
239
|
+
*
|
|
240
|
+
* Throws a `HarnessError`, code `invalid_mcp_config`, for a config that can't be used, and an `McpError`, code
|
|
241
|
+
* `mcp_connect_failed`, when the server does not start, does not finish the handshake within `connectTimeoutMs`, is
|
|
242
|
+
* aborted, or negotiates a revision this harness does not know.
|
|
243
|
+
*/
|
|
244
|
+
export async function connectMcpServer(config, options = {}) {
|
|
245
|
+
const settings = checkServerConfig(config);
|
|
246
|
+
const log = options.log ?? (() => { });
|
|
247
|
+
const ends = Date.now() + settings.connectMs;
|
|
248
|
+
const left = () => ({ ms: ends - Date.now(), signal: options.signal });
|
|
249
|
+
const failed = (error) => new McpError("mcp_connect_failed", config.name, `it did not connect: ${describe(error)}`, { cause: error });
|
|
250
|
+
const channel = channelOf(config, log);
|
|
251
|
+
try {
|
|
252
|
+
return await handshake(config, settings, channel, undefined, log, left());
|
|
253
|
+
}
|
|
254
|
+
catch (first) {
|
|
255
|
+
const exitedOnProbe = channel instanceof StdioChannel && channel.exitedOnProbe;
|
|
256
|
+
if (!exitedOnProbe || options.signal?.aborted === true || left().ms <= 0)
|
|
257
|
+
throw failed(first);
|
|
258
|
+
log(`the server "${config.name}" closed after the probe, so it is started again as a legacy server`);
|
|
259
|
+
try {
|
|
260
|
+
return await handshake(config, settings, channelOf(config, log), "legacy", log, left());
|
|
261
|
+
}
|
|
262
|
+
catch (second) {
|
|
263
|
+
throw failed(second);
|
|
264
|
+
}
|
|
265
|
+
}
|
|
266
|
+
}
|
|
267
|
+
//# sourceMappingURL=connection.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"connection.js","sourceRoot":"","sources":["../../src/mcp/connection.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `connectMcpServer()`: one server behind `McpConnection`, over `@modelcontextprotocol/client` 2.4.0 (ADR 0021). The\n * client negotiates the era per connection: it probes with `server/discover` and falls back to `initialize` when the\n * server gives no sign of the 2026-07-28 revision. This module reads the result through the client's\n * `getProtocolEra()`, and only it imports the client, so the base can change without touching the registry.\n */\nimport { Client, type Transport } from \"@modelcontextprotocol/client\";\nimport { HarnessError } from \"../errors.js\";\nimport { checkToolList, resultOf, shortText } from \"./content.js\";\nimport { type McpCallFailure, McpError } from \"./errors.js\";\nimport { checkStdioTransport, StdioChannel } from \"./stdio.js\";\nimport type { McpCallResult, McpChannel, McpConnection, McpEra, McpServerConfig, McpTool } from \"./types.js\";\n\nconst MODERN_VERSION = \"2026-07-28\";\nconst DEFAULT_CONNECT_TIMEOUT_MS = 30_000;\nconst DEFAULT_PROBE_TIMEOUT_MS = 5_000;\nconst DEFAULT_REQUEST_TIMEOUT_MS = 60_000;\nconst DEFAULT_MAX_TOOLS = 256;\n// The pages a tool list may take. A server whose cursor never ends can't keep the connect busy.\nconst MAX_LIST_PAGES = 8;\n// The longest delay a timer takes: a larger one fires at once.\nconst MAX_TIMER_MS = 2 ** 31 - 1;\nconst SERVER_NAME = /^[A-Za-z0-9][A-Za-z0-9-]{0,31}$/;\nconst CLIENT_INFO = { name: \"buildanagent-harness\", version: \"0.0.0\" };\n\nconst describe = (error: unknown): string => shortText(error instanceof Error ? error.message : String(error));\n\nfunction timeout(name: string, value: number | undefined, fallback: number): number {\n if (value === undefined) return fallback;\n if (!(Number.isInteger(value) && value >= 1 && value <= MAX_TIMER_MS)) {\n throw new HarnessError(\n \"invalid_mcp_config\",\n `${name} must be a whole number of milliseconds from 1 to ${MAX_TIMER_MS}`,\n );\n }\n return value;\n}\n\n/** A server's settings with their defaults, checked. Throws a `HarnessError`, code `invalid_mcp_config`. */\nexport function checkServerConfig(config: McpServerConfig) {\n if (typeof config?.name !== \"string\" || !SERVER_NAME.test(config.name)) {\n throw new HarnessError(\n \"invalid_mcp_config\",\n `an MCP server name must be 1 to 32 characters from A-Z, a-z, 0-9 and -, starting with a letter or digit, got ${JSON.stringify(config?.name)}`,\n );\n }\n const transport = config.transport;\n if (transport?.kind === \"stdio\") checkStdioTransport(transport);\n else if (transport?.kind !== \"in_process\" || typeof transport.channel?.send !== \"function\") {\n throw new HarnessError(\n \"invalid_mcp_config\",\n `the MCP server \"${config.name}\" needs a stdio or in_process transport`,\n );\n }\n const maxTools = config.maxTools ?? DEFAULT_MAX_TOOLS;\n if (!Number.isInteger(maxTools) || maxTools < 1) {\n throw new HarnessError(\"invalid_mcp_config\", \"maxTools must be a whole number, 1 or more\");\n }\n const connectMs = timeout(\"connectTimeoutMs\", config.connectTimeoutMs, DEFAULT_CONNECT_TIMEOUT_MS);\n // A probe that outlasts the handshake would never let a silent server fall back to legacy, so a probe timeout the\n // config names must be shorter, and the default shrinks to half the handshake when it would not be.\n if (config.probeTimeoutMs !== undefined && config.probeTimeoutMs >= connectMs) {\n throw new HarnessError(\"invalid_mcp_config\", \"probeTimeoutMs must be shorter than connectTimeoutMs\");\n }\n return {\n connectMs,\n probeMs: timeout(\n \"probeTimeoutMs\",\n config.probeTimeoutMs,\n Math.min(DEFAULT_PROBE_TIMEOUT_MS, Math.ceil(connectMs / 2)),\n ),\n requestMs: timeout(\"requestTimeoutMs\", config.requestTimeoutMs, DEFAULT_REQUEST_TIMEOUT_MS),\n maxTools,\n };\n}\n\ntype Settings = ReturnType<typeof checkServerConfig>;\n\n/** Why a call failed, read from what the client library threw. */\nfunction failureOf(error: unknown, signal: AbortSignal, closed: boolean): McpCallFailure {\n if (signal.aborted) return \"aborted\";\n if (closed) return \"closed\";\n const code = (error as { code?: unknown } | null)?.code;\n if (code === \"REQUEST_TIMEOUT\") return \"timeout\";\n if (code === \"CONNECTION_CLOSED\" || code === \"NOT_CONNECTED\" || code === \"SEND_FAILED\") return \"closed\";\n if (code === \"UNSUPPORTED_RESULT_TYPE\" || code === \"INPUT_REQUIRED_ROUNDS_EXCEEDED\") return \"input_required\";\n return \"server_error\";\n}\n\nconst FAILURE_TEXT: Record<McpCallFailure, string> = {\n closed: \"the connection closed before the call finished\",\n timeout: \"the call timed out\",\n aborted: \"the call was aborted\",\n input_required: \"the server asked for input from the user, which this harness does not supply yet\",\n server_error: \"the server answered with an error\",\n};\n\nclass Connection implements McpConnection {\n readonly server: string;\n readonly era: McpEra;\n readonly protocolVersion: string;\n readonly #client: Client;\n readonly #channel: McpChannel;\n readonly #settings: Settings;\n #closed = false;\n #closing: Promise<void> | undefined;\n\n constructor(server: string, client: Client, channel: McpChannel, settings: Settings, era: McpEra, version: string) {\n this.server = server;\n this.#client = client;\n this.#channel = channel;\n this.#settings = settings;\n this.era = era;\n this.protocolVersion = version;\n const previous = channel.onclose;\n channel.onclose = () => {\n this.#closed = true;\n previous?.();\n };\n }\n\n get closed(): boolean {\n return this.#closed;\n }\n\n /**\n * The server's tools, read one page at a time. The walk stops as soon as the list passes `maxTools` or runs past\n * eight pages, so a server can make the harness hold at most one page beyond the limit, each page bounded by the\n * line limit. The client's own walk would gather every page before anything counted them.\n */\n async listTools(): Promise<readonly McpTool[]> {\n const listed: unknown[] = [];\n let cursor: string | undefined;\n for (let page = 1; ; page += 1) {\n const result = await this.#page(cursor);\n const tools = (result as { tools?: unknown }).tools;\n if (!Array.isArray(tools)) return checkToolList(this.server, tools, this.#settings.maxTools);\n listed.push(...tools);\n // One past the limit is enough for checkToolList() to refuse, so no later page is asked for.\n if (listed.length > this.#settings.maxTools) break;\n const next = (result as { nextCursor?: unknown }).nextCursor;\n if (typeof next !== \"string\" || next === \"\") break;\n if (page >= MAX_LIST_PAGES) {\n throw new McpError(\n \"mcp_tool_list_refused\",\n this.server,\n `its tool list was refused, so none of its tools was registered: it runs past ${MAX_LIST_PAGES} pages`,\n );\n }\n cursor = next;\n }\n return checkToolList(this.server, listed, this.#settings.maxTools);\n }\n\n async #page(cursor: string | undefined): Promise<unknown> {\n const options = { timeout: this.#settings.requestMs };\n try {\n // The first page goes as a plain request, since the client's listTools() with no cursor walks every page itself.\n return cursor === undefined\n ? await this.#client.request({ method: \"tools/list\" }, options)\n : await this.#client.listTools({ cursor }, options);\n } catch (error) {\n throw new McpError(\"mcp_tool_list_refused\", this.server, `its tool list could not be read: ${describe(error)}`, {\n cause: error,\n });\n }\n }\n\n async callTool(name: string, args: unknown, signal: AbortSignal): Promise<McpCallResult> {\n if (this.#closed) {\n throw new McpError(\"mcp_call_failed\", this.server, FAILURE_TEXT.closed, { failure: \"closed\" });\n }\n const input = typeof args === \"object\" && args !== null && !Array.isArray(args) ? args : {};\n try {\n const result = await this.#client.callTool(\n { name, arguments: input as Record<string, unknown> },\n { signal, timeout: this.#settings.requestMs },\n );\n return resultOf(result);\n } catch (error) {\n const failure = failureOf(error, signal, this.#closed);\n const detail = failure === \"server_error\" ? `: ${describe(error)}` : \"\";\n throw new McpError(\"mcp_call_failed\", this.server, `${FAILURE_TEXT[failure]}${detail}`, {\n cause: error,\n failure,\n });\n }\n }\n\n stderr(): string {\n return this.#channel instanceof StdioChannel ? this.#channel.stderr : \"\";\n }\n\n close(): Promise<void> {\n this.#closing ??= (async () => {\n this.#closed = true;\n await this.#client.close().catch(() => {});\n await this.#channel.close().catch(() => {});\n })();\n return this.#closing;\n }\n}\n\nfunction channelOf(config: McpServerConfig, log: (line: string) => void): McpChannel {\n return config.transport.kind === \"stdio\" ? new StdioChannel(config.transport, log) : config.transport.channel;\n}\n\n/** Connects through `channel`, bounded by `connectMs`, and closes everything when it fails. */\nasync function handshake(\n config: McpServerConfig,\n settings: Settings,\n channel: McpChannel,\n prior: \"legacy\" | undefined,\n log: (line: string) => void,\n deadline: { readonly ms: number; readonly signal: AbortSignal | undefined },\n): Promise<Connection> {\n const client = new Client(CLIENT_INFO, {\n capabilities: {},\n versionNegotiation: { mode: \"auto\", probe: { timeoutMs: settings.probeMs } },\n // A server's request for user input fails the call: whether it may pause a turn waits on the owner.\n inputRequired: { autoFulfill: false },\n listMaxPages: MAX_LIST_PAGES,\n // The harness reads a result's content, not its structured content, so a server's output schema is never compiled:\n // a hostile pattern or reference in it can cost nothing.\n jsonSchemaValidator: {\n getValidator: () => (input: unknown) => ({ valid: true, data: input as never, errorMessage: undefined }),\n },\n });\n // The tool list stays as registered at connect. A changed list is announced, and a later todo diffs it against a pin.\n client.setNotificationHandler(\"notifications/tools/list_changed\", () => {\n log(`the server \"${config.name}\" says its tool list changed; its tools stay as they were registered`);\n });\n let timer: ReturnType<typeof setTimeout> | undefined;\n let onAbort: (() => void) | undefined;\n const expired = new Promise<never>((_, reject) => {\n timer = setTimeout(\n () => reject(new Error(`the handshake did not finish in ${settings.connectMs} ms`)),\n Math.max(1, deadline.ms),\n );\n onAbort = () => reject(new Error(\"the connect was aborted\"));\n if (deadline.signal?.aborted) onAbort();\n else deadline.signal?.addEventListener(\"abort\", onAbort, { once: true });\n });\n try {\n const connecting = client.connect(channel as unknown as Transport, {\n timeout: Math.max(1, deadline.ms),\n ...(prior === undefined ? {} : { prior: { kind: prior } }),\n });\n connecting.catch(() => {});\n await Promise.race([connecting, expired]);\n const era = client.getProtocolEra();\n const version = client.getNegotiatedProtocolVersion() ?? \"\";\n if (era === \"modern\" && version !== MODERN_VERSION) {\n throw new Error(`the server negotiated the revision ${shortText(version, 32)}, which this harness does not know`);\n }\n return new Connection(\n config.name,\n client,\n channel,\n settings,\n era === \"modern\" ? MODERN_VERSION : \"legacy\",\n version,\n );\n } catch (error) {\n await client.close().catch(() => {});\n await channel.close().catch(() => {});\n throw error;\n } finally {\n clearTimeout(timer);\n if (onAbort !== undefined) deadline.signal?.removeEventListener(\"abort\", onAbort);\n }\n}\n\n/**\n * Connects one server and negotiates its era. A stdio server that exits cleanly after the `server/discover` probe, as\n * servers on some older SDKs do on any request before `initialize`, is started once more and spoken to as a legacy\n * server; a server that crashes runs once. The whole connect, a restart included, takes at most `connectTimeoutMs`.\n * `signal` aborts it, and the server is closed.\n *\n * Throws a `HarnessError`, code `invalid_mcp_config`, for a config that can't be used, and an `McpError`, code\n * `mcp_connect_failed`, when the server does not start, does not finish the handshake within `connectTimeoutMs`, is\n * aborted, or negotiates a revision this harness does not know.\n */\nexport async function connectMcpServer(\n config: McpServerConfig,\n options: { readonly log?: (line: string) => void; readonly signal?: AbortSignal } = {},\n): Promise<McpConnection> {\n const settings = checkServerConfig(config);\n const log = options.log ?? (() => {});\n const ends = Date.now() + settings.connectMs;\n const left = () => ({ ms: ends - Date.now(), signal: options.signal });\n const failed = (error: unknown) =>\n new McpError(\"mcp_connect_failed\", config.name, `it did not connect: ${describe(error)}`, { cause: error });\n const channel = channelOf(config, log);\n try {\n return await handshake(config, settings, channel, undefined, log, left());\n } catch (first) {\n const exitedOnProbe = channel instanceof StdioChannel && channel.exitedOnProbe;\n if (!exitedOnProbe || options.signal?.aborted === true || left().ms <= 0) throw failed(first);\n log(`the server \"${config.name}\" closed after the probe, so it is started again as a legacy server`);\n try {\n return await handshake(config, settings, channelOf(config, log), \"legacy\", log, left());\n } catch (second) {\n throw failed(second);\n }\n }\n}\n"]}
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
import type { McpCallResult, McpTool } from "./types.js";
|
|
2
|
+
/**
|
|
3
|
+
* `text` cut to at most `max` UTF-16 units, with `…` after it when it was cut. It never splits a surrogate pair, since a
|
|
4
|
+
* lone half would make the canonical JSON that the record hashes refuse the text, and the server's whole list with it.
|
|
5
|
+
*/
|
|
6
|
+
export declare function cut(text: string, max: number): string;
|
|
7
|
+
/** A server's text cut to `max` characters, with its control characters replaced, for an error message. */
|
|
8
|
+
export declare function shortText(text: string, max?: number): string;
|
|
9
|
+
/**
|
|
10
|
+
* The server's tool list, checked as a whole: it is refused when it is longer than `maxTools`, when any tool fails its
|
|
11
|
+
* check, or when two names match once normalised (NFKC, then lower case), since they would read as one tool to a
|
|
12
|
+
* person approving a call.
|
|
13
|
+
*/
|
|
14
|
+
export declare function checkToolList(server: string, tools: unknown, maxTools: number): McpTool[];
|
|
15
|
+
/**
|
|
16
|
+
* The server's input schema with every keyword removed that runs a regular expression on the model's input: `pattern`,
|
|
17
|
+
* `patternProperties` and `format`. The SDK checks a call's input against the schema before the permission gate, and a
|
|
18
|
+
* pattern such as `^(a+)+$` runs on a backtracking engine, so a server could freeze the harness with a schema alone. The
|
|
19
|
+
* server still checks its own input, and the model still reads the description. A schema nested deeper than 64 levels
|
|
20
|
+
* is refused, since no real tool needs one and walking it could exhaust the stack.
|
|
21
|
+
*/
|
|
22
|
+
export declare function safeSchema(schema: unknown, depth?: number): unknown;
|
|
23
|
+
/**
|
|
24
|
+
* A `tools/call` result as the model reads it. Structured content stands in, as JSON, only when there is no content,
|
|
25
|
+
* so a result is never empty by accident.
|
|
26
|
+
*/
|
|
27
|
+
export declare function resultOf(result: unknown): McpCallResult;
|