amplifier-agent-ts 0.4.0 → 0.6.1
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/dist/argv-builder.d.ts +28 -13
- package/dist/argv-builder.js +31 -15
- package/dist/index.d.ts +116 -18
- package/dist/index.js +113 -21
- package/dist/mcp-spill.d.ts +3 -1
- package/dist/mcp-spill.js +5 -3
- package/dist/session.d.ts +77 -14
- package/dist/session.js +64 -19
- package/dist/transport.d.ts +39 -0
- package/dist/transport.js +44 -0
- package/dist/types.d.ts +13 -41
- package/package.json +2 -2
package/dist/argv-builder.d.ts
CHANGED
|
@@ -14,7 +14,7 @@ export interface AssembleArgvInput {
|
|
|
14
14
|
sessionId: string;
|
|
15
15
|
/** Final user prompt — emitted last as a positional argument. */
|
|
16
16
|
prompt: string;
|
|
17
|
-
/** Protocol version the wrapper speaks (e.g. "0.
|
|
17
|
+
/** Protocol version the wrapper speaks (e.g. "0.3.0"). */
|
|
18
18
|
protocolVersion: string;
|
|
19
19
|
/** When true, emit `--resume` instead of `--fresh`. */
|
|
20
20
|
resume?: boolean;
|
|
@@ -23,24 +23,39 @@ export interface AssembleArgvInput {
|
|
|
23
23
|
/** Provider override; emits `--provider <providerOverride>`. */
|
|
24
24
|
providerOverride?: string;
|
|
25
25
|
/**
|
|
26
|
-
* Path to the
|
|
27
|
-
*
|
|
28
|
-
*
|
|
26
|
+
* Path to the engine's host config file (Issue #1). Emits
|
|
27
|
+
* `--config <configPath>`. The engine's `single_turn` mode reads this
|
|
28
|
+
* to compose the host_config layer (approval mode, MCP servers,
|
|
29
|
+
* provider defaults, allowProtocolSkew, etc.) — see
|
|
30
|
+
* `src/amplifier_agent_cli/modes/single_turn.py` (`--config` option).
|
|
29
31
|
*/
|
|
30
|
-
|
|
31
|
-
/**
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
32
|
+
configPath?: string;
|
|
33
|
+
/**
|
|
34
|
+
* Approval-mode override forwarded to the engine (Issue #10). When set,
|
|
35
|
+
* emits `-y` (always allow) or `-n` (always deny). `"prompt"` is left
|
|
36
|
+
* implicit so the engine falls back to its host_config approval.mode
|
|
37
|
+
* or its TTY-based default.
|
|
38
|
+
*
|
|
39
|
+
* The wrapper unconditionally emits `-y` from older revisions has been
|
|
40
|
+
* removed — the caller now owns this policy decision.
|
|
41
|
+
*/
|
|
42
|
+
approvalMode?: "yes" | "no" | "prompt";
|
|
39
43
|
}
|
|
40
44
|
/**
|
|
41
45
|
* Build the argv array for `amplifier-agent run`.
|
|
42
46
|
*
|
|
43
47
|
* Pure function: no I/O, no env reads, no globals. Order is canonical and
|
|
44
48
|
* stable so wrapper integration tests can pin against it.
|
|
49
|
+
*
|
|
50
|
+
* Removed argv flags (no longer emitted by this wrapper):
|
|
51
|
+
* - `--mcp-config-path` (engine PR #29): MCP config is now forwarded via the
|
|
52
|
+
* `AMPLIFIER_MCP_CONFIG` env var injected into the engine's subprocess
|
|
53
|
+
* environment at spawn time (or via `host_config["mcp"]["configPath"]` in
|
|
54
|
+
* the host's config file).
|
|
55
|
+
* - `--env-allowlist`, `--env-extra` (engine PR #27): env composition is
|
|
56
|
+
* the host's responsibility. Hosts either set `$AMPLIFIER_AGENT_CONFIG`
|
|
57
|
+
* in the subprocess env or pass `--config <path>` per turn.
|
|
58
|
+
* - `--allow-protocol-skew` (engine PR #27): the unsafe override moved to
|
|
59
|
+
* `host_config.allowProtocolSkew: true` in the JSON config file.
|
|
45
60
|
*/
|
|
46
61
|
export declare function assembleArgv(input: AssembleArgvInput): string[];
|
package/dist/argv-builder.js
CHANGED
|
@@ -14,6 +14,17 @@
|
|
|
14
14
|
*
|
|
15
15
|
* Pure function: no I/O, no env reads, no globals. Order is canonical and
|
|
16
16
|
* stable so wrapper integration tests can pin against it.
|
|
17
|
+
*
|
|
18
|
+
* Removed argv flags (no longer emitted by this wrapper):
|
|
19
|
+
* - `--mcp-config-path` (engine PR #29): MCP config is now forwarded via the
|
|
20
|
+
* `AMPLIFIER_MCP_CONFIG` env var injected into the engine's subprocess
|
|
21
|
+
* environment at spawn time (or via `host_config["mcp"]["configPath"]` in
|
|
22
|
+
* the host's config file).
|
|
23
|
+
* - `--env-allowlist`, `--env-extra` (engine PR #27): env composition is
|
|
24
|
+
* the host's responsibility. Hosts either set `$AMPLIFIER_AGENT_CONFIG`
|
|
25
|
+
* in the subprocess env or pass `--config <path>` per turn.
|
|
26
|
+
* - `--allow-protocol-skew` (engine PR #27): the unsafe override moved to
|
|
27
|
+
* `host_config.allowProtocolSkew: true` in the JSON config file.
|
|
17
28
|
*/
|
|
18
29
|
export function assembleArgv(input) {
|
|
19
30
|
const argv = [];
|
|
@@ -26,25 +37,30 @@ export function assembleArgv(input) {
|
|
|
26
37
|
if (input.providerOverride !== undefined) {
|
|
27
38
|
argv.push("--provider", input.providerOverride);
|
|
28
39
|
}
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
if (input.hostCapabilities !== undefined) {
|
|
33
|
-
argv.push("--host-capabilities", JSON.stringify(input.hostCapabilities));
|
|
34
|
-
}
|
|
35
|
-
if (input.envAllowlist !== undefined && input.envAllowlist.length > 0) {
|
|
36
|
-
argv.push("--env-allowlist", input.envAllowlist.join(","));
|
|
37
|
-
}
|
|
38
|
-
if (input.envExtra !== undefined) {
|
|
39
|
-
argv.push("--env-extra", JSON.stringify(input.envExtra));
|
|
40
|
+
// Issue #1: surface the engine's --config flag.
|
|
41
|
+
if (input.configPath !== undefined) {
|
|
42
|
+
argv.push("--config", input.configPath);
|
|
40
43
|
}
|
|
41
44
|
argv.push("--output", "json");
|
|
42
45
|
argv.push("--protocol-version", input.protocolVersion);
|
|
43
|
-
|
|
44
|
-
|
|
46
|
+
// Issue #10: approval policy is now caller-controlled.
|
|
47
|
+
// - "yes" -> -y (always allow)
|
|
48
|
+
// - "no" -> -n (always deny)
|
|
49
|
+
// - "prompt" -> emit nothing; engine falls back to host_config.approval.mode
|
|
50
|
+
// or the bundle's TTY-based default. This is the only way to
|
|
51
|
+
// defer to the engine's policy resolution.
|
|
52
|
+
// - undefined -> preserve historical default (-y) so existing callers
|
|
53
|
+
// who haven't opted into the approval API are unaffected.
|
|
54
|
+
const mode = input.approvalMode;
|
|
55
|
+
if (mode === "yes" || mode === undefined) {
|
|
56
|
+
argv.push("-y");
|
|
57
|
+
}
|
|
58
|
+
else if (mode === "no") {
|
|
59
|
+
argv.push("-n");
|
|
60
|
+
}
|
|
61
|
+
else {
|
|
62
|
+
// mode === "prompt": deliberately emit no flag.
|
|
45
63
|
}
|
|
46
|
-
// SC-C: wrapper enforces auto-allow at the bundle layer.
|
|
47
|
-
argv.push("-y");
|
|
48
64
|
// Prompt is the final positional argument.
|
|
49
65
|
argv.push(input.prompt);
|
|
50
66
|
return argv;
|
package/dist/index.d.ts
CHANGED
|
@@ -11,16 +11,49 @@ export { AaaError, SessionHandle } from "./session.js";
|
|
|
11
11
|
export type { DisplayEvent, EngineInfo, SessionHandleParams, } from "./session.js";
|
|
12
12
|
export type { ApprovalResponse } from "./approval.js";
|
|
13
13
|
export type { EngineVersionPayload } from "./spawn.js";
|
|
14
|
+
/** @public */
|
|
15
|
+
export { assembleArgv } from "./argv-builder.js";
|
|
16
|
+
/** @public */
|
|
17
|
+
export type { AssembleArgvInput } from "./argv-builder.js";
|
|
18
|
+
/** @public */
|
|
19
|
+
export { resolveMcpConfigPath, cleanupSpillFile } from "./mcp-spill.js";
|
|
20
|
+
/** @public */
|
|
21
|
+
export type { McpSpillResult } from "./mcp-spill.js";
|
|
22
|
+
/** @public */
|
|
23
|
+
export { resolveBinaryPath, buildEnv, probeEngineVersion, DEFAULT_ALLOWLIST, BLOCKED_ENV_KEYS, } from "./spawn.js";
|
|
24
|
+
/** @public */
|
|
25
|
+
export type { ResolveBinaryPathOptions, BuildEnvOptions, } from "./spawn.js";
|
|
26
|
+
/** @public */
|
|
27
|
+
export { Transport, parseNdjsonStream } from "./transport.js";
|
|
28
|
+
/** @public */
|
|
29
|
+
export type { TransportOptions, ExitInfo, ParseNdjsonStreamOptions, } from "./transport.js";
|
|
30
|
+
/** @public */
|
|
31
|
+
export { checkProtocolVersion } from "./version.js";
|
|
32
|
+
/** @public */
|
|
33
|
+
export type { VersionCheckResult, VersionCheckOk, VersionCheckFail, CheckProtocolVersionOptions, } from "./version.js";
|
|
34
|
+
/** @public */
|
|
35
|
+
export { parseRunOutput, STDERR_TAIL_BYTES } from "./run-output-parser.js";
|
|
36
|
+
/** @public */
|
|
37
|
+
export type { SubprocessOutcome } from "./run-output-parser.js";
|
|
38
|
+
/** @public */
|
|
39
|
+
export { makeApprovalHandler } from "./approval.js";
|
|
40
|
+
/** @public */
|
|
41
|
+
export type { ApprovalAdapter, ApprovalRequest, ApprovalHandler, } from "./approval.js";
|
|
14
42
|
import { SessionHandle } from "./session.js";
|
|
15
|
-
import type { DisplayEvent } from "./session.js";
|
|
43
|
+
import type { DisplayEvent, ChildProcessFactory } from "./session.js";
|
|
16
44
|
import type { ApprovalResponse } from "./approval.js";
|
|
17
|
-
import type { McpServerConfig
|
|
18
|
-
export type { McpServerConfig
|
|
45
|
+
import type { McpServerConfig } from "./types.js";
|
|
46
|
+
export type { McpServerConfig } from "./types.js";
|
|
47
|
+
/** @public */
|
|
48
|
+
export type { ChildProcessFactory } from "./session.js";
|
|
19
49
|
/**
|
|
20
50
|
* The protocol version that this TypeScript wrapper requires.
|
|
21
|
-
* Forwarded to the engine via `--protocol-version` on every `submit()
|
|
51
|
+
* Forwarded to the engine via `--protocol-version` on every `submit()` and
|
|
52
|
+
* checked at `spawnAgent()` time against the engine's reported protocol
|
|
53
|
+
* version (see Issue #9 — `checkProtocolVersion()` is wired into the init
|
|
54
|
+
* path so skew fails fast wrapper-side before any subprocess spawn).
|
|
22
55
|
*/
|
|
23
|
-
export declare const PROTOCOL_VERSION_REQUIRED_BY_WRAPPER = "0.
|
|
56
|
+
export declare const PROTOCOL_VERSION_REQUIRED_BY_WRAPPER = "0.3.0";
|
|
24
57
|
/** Parameters for spawnAgent(). Signature is locked verbatim by design §8.2. */
|
|
25
58
|
export interface SpawnAgentParams {
|
|
26
59
|
/** 'burst' reserved; throws AaaError(lifecycle_unsupported) at runtime. */
|
|
@@ -34,32 +67,97 @@ export interface SpawnAgentParams {
|
|
|
34
67
|
};
|
|
35
68
|
providerOverride?: string;
|
|
36
69
|
/**
|
|
37
|
-
*
|
|
70
|
+
* Approval policy (Issue #10).
|
|
38
71
|
*
|
|
39
|
-
*
|
|
40
|
-
*
|
|
41
|
-
*
|
|
72
|
+
* Two shapes are accepted:
|
|
73
|
+
*
|
|
74
|
+
* 1. `{ mode: 'yes' | 'no' | 'prompt' }` — the static-policy shape.
|
|
75
|
+
* Maps to engine argv:
|
|
76
|
+
* - `'yes'` → `-y` (auto-allow every tool call)
|
|
77
|
+
* - `'no'` → `-n` (auto-deny every tool call)
|
|
78
|
+
* - `'prompt'` → emit no flag; the engine falls back to
|
|
79
|
+
* `host_config.approval.mode` or the bundle's
|
|
80
|
+
* TTY-based default. This is how a host hands
|
|
81
|
+
* policy resolution back to the engine.
|
|
82
|
+
*
|
|
83
|
+
* Engine compatibility: requires `amplifier-agent >= 0.4.0`
|
|
84
|
+
* (PR #34 added `host_config.approval.mode`).
|
|
85
|
+
*
|
|
86
|
+
* 2. `{ onRequest, timeoutMs }` — the legacy mid-turn callback shape.
|
|
87
|
+
* **NOT SUPPORTED IN v1.** Passing a non-null `onRequest` still
|
|
88
|
+
* throws `AaaError(approval_not_supported_in_v1)`. The v1 wire has
|
|
89
|
+
* no mid-turn host channel.
|
|
90
|
+
*
|
|
91
|
+
* When unset, the wrapper defaults to `mode: 'yes'` for backward
|
|
92
|
+
* compatibility with pre-0.6 behaviour (the wrapper unconditionally
|
|
93
|
+
* emitted `-y`).
|
|
42
94
|
*/
|
|
43
95
|
approval?: {
|
|
44
|
-
|
|
45
|
-
|
|
96
|
+
mode?: "yes" | "no" | "prompt";
|
|
97
|
+
onRequest?: (req: unknown) => Promise<ApprovalResponse>;
|
|
98
|
+
timeoutMs?: number;
|
|
46
99
|
};
|
|
47
100
|
display?: {
|
|
48
101
|
onEvent?: (event: DisplayEvent) => void;
|
|
49
102
|
subagentEvents?: "all" | "none";
|
|
50
103
|
};
|
|
51
|
-
/**
|
|
52
|
-
|
|
53
|
-
|
|
104
|
+
/**
|
|
105
|
+
* Optional MCP servers. Spilled to a 0600 tmpfile per submit and forwarded
|
|
106
|
+
* to the engine via the `AMPLIFIER_MCP_CONFIG` env var injected into the
|
|
107
|
+
* subprocess environment. The former `--mcp-config-path` argv flag was
|
|
108
|
+
* removed; `tool-mcp` reads the env var natively via its config-discovery
|
|
109
|
+
* priority chain.
|
|
110
|
+
*/
|
|
54
111
|
mcpServers?: Record<string, McpServerConfig>;
|
|
55
|
-
/** Optional host envelope forwarded via `--host-capabilities` (A1). */
|
|
56
|
-
host?: {
|
|
57
|
-
capabilities?: HostCapabilities;
|
|
58
|
-
};
|
|
59
112
|
/** Per-submit timeout in ms (default: 10 minutes). */
|
|
60
113
|
timeoutMs?: number;
|
|
114
|
+
/**
|
|
115
|
+
* Path to a host config file (Issue #1). Forwarded to the engine via
|
|
116
|
+
* `--config <configPath>` so the engine's host_config layer
|
|
117
|
+
* (approval mode, MCP servers, provider defaults,
|
|
118
|
+
* `allowProtocolSkew`, etc.) is composed from the file the host
|
|
119
|
+
* already manages.
|
|
120
|
+
*
|
|
121
|
+
* Mirrors the engine's `single_turn --config` flag (engine PR #27 /
|
|
122
|
+
* v0.4.0). When unset, the engine's resolution order applies (env
|
|
123
|
+
* `AMPLIFIER_AGENT_CONFIG`, then `~/.config/amplifier-agent/host_config.json`).
|
|
124
|
+
*
|
|
125
|
+
* @public
|
|
126
|
+
*/
|
|
127
|
+
configPath?: string;
|
|
128
|
+
/**
|
|
129
|
+
* Bypass the wrapper-side protocol-version check (Issue #9).
|
|
130
|
+
*
|
|
131
|
+
* Default `false`: `spawnAgent()` probes the engine's protocol version once
|
|
132
|
+
* during initialization and rejects with `AaaError(protocol_version_mismatch)`
|
|
133
|
+
* when it differs from `PROTOCOL_VERSION_REQUIRED_BY_WRAPPER`. Setting this to
|
|
134
|
+
* `true` skips the check and lets the engine run regardless — useful for
|
|
135
|
+
* exploratory work against pre-release engine versions, but unsafe by default.
|
|
136
|
+
*
|
|
137
|
+
* Mirrors the engine-side `host_config.allowProtocolSkew` knob.
|
|
138
|
+
*/
|
|
139
|
+
allowProtocolSkew?: boolean;
|
|
61
140
|
/** Replaces the real resolveBinaryPath() call. */
|
|
62
141
|
_binaryResolver?: () => string;
|
|
142
|
+
/**
|
|
143
|
+
* Replaces the real probeEngineVersion() call (Issue #9 + #7). When set,
|
|
144
|
+
* `spawnAgent()` invokes this factory instead of spawning
|
|
145
|
+
* `<binaryPath> version --json`. Reserved for tests and host-side stubs.
|
|
146
|
+
*/
|
|
147
|
+
_engineVersionProbe?: () => Promise<{
|
|
148
|
+
version: string;
|
|
149
|
+
protocolVersion: string;
|
|
150
|
+
bundleDigest?: string;
|
|
151
|
+
}>;
|
|
152
|
+
/**
|
|
153
|
+
* Override the subprocess factory used inside `SessionHandle.submit()`
|
|
154
|
+
* (Issue #3). When set, the wrapper invokes this factory in place of
|
|
155
|
+
* `child_process.spawn`. Useful for sandboxing, harness wrapping, or
|
|
156
|
+
* test doubles.
|
|
157
|
+
*
|
|
158
|
+
* @public
|
|
159
|
+
*/
|
|
160
|
+
runChildProcess?: ChildProcessFactory;
|
|
63
161
|
}
|
|
64
162
|
/**
|
|
65
163
|
* Compose all internal components into the single public entry point.
|
package/dist/index.js
CHANGED
|
@@ -9,14 +9,49 @@
|
|
|
9
9
|
*/
|
|
10
10
|
// Re-export public types and classes from sub-modules.
|
|
11
11
|
export { AaaError, SessionHandle } from "./session.js";
|
|
12
|
+
// ---------------------------------------------------------------------------
|
|
13
|
+
// Public re-exports of wrapper internals (Issue #5).
|
|
14
|
+
//
|
|
15
|
+
// These helpers and their associated types are part of the wrapper's
|
|
16
|
+
// supported public surface. They are useful to host authors who want to:
|
|
17
|
+
// - Inspect the argv the wrapper would emit (`assembleArgv`)
|
|
18
|
+
// - Inject their own subprocess factory (`runChildProcess` + spawn helpers)
|
|
19
|
+
// - Probe the engine binary themselves (`resolveBinaryPath`,
|
|
20
|
+
// `probeEngineVersion`, `buildEnv`)
|
|
21
|
+
// - Drive the NDJSON event pipeline manually (`Transport`,
|
|
22
|
+
// `parseNdjsonStream`)
|
|
23
|
+
// - Reuse the same protocol-version comparison the wrapper uses
|
|
24
|
+
// (`checkProtocolVersion`)
|
|
25
|
+
// - Parse a captured run-output payload (`parseRunOutput`)
|
|
26
|
+
//
|
|
27
|
+
// All exports below are annotated `@public` in their defining module.
|
|
28
|
+
// ---------------------------------------------------------------------------
|
|
29
|
+
/** @public */
|
|
30
|
+
export { assembleArgv } from "./argv-builder.js";
|
|
31
|
+
/** @public */
|
|
32
|
+
export { resolveMcpConfigPath, cleanupSpillFile } from "./mcp-spill.js";
|
|
33
|
+
/** @public */
|
|
34
|
+
export { resolveBinaryPath, buildEnv, probeEngineVersion, DEFAULT_ALLOWLIST, BLOCKED_ENV_KEYS, } from "./spawn.js";
|
|
35
|
+
/** @public */
|
|
36
|
+
export { Transport, parseNdjsonStream } from "./transport.js";
|
|
37
|
+
/** @public */
|
|
38
|
+
export { checkProtocolVersion } from "./version.js";
|
|
39
|
+
/** @public */
|
|
40
|
+
export { parseRunOutput, STDERR_TAIL_BYTES } from "./run-output-parser.js";
|
|
41
|
+
/** @public */
|
|
42
|
+
export { makeApprovalHandler } from "./approval.js";
|
|
12
43
|
// Internal imports used by spawnAgent().
|
|
13
44
|
import { AaaError, SessionHandle } from "./session.js";
|
|
14
|
-
import { resolveBinaryPath, buildEnv, DEFAULT_ALLOWLIST } from "./spawn.js";
|
|
45
|
+
import { resolveBinaryPath, buildEnv, probeEngineVersion, DEFAULT_ALLOWLIST, } from "./spawn.js";
|
|
46
|
+
import { checkProtocolVersion } from "./version.js";
|
|
15
47
|
/**
|
|
16
48
|
* The protocol version that this TypeScript wrapper requires.
|
|
17
|
-
* Forwarded to the engine via `--protocol-version` on every `submit()
|
|
49
|
+
* Forwarded to the engine via `--protocol-version` on every `submit()` and
|
|
50
|
+
* checked at `spawnAgent()` time against the engine's reported protocol
|
|
51
|
+
* version (see Issue #9 — `checkProtocolVersion()` is wired into the init
|
|
52
|
+
* path so skew fails fast wrapper-side before any subprocess spawn).
|
|
18
53
|
*/
|
|
19
|
-
export const PROTOCOL_VERSION_REQUIRED_BY_WRAPPER = "0.
|
|
54
|
+
export const PROTOCOL_VERSION_REQUIRED_BY_WRAPPER = "0.3.0";
|
|
20
55
|
// ---------------------------------------------------------------------------
|
|
21
56
|
// spawnAgent() — locked public entry point (Mode A v2)
|
|
22
57
|
// ---------------------------------------------------------------------------
|
|
@@ -39,13 +74,23 @@ export async function spawnAgent(params) {
|
|
|
39
74
|
// SC-C: reject mid-turn approval callback before any other work. The Mode A
|
|
40
75
|
// wire has no mid-turn request channel; warning-only acceptance would ship
|
|
41
76
|
// silent auto-allow to a host author who believed their callback was wired.
|
|
77
|
+
// Issue #10: `approval.mode` is the supported policy hook in v1; `onRequest`
|
|
78
|
+
// remains unsupported until a mid-turn channel returns (track WG-4).
|
|
42
79
|
if (params.approval?.onRequest !== undefined) {
|
|
43
80
|
throw new AaaError("approval_not_supported_in_v1", "Mid-turn approval callbacks (params.approval.onRequest) are not supported in v1. " +
|
|
44
|
-
"The Mode A wire has no mid-turn request channel.
|
|
45
|
-
"
|
|
46
|
-
"
|
|
47
|
-
"
|
|
48
|
-
|
|
81
|
+
"The Mode A wire has no mid-turn request channel. Use the static-policy shape " +
|
|
82
|
+
"`approval: { mode: 'yes' | 'no' | 'prompt' }` instead — it maps to engine argv " +
|
|
83
|
+
"(`-y` / `-n`) and to `host_config.approval.mode`. Mid-turn callbacks will return " +
|
|
84
|
+
"in v1.x — track WG-4 in amendment §6.", { classification: "protocol", severity: "error" });
|
|
85
|
+
}
|
|
86
|
+
// Issue #10: validate the static-policy shape if present.
|
|
87
|
+
let approvalModeArg;
|
|
88
|
+
if (params.approval?.mode !== undefined) {
|
|
89
|
+
const m = params.approval.mode;
|
|
90
|
+
if (m !== "yes" && m !== "no" && m !== "prompt") {
|
|
91
|
+
throw new AaaError("invalid_approval_mode", `params.approval.mode must be 'yes', 'no', or 'prompt' (got ${JSON.stringify(m)})`, { classification: "protocol", severity: "error" });
|
|
92
|
+
}
|
|
93
|
+
approvalModeArg = m;
|
|
49
94
|
}
|
|
50
95
|
// 1. Lifecycle guard (D10).
|
|
51
96
|
if (params.lifecycle !== "one-shot") {
|
|
@@ -76,11 +121,51 @@ export async function spawnAgent(params) {
|
|
|
76
121
|
allowlist,
|
|
77
122
|
extra,
|
|
78
123
|
});
|
|
79
|
-
// 4.
|
|
80
|
-
//
|
|
81
|
-
//
|
|
82
|
-
//
|
|
83
|
-
//
|
|
124
|
+
// 4. Issue #9: probe the engine binary for its protocol version and run
|
|
125
|
+
// `checkProtocolVersion()` BEFORE constructing a SessionHandle. This is
|
|
126
|
+
// a single `amplifier-agent version --json` roundtrip during init — far
|
|
127
|
+
// cheaper than discovering a mismatch on the first `submit()` after the
|
|
128
|
+
// engine has done its full bundle-load dance. The probe result is also
|
|
129
|
+
// cached on the handle for `getEngineInfo()` (Issue #7).
|
|
130
|
+
//
|
|
131
|
+
// Callers can:
|
|
132
|
+
// - Inject a synthetic probe via `_engineVersionProbe` (tests).
|
|
133
|
+
// - Bypass the check entirely with `allowProtocolSkew: true`.
|
|
134
|
+
let engineVersionPayload;
|
|
135
|
+
try {
|
|
136
|
+
if (params._engineVersionProbe) {
|
|
137
|
+
engineVersionPayload = await params._engineVersionProbe();
|
|
138
|
+
}
|
|
139
|
+
else {
|
|
140
|
+
engineVersionPayload = await probeEngineVersion(binaryPath, subprocessEnv);
|
|
141
|
+
}
|
|
142
|
+
}
|
|
143
|
+
catch (e) {
|
|
144
|
+
// Probe failure is non-fatal when skew is allowed: fall back to empty
|
|
145
|
+
// metadata. Otherwise surface it as a typed error.
|
|
146
|
+
if (params.allowProtocolSkew === true) {
|
|
147
|
+
engineVersionPayload = { version: "", protocolVersion: "" };
|
|
148
|
+
}
|
|
149
|
+
else {
|
|
150
|
+
const msg = e.message ?? "engine version probe failed";
|
|
151
|
+
throw new AaaError("engine_probe_failed", `Could not probe engine binary at ${binaryPath} for protocol version: ${msg}`, { classification: "transport", severity: "error" });
|
|
152
|
+
}
|
|
153
|
+
}
|
|
154
|
+
const check = checkProtocolVersion({
|
|
155
|
+
wrapper: PROTOCOL_VERSION_REQUIRED_BY_WRAPPER,
|
|
156
|
+
engine: engineVersionPayload.protocolVersion,
|
|
157
|
+
allowSkew: params.allowProtocolSkew === true,
|
|
158
|
+
});
|
|
159
|
+
if (!check.ok) {
|
|
160
|
+
throw new AaaError(check.code, check.remediation, {
|
|
161
|
+
classification: "protocol",
|
|
162
|
+
severity: "error",
|
|
163
|
+
});
|
|
164
|
+
}
|
|
165
|
+
// 5. Return a SessionHandle. NO subprocess spawned here — the engine is
|
|
166
|
+
// launched per submit() (amendment §5.2). Skew override now lives in
|
|
167
|
+
// `host_config.allowProtocolSkew: true` in the host config file (engine
|
|
168
|
+
// PR #27); the wrapper no longer forwards an argv flag for it.
|
|
84
169
|
return new SessionHandle({
|
|
85
170
|
binaryPath,
|
|
86
171
|
sessionId: params.sessionId,
|
|
@@ -88,18 +173,25 @@ export async function spawnAgent(params) {
|
|
|
88
173
|
...(params.resume !== undefined ? { resume: params.resume } : {}),
|
|
89
174
|
...(params.cwd !== undefined ? { cwd: params.cwd } : {}),
|
|
90
175
|
...(params.mcpServers !== undefined ? { mcpServers: params.mcpServers } : {}),
|
|
91
|
-
...(params.host?.capabilities !== undefined
|
|
92
|
-
? { hostCapabilities: params.host.capabilities }
|
|
93
|
-
: {}),
|
|
94
|
-
envAllowlist: allowlist,
|
|
95
|
-
envExtra: extra,
|
|
96
176
|
...(params.providerOverride !== undefined
|
|
97
177
|
? { providerOverride: params.providerOverride }
|
|
98
178
|
: {}),
|
|
99
|
-
...(params.allowProtocolSkew !== undefined
|
|
100
|
-
? { allowProtocolSkew: params.allowProtocolSkew }
|
|
101
|
-
: {}),
|
|
102
179
|
protocolVersion: PROTOCOL_VERSION_REQUIRED_BY_WRAPPER,
|
|
103
180
|
...(params.timeoutMs !== undefined ? { timeoutMs: params.timeoutMs } : {}),
|
|
181
|
+
...(params.runChildProcess !== undefined
|
|
182
|
+
? { runChildProcess: params.runChildProcess }
|
|
183
|
+
: {}),
|
|
184
|
+
// Issue #1: forward host config path so assembleArgv can emit
|
|
185
|
+
// --config <path>.
|
|
186
|
+
...(params.configPath !== undefined ? { configPath: params.configPath } : {}),
|
|
187
|
+
// Issue #10: forward the validated approval mode so assembleArgv can
|
|
188
|
+
// emit -y / -n / nothing.
|
|
189
|
+
...(approvalModeArg !== undefined ? { approvalMode: approvalModeArg } : {}),
|
|
190
|
+
// Issue #4: thread display.onEvent through so SessionHandle can
|
|
191
|
+
// dispatch parsed NDJSON wire events to it.
|
|
192
|
+
...(params.display !== undefined ? { display: params.display } : {}),
|
|
193
|
+
// Issue #7: persist engine metadata resolved during the probe.
|
|
194
|
+
engineVersion: engineVersionPayload.version,
|
|
195
|
+
bundleDigest: engineVersionPayload.bundleDigest ?? "",
|
|
104
196
|
});
|
|
105
197
|
}
|
package/dist/mcp-spill.d.ts
CHANGED
|
@@ -1,10 +1,12 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Result of
|
|
2
|
+
* Result of spilling the MCP servers map to a tmpfile.
|
|
3
3
|
*
|
|
4
4
|
* - When `mcpServers` is null/undefined/empty: `configPath` is `null`.
|
|
5
5
|
* - When servers are present: `configPath` points at the 0600 spill file.
|
|
6
6
|
* The file contains `{"mcpServers": <map>}` in the format that
|
|
7
7
|
* amplifier-module-tool-mcp expects when reading `AMPLIFIER_MCP_CONFIG`.
|
|
8
|
+
* The caller injects the path into the engine's subprocess environment
|
|
9
|
+
* as `AMPLIFIER_MCP_CONFIG`.
|
|
8
10
|
*/
|
|
9
11
|
export interface McpSpillResult {
|
|
10
12
|
configPath: string | null;
|
package/dist/mcp-spill.js
CHANGED
|
@@ -4,9 +4,11 @@
|
|
|
4
4
|
* The wrapper always spills the MCP server map to a 0600 tmpfile under
|
|
5
5
|
* `${XDG_RUNTIME_DIR || os.tmpdir()}/amplifier-agent/<sessionId>/mcp.json`.
|
|
6
6
|
* The file is written in the format documented by amplifier-module-tool-mcp:
|
|
7
|
-
* a top-level `{"mcpServers": <map>}` object. The
|
|
8
|
-
*
|
|
9
|
-
* module reads it via its standard config
|
|
7
|
+
* a top-level `{"mcpServers": <map>}` object. The caller (`SessionHandle`)
|
|
8
|
+
* injects the spilled path into the engine's subprocess environment as
|
|
9
|
+
* `AMPLIFIER_MCP_CONFIG`; the module reads it via its standard config
|
|
10
|
+
* discovery (config.py priority chain). The former `--mcp-config-path` argv
|
|
11
|
+
* flag was dropped — the env var is the single forwarding mechanism.
|
|
10
12
|
*
|
|
11
13
|
* `cleanupSpillFile` is the matching teardown — idempotent unlink that
|
|
12
14
|
* swallows ENOENT so callers can call it unconditionally on every exit path.
|
package/dist/session.d.ts
CHANGED
|
@@ -22,8 +22,22 @@
|
|
|
22
22
|
* file created on this turn (CR-A cleanup).
|
|
23
23
|
* - `dispose()` is a synonym for `cancel()`.
|
|
24
24
|
*/
|
|
25
|
-
import type { ChildProcess } from "node:child_process";
|
|
26
|
-
import type { McpServerConfig
|
|
25
|
+
import type { ChildProcess, SpawnOptions } from "node:child_process";
|
|
26
|
+
import type { McpServerConfig } from "./types.js";
|
|
27
|
+
/**
|
|
28
|
+
* Factory function compatible with the surface of `child_process.spawn`
|
|
29
|
+
* that `SessionHandle` calls. Hosts can supply this via
|
|
30
|
+
* `SpawnAgentParams.runChildProcess` (Issue #3) to substitute their own
|
|
31
|
+
* subprocess factory — useful for sandboxing, harness wrapping, or test
|
|
32
|
+
* doubles.
|
|
33
|
+
*
|
|
34
|
+
* The factory is invoked exactly once per `submit()` with the resolved
|
|
35
|
+
* binary path, the assembled argv array, and the spawn options the wrapper
|
|
36
|
+
* would have used (including `detached`, `stdio`, `env`, and optional `cwd`).
|
|
37
|
+
*
|
|
38
|
+
* @public
|
|
39
|
+
*/
|
|
40
|
+
export type ChildProcessFactory = (command: string, args: readonly string[], options: SpawnOptions) => ChildProcess;
|
|
27
41
|
/**
|
|
28
42
|
* A display event yielded by `SessionHandle.submit()`.
|
|
29
43
|
*
|
|
@@ -49,6 +63,23 @@ export type DisplayEvent = {
|
|
|
49
63
|
message: string;
|
|
50
64
|
stderrTail?: string;
|
|
51
65
|
retryable: boolean;
|
|
66
|
+
}
|
|
67
|
+
/**
|
|
68
|
+
* Wire-protocol notification dispatched from the engine's stderr NDJSON
|
|
69
|
+
* stream (Issue #2 / #6). One of the 9 wire event types the engine
|
|
70
|
+
* emits: progress, result/delta, result/final, thinking/delta,
|
|
71
|
+
* thinking/final, tool/started, tool/completed, approval/request,
|
|
72
|
+
* approval/timeout, plus the wire-level error notification.
|
|
73
|
+
*
|
|
74
|
+
* `method` is the JSON-RPC method name verbatim from the wire envelope
|
|
75
|
+
* (e.g. `"progress"`, `"tool/started"`). `params` is the raw payload
|
|
76
|
+
* dictionary the engine emitted, unaltered. Callers may narrow on
|
|
77
|
+
* `method` and cast `params` to a typed shape from `./types.ts`.
|
|
78
|
+
*/
|
|
79
|
+
| {
|
|
80
|
+
type: "notification";
|
|
81
|
+
method: string;
|
|
82
|
+
params: unknown;
|
|
52
83
|
};
|
|
53
84
|
/** Typed error for AaA wrapper lifecycle and protocol violations. */
|
|
54
85
|
export declare class AaaError extends Error {
|
|
@@ -89,22 +120,52 @@ export interface SessionHandleParams {
|
|
|
89
120
|
resume?: boolean;
|
|
90
121
|
/** Working directory for the subprocess. */
|
|
91
122
|
cwd?: string;
|
|
92
|
-
/**
|
|
123
|
+
/**
|
|
124
|
+
* MCP servers to forward to the engine. CR-A spill applies: the map is
|
|
125
|
+
* written to a 0600 tmpfile and the path is injected into the engine's
|
|
126
|
+
* subprocess environment as `AMPLIFIER_MCP_CONFIG`. The former
|
|
127
|
+
* `--mcp-config-path` argv flag was removed.
|
|
128
|
+
*/
|
|
93
129
|
mcpServers?: Record<string, McpServerConfig>;
|
|
94
|
-
/** Host capabilities forwarded via `--host-capabilities`. */
|
|
95
|
-
hostCapabilities?: HostCapabilities;
|
|
96
|
-
/** Allowlisted env variable names forwarded via `--env-allowlist`. */
|
|
97
|
-
envAllowlist?: string[];
|
|
98
|
-
/** Extra env entries forwarded via `--env-extra`. */
|
|
99
|
-
envExtra?: Record<string, string>;
|
|
100
130
|
/** Provider override forwarded via `--provider`. */
|
|
101
131
|
providerOverride?: string;
|
|
102
|
-
/**
|
|
103
|
-
|
|
104
|
-
|
|
132
|
+
/**
|
|
133
|
+
* Path to the engine's host config file (Issue #1). Forwarded to the
|
|
134
|
+
* engine via `--config <configPath>`. See the engine's
|
|
135
|
+
* `single_turn` mode for the resolved-precedence rules between argv
|
|
136
|
+
* flags, host_config, and the bundle's TTY-based default.
|
|
137
|
+
*/
|
|
138
|
+
configPath?: string;
|
|
139
|
+
/**
|
|
140
|
+
* Approval mode override (Issue #10). Maps to engine argv:
|
|
141
|
+
* `"yes" -> -y`, `"no" -> -n`, `"prompt" -> emit nothing` so the engine
|
|
142
|
+
* falls back to `host_config.approval.mode` or its bundle/TTY default.
|
|
143
|
+
* Undefined preserves the historical default (`-y`) for callers that
|
|
144
|
+
* have not opted into the approval API.
|
|
145
|
+
*/
|
|
146
|
+
approvalMode?: "yes" | "no" | "prompt";
|
|
147
|
+
/** Protocol version the wrapper speaks (e.g. "0.3.0"). */
|
|
105
148
|
protocolVersion: string;
|
|
106
149
|
/** Per-submit timeout in milliseconds. Defaults to 10 minutes. */
|
|
107
150
|
timeoutMs?: number;
|
|
151
|
+
/**
|
|
152
|
+
* Optional override for the subprocess factory (Issue #3). When set, the
|
|
153
|
+
* handle invokes this function instead of `child_process.spawn`.
|
|
154
|
+
*/
|
|
155
|
+
runChildProcess?: ChildProcessFactory;
|
|
156
|
+
/**
|
|
157
|
+
* Display sink (Issue #4). When set, every parsed NDJSON wire-event from
|
|
158
|
+
* the engine subprocess's stderr stream is dispatched here, in addition
|
|
159
|
+
* to whatever the iterator yields. Pass-through from
|
|
160
|
+
* `SpawnAgentParams.display`.
|
|
161
|
+
*/
|
|
162
|
+
display?: {
|
|
163
|
+
onEvent?: (event: DisplayEvent) => void;
|
|
164
|
+
};
|
|
165
|
+
/** Engine metadata resolved at spawnAgent() time (Issue #7). */
|
|
166
|
+
engineVersion?: string;
|
|
167
|
+
/** Bundle digest resolved at spawnAgent() time (Issue #7). */
|
|
168
|
+
bundleDigest?: string;
|
|
108
169
|
}
|
|
109
170
|
/**
|
|
110
171
|
* Wait for `child` to fire `exit`, or `ms` to elapse — whichever first.
|
|
@@ -133,8 +194,10 @@ export declare class SessionHandle {
|
|
|
133
194
|
/**
|
|
134
195
|
* Async generator implementing the §5.2 iterable behavior:
|
|
135
196
|
* (i) yield `{type:'init', sessionId}` synchronously (SC-1);
|
|
136
|
-
* (ii) CR-A:
|
|
137
|
-
* (iii) build argv via `assembleArgv
|
|
197
|
+
* (ii) CR-A: spill MCP servers to a 0600 tmpfile (when provided);
|
|
198
|
+
* (iii) build argv via `assembleArgv` and the subprocess env (injecting
|
|
199
|
+
* `AMPLIFIER_MCP_CONFIG` for the spilled path when present — the
|
|
200
|
+
* former `--mcp-config-path` argv flag was removed);
|
|
138
201
|
* (iv) SC-B: spawn with `detached:true` so PID == PGID for group signals;
|
|
139
202
|
* (v) accumulate stdout/stderr from chunks;
|
|
140
203
|
* (vi) start a 2s activity ticker → queue;
|
package/dist/session.js
CHANGED
|
@@ -26,6 +26,7 @@ import { spawn as childSpawn } from "node:child_process";
|
|
|
26
26
|
import { assembleArgv } from "./argv-builder.js";
|
|
27
27
|
import { resolveMcpConfigPath, cleanupSpillFile } from "./mcp-spill.js";
|
|
28
28
|
import { parseRunOutput, STDERR_TAIL_BYTES } from "./run-output-parser.js";
|
|
29
|
+
import { parseNdjsonStream } from "./transport.js";
|
|
29
30
|
/** Typed error for AaA wrapper lifecycle and protocol violations. */
|
|
30
31
|
export class AaaError extends Error {
|
|
31
32
|
code;
|
|
@@ -95,11 +96,13 @@ export class SessionHandle {
|
|
|
95
96
|
this.engineInfo = {
|
|
96
97
|
binaryPath: params.binaryPath,
|
|
97
98
|
protocolVersion: params.protocolVersion,
|
|
98
|
-
// engineVersion
|
|
99
|
-
//
|
|
100
|
-
//
|
|
101
|
-
|
|
102
|
-
|
|
99
|
+
// Issue #7: engineVersion + bundleDigest are populated from the engine
|
|
100
|
+
// version probe that spawnAgent() runs during initialization (Issue #9).
|
|
101
|
+
// Falls back to empty strings when the engine omits a field (e.g. the
|
|
102
|
+
// `version --json` payload does not include bundleDigest until a future
|
|
103
|
+
// engine release ships an admin endpoint exposing it).
|
|
104
|
+
engineVersion: params.engineVersion ?? "",
|
|
105
|
+
bundleDigest: params.bundleDigest ?? "",
|
|
103
106
|
};
|
|
104
107
|
}
|
|
105
108
|
/** Return resolved engine metadata (D5). */
|
|
@@ -121,8 +124,10 @@ export class SessionHandle {
|
|
|
121
124
|
/**
|
|
122
125
|
* Async generator implementing the §5.2 iterable behavior:
|
|
123
126
|
* (i) yield `{type:'init', sessionId}` synchronously (SC-1);
|
|
124
|
-
* (ii) CR-A:
|
|
125
|
-
* (iii) build argv via `assembleArgv
|
|
127
|
+
* (ii) CR-A: spill MCP servers to a 0600 tmpfile (when provided);
|
|
128
|
+
* (iii) build argv via `assembleArgv` and the subprocess env (injecting
|
|
129
|
+
* `AMPLIFIER_MCP_CONFIG` for the spilled path when present — the
|
|
130
|
+
* former `--mcp-config-path` argv flag was removed);
|
|
126
131
|
* (iv) SC-B: spawn with `detached:true` so PID == PGID for group signals;
|
|
127
132
|
* (v) accumulate stdout/stderr from chunks;
|
|
128
133
|
* (vi) start a 2s activity ticker → queue;
|
|
@@ -135,14 +140,19 @@ export class SessionHandle {
|
|
|
135
140
|
async *makeIterable(prompt) {
|
|
136
141
|
// (i) SC-1: yield init synchronously, BEFORE any async work.
|
|
137
142
|
yield { type: "init", sessionId: this.params.sessionId };
|
|
138
|
-
// (ii) CR-A:
|
|
143
|
+
// (ii) CR-A: spill MCP servers to a 0600 tmpfile (configPath is null when
|
|
144
|
+
// mcpServers is null/empty).
|
|
139
145
|
// Cast through `unknown`: McpServerConfig is the schema-validated wire type
|
|
140
146
|
// (no index signature), while resolveMcpConfigPath's McpServerLike has an
|
|
141
147
|
// open index signature. The two are runtime-compatible but TS rightly
|
|
142
148
|
// rejects assignability without the cast.
|
|
143
149
|
const spill = await resolveMcpConfigPath((this.params.mcpServers ?? null), this.params.sessionId);
|
|
144
150
|
this.mcpSpillPath = spill.configPath;
|
|
145
|
-
// (iii) build argv (pure function — no I/O).
|
|
151
|
+
// (iii) build argv (pure function — no I/O). The MCP config path is
|
|
152
|
+
// forwarded to the engine via AMPLIFIER_MCP_CONFIG (subprocess env)
|
|
153
|
+
// rather than via an argv flag. `configPath` (Issue #1) and
|
|
154
|
+
// `approvalMode` (Issue #10) are forwarded via argv flags emitted
|
|
155
|
+
// by assembleArgv.
|
|
146
156
|
const argv = assembleArgv({
|
|
147
157
|
sessionId: this.params.sessionId,
|
|
148
158
|
prompt,
|
|
@@ -150,17 +160,29 @@ export class SessionHandle {
|
|
|
150
160
|
resume: this.params.resume,
|
|
151
161
|
cwd: this.params.cwd,
|
|
152
162
|
providerOverride: this.params.providerOverride,
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
envAllowlist: this.params.envAllowlist,
|
|
156
|
-
envExtra: this.params.envExtra,
|
|
157
|
-
allowProtocolSkew: this.params.allowProtocolSkew,
|
|
163
|
+
configPath: this.params.configPath,
|
|
164
|
+
approvalMode: this.params.approvalMode,
|
|
158
165
|
});
|
|
166
|
+
// Build the subprocess env. When we spilled an MCP config, set
|
|
167
|
+
// AMPLIFIER_MCP_CONFIG so tool-mcp reads it natively via its
|
|
168
|
+
// config-discovery priority chain. We copy the params env into a fresh
|
|
169
|
+
// object so the stored SessionHandle env is never mutated.
|
|
170
|
+
const subprocessEnv = {
|
|
171
|
+
...this.params.subprocessEnv,
|
|
172
|
+
};
|
|
173
|
+
if (spill.configPath !== null) {
|
|
174
|
+
subprocessEnv.AMPLIFIER_MCP_CONFIG = spill.configPath;
|
|
175
|
+
}
|
|
159
176
|
// (iv) SC-B: spawn detached → new session group → PID == PGID.
|
|
160
|
-
|
|
177
|
+
// Issue #3: when the caller provided a `runChildProcess` factory, use it
|
|
178
|
+
// in place of `child_process.spawn`. The factory must satisfy the
|
|
179
|
+
// ChildProcessFactory contract (same signature surface SessionHandle
|
|
180
|
+
// requires).
|
|
181
|
+
const spawnFn = this.params.runChildProcess ?? childSpawn;
|
|
182
|
+
const child = spawnFn(this.params.binaryPath, argv, {
|
|
161
183
|
detached: true,
|
|
162
184
|
stdio: ["ignore", "pipe", "pipe"],
|
|
163
|
-
env:
|
|
185
|
+
env: subprocessEnv,
|
|
164
186
|
...(this.params.cwd !== undefined ? { cwd: this.params.cwd } : {}),
|
|
165
187
|
});
|
|
166
188
|
this.subprocess = child;
|
|
@@ -170,9 +192,32 @@ export class SessionHandle {
|
|
|
170
192
|
child.stdout?.on("data", (chunk) => {
|
|
171
193
|
stdoutBuf += typeof chunk === "string" ? chunk : chunk.toString("utf-8");
|
|
172
194
|
});
|
|
173
|
-
child.
|
|
174
|
-
|
|
175
|
-
|
|
195
|
+
// Issue #2 / #6: wire `parseNdjsonStream` onto the child's stderr. The
|
|
196
|
+
// engine emits one JSON object per line for each wire-protocol
|
|
197
|
+
// notification (progress, result/delta, tool/started, etc.).
|
|
198
|
+
// - JSON lines are parsed into `notification` DisplayEvents and
|
|
199
|
+
// dispatched to `params.display?.onEvent` (Issue #4).
|
|
200
|
+
// - Non-JSON lines are accumulated into `stderrBuf` so the
|
|
201
|
+
// stderrTail surface on parseRunOutput stays useful for
|
|
202
|
+
// diagnostic snapshots.
|
|
203
|
+
// - JSON lines are also appended to `stderrBuf` verbatim, so a
|
|
204
|
+
// crash-time tail still contains the wire-event context.
|
|
205
|
+
const displayOnEvent = this.params.display?.onEvent;
|
|
206
|
+
if (child.stderr) {
|
|
207
|
+
void parseNdjsonStream(child.stderr, {
|
|
208
|
+
onJson: (obj) => {
|
|
209
|
+
stderrBuf += JSON.stringify(obj) + "\n";
|
|
210
|
+
if (displayOnEvent) {
|
|
211
|
+
const method = typeof obj.method === "string" ? obj.method : "unknown";
|
|
212
|
+
const params = "params" in obj ? obj.params : obj;
|
|
213
|
+
displayOnEvent({ type: "notification", method, params });
|
|
214
|
+
}
|
|
215
|
+
},
|
|
216
|
+
onNonJson: (line) => {
|
|
217
|
+
stderrBuf += line + "\n";
|
|
218
|
+
},
|
|
219
|
+
});
|
|
220
|
+
}
|
|
176
221
|
const queue = [];
|
|
177
222
|
let wake = null;
|
|
178
223
|
const push = (item) => {
|
package/dist/transport.d.ts
CHANGED
|
@@ -11,6 +11,7 @@
|
|
|
11
11
|
*
|
|
12
12
|
* No JSON-RPC semantics here — that is Task 6.
|
|
13
13
|
*/
|
|
14
|
+
import type { Readable } from "node:stream";
|
|
14
15
|
export interface TransportOptions {
|
|
15
16
|
/** Command to spawn (e.g. "cat", "sh"). */
|
|
16
17
|
command: string;
|
|
@@ -35,6 +36,44 @@ export interface ExitInfo {
|
|
|
35
36
|
/** Signal name if the process was killed by a signal, otherwise null. */
|
|
36
37
|
signal: string | null;
|
|
37
38
|
}
|
|
39
|
+
/**
|
|
40
|
+
* Options for {@link parseNdjsonStream}.
|
|
41
|
+
*
|
|
42
|
+
* @public
|
|
43
|
+
*/
|
|
44
|
+
export interface ParseNdjsonStreamOptions {
|
|
45
|
+
/**
|
|
46
|
+
* Invoked once per line that parses cleanly as JSON. Failures in the
|
|
47
|
+
* callback are NOT caught — the caller is responsible for not throwing
|
|
48
|
+
* inside the dispatcher.
|
|
49
|
+
*/
|
|
50
|
+
onJson: (obj: Record<string, unknown>) => void;
|
|
51
|
+
/**
|
|
52
|
+
* Invoked once per line that does NOT parse as JSON (e.g. plain stderr
|
|
53
|
+
* text, partial frames). The line is delivered verbatim without the
|
|
54
|
+
* trailing newline. Default: silently drop the line.
|
|
55
|
+
*/
|
|
56
|
+
onNonJson?: (line: string) => void;
|
|
57
|
+
}
|
|
58
|
+
/**
|
|
59
|
+
* Consume an NDJSON stream line-by-line, dispatching each parseable JSON
|
|
60
|
+
* line to `onJson` and each non-JSON line to `onNonJson` (or silently
|
|
61
|
+
* dropping it).
|
|
62
|
+
*
|
|
63
|
+
* Implements the same parsing model that {@link Transport} uses internally,
|
|
64
|
+
* but exposed as a standalone helper so SessionHandle can wire it onto
|
|
65
|
+
* the engine subprocess's stderr stream without owning the spawn.
|
|
66
|
+
*
|
|
67
|
+
* **Wire contract:** the engine emits one JSON object per line on stderr
|
|
68
|
+
* for each wire-protocol notification (Issue #2 / #6). Each parsed object
|
|
69
|
+
* is delivered verbatim to `onJson`; the caller decides how to interpret
|
|
70
|
+
* the `method`/`params` shape.
|
|
71
|
+
*
|
|
72
|
+
* Returns a Promise that resolves when the underlying stream emits `end`.
|
|
73
|
+
*
|
|
74
|
+
* @public
|
|
75
|
+
*/
|
|
76
|
+
export declare function parseNdjsonStream(stream: Readable, options: ParseNdjsonStreamOptions): Promise<void>;
|
|
38
77
|
export declare class Transport {
|
|
39
78
|
private readonly opts;
|
|
40
79
|
private proc;
|
package/dist/transport.js
CHANGED
|
@@ -13,6 +13,50 @@
|
|
|
13
13
|
*/
|
|
14
14
|
import { spawn } from "node:child_process";
|
|
15
15
|
import { createInterface } from "node:readline";
|
|
16
|
+
/**
|
|
17
|
+
* Consume an NDJSON stream line-by-line, dispatching each parseable JSON
|
|
18
|
+
* line to `onJson` and each non-JSON line to `onNonJson` (or silently
|
|
19
|
+
* dropping it).
|
|
20
|
+
*
|
|
21
|
+
* Implements the same parsing model that {@link Transport} uses internally,
|
|
22
|
+
* but exposed as a standalone helper so SessionHandle can wire it onto
|
|
23
|
+
* the engine subprocess's stderr stream without owning the spawn.
|
|
24
|
+
*
|
|
25
|
+
* **Wire contract:** the engine emits one JSON object per line on stderr
|
|
26
|
+
* for each wire-protocol notification (Issue #2 / #6). Each parsed object
|
|
27
|
+
* is delivered verbatim to `onJson`; the caller decides how to interpret
|
|
28
|
+
* the `method`/`params` shape.
|
|
29
|
+
*
|
|
30
|
+
* Returns a Promise that resolves when the underlying stream emits `end`.
|
|
31
|
+
*
|
|
32
|
+
* @public
|
|
33
|
+
*/
|
|
34
|
+
export function parseNdjsonStream(stream, options) {
|
|
35
|
+
return new Promise((resolve, reject) => {
|
|
36
|
+
const rl = createInterface({ input: stream });
|
|
37
|
+
rl.on("line", (line) => {
|
|
38
|
+
const trimmed = line.trim();
|
|
39
|
+
if (trimmed.length === 0)
|
|
40
|
+
return;
|
|
41
|
+
try {
|
|
42
|
+
const obj = JSON.parse(trimmed);
|
|
43
|
+
if (typeof obj === "object" && obj !== null) {
|
|
44
|
+
options.onJson(obj);
|
|
45
|
+
}
|
|
46
|
+
else if (options.onNonJson) {
|
|
47
|
+
// JSON-parseable but not an object (e.g. a bare number/string).
|
|
48
|
+
options.onNonJson(line);
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
catch {
|
|
52
|
+
if (options.onNonJson)
|
|
53
|
+
options.onNonJson(line);
|
|
54
|
+
}
|
|
55
|
+
});
|
|
56
|
+
rl.on("close", () => resolve());
|
|
57
|
+
stream.on("error", (err) => reject(err));
|
|
58
|
+
});
|
|
59
|
+
}
|
|
16
60
|
export class Transport {
|
|
17
61
|
opts;
|
|
18
62
|
proc = null;
|
package/dist/types.d.ts
CHANGED
|
@@ -85,22 +85,6 @@ export interface ErrorNotification {
|
|
|
85
85
|
message: string;
|
|
86
86
|
recoverable: boolean;
|
|
87
87
|
}
|
|
88
|
-
/**
|
|
89
|
-
* Capabilities advertised by the host to the agent (design §4.10.1).
|
|
90
|
-
*/
|
|
91
|
-
export interface HostCapabilities {
|
|
92
|
-
supports_steering?: boolean;
|
|
93
|
-
supports_structured_errors?: boolean;
|
|
94
|
-
}
|
|
95
|
-
/**
|
|
96
|
-
* ``initialize.params.host`` envelope for host-side capability advertisement.
|
|
97
|
-
*/
|
|
98
|
-
export interface InitializeHostParams {
|
|
99
|
-
capabilities?: HostCapabilities;
|
|
100
|
-
}
|
|
101
|
-
/**
|
|
102
|
-
* Capabilities advertised by the host to the agent (design §4.10.1).
|
|
103
|
-
*/
|
|
104
88
|
/**
|
|
105
89
|
* Parameters for the ``initialize`` JSON-RPC method.
|
|
106
90
|
*/
|
|
@@ -114,35 +98,11 @@ export interface InitializeParams {
|
|
|
114
98
|
resume?: boolean;
|
|
115
99
|
providerOverride?: string;
|
|
116
100
|
cwd?: string;
|
|
117
|
-
|
|
118
|
-
[k: string]: McpServerConfig;
|
|
119
|
-
};
|
|
120
|
-
host?: InitializeHostParams;
|
|
101
|
+
mcpConfigPath?: string;
|
|
121
102
|
}
|
|
122
103
|
/**
|
|
123
104
|
* Identity of the connecting client.
|
|
124
105
|
*/
|
|
125
|
-
/**
|
|
126
|
-
* Per-server MCP configuration passed via ``initialize.params.mcpServers``.
|
|
127
|
-
*/
|
|
128
|
-
export interface McpServerConfig {
|
|
129
|
-
transport: string;
|
|
130
|
-
command?: string;
|
|
131
|
-
args?: string[];
|
|
132
|
-
env?: {
|
|
133
|
-
[k: string]: string;
|
|
134
|
-
};
|
|
135
|
-
url?: string;
|
|
136
|
-
headers?: {
|
|
137
|
-
[k: string]: string;
|
|
138
|
-
};
|
|
139
|
-
}
|
|
140
|
-
/**
|
|
141
|
-
* ``initialize.params.host`` envelope for host-side capability advertisement.
|
|
142
|
-
*/
|
|
143
|
-
/**
|
|
144
|
-
* Capabilities advertised by the host to the agent (design §4.10.1).
|
|
145
|
-
*/
|
|
146
106
|
/**
|
|
147
107
|
* Result returned by the ``initialize`` JSON-RPC method.
|
|
148
108
|
*/
|
|
@@ -170,6 +130,18 @@ export interface SessionState {
|
|
|
170
130
|
/**
|
|
171
131
|
* Per-server MCP configuration passed via ``initialize.params.mcpServers``.
|
|
172
132
|
*/
|
|
133
|
+
export interface McpServerConfig {
|
|
134
|
+
transport: string;
|
|
135
|
+
command?: string;
|
|
136
|
+
args?: string[];
|
|
137
|
+
env?: {
|
|
138
|
+
[k: string]: string;
|
|
139
|
+
};
|
|
140
|
+
url?: string;
|
|
141
|
+
headers?: {
|
|
142
|
+
[k: string]: string;
|
|
143
|
+
};
|
|
144
|
+
}
|
|
173
145
|
/**
|
|
174
146
|
* Arbitrary progress update. ``percent`` is optional (0-100).
|
|
175
147
|
*/
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "amplifier-agent-ts",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.6.1",
|
|
4
4
|
"description": "TypeScript SDK for the Amplifier agent. Spawns and drives the amplifier-agent Python CLI over a stdio protocol.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"exports": {
|
|
@@ -51,6 +51,6 @@
|
|
|
51
51
|
"json-schema-to-typescript": "^15.0.0",
|
|
52
52
|
"tsx": "^4.7.0",
|
|
53
53
|
"typescript": "^5.4.0",
|
|
54
|
-
"vitest": "^1.
|
|
54
|
+
"vitest": "^4.1.0"
|
|
55
55
|
}
|
|
56
56
|
}
|