@buildanagent/harness 0.0.0-stage → 0.1.0-alpha.29
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 +822 -2
- 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 +15 -0
- package/dist/context/file-spill.js +40 -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 +10 -0
- package/dist/context/spill.js +18 -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 +54 -0
- package/dist/credentials/allowlist.js +134 -0
- package/dist/credentials/allowlist.js.map +1 -0
- package/dist/credentials/egress-policy.d.ts +69 -0
- package/dist/credentials/egress-policy.js +170 -0
- package/dist/credentials/egress-policy.js.map +1 -0
- package/dist/credentials/egress-proxy.d.ts +82 -0
- package/dist/credentials/egress-proxy.js +650 -0
- package/dist/credentials/egress-proxy.js.map +1 -0
- package/dist/credentials/git-route.d.ts +68 -0
- package/dist/credentials/git-route.js +288 -0
- package/dist/credentials/git-route.js.map +1 -0
- package/dist/credentials/index.d.ts +13 -0
- package/dist/credentials/index.js +14 -0
- package/dist/credentials/index.js.map +1 -0
- package/dist/credentials/scrub.d.ts +23 -0
- package/dist/credentials/scrub.js +115 -0
- package/dist/credentials/scrub.js.map +1 -0
- package/dist/errors.d.ts +60 -0
- package/dist/errors.js +67 -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 +45 -0
- package/dist/sandbox/base.js +74 -0
- package/dist/sandbox/base.js.map +1 -0
- package/dist/sandbox/docker/index.d.ts +41 -0
- package/dist/sandbox/docker/index.js +497 -0
- package/dist/sandbox/docker/index.js.map +1 -0
- package/dist/sandbox/errors.d.ts +44 -0
- package/dist/sandbox/errors.js +57 -0
- package/dist/sandbox/errors.js.map +1 -0
- package/dist/sandbox/host-files.d.ts +65 -0
- package/dist/sandbox/host-files.js +258 -0
- package/dist/sandbox/host-files.js.map +1 -0
- package/dist/sandbox/index.d.ts +10 -0
- package/dist/sandbox/index.js +10 -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/policy.d.ts +49 -0
- package/dist/sandbox/policy.js +149 -0
- package/dist/sandbox/policy.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 +38 -0
- package/dist/sandbox/srt/index.js +283 -0
- package/dist/sandbox/srt/index.js.map +1 -0
- package/dist/sandbox/srt/settings.d.ts +60 -0
- package/dist/sandbox/srt/settings.js +84 -0
- package/dist/sandbox/srt/settings.js.map +1 -0
- package/dist/sandbox/types.d.ts +125 -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 +52 -0
- package/dist/testing/fake-sandbox.js +370 -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 +468 -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/builtins/bash.d.ts +9 -0
- package/dist/tools/builtins/bash.js +75 -0
- package/dist/tools/builtins/bash.js.map +1 -0
- package/dist/tools/builtins/builtins.d.ts +38 -0
- package/dist/tools/builtins/builtins.js +48 -0
- package/dist/tools/builtins/builtins.js.map +1 -0
- package/dist/tools/builtins/descriptions.d.ts +69 -0
- package/dist/tools/builtins/descriptions.js +94 -0
- package/dist/tools/builtins/descriptions.js.map +1 -0
- package/dist/tools/builtins/fetch.d.ts +12 -0
- package/dist/tools/builtins/fetch.js +157 -0
- package/dist/tools/builtins/fetch.js.map +1 -0
- package/dist/tools/builtins/files.d.ts +27 -0
- package/dist/tools/builtins/files.js +274 -0
- package/dist/tools/builtins/files.js.map +1 -0
- package/dist/tools/builtins/paths.d.ts +30 -0
- package/dist/tools/builtins/paths.js +62 -0
- package/dist/tools/builtins/paths.js.map +1 -0
- package/dist/tools/builtins/results.d.ts +15 -0
- package/dist/tools/builtins/results.js +31 -0
- package/dist/tools/builtins/results.js.map +1 -0
- package/dist/tools/builtins/search.d.ts +18 -0
- package/dist/tools/builtins/search.js +217 -0
- package/dist/tools/builtins/search.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 +12 -0
- package/dist/tools/index.js +11 -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 +469 -0
- package/package.json +118 -3
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What the stdio and WebSocket transports share once a message is framed: the dispatcher connection, the envelope
|
|
3
|
+
* check, the transport's own bounded error answers, and the fallbacks for a server message JSON can't carry. A
|
|
4
|
+
* transport frames what its client sends, hands each parsed value to `handle()` or each framing error to `refuse()`,
|
|
5
|
+
* and writes the lines `encode()` makes, so both transports answer the same bad message the same way.
|
|
6
|
+
*/
|
|
7
|
+
import { type ProtocolError } from "@buildanagent/protocol";
|
|
8
|
+
import type { Dispatcher } from "./dispatcher.js";
|
|
9
|
+
/** The default of each transport's `writeTimeoutMs`. */
|
|
10
|
+
export declare const DEFAULT_WRITE_TIMEOUT_MS = 30000;
|
|
11
|
+
/** Checks a transport's `writeTimeoutMs`, before it connects, and returns the value to use. */
|
|
12
|
+
export declare function checkWriteTimeout(ms: number | undefined): number;
|
|
13
|
+
/** An error's message, or the thrown value as text, for a diagnostic line. */
|
|
14
|
+
export declare const messageOf: (error: unknown) => string;
|
|
15
|
+
/** What a transport gives the session: where its lines go, where its diagnostics go, and how it stops. */
|
|
16
|
+
export interface RpcPeer {
|
|
17
|
+
/** The prefix of every diagnostic, such as `stdio`. */
|
|
18
|
+
readonly label: string;
|
|
19
|
+
readonly log: (line: string) => void;
|
|
20
|
+
/** Writes one line `encode()` made, newline included, and returns what to wait for when the output is full. */
|
|
21
|
+
write(line: string): PromiseLike<void> | undefined;
|
|
22
|
+
/** Stops the transport because the client broke a bound, or the dispatcher closed the connection. */
|
|
23
|
+
stop(why: string): void;
|
|
24
|
+
}
|
|
25
|
+
/** One client's connection, and the answers the transport writes beside it, as the module comment describes. */
|
|
26
|
+
export declare class RpcSession {
|
|
27
|
+
#private;
|
|
28
|
+
/** Connects to `dispatcher`, which throws when it is closed. */
|
|
29
|
+
constructor(dispatcher: Dispatcher, peer: RpcPeer);
|
|
30
|
+
/** The commands read whose responses are not queued yet. */
|
|
31
|
+
get commands(): ReadonlySet<Promise<void>>;
|
|
32
|
+
/** The delivery the connection's queue waits on, if any. */
|
|
33
|
+
get delivering(): PromiseLike<void> | undefined;
|
|
34
|
+
/** Closes the connection; the dispatcher's own close of it is no longer reported as a stop. */
|
|
35
|
+
close(): void;
|
|
36
|
+
/** Checks one parsed message's envelope and hands it to the connection, or answers why it can't. */
|
|
37
|
+
handle(value: unknown): void;
|
|
38
|
+
/**
|
|
39
|
+
* Logs and answers what the transport could not hand to the connection. An answer the output takes at once costs
|
|
40
|
+
* nothing; one that waits on a full output counts until the output has room, and once 128 wait, the transport stops.
|
|
41
|
+
*/
|
|
42
|
+
refuse(error: ProtocolError, fallbackCode: number, what: string): void;
|
|
43
|
+
}
|
|
@@ -0,0 +1,167 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What the stdio and WebSocket transports share once a message is framed: the dispatcher connection, the envelope
|
|
3
|
+
* check, the transport's own bounded error answers, and the fallbacks for a server message JSON can't carry. A
|
|
4
|
+
* transport frames what its client sends, hands each parsed value to `handle()` or each framing error to `refuse()`,
|
|
5
|
+
* and writes the lines `encode()` makes, so both transports answer the same bad message the same way.
|
|
6
|
+
*/
|
|
7
|
+
import { decode, ErrorCodes, encode, isProtocolError, } from "@buildanagent/protocol";
|
|
8
|
+
import { HarnessError } from "../errors.js";
|
|
9
|
+
/** The default of each transport's `writeTimeoutMs`. */
|
|
10
|
+
export const DEFAULT_WRITE_TIMEOUT_MS = 30_000;
|
|
11
|
+
/** The longest delay a timer takes; past it, `setTimeout` fires at once. */
|
|
12
|
+
const MAX_TIMER_MS = 2_147_483_647;
|
|
13
|
+
/** Checks a transport's `writeTimeoutMs`, before it connects, and returns the value to use. */
|
|
14
|
+
export function checkWriteTimeout(ms) {
|
|
15
|
+
if (ms === undefined)
|
|
16
|
+
return DEFAULT_WRITE_TIMEOUT_MS;
|
|
17
|
+
if (ms === Number.POSITIVE_INFINITY || (Number.isInteger(ms) && ms > 0 && ms <= MAX_TIMER_MS))
|
|
18
|
+
return ms;
|
|
19
|
+
throw new HarnessError("invalid_transport_options", `writeTimeoutMs must be a whole number from 1 to ${MAX_TIMER_MS}, or Infinity, got ${ms}`);
|
|
20
|
+
}
|
|
21
|
+
/**
|
|
22
|
+
* How many of the transport's own error answers, for messages it could not read, may wait on a full output. Past
|
|
23
|
+
* that, the client sends bad messages without reading the answers, and the transport stops, as the connection does
|
|
24
|
+
* for refusals.
|
|
25
|
+
*/
|
|
26
|
+
const MAX_WAITING_ERRORS = 128;
|
|
27
|
+
/** The error answer to a server request that could not be written, handed back so the server stops waiting on it. */
|
|
28
|
+
const UNWRITABLE_REQUEST = { code: ErrorCodes.InternalError, message: "the server could not write this request" };
|
|
29
|
+
/** An error's message, or the thrown value as text, for a diagnostic line. */
|
|
30
|
+
export const messageOf = (error) => (error instanceof Error ? error.message : String(error));
|
|
31
|
+
/** A refused value that answers a request: JSON-RPC never answers a response, even a malformed one. */
|
|
32
|
+
const isResponseLike = (value) => typeof value === "object" &&
|
|
33
|
+
value !== null &&
|
|
34
|
+
!Array.isArray(value) &&
|
|
35
|
+
!("method" in value) &&
|
|
36
|
+
("result" in value || "error" in value);
|
|
37
|
+
/** One client's connection, and the answers the transport writes beside it, as the module comment describes. */
|
|
38
|
+
export class RpcSession {
|
|
39
|
+
#peer;
|
|
40
|
+
#connection;
|
|
41
|
+
/** Each command read whose response is not queued yet. */
|
|
42
|
+
#commands = new Set();
|
|
43
|
+
/** The delivery the connection's queue waits on, if any, so a transport can wait for it before it closes. */
|
|
44
|
+
#delivering;
|
|
45
|
+
/** The transport's own error answers that wait on a full output. */
|
|
46
|
+
#waitingErrors = 0;
|
|
47
|
+
/** True once the transport closes the connection itself, so its own close is not taken for the server's. */
|
|
48
|
+
#closing = false;
|
|
49
|
+
/** Connects to `dispatcher`, which throws when it is closed. */
|
|
50
|
+
constructor(dispatcher, peer) {
|
|
51
|
+
this.#peer = peer;
|
|
52
|
+
this.#connection = dispatcher.connect((message) => this.#deliver(message), {
|
|
53
|
+
onClose: () => {
|
|
54
|
+
if (!this.#closing)
|
|
55
|
+
peer.stop("the connection closed");
|
|
56
|
+
},
|
|
57
|
+
});
|
|
58
|
+
}
|
|
59
|
+
/** The commands read whose responses are not queued yet. */
|
|
60
|
+
get commands() {
|
|
61
|
+
return this.#commands;
|
|
62
|
+
}
|
|
63
|
+
/** The delivery the connection's queue waits on, if any. */
|
|
64
|
+
get delivering() {
|
|
65
|
+
return this.#delivering;
|
|
66
|
+
}
|
|
67
|
+
/** Closes the connection; the dispatcher's own close of it is no longer reported as a stop. */
|
|
68
|
+
close() {
|
|
69
|
+
this.#closing = true;
|
|
70
|
+
this.#connection.close();
|
|
71
|
+
}
|
|
72
|
+
/** Checks one parsed message's envelope and hands it to the connection, or answers why it can't. */
|
|
73
|
+
handle(value) {
|
|
74
|
+
let message;
|
|
75
|
+
try {
|
|
76
|
+
message = decode(value);
|
|
77
|
+
}
|
|
78
|
+
catch (error) {
|
|
79
|
+
if (!isProtocolError(error))
|
|
80
|
+
throw error;
|
|
81
|
+
if (isResponseLike(value)) {
|
|
82
|
+
// The server's request it meant to answer still waits, as for any answer the server can't use.
|
|
83
|
+
this.#peer.log(`${this.#peer.label}: ignored a malformed response: ${error.message}`);
|
|
84
|
+
return;
|
|
85
|
+
}
|
|
86
|
+
this.refuse(error, ErrorCodes.InvalidRequest, "a message");
|
|
87
|
+
return;
|
|
88
|
+
}
|
|
89
|
+
this.#track(this.#connection.receive(message));
|
|
90
|
+
}
|
|
91
|
+
/**
|
|
92
|
+
* Logs and answers what the transport could not hand to the connection. An answer the output takes at once costs
|
|
93
|
+
* nothing; one that waits on a full output counts until the output has room, and once 128 wait, the transport stops.
|
|
94
|
+
*/
|
|
95
|
+
refuse(error, fallbackCode, what) {
|
|
96
|
+
this.#peer.log(`${this.#peer.label}: refused ${what}: ${error.message}`);
|
|
97
|
+
if (this.#waitingErrors >= MAX_WAITING_ERRORS) {
|
|
98
|
+
this.#peer.stop(`${MAX_WAITING_ERRORS} error responses wait unread`);
|
|
99
|
+
return;
|
|
100
|
+
}
|
|
101
|
+
const sent = this.#writeLine({
|
|
102
|
+
jsonrpc: "2.0",
|
|
103
|
+
id: error.requestId ?? null,
|
|
104
|
+
error: { code: error.rpcCode ?? fallbackCode, message: error.message },
|
|
105
|
+
});
|
|
106
|
+
if (sent === undefined)
|
|
107
|
+
return;
|
|
108
|
+
this.#waitingErrors += 1;
|
|
109
|
+
void Promise.resolve(sent).then(() => {
|
|
110
|
+
this.#waitingErrors -= 1;
|
|
111
|
+
});
|
|
112
|
+
}
|
|
113
|
+
/** Keeps a message the connection is handling until its response is queued, so a transport can wait for it. */
|
|
114
|
+
#track(receiving) {
|
|
115
|
+
const received = receiving.catch((error) => {
|
|
116
|
+
this.#peer.log(`${this.#peer.label}: a message failed: ${messageOf(error)}`);
|
|
117
|
+
});
|
|
118
|
+
this.#commands.add(received);
|
|
119
|
+
void received.then(() => this.#commands.delete(received));
|
|
120
|
+
}
|
|
121
|
+
/** The connection's `send`: writes one message and, when the output is full, returns what to wait for. */
|
|
122
|
+
#deliver(message) {
|
|
123
|
+
const sent = this.#writeLine(message);
|
|
124
|
+
if (sent === undefined)
|
|
125
|
+
return undefined;
|
|
126
|
+
const tracked = Promise.resolve(sent).then(() => {
|
|
127
|
+
if (this.#delivering === tracked)
|
|
128
|
+
this.#delivering = undefined;
|
|
129
|
+
});
|
|
130
|
+
this.#delivering = tracked;
|
|
131
|
+
return tracked;
|
|
132
|
+
}
|
|
133
|
+
#writeLine(message) {
|
|
134
|
+
let line;
|
|
135
|
+
try {
|
|
136
|
+
line = encode(message);
|
|
137
|
+
}
|
|
138
|
+
catch (error) {
|
|
139
|
+
this.#peer.log(`${this.#peer.label}: a server message could not be written: ${messageOf(error)}`);
|
|
140
|
+
return this.#unwritable(message);
|
|
141
|
+
}
|
|
142
|
+
return this.#peer.write(line);
|
|
143
|
+
}
|
|
144
|
+
/**
|
|
145
|
+
* Keeps a message JSON can't carry from leaving anyone waiting. A response goes out as an `InternalError`, so the
|
|
146
|
+
* client gets an answer. A server request is answered back into the connection with an error, as if the client had
|
|
147
|
+
* failed it, so a tool call ends with an error result. A notification is dropped.
|
|
148
|
+
*/
|
|
149
|
+
#unwritable(message) {
|
|
150
|
+
if (!("id" in message) || message.id === null)
|
|
151
|
+
return undefined;
|
|
152
|
+
if ("method" in message) {
|
|
153
|
+
const answer = { jsonrpc: "2.0", id: message.id, error: UNWRITABLE_REQUEST };
|
|
154
|
+
// After this delivery returns, so the connection sees the answer once it has recorded the request. The answer
|
|
155
|
+
// counts as a command read, so the end of the input waits for it before the connection closes.
|
|
156
|
+
this.#track(Promise.resolve().then(() => this.#connection.receive(answer)));
|
|
157
|
+
return undefined;
|
|
158
|
+
}
|
|
159
|
+
// The fallback waits for room like any line, so the connection's queue holds the next message meanwhile.
|
|
160
|
+
return this.#peer.write(encode({
|
|
161
|
+
jsonrpc: "2.0",
|
|
162
|
+
id: message.id,
|
|
163
|
+
error: { code: ErrorCodes.InternalError, message: "the response could not be written" },
|
|
164
|
+
}));
|
|
165
|
+
}
|
|
166
|
+
}
|
|
167
|
+
//# sourceMappingURL=rpc-session.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"rpc-session.js","sourceRoot":"","sources":["../../src/server/rpc-session.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What the stdio and WebSocket transports share once a message is framed: the dispatcher connection, the envelope\n * check, the transport's own bounded error answers, and the fallbacks for a server message JSON can't carry. A\n * transport frames what its client sends, hands each parsed value to `handle()` or each framing error to `refuse()`,\n * and writes the lines `encode()` makes, so both transports answer the same bad message the same way.\n */\nimport {\n type ClientMessage,\n decode,\n ErrorCodes,\n encode,\n isProtocolError,\n type ProtocolError,\n type ServerMessage,\n} from \"@buildanagent/protocol\";\nimport { HarnessError } from \"../errors.js\";\nimport type { Connection, Dispatcher } from \"./dispatcher.js\";\n\n/** The default of each transport's `writeTimeoutMs`. */\nexport const DEFAULT_WRITE_TIMEOUT_MS = 30_000;\n\n/** The longest delay a timer takes; past it, `setTimeout` fires at once. */\nconst MAX_TIMER_MS = 2_147_483_647;\n\n/** Checks a transport's `writeTimeoutMs`, before it connects, and returns the value to use. */\nexport function checkWriteTimeout(ms: number | undefined): number {\n if (ms === undefined) return DEFAULT_WRITE_TIMEOUT_MS;\n if (ms === Number.POSITIVE_INFINITY || (Number.isInteger(ms) && ms > 0 && ms <= MAX_TIMER_MS)) return ms;\n throw new HarnessError(\n \"invalid_transport_options\",\n `writeTimeoutMs must be a whole number from 1 to ${MAX_TIMER_MS}, or Infinity, got ${ms}`,\n );\n}\n\n/**\n * How many of the transport's own error answers, for messages it could not read, may wait on a full output. Past\n * that, the client sends bad messages without reading the answers, and the transport stops, as the connection does\n * for refusals.\n */\nconst MAX_WAITING_ERRORS = 128;\n\n/** The error answer to a server request that could not be written, handed back so the server stops waiting on it. */\nconst UNWRITABLE_REQUEST = { code: ErrorCodes.InternalError, message: \"the server could not write this request\" };\n\n/** An error's message, or the thrown value as text, for a diagnostic line. */\nexport const messageOf = (error: unknown): string => (error instanceof Error ? error.message : String(error));\n\n/** A refused value that answers a request: JSON-RPC never answers a response, even a malformed one. */\nconst isResponseLike = (value: unknown): boolean =>\n typeof value === \"object\" &&\n value !== null &&\n !Array.isArray(value) &&\n !(\"method\" in value) &&\n (\"result\" in value || \"error\" in value);\n\n/** What a transport gives the session: where its lines go, where its diagnostics go, and how it stops. */\nexport interface RpcPeer {\n /** The prefix of every diagnostic, such as `stdio`. */\n readonly label: string;\n readonly log: (line: string) => void;\n /** Writes one line `encode()` made, newline included, and returns what to wait for when the output is full. */\n write(line: string): PromiseLike<void> | undefined;\n /** Stops the transport because the client broke a bound, or the dispatcher closed the connection. */\n stop(why: string): void;\n}\n\n/** One client's connection, and the answers the transport writes beside it, as the module comment describes. */\nexport class RpcSession {\n readonly #peer: RpcPeer;\n readonly #connection: Connection;\n /** Each command read whose response is not queued yet. */\n readonly #commands = new Set<Promise<void>>();\n /** The delivery the connection's queue waits on, if any, so a transport can wait for it before it closes. */\n #delivering: PromiseLike<void> | undefined;\n /** The transport's own error answers that wait on a full output. */\n #waitingErrors = 0;\n /** True once the transport closes the connection itself, so its own close is not taken for the server's. */\n #closing = false;\n\n /** Connects to `dispatcher`, which throws when it is closed. */\n constructor(dispatcher: Dispatcher, peer: RpcPeer) {\n this.#peer = peer;\n this.#connection = dispatcher.connect((message) => this.#deliver(message), {\n onClose: () => {\n if (!this.#closing) peer.stop(\"the connection closed\");\n },\n });\n }\n\n /** The commands read whose responses are not queued yet. */\n get commands(): ReadonlySet<Promise<void>> {\n return this.#commands;\n }\n\n /** The delivery the connection's queue waits on, if any. */\n get delivering(): PromiseLike<void> | undefined {\n return this.#delivering;\n }\n\n /** Closes the connection; the dispatcher's own close of it is no longer reported as a stop. */\n close(): void {\n this.#closing = true;\n this.#connection.close();\n }\n\n /** Checks one parsed message's envelope and hands it to the connection, or answers why it can't. */\n handle(value: unknown): void {\n let message: ClientMessage;\n try {\n message = decode(value) as ClientMessage;\n } catch (error) {\n if (!isProtocolError(error)) throw error;\n if (isResponseLike(value)) {\n // The server's request it meant to answer still waits, as for any answer the server can't use.\n this.#peer.log(`${this.#peer.label}: ignored a malformed response: ${error.message}`);\n return;\n }\n this.refuse(error, ErrorCodes.InvalidRequest, \"a message\");\n return;\n }\n this.#track(this.#connection.receive(message));\n }\n\n /**\n * Logs and answers what the transport could not hand to the connection. An answer the output takes at once costs\n * nothing; one that waits on a full output counts until the output has room, and once 128 wait, the transport stops.\n */\n refuse(error: ProtocolError, fallbackCode: number, what: string): void {\n this.#peer.log(`${this.#peer.label}: refused ${what}: ${error.message}`);\n if (this.#waitingErrors >= MAX_WAITING_ERRORS) {\n this.#peer.stop(`${MAX_WAITING_ERRORS} error responses wait unread`);\n return;\n }\n const sent = this.#writeLine({\n jsonrpc: \"2.0\",\n id: error.requestId ?? null,\n error: { code: error.rpcCode ?? fallbackCode, message: error.message },\n } as ServerMessage);\n if (sent === undefined) return;\n this.#waitingErrors += 1;\n void Promise.resolve(sent).then(() => {\n this.#waitingErrors -= 1;\n });\n }\n\n /** Keeps a message the connection is handling until its response is queued, so a transport can wait for it. */\n #track(receiving: Promise<void>): void {\n const received = receiving.catch((error: unknown) => {\n this.#peer.log(`${this.#peer.label}: a message failed: ${messageOf(error)}`);\n });\n this.#commands.add(received);\n void received.then(() => this.#commands.delete(received));\n }\n\n /** The connection's `send`: writes one message and, when the output is full, returns what to wait for. */\n #deliver(message: ServerMessage): PromiseLike<void> | undefined {\n const sent = this.#writeLine(message);\n if (sent === undefined) return undefined;\n const tracked = Promise.resolve(sent).then(() => {\n if (this.#delivering === tracked) this.#delivering = undefined;\n });\n this.#delivering = tracked;\n return tracked;\n }\n\n #writeLine(message: ServerMessage): PromiseLike<void> | undefined {\n let line: string;\n try {\n line = encode(message);\n } catch (error) {\n this.#peer.log(`${this.#peer.label}: a server message could not be written: ${messageOf(error)}`);\n return this.#unwritable(message);\n }\n return this.#peer.write(line);\n }\n\n /**\n * Keeps a message JSON can't carry from leaving anyone waiting. A response goes out as an `InternalError`, so the\n * client gets an answer. A server request is answered back into the connection with an error, as if the client had\n * failed it, so a tool call ends with an error result. A notification is dropped.\n */\n #unwritable(message: ServerMessage): PromiseLike<void> | undefined {\n if (!(\"id\" in message) || message.id === null) return undefined;\n if (\"method\" in message) {\n const answer = { jsonrpc: \"2.0\" as const, id: message.id, error: UNWRITABLE_REQUEST };\n // After this delivery returns, so the connection sees the answer once it has recorded the request. The answer\n // counts as a command read, so the end of the input waits for it before the connection closes.\n this.#track(Promise.resolve().then(() => this.#connection.receive(answer)));\n return undefined;\n }\n // The fallback waits for room like any line, so the connection's queue holds the next message meanwhile.\n return this.#peer.write(\n encode({\n jsonrpc: \"2.0\",\n id: message.id,\n error: { code: ErrorCodes.InternalError, message: \"the response could not be written\" },\n }),\n );\n }\n}\n"]}
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
/** A Node `Readable` as the transport reads it, such as `process.stdin`. A string chunk is read as UTF-8. */
|
|
2
|
+
export interface NodeInput {
|
|
3
|
+
/** Adds the listener the transport reads chunks with. */
|
|
4
|
+
on(event: "data", listener: (chunk: Uint8Array | string) => void): unknown;
|
|
5
|
+
/** Adds the listener that tells the transport the input ended. */
|
|
6
|
+
on(event: "end" | "close", listener: () => void): unknown;
|
|
7
|
+
/** Adds the listener that tells the transport the input failed. */
|
|
8
|
+
on(event: "error", listener: (error: Error) => void): unknown;
|
|
9
|
+
/** Removes the chunk listener when the transport lets the input go. */
|
|
10
|
+
removeListener(event: "data", listener: (chunk: Uint8Array | string) => void): unknown;
|
|
11
|
+
/** Removes the end listener when the transport lets the input go. */
|
|
12
|
+
removeListener(event: "end" | "close", listener: () => void): unknown;
|
|
13
|
+
/** Removes the failure listener when the transport lets the input go. */
|
|
14
|
+
removeListener(event: "error", listener: (error: Error) => void): unknown;
|
|
15
|
+
/** Stops the flow while a chunk waits to be read, and when the transport lets the input go. */
|
|
16
|
+
pause(): unknown;
|
|
17
|
+
/** Starts the flow again once the transport wants the next chunk. */
|
|
18
|
+
resume(): unknown;
|
|
19
|
+
}
|
|
20
|
+
/** The bytes the transport reads: a Node `Readable` such as `process.stdin`, or a Web `ReadableStream`. */
|
|
21
|
+
export type StdioInput = NodeInput | ReadableStream<Uint8Array>;
|
|
22
|
+
/** A Node `Writable` as the transport writes to it, such as `process.stdout`. */
|
|
23
|
+
export interface NodeOutput {
|
|
24
|
+
/** Writes one line; `false` means the output is full until `drain`. */
|
|
25
|
+
write(chunk: Uint8Array, callback: (error?: Error | null) => void): boolean;
|
|
26
|
+
/** Adds the listener for room again, or for the output's close. */
|
|
27
|
+
on(event: "drain" | "close", listener: () => void): unknown;
|
|
28
|
+
/** Adds the listener that tells the transport the output failed. */
|
|
29
|
+
on(event: "error", listener: (error: Error) => void): unknown;
|
|
30
|
+
/** Removes a room or close listener once its wait ends or the transport lets the output go. */
|
|
31
|
+
removeListener(event: "drain" | "close", listener: () => void): unknown;
|
|
32
|
+
/** Removes the failure listener when the transport lets the output go. */
|
|
33
|
+
removeListener(event: "error", listener: (error: Error) => void): unknown;
|
|
34
|
+
}
|
|
35
|
+
/** Where the transport writes: a Node `Writable` such as `process.stdout`, or a Web `WritableStream`. */
|
|
36
|
+
export type StdioOutput = NodeOutput | WritableStream<Uint8Array>;
|
|
37
|
+
/** Why the transport stopped early, set once, and the waits that end when it does. */
|
|
38
|
+
export declare class Stopper {
|
|
39
|
+
#private;
|
|
40
|
+
get reason(): string | undefined;
|
|
41
|
+
get stopped(): boolean;
|
|
42
|
+
/** How many waits are subscribed now, so a test can check that none is left behind. */
|
|
43
|
+
get waits(): number;
|
|
44
|
+
stop(why: string): void;
|
|
45
|
+
/** Calls `listener` once the transport stops, and returns how to stop listening. */
|
|
46
|
+
onStop(listener: () => void): () => void;
|
|
47
|
+
/** Settles as `promise` does, or with `undefined` once the transport stops, whichever is first. */
|
|
48
|
+
until<T>(promise: PromiseLike<T>): Promise<T | undefined>;
|
|
49
|
+
}
|
|
50
|
+
/** One line out. `write()` returns a promise only when the output is full; `flushed()` waits for every line so far. */
|
|
51
|
+
export interface LineWriter {
|
|
52
|
+
write(bytes: Uint8Array): PromiseLike<void> | undefined;
|
|
53
|
+
flushed(): Promise<void>;
|
|
54
|
+
release(): void;
|
|
55
|
+
}
|
|
56
|
+
/** The next chunk in, or the end. `next()` rejects when the input fails. */
|
|
57
|
+
export interface ChunkReader {
|
|
58
|
+
next(): Promise<IteratorResult<Uint8Array | string, undefined>>;
|
|
59
|
+
release(): void;
|
|
60
|
+
}
|
|
61
|
+
/**
|
|
62
|
+
* A writer for either kind of output. A failed or closed output stops `stopper`. `onTaken` is called each time the
|
|
63
|
+
* output takes a line: a Node stream calls its write callback without an error, or a Web stream's write resolves.
|
|
64
|
+
*/
|
|
65
|
+
export declare function lineWriter(output: StdioOutput, stopper: Stopper, onTaken?: () => void): LineWriter;
|
|
66
|
+
/** A reader for either kind of input. */
|
|
67
|
+
export declare function chunkReader(input: StdioInput): ChunkReader;
|
|
@@ -0,0 +1,218 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The stream ends of the stdio transport: a reader and a writer for Node streams and for Web streams, and the stopper
|
|
3
|
+
* they share. Every wait here subscribes to the stopper and unsubscribes when it settles. A full output has one shared
|
|
4
|
+
* wait for room, so a long session under backpressure adds no listener and no promise reaction that outlives the
|
|
5
|
+
* wait. Releasing a reader or a writer removes the transport's listeners and locks and leaves the stream itself
|
|
6
|
+
* open: the host owns it.
|
|
7
|
+
*/
|
|
8
|
+
import { messageOf } from "./rpc-session.js";
|
|
9
|
+
/** Why the transport stopped early, set once, and the waits that end when it does. */
|
|
10
|
+
export class Stopper {
|
|
11
|
+
#reason;
|
|
12
|
+
#listeners = new Set();
|
|
13
|
+
get reason() {
|
|
14
|
+
return this.#reason;
|
|
15
|
+
}
|
|
16
|
+
get stopped() {
|
|
17
|
+
return this.#reason !== undefined;
|
|
18
|
+
}
|
|
19
|
+
/** How many waits are subscribed now, so a test can check that none is left behind. */
|
|
20
|
+
get waits() {
|
|
21
|
+
return this.#listeners.size;
|
|
22
|
+
}
|
|
23
|
+
stop(why) {
|
|
24
|
+
if (this.#reason !== undefined)
|
|
25
|
+
return;
|
|
26
|
+
this.#reason = why;
|
|
27
|
+
const listeners = [...this.#listeners];
|
|
28
|
+
this.#listeners.clear();
|
|
29
|
+
for (const listener of listeners)
|
|
30
|
+
listener();
|
|
31
|
+
}
|
|
32
|
+
/** Calls `listener` once the transport stops, and returns how to stop listening. */
|
|
33
|
+
onStop(listener) {
|
|
34
|
+
this.#listeners.add(listener);
|
|
35
|
+
return () => this.#listeners.delete(listener);
|
|
36
|
+
}
|
|
37
|
+
/** Settles as `promise` does, or with `undefined` once the transport stops, whichever is first. */
|
|
38
|
+
until(promise) {
|
|
39
|
+
if (this.stopped)
|
|
40
|
+
return Promise.resolve(undefined);
|
|
41
|
+
return new Promise((resolve, reject) => {
|
|
42
|
+
const off = this.onStop(() => resolve(undefined));
|
|
43
|
+
promise.then((value) => {
|
|
44
|
+
off();
|
|
45
|
+
resolve(value);
|
|
46
|
+
}, (error) => {
|
|
47
|
+
off();
|
|
48
|
+
reject(error);
|
|
49
|
+
});
|
|
50
|
+
});
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
const isWebOutput = (output) => "getWriter" in output;
|
|
54
|
+
/**
|
|
55
|
+
* A writer for either kind of output. A failed or closed output stops `stopper`. `onTaken` is called each time the
|
|
56
|
+
* output takes a line: a Node stream calls its write callback without an error, or a Web stream's write resolves.
|
|
57
|
+
*/
|
|
58
|
+
export function lineWriter(output, stopper, onTaken = () => undefined) {
|
|
59
|
+
return isWebOutput(output) ? webWriter(output, stopper, onTaken) : nodeWriter(output, stopper, onTaken);
|
|
60
|
+
}
|
|
61
|
+
function nodeWriter(output, stopper, onTaken) {
|
|
62
|
+
let last = Promise.resolve();
|
|
63
|
+
// The one wait for room while the output is full, shared by every write made meanwhile.
|
|
64
|
+
let full;
|
|
65
|
+
const onError = (error) => stopper.stop(`the output failed: ${error.message}`);
|
|
66
|
+
const onClose = () => stopper.stop("the output closed");
|
|
67
|
+
output.on("error", onError);
|
|
68
|
+
output.on("close", onClose);
|
|
69
|
+
const room = () => {
|
|
70
|
+
full ??= new Promise((resolve) => {
|
|
71
|
+
const done = () => {
|
|
72
|
+
output.removeListener("drain", done);
|
|
73
|
+
off();
|
|
74
|
+
full = undefined;
|
|
75
|
+
resolve();
|
|
76
|
+
};
|
|
77
|
+
output.on("drain", done);
|
|
78
|
+
const off = stopper.onStop(done);
|
|
79
|
+
});
|
|
80
|
+
return full;
|
|
81
|
+
};
|
|
82
|
+
return {
|
|
83
|
+
write(bytes) {
|
|
84
|
+
if (stopper.stopped)
|
|
85
|
+
return undefined;
|
|
86
|
+
let ready = true;
|
|
87
|
+
last = new Promise((resolve) => {
|
|
88
|
+
ready = output.write(bytes, (error) => {
|
|
89
|
+
if (error)
|
|
90
|
+
onError(error);
|
|
91
|
+
else
|
|
92
|
+
onTaken();
|
|
93
|
+
resolve();
|
|
94
|
+
});
|
|
95
|
+
});
|
|
96
|
+
return ready ? undefined : room();
|
|
97
|
+
},
|
|
98
|
+
flushed: () => stopper.until(last).then(() => undefined),
|
|
99
|
+
release() {
|
|
100
|
+
output.removeListener("error", onError);
|
|
101
|
+
output.removeListener("close", onClose);
|
|
102
|
+
},
|
|
103
|
+
};
|
|
104
|
+
}
|
|
105
|
+
function webWriter(output, stopper, onTaken) {
|
|
106
|
+
const writer = output.getWriter();
|
|
107
|
+
let last = Promise.resolve();
|
|
108
|
+
let full;
|
|
109
|
+
let released = false;
|
|
110
|
+
writer.closed.then(() => {
|
|
111
|
+
if (!released)
|
|
112
|
+
stopper.stop("the output closed");
|
|
113
|
+
}, (error) => {
|
|
114
|
+
if (!released)
|
|
115
|
+
stopper.stop(`the output failed: ${messageOf(error)}`);
|
|
116
|
+
});
|
|
117
|
+
return {
|
|
118
|
+
write(bytes) {
|
|
119
|
+
if (stopper.stopped)
|
|
120
|
+
return undefined;
|
|
121
|
+
last = writer.write(bytes).then(onTaken, () => undefined);
|
|
122
|
+
// A Web stream counts what waits in its own queue; `ready` settles once there is room again.
|
|
123
|
+
if (writer.desiredSize !== null && writer.desiredSize > 0)
|
|
124
|
+
return undefined;
|
|
125
|
+
full ??= stopper.until(writer.ready.catch(() => undefined)).then(() => {
|
|
126
|
+
full = undefined;
|
|
127
|
+
});
|
|
128
|
+
return full;
|
|
129
|
+
},
|
|
130
|
+
flushed: () => stopper.until(last).then(() => undefined),
|
|
131
|
+
release() {
|
|
132
|
+
released = true;
|
|
133
|
+
writer.releaseLock();
|
|
134
|
+
},
|
|
135
|
+
};
|
|
136
|
+
}
|
|
137
|
+
/** A reader for either kind of input. */
|
|
138
|
+
export function chunkReader(input) {
|
|
139
|
+
return "getReader" in input ? webReader(input) : nodeReader(input);
|
|
140
|
+
}
|
|
141
|
+
/**
|
|
142
|
+
* Reads a Node stream by its events, pausing it while a chunk waits to be read, so the stream's own buffer holds the
|
|
143
|
+
* rest. `release()` removes the listeners and pauses the stream, which leaves it open, unlike an async iterator's
|
|
144
|
+
* `return()`, which destroys it and waits behind a pending read.
|
|
145
|
+
*/
|
|
146
|
+
function nodeReader(input) {
|
|
147
|
+
const queue = [];
|
|
148
|
+
let ended = false;
|
|
149
|
+
let failure;
|
|
150
|
+
let wake;
|
|
151
|
+
const notify = () => {
|
|
152
|
+
const waiting = wake;
|
|
153
|
+
wake = undefined;
|
|
154
|
+
waiting?.();
|
|
155
|
+
};
|
|
156
|
+
const onData = (chunk) => {
|
|
157
|
+
queue.push(chunk);
|
|
158
|
+
input.pause();
|
|
159
|
+
notify();
|
|
160
|
+
};
|
|
161
|
+
const onEnd = () => {
|
|
162
|
+
ended = true;
|
|
163
|
+
notify();
|
|
164
|
+
};
|
|
165
|
+
const onError = (error) => {
|
|
166
|
+
failure = error;
|
|
167
|
+
notify();
|
|
168
|
+
};
|
|
169
|
+
input.on("data", onData);
|
|
170
|
+
input.on("end", onEnd);
|
|
171
|
+
input.on("close", onEnd);
|
|
172
|
+
input.on("error", onError);
|
|
173
|
+
return {
|
|
174
|
+
async next() {
|
|
175
|
+
for (;;) {
|
|
176
|
+
const chunk = queue.shift();
|
|
177
|
+
if (chunk !== undefined)
|
|
178
|
+
return { done: false, value: chunk };
|
|
179
|
+
if (failure !== undefined)
|
|
180
|
+
throw failure;
|
|
181
|
+
if (ended)
|
|
182
|
+
return { done: true, value: undefined };
|
|
183
|
+
input.resume();
|
|
184
|
+
await new Promise((resolve) => {
|
|
185
|
+
wake = resolve;
|
|
186
|
+
});
|
|
187
|
+
}
|
|
188
|
+
},
|
|
189
|
+
release() {
|
|
190
|
+
input.removeListener("data", onData);
|
|
191
|
+
input.removeListener("end", onEnd);
|
|
192
|
+
input.removeListener("close", onEnd);
|
|
193
|
+
input.removeListener("error", onError);
|
|
194
|
+
input.pause();
|
|
195
|
+
ended = true;
|
|
196
|
+
notify();
|
|
197
|
+
},
|
|
198
|
+
};
|
|
199
|
+
}
|
|
200
|
+
/** Reads a Web stream through its reader. `release()` releases the lock, which leaves the stream uncancelled. */
|
|
201
|
+
function webReader(input) {
|
|
202
|
+
const reader = input.getReader();
|
|
203
|
+
let released = false;
|
|
204
|
+
return {
|
|
205
|
+
async next() {
|
|
206
|
+
if (released)
|
|
207
|
+
return { done: true, value: undefined };
|
|
208
|
+
const read = await reader.read();
|
|
209
|
+
return read.done ? { done: true, value: undefined } : { done: false, value: read.value };
|
|
210
|
+
},
|
|
211
|
+
release() {
|
|
212
|
+
released = true;
|
|
213
|
+
// A read still pending rejects with the release, which nothing waits for by then.
|
|
214
|
+
reader.releaseLock();
|
|
215
|
+
},
|
|
216
|
+
};
|
|
217
|
+
}
|
|
218
|
+
//# sourceMappingURL=stdio-streams.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"stdio-streams.js","sourceRoot":"","sources":["../../src/server/stdio-streams.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The stream ends of the stdio transport: a reader and a writer for Node streams and for Web streams, and the stopper\n * they share. Every wait here subscribes to the stopper and unsubscribes when it settles. A full output has one shared\n * wait for room, so a long session under backpressure adds no listener and no promise reaction that outlives the\n * wait. Releasing a reader or a writer removes the transport's listeners and locks and leaves the stream itself\n * open: the host owns it.\n */\nimport { messageOf } from \"./rpc-session.js\";\n\n/** A Node `Readable` as the transport reads it, such as `process.stdin`. A string chunk is read as UTF-8. */\nexport interface NodeInput {\n /** Adds the listener the transport reads chunks with. */\n on(event: \"data\", listener: (chunk: Uint8Array | string) => void): unknown;\n /** Adds the listener that tells the transport the input ended. */\n on(event: \"end\" | \"close\", listener: () => void): unknown;\n /** Adds the listener that tells the transport the input failed. */\n on(event: \"error\", listener: (error: Error) => void): unknown;\n /** Removes the chunk listener when the transport lets the input go. */\n removeListener(event: \"data\", listener: (chunk: Uint8Array | string) => void): unknown;\n /** Removes the end listener when the transport lets the input go. */\n removeListener(event: \"end\" | \"close\", listener: () => void): unknown;\n /** Removes the failure listener when the transport lets the input go. */\n removeListener(event: \"error\", listener: (error: Error) => void): unknown;\n /** Stops the flow while a chunk waits to be read, and when the transport lets the input go. */\n pause(): unknown;\n /** Starts the flow again once the transport wants the next chunk. */\n resume(): unknown;\n}\n\n/** The bytes the transport reads: a Node `Readable` such as `process.stdin`, or a Web `ReadableStream`. */\nexport type StdioInput = NodeInput | ReadableStream<Uint8Array>;\n\n/** A Node `Writable` as the transport writes to it, such as `process.stdout`. */\nexport interface NodeOutput {\n /** Writes one line; `false` means the output is full until `drain`. */\n write(chunk: Uint8Array, callback: (error?: Error | null) => void): boolean;\n /** Adds the listener for room again, or for the output's close. */\n on(event: \"drain\" | \"close\", listener: () => void): unknown;\n /** Adds the listener that tells the transport the output failed. */\n on(event: \"error\", listener: (error: Error) => void): unknown;\n /** Removes a room or close listener once its wait ends or the transport lets the output go. */\n removeListener(event: \"drain\" | \"close\", listener: () => void): unknown;\n /** Removes the failure listener when the transport lets the output go. */\n removeListener(event: \"error\", listener: (error: Error) => void): unknown;\n}\n\n/** Where the transport writes: a Node `Writable` such as `process.stdout`, or a Web `WritableStream`. */\nexport type StdioOutput = NodeOutput | WritableStream<Uint8Array>;\n\n/** Why the transport stopped early, set once, and the waits that end when it does. */\nexport class Stopper {\n #reason: string | undefined;\n readonly #listeners = new Set<() => void>();\n\n get reason(): string | undefined {\n return this.#reason;\n }\n\n get stopped(): boolean {\n return this.#reason !== undefined;\n }\n\n /** How many waits are subscribed now, so a test can check that none is left behind. */\n get waits(): number {\n return this.#listeners.size;\n }\n\n stop(why: string): void {\n if (this.#reason !== undefined) return;\n this.#reason = why;\n const listeners = [...this.#listeners];\n this.#listeners.clear();\n for (const listener of listeners) listener();\n }\n\n /** Calls `listener` once the transport stops, and returns how to stop listening. */\n onStop(listener: () => void): () => void {\n this.#listeners.add(listener);\n return () => this.#listeners.delete(listener);\n }\n\n /** Settles as `promise` does, or with `undefined` once the transport stops, whichever is first. */\n until<T>(promise: PromiseLike<T>): Promise<T | undefined> {\n if (this.stopped) return Promise.resolve(undefined);\n return new Promise<T | undefined>((resolve, reject) => {\n const off = this.onStop(() => resolve(undefined));\n promise.then(\n (value) => {\n off();\n resolve(value);\n },\n (error: unknown) => {\n off();\n reject(error);\n },\n );\n });\n }\n}\n\n/** One line out. `write()` returns a promise only when the output is full; `flushed()` waits for every line so far. */\nexport interface LineWriter {\n write(bytes: Uint8Array): PromiseLike<void> | undefined;\n flushed(): Promise<void>;\n release(): void;\n}\n\n/** The next chunk in, or the end. `next()` rejects when the input fails. */\nexport interface ChunkReader {\n next(): Promise<IteratorResult<Uint8Array | string, undefined>>;\n release(): void;\n}\n\nconst isWebOutput = (output: StdioOutput): output is WritableStream<Uint8Array> => \"getWriter\" in output;\n\n/**\n * A writer for either kind of output. A failed or closed output stops `stopper`. `onTaken` is called each time the\n * output takes a line: a Node stream calls its write callback without an error, or a Web stream's write resolves.\n */\nexport function lineWriter(output: StdioOutput, stopper: Stopper, onTaken: () => void = () => undefined): LineWriter {\n return isWebOutput(output) ? webWriter(output, stopper, onTaken) : nodeWriter(output, stopper, onTaken);\n}\n\nfunction nodeWriter(output: NodeOutput, stopper: Stopper, onTaken: () => void): LineWriter {\n let last: Promise<void> = Promise.resolve();\n // The one wait for room while the output is full, shared by every write made meanwhile.\n let full: Promise<void> | undefined;\n const onError = (error: Error) => stopper.stop(`the output failed: ${error.message}`);\n const onClose = () => stopper.stop(\"the output closed\");\n output.on(\"error\", onError);\n output.on(\"close\", onClose);\n const room = (): Promise<void> => {\n full ??= new Promise<void>((resolve) => {\n const done = () => {\n output.removeListener(\"drain\", done);\n off();\n full = undefined;\n resolve();\n };\n output.on(\"drain\", done);\n const off = stopper.onStop(done);\n });\n return full;\n };\n return {\n write(bytes) {\n if (stopper.stopped) return undefined;\n let ready = true;\n last = new Promise<void>((resolve) => {\n ready = output.write(bytes, (error) => {\n if (error) onError(error);\n else onTaken();\n resolve();\n });\n });\n return ready ? undefined : room();\n },\n flushed: () => stopper.until(last).then(() => undefined),\n release() {\n output.removeListener(\"error\", onError);\n output.removeListener(\"close\", onClose);\n },\n };\n}\n\nfunction webWriter(output: WritableStream<Uint8Array>, stopper: Stopper, onTaken: () => void): LineWriter {\n const writer = output.getWriter();\n let last: Promise<void> = Promise.resolve();\n let full: Promise<void> | undefined;\n let released = false;\n writer.closed.then(\n () => {\n if (!released) stopper.stop(\"the output closed\");\n },\n (error: unknown) => {\n if (!released) stopper.stop(`the output failed: ${messageOf(error)}`);\n },\n );\n return {\n write(bytes) {\n if (stopper.stopped) return undefined;\n last = writer.write(bytes).then(onTaken, () => undefined);\n // A Web stream counts what waits in its own queue; `ready` settles once there is room again.\n if (writer.desiredSize !== null && writer.desiredSize > 0) return undefined;\n full ??= stopper.until(writer.ready.catch(() => undefined)).then(() => {\n full = undefined;\n });\n return full;\n },\n flushed: () => stopper.until(last).then(() => undefined),\n release() {\n released = true;\n writer.releaseLock();\n },\n };\n}\n\n/** A reader for either kind of input. */\nexport function chunkReader(input: StdioInput): ChunkReader {\n return \"getReader\" in input ? webReader(input) : nodeReader(input);\n}\n\n/**\n * Reads a Node stream by its events, pausing it while a chunk waits to be read, so the stream's own buffer holds the\n * rest. `release()` removes the listeners and pauses the stream, which leaves it open, unlike an async iterator's\n * `return()`, which destroys it and waits behind a pending read.\n */\nfunction nodeReader(input: NodeInput): ChunkReader {\n const queue: (Uint8Array | string)[] = [];\n let ended = false;\n let failure: Error | undefined;\n let wake: (() => void) | undefined;\n const notify = () => {\n const waiting = wake;\n wake = undefined;\n waiting?.();\n };\n const onData = (chunk: Uint8Array | string) => {\n queue.push(chunk);\n input.pause();\n notify();\n };\n const onEnd = () => {\n ended = true;\n notify();\n };\n const onError = (error: Error) => {\n failure = error;\n notify();\n };\n input.on(\"data\", onData);\n input.on(\"end\", onEnd);\n input.on(\"close\", onEnd);\n input.on(\"error\", onError);\n return {\n async next() {\n for (;;) {\n const chunk = queue.shift();\n if (chunk !== undefined) return { done: false, value: chunk };\n if (failure !== undefined) throw failure;\n if (ended) return { done: true, value: undefined };\n input.resume();\n await new Promise<void>((resolve) => {\n wake = resolve;\n });\n }\n },\n release() {\n input.removeListener(\"data\", onData);\n input.removeListener(\"end\", onEnd);\n input.removeListener(\"close\", onEnd);\n input.removeListener(\"error\", onError);\n input.pause();\n ended = true;\n notify();\n },\n };\n}\n\n/** Reads a Web stream through its reader. `release()` releases the lock, which leaves the stream uncancelled. */\nfunction webReader(input: ReadableStream<Uint8Array>): ChunkReader {\n const reader = input.getReader();\n let released = false;\n return {\n async next() {\n if (released) return { done: true, value: undefined };\n const read = await reader.read();\n return read.done ? { done: true, value: undefined } : { done: false, value: read.value };\n },\n release() {\n released = true;\n // A read still pending rejects with the release, which nothing waits for by then.\n reader.releaseLock();\n },\n };\n}\n"]}
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
import type { Dispatcher } from "./dispatcher.js";
|
|
2
|
+
import { type StdioInput, type StdioOutput } from "./stdio-streams.js";
|
|
3
|
+
export type { NodeInput, NodeOutput, StdioInput, StdioOutput } from "./stdio-streams.js";
|
|
4
|
+
/** The streams `stdioTransport()` serves a client over. */
|
|
5
|
+
export interface StdioIo {
|
|
6
|
+
/** What the client sends. Its end is the client's goodbye. */
|
|
7
|
+
readonly input: StdioInput;
|
|
8
|
+
/** What the server sends: protocol lines only. */
|
|
9
|
+
readonly output: StdioOutput;
|
|
10
|
+
/**
|
|
11
|
+
* Takes one line of the transport's own diagnostics, such as a malformed line it answered with an error. Point it at
|
|
12
|
+
* stderr, never at `output`. A line never holds what the client sent. Default: diagnostics are dropped.
|
|
13
|
+
*/
|
|
14
|
+
readonly log?: (line: string) => void;
|
|
15
|
+
}
|
|
16
|
+
/** What `stdioTransport()` takes besides the dispatcher and the streams. */
|
|
17
|
+
export interface StdioOptions {
|
|
18
|
+
/** The most bytes one input line may hold, newline excluded. A longer line is answered with an error. Default 8 MiB. */
|
|
19
|
+
readonly maxLineBytes?: number;
|
|
20
|
+
/** Stops the transport now: the connection closes, and nothing more is read or waited for. */
|
|
21
|
+
readonly signal?: AbortSignal;
|
|
22
|
+
/**
|
|
23
|
+
* How long, in milliseconds, the output may take to take each queued line once the input has ended. The limit is per
|
|
24
|
+
* line: the clock starts when the transport begins to wait for the output and restarts each time the output takes a
|
|
25
|
+
* whole line, because an output reports no progress within a line. A client that goes on reading is therefore cut
|
|
26
|
+
* off only when one line takes longer than this, so a host that sends very large lines to slow clients raises it. A
|
|
27
|
+
* client that has closed its input and takes no line for this long ends the transport: it logs why and closes the
|
|
28
|
+
* connection, as for a failed output. While the input is open there is no timeout, because the queue already bounds
|
|
29
|
+
* what a slow client costs, and the time the dispatcher takes to answer a command does not count. A whole number
|
|
30
|
+
* from 1 to 2,147,483,647, or `Infinity` to wait forever. Default 30,000 (30 seconds).
|
|
31
|
+
*/
|
|
32
|
+
readonly writeTimeoutMs?: number;
|
|
33
|
+
}
|
|
34
|
+
/**
|
|
35
|
+
* Serves one client over a pair of byte streams, one JSON-RPC 2.0 message per line, and resolves once the client is
|
|
36
|
+
* done. `buildanagent rpc` calls it with `process.stdin`, `process.stdout` and a `log` that writes to stderr.
|
|
37
|
+
*
|
|
38
|
+
* Each line is read with the protocol's framer, which splits on `\n` only, and checked with `decode()`. A line that
|
|
39
|
+
* isn't JSON is answered with `ParseError`, and a message without a valid envelope, or a line over `maxLineBytes`,
|
|
40
|
+
* with `InvalidRequest`; the error carries the request's id when it could be read and `null` otherwise. A malformed
|
|
41
|
+
* response, one that carries `result` or `error`, is only logged, because JSON-RPC never answers a response. A bad
|
|
42
|
+
* line never ends the stream. The transport stops once 128 of its error answers wait on a full output, because the
|
|
43
|
+
* client is sending bad lines without reading.
|
|
44
|
+
*
|
|
45
|
+
* What the server sends waits for the output to take it, so a client that stops reading holds the server's queue, and
|
|
46
|
+
* the dispatcher drops live events past the queue size instead of buffering them.
|
|
47
|
+
*
|
|
48
|
+
* The end of the input is the client's goodbye. The transport answers every command it has read, waits until each
|
|
49
|
+
* line already sent is written, then closes the connection and resolves. A turn the client started goes on in the
|
|
50
|
+
* dispatcher, but its events have nowhere to go, so a client that wants `turn/settled` keeps its input open until that
|
|
51
|
+
* arrives. An input that fails is logged and then treated as an end. Once the input has ended, the output must take
|
|
52
|
+
* each queued line within `writeTimeoutMs`, 30 seconds by default; when one line takes longer, the transport stops and
|
|
53
|
+
* logs why. The transport resolves
|
|
54
|
+
* without waiting, and logs why, when the output fails or closes, when the dispatcher closes the connection or when
|
|
55
|
+
* `signal` aborts. It never ends, closes or cancels either stream: it removes its listeners and releases its locks,
|
|
56
|
+
* and the host owns the rest. A `writeTimeoutMs` that is not a whole number from 1 to 2,147,483,647 or `Infinity`
|
|
57
|
+
* rejects with a `HarnessError`, code `invalid_transport_options`, before the transport connects.
|
|
58
|
+
*/
|
|
59
|
+
export declare function stdioTransport(dispatcher: Dispatcher, io: StdioIo, options?: StdioOptions): Promise<void>;
|