amplifier-agent-ts 0.3.1 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -23,11 +23,11 @@ export interface AssembleArgvInput {
23
23
  /** Provider override; emits `--provider <providerOverride>`. */
24
24
  providerOverride?: string;
25
25
  /**
26
- * Pre-resolved value for `--mcp-servers`. Caller decides whether this is
27
- * inline JSON or an `@/path/to/file.json` spill reference; argv-builder
28
- * threads it through unchanged.
26
+ * Path to the MCP config JSON file, pre-spilled by `resolveMcpConfigPath`.
27
+ * Passed to the engine as `--mcp-config-path <path>`; the engine sets
28
+ * `AMPLIFIER_MCP_CONFIG` so the tool-mcp module loads it during mount.
29
29
  */
30
- mcpServersFlag?: string;
30
+ mcpConfigPath?: string;
31
31
  /** Host capabilities object — emitted as `--host-capabilities <JSON>`. */
32
32
  hostCapabilities?: unknown;
33
33
  /** Allowlisted env variable names — emits `--env-allowlist <comma-joined>`. */
@@ -26,8 +26,8 @@ export function assembleArgv(input) {
26
26
  if (input.providerOverride !== undefined) {
27
27
  argv.push("--provider", input.providerOverride);
28
28
  }
29
- if (input.mcpServersFlag !== undefined) {
30
- argv.push("--mcp-servers", input.mcpServersFlag);
29
+ if (input.mcpConfigPath !== undefined) {
30
+ argv.push("--mcp-config-path", input.mcpConfigPath);
31
31
  }
32
32
  if (input.hostCapabilities !== undefined) {
33
33
  argv.push("--host-capabilities", JSON.stringify(input.hostCapabilities));
package/dist/index.d.ts CHANGED
@@ -20,7 +20,7 @@ export type { McpServerConfig, HostCapabilities } from "./types.js";
20
20
  * The protocol version that this TypeScript wrapper requires.
21
21
  * Forwarded to the engine via `--protocol-version` on every `submit()`.
22
22
  */
23
- export declare const PROTOCOL_VERSION_REQUIRED_BY_WRAPPER = "0.1.0";
23
+ export declare const PROTOCOL_VERSION_REQUIRED_BY_WRAPPER = "0.2.0";
24
24
  /** Parameters for spawnAgent(). Signature is locked verbatim by design §8.2. */
25
25
  export interface SpawnAgentParams {
26
26
  /** 'burst' reserved; throws AaaError(lifecycle_unsupported) at runtime. */
package/dist/index.js CHANGED
@@ -16,7 +16,7 @@ import { resolveBinaryPath, buildEnv, DEFAULT_ALLOWLIST } from "./spawn.js";
16
16
  * The protocol version that this TypeScript wrapper requires.
17
17
  * Forwarded to the engine via `--protocol-version` on every `submit()`.
18
18
  */
19
- export const PROTOCOL_VERSION_REQUIRED_BY_WRAPPER = "0.1.0";
19
+ export const PROTOCOL_VERSION_REQUIRED_BY_WRAPPER = "0.2.0";
20
20
  // ---------------------------------------------------------------------------
21
21
  // spawnAgent() — locked public entry point (Mode A v2)
22
22
  // ---------------------------------------------------------------------------
@@ -1,40 +1,40 @@
1
1
  /**
2
- * Result of resolving the `--mcp-servers` flag value.
2
+ * Result of resolving the `--mcp-config-path` flag value.
3
3
  *
4
- * - When `mcpServers` is null/undefined/empty: both fields are `null`.
5
- * - When no server has a non-empty env block: `flag` is inline JSON,
6
- * `spillPath` is `null` (no cleanup needed).
7
- * - When any server has a non-empty env block: `flag` is `@<spillPath>`,
8
- * `spillPath` points at the 0600 tmpfile (caller must cleanup).
4
+ * - When `mcpServers` is null/undefined/empty: `configPath` is `null`.
5
+ * - When servers are present: `configPath` points at the 0600 spill file.
6
+ * The file contains `{"mcpServers": <map>}` in the format that
7
+ * amplifier-module-tool-mcp expects when reading `AMPLIFIER_MCP_CONFIG`.
9
8
  */
10
9
  export interface McpSpillResult {
11
- flag: string | null;
12
- spillPath: string | null;
10
+ configPath: string | null;
13
11
  }
14
12
  /**
15
- * Loose shape for an MCP server entry. We only inspect `env` here; the rest
16
- * is threaded through untouched into the spilled JSON or inline payload.
13
+ * Loose shape for an MCP server entry. The full map is written verbatim
14
+ * into the spill file; no field is inspected beyond presence of the key.
17
15
  */
18
16
  interface McpServerLike {
19
- env?: Record<string, string> | undefined;
20
17
  [k: string]: unknown;
21
18
  }
22
19
  type McpServersMap = Record<string, McpServerLike>;
23
20
  /**
24
- * Resolve the value to pass for `--mcp-servers`.
21
+ * Resolve the MCP config file path to pass as `--mcp-config-path`.
22
+ *
23
+ * Always spills to a 0600 tmpfile. The file content wraps the server map
24
+ * in the top-level `mcpServers` key that amplifier-module-tool-mcp expects.
25
25
  *
26
26
  * @param mcpServers Map of server-id -> config, or null/undefined.
27
27
  * @param sessionId Session identifier; used as the per-session subdirectory
28
28
  * under the spill base so concurrent sessions never clash.
29
29
  *
30
- * @returns A `McpSpillResult` with the flag value and (if spilled) the
31
- * on-disk path for later cleanup.
30
+ * @returns A `McpSpillResult` with the on-disk config path (or null if there
31
+ * are no servers to spill).
32
32
  */
33
- export declare function resolveMcpServersFlag(mcpServers: McpServersMap | null | undefined, sessionId: string): Promise<McpSpillResult>;
33
+ export declare function resolveMcpConfigPath(mcpServers: McpServersMap | null | undefined, sessionId: string): Promise<McpSpillResult>;
34
34
  /**
35
35
  * Idempotently remove a spill file. Safe to call with `null` (no-op) and
36
36
  * safe to call when the file is already gone (ENOENT swallowed). Other
37
37
  * I/O errors propagate.
38
38
  */
39
- export declare function cleanupSpillFile(spillPath: string | null | undefined): Promise<void>;
39
+ export declare function cleanupSpillFile(configPath: string | null | undefined): Promise<void>;
40
40
  export {};
package/dist/mcp-spill.js CHANGED
@@ -1,12 +1,12 @@
1
1
  /**
2
- * mcp-spill.ts — secret-aware MCP servers config resolution (CR-A).
2
+ * mcp-spill.ts — MCP servers config path resolution (CR-A, protocol 0.2.0).
3
3
  *
4
- * A3'/CR-A: When forwarding `--mcp-servers` to the engine binary, the wrapper
5
- * must avoid placing secret-bearing env blocks on the command line. If any
6
- * server in the config has a non-empty `env` block, the full JSON is spilled
7
- * to a 0600 tmpfile under `${XDG_RUNTIME_DIR || os.tmpdir()}/amplifier-agent/<sessionId>/`
8
- * and the flag value is `@<path>`. When no server has env, the JSON is inlined
9
- * directly (no spill, no cleanup needed).
4
+ * The wrapper always spills the MCP server map to a 0600 tmpfile under
5
+ * `${XDG_RUNTIME_DIR || os.tmpdir()}/amplifier-agent/<sessionId>/mcp.json`.
6
+ * The file is written in the format documented by amplifier-module-tool-mcp:
7
+ * a top-level `{"mcpServers": <map>}` object. The engine receives the plain
8
+ * file path via `--mcp-config-path` and sets `AMPLIFIER_MCP_CONFIG`; the
9
+ * module reads it via its standard config discovery (config.py priority chain).
10
10
  *
11
11
  * `cleanupSpillFile` is the matching teardown — idempotent unlink that
12
12
  * swallows ENOENT so callers can call it unconditionally on every exit path.
@@ -14,23 +14,6 @@
14
14
  import { mkdir, writeFile, unlink } from "node:fs/promises";
15
15
  import { tmpdir } from "node:os";
16
16
  import { join } from "node:path";
17
- /**
18
- * Return true when at least one server has a non-empty `env` block.
19
- * An empty object (`{}`) does NOT trigger spilling — only env blocks with
20
- * at least one key are considered secret-bearing.
21
- */
22
- function anyServerHasEnv(mcpServers) {
23
- for (const key of Object.keys(mcpServers)) {
24
- const server = mcpServers[key];
25
- if (!server)
26
- continue;
27
- const env = server.env;
28
- if (env && typeof env === "object" && Object.keys(env).length > 0) {
29
- return true;
30
- }
31
- }
32
- return false;
33
- }
34
17
  /**
35
18
  * Compute the base directory for spill files. Prefers
36
19
  * `$XDG_RUNTIME_DIR/amplifier-agent` (typically a tmpfs on Linux) and falls
@@ -44,40 +27,43 @@ function spillBaseDir() {
44
27
  return join(tmpdir(), "amplifier-agent");
45
28
  }
46
29
  /**
47
- * Resolve the value to pass for `--mcp-servers`.
30
+ * Resolve the MCP config file path to pass as `--mcp-config-path`.
31
+ *
32
+ * Always spills to a 0600 tmpfile. The file content wraps the server map
33
+ * in the top-level `mcpServers` key that amplifier-module-tool-mcp expects.
48
34
  *
49
35
  * @param mcpServers Map of server-id -> config, or null/undefined.
50
36
  * @param sessionId Session identifier; used as the per-session subdirectory
51
37
  * under the spill base so concurrent sessions never clash.
52
38
  *
53
- * @returns A `McpSpillResult` with the flag value and (if spilled) the
54
- * on-disk path for later cleanup.
39
+ * @returns A `McpSpillResult` with the on-disk config path (or null if there
40
+ * are no servers to spill).
55
41
  */
56
- export async function resolveMcpServersFlag(mcpServers, sessionId) {
42
+ export async function resolveMcpConfigPath(mcpServers, sessionId) {
57
43
  if (!mcpServers || Object.keys(mcpServers).length === 0) {
58
- return { flag: null, spillPath: null };
59
- }
60
- if (!anyServerHasEnv(mcpServers)) {
61
- // No secrets — safe to inline as a JSON string.
62
- return { flag: JSON.stringify(mcpServers), spillPath: null };
44
+ return { configPath: null };
63
45
  }
64
- // Secret-bearing: spill to a 0600 tmpfile under a 0700 per-session dir.
46
+ // Always spill to a 0600 tmpfile under a 0700 per-session dir.
47
+ // Wrap the server map in the top-level "mcpServers" key that the module
48
+ // expects when reading AMPLIFIER_MCP_CONFIG (see tool-mcp/config.py).
65
49
  const dir = join(spillBaseDir(), sessionId);
66
50
  await mkdir(dir, { recursive: true, mode: 0o700 });
67
51
  const filePath = join(dir, "mcp.json");
68
- await writeFile(filePath, JSON.stringify(mcpServers), { mode: 0o600 });
69
- return { flag: `@${filePath}`, spillPath: filePath };
52
+ await writeFile(filePath, JSON.stringify({ mcpServers: mcpServers }), {
53
+ mode: 0o600,
54
+ });
55
+ return { configPath: filePath };
70
56
  }
71
57
  /**
72
58
  * Idempotently remove a spill file. Safe to call with `null` (no-op) and
73
59
  * safe to call when the file is already gone (ENOENT swallowed). Other
74
60
  * I/O errors propagate.
75
61
  */
76
- export async function cleanupSpillFile(spillPath) {
77
- if (!spillPath)
62
+ export async function cleanupSpillFile(configPath) {
63
+ if (!configPath)
78
64
  return;
79
65
  try {
80
- await unlink(spillPath);
66
+ await unlink(configPath);
81
67
  }
82
68
  catch (err) {
83
69
  const code = err.code;
package/dist/session.d.ts CHANGED
@@ -89,7 +89,7 @@ export interface SessionHandleParams {
89
89
  resume?: boolean;
90
90
  /** Working directory for the subprocess. */
91
91
  cwd?: string;
92
- /** MCP servers to forward via `--mcp-servers` (CR-A spill applies). */
92
+ /** MCP servers to forward via `--mcp-config-path` (CR-A spill applies). */
93
93
  mcpServers?: Record<string, McpServerConfig>;
94
94
  /** Host capabilities forwarded via `--host-capabilities`. */
95
95
  hostCapabilities?: HostCapabilities;
@@ -133,7 +133,7 @@ export declare class SessionHandle {
133
133
  /**
134
134
  * Async generator implementing the §5.2 iterable behavior:
135
135
  * (i) yield `{type:'init', sessionId}` synchronously (SC-1);
136
- * (ii) CR-A: resolve `--mcp-servers` flag (spill if env-bearing);
136
+ * (ii) CR-A: resolve `--mcp-config-path` (always spill to tmpfile);
137
137
  * (iii) build argv via `assembleArgv`;
138
138
  * (iv) SC-B: spawn with `detached:true` so PID == PGID for group signals;
139
139
  * (v) accumulate stdout/stderr from chunks;
package/dist/session.js CHANGED
@@ -24,7 +24,7 @@
24
24
  */
25
25
  import { spawn as childSpawn } from "node:child_process";
26
26
  import { assembleArgv } from "./argv-builder.js";
27
- import { resolveMcpServersFlag, cleanupSpillFile } from "./mcp-spill.js";
27
+ import { resolveMcpConfigPath, cleanupSpillFile } from "./mcp-spill.js";
28
28
  import { parseRunOutput, STDERR_TAIL_BYTES } from "./run-output-parser.js";
29
29
  /** Typed error for AaA wrapper lifecycle and protocol violations. */
30
30
  export class AaaError extends Error {
@@ -121,7 +121,7 @@ export class SessionHandle {
121
121
  /**
122
122
  * Async generator implementing the §5.2 iterable behavior:
123
123
  * (i) yield `{type:'init', sessionId}` synchronously (SC-1);
124
- * (ii) CR-A: resolve `--mcp-servers` flag (spill if env-bearing);
124
+ * (ii) CR-A: resolve `--mcp-config-path` (always spill to tmpfile);
125
125
  * (iii) build argv via `assembleArgv`;
126
126
  * (iv) SC-B: spawn with `detached:true` so PID == PGID for group signals;
127
127
  * (v) accumulate stdout/stderr from chunks;
@@ -135,13 +135,13 @@ export class SessionHandle {
135
135
  async *makeIterable(prompt) {
136
136
  // (i) SC-1: yield init synchronously, BEFORE any async work.
137
137
  yield { type: "init", sessionId: this.params.sessionId };
138
- // (ii) CR-A: resolve --mcp-servers (inline JSON OR spill to 0600 tmpfile).
138
+ // (ii) CR-A: resolve --mcp-config-path (always spill to 0600 tmpfile).
139
139
  // Cast through `unknown`: McpServerConfig is the schema-validated wire type
140
- // (no index signature), while resolveMcpServersFlag's McpServerLike has an
141
- // open index signature. The two are runtime-compatible — only `env` is
142
- // inspected — but TS rightly rejects assignability without the cast.
143
- const spill = await resolveMcpServersFlag((this.params.mcpServers ?? null), this.params.sessionId);
144
- this.mcpSpillPath = spill.spillPath;
140
+ // (no index signature), while resolveMcpConfigPath's McpServerLike has an
141
+ // open index signature. The two are runtime-compatible but TS rightly
142
+ // rejects assignability without the cast.
143
+ const spill = await resolveMcpConfigPath((this.params.mcpServers ?? null), this.params.sessionId);
144
+ this.mcpSpillPath = spill.configPath;
145
145
  // (iii) build argv (pure function — no I/O).
146
146
  const argv = assembleArgv({
147
147
  sessionId: this.params.sessionId,
@@ -150,7 +150,7 @@ export class SessionHandle {
150
150
  resume: this.params.resume,
151
151
  cwd: this.params.cwd,
152
152
  providerOverride: this.params.providerOverride,
153
- mcpServersFlag: spill.flag ?? undefined,
153
+ mcpConfigPath: spill.configPath ?? undefined,
154
154
  hostCapabilities: this.params.hostCapabilities,
155
155
  envAllowlist: this.params.envAllowlist,
156
156
  envExtra: this.params.envExtra,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "amplifier-agent-ts",
3
- "version": "0.3.1",
3
+ "version": "0.4.0",
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": {