amplifier-agent-ts 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +105 -0
- package/dist/approval.d.ts +40 -0
- package/dist/approval.js +49 -0
- package/dist/argv-builder.d.ts +46 -0
- package/dist/argv-builder.js +51 -0
- package/dist/index.d.ts +79 -0
- package/dist/index.js +105 -0
- package/dist/mcp-spill.d.ts +40 -0
- package/dist/mcp-spill.js +88 -0
- package/dist/run-output-parser.d.ts +33 -0
- package/dist/run-output-parser.js +149 -0
- package/dist/session.d.ts +159 -0
- package/dist/session.js +317 -0
- package/dist/spawn.d.ts +61 -0
- package/dist/spawn.js +118 -0
- package/dist/transport.d.ts +69 -0
- package/dist/transport.js +113 -0
- package/dist/types.d.ts +318 -0
- package/dist/types.js +4 -0
- package/dist/version.d.ts +35 -0
- package/dist/version.js +28 -0
- package/package.json +57 -0
package/dist/spawn.js
ADDED
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Binary discovery, environment allowlist, and engine version probe.
|
|
3
|
+
*
|
|
4
|
+
* resolveBinaryPath() — find the amplifier-agent binary
|
|
5
|
+
* buildEnv() — filter subprocess env to a safe allowlist
|
|
6
|
+
* probeEngineVersion() — run `amplifier-agent version --json` and parse result
|
|
7
|
+
*/
|
|
8
|
+
import { execFile, execSync } from "node:child_process";
|
|
9
|
+
import { existsSync } from "node:fs";
|
|
10
|
+
import { promisify } from "node:util";
|
|
11
|
+
import { AaaError } from "./session.js";
|
|
12
|
+
const execFileAsync = promisify(execFile);
|
|
13
|
+
/** Variables always passed through to subprocess (exact name match). */
|
|
14
|
+
export const DEFAULT_ALLOWLIST = [
|
|
15
|
+
"PATH",
|
|
16
|
+
"HOME",
|
|
17
|
+
"USER",
|
|
18
|
+
"LANG",
|
|
19
|
+
"TERM",
|
|
20
|
+
"TMPDIR",
|
|
21
|
+
];
|
|
22
|
+
/**
|
|
23
|
+
* Environment variable names that are NEVER allowed in env.extra
|
|
24
|
+
* regardless of allowlist (design §4.12.1). These can be used to inject
|
|
25
|
+
* code into the subprocess (e.g. via shared-library preloading or Python
|
|
26
|
+
* import-path manipulation).
|
|
27
|
+
*/
|
|
28
|
+
export const BLOCKED_ENV_KEYS = new Set([
|
|
29
|
+
"PYTHONPATH",
|
|
30
|
+
"LD_PRELOAD",
|
|
31
|
+
"LD_LIBRARY_PATH",
|
|
32
|
+
"PYTHONSTARTUP",
|
|
33
|
+
"PATH",
|
|
34
|
+
"PYTHONHOME",
|
|
35
|
+
"PYTHONNOUSERSITE",
|
|
36
|
+
"DYLD_INSERT_LIBRARIES",
|
|
37
|
+
"DYLD_LIBRARY_PATH",
|
|
38
|
+
]);
|
|
39
|
+
/**
|
|
40
|
+
* Resolve the path to the amplifier-agent binary.
|
|
41
|
+
*
|
|
42
|
+
* Resolution order:
|
|
43
|
+
* 1. AMPLIFIER_AGENT_BIN env var (if set and the path exists on disk)
|
|
44
|
+
* 2. `which amplifier-agent` via PATH lookup
|
|
45
|
+
*
|
|
46
|
+
* @throws Error with code 'binary_not_found' if neither path resolves.
|
|
47
|
+
*/
|
|
48
|
+
export function resolveBinaryPath(opts = {}) {
|
|
49
|
+
const env = opts.env ?? process.env;
|
|
50
|
+
const envBin = env["AMPLIFIER_AGENT_BIN"];
|
|
51
|
+
if (envBin) {
|
|
52
|
+
if (existsSync(envBin)) {
|
|
53
|
+
return envBin;
|
|
54
|
+
}
|
|
55
|
+
// env var set but path doesn't exist — still return it (caller handles errors)
|
|
56
|
+
return envBin;
|
|
57
|
+
}
|
|
58
|
+
try {
|
|
59
|
+
const whichResult = execSync("which amplifier-agent", { encoding: "utf-8" }).trim();
|
|
60
|
+
if (whichResult) {
|
|
61
|
+
return whichResult;
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
catch {
|
|
65
|
+
// which failed — binary not on PATH
|
|
66
|
+
}
|
|
67
|
+
const err = new Error("amplifier-agent binary not found. " +
|
|
68
|
+
"Install amplifier-agent: pip install amplifier-agent, " +
|
|
69
|
+
"or set AMPLIFIER_AGENT_BIN to the binary path.");
|
|
70
|
+
err.code = "binary_not_found";
|
|
71
|
+
throw err;
|
|
72
|
+
}
|
|
73
|
+
/**
|
|
74
|
+
* Build the subprocess environment from the caller's process environment.
|
|
75
|
+
*
|
|
76
|
+
* Only variables whose name is in `allowlist`, starts with `AMPLIFIER_`,
|
|
77
|
+
* or starts with `LC_` are included. `extra` entries are merged last.
|
|
78
|
+
*/
|
|
79
|
+
export function buildEnv(opts) {
|
|
80
|
+
const { processEnv, allowlist, extra = {} } = opts;
|
|
81
|
+
// Reject blocked keys in extra up-front (design §4.12.1, SC-3).
|
|
82
|
+
for (const key of Object.keys(extra)) {
|
|
83
|
+
if (BLOCKED_ENV_KEYS.has(key)) {
|
|
84
|
+
throw new AaaError("env_injection_rejected", `env.extra key '${key}' is blocked for security reasons (design §4.12.1).`, { classification: "protocol", severity: "error" });
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
const allowSet = new Set(allowlist);
|
|
88
|
+
const result = {};
|
|
89
|
+
for (const [key, value] of Object.entries(processEnv)) {
|
|
90
|
+
if (value === undefined)
|
|
91
|
+
continue;
|
|
92
|
+
if (allowSet.has(key) ||
|
|
93
|
+
key.startsWith("AMPLIFIER_") ||
|
|
94
|
+
key.startsWith("LC_")) {
|
|
95
|
+
result[key] = value;
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
// Merge extras last — they win over everything
|
|
99
|
+
for (const [key, value] of Object.entries(extra)) {
|
|
100
|
+
result[key] = value;
|
|
101
|
+
}
|
|
102
|
+
return result;
|
|
103
|
+
}
|
|
104
|
+
/**
|
|
105
|
+
* Run `<binPath> version --json` and parse the JSON response.
|
|
106
|
+
*
|
|
107
|
+
* @param binPath Absolute path to the amplifier-agent binary.
|
|
108
|
+
* @param env Environment to pass to the subprocess.
|
|
109
|
+
* @param timeoutMs Timeout in milliseconds (default: 5000).
|
|
110
|
+
*/
|
|
111
|
+
export async function probeEngineVersion(binPath, env, timeoutMs = 5000) {
|
|
112
|
+
const { stdout } = await execFileAsync(binPath, ["version", "--json"], {
|
|
113
|
+
encoding: "utf-8",
|
|
114
|
+
timeout: timeoutMs,
|
|
115
|
+
env,
|
|
116
|
+
});
|
|
117
|
+
return JSON.parse(stdout.trim());
|
|
118
|
+
}
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* NDJSON subprocess transport.
|
|
3
|
+
*
|
|
4
|
+
* Spawns a child process and exchanges JSON frames over its stdio:
|
|
5
|
+
* - onFrame(cb): register a callback to receive parsed JSON objects from stdout
|
|
6
|
+
* - send(obj): write a JSON frame (NDJSON) to stdin
|
|
7
|
+
* - terminate(): send SIGTERM and await process exit
|
|
8
|
+
*
|
|
9
|
+
* Defensive requirement (MCP-style tolerance): non-JSON stdout lines are
|
|
10
|
+
* logged to the stderr sink (or process.stderr) and dropped silently.
|
|
11
|
+
*
|
|
12
|
+
* No JSON-RPC semantics here — that is Task 6.
|
|
13
|
+
*/
|
|
14
|
+
export interface TransportOptions {
|
|
15
|
+
/** Command to spawn (e.g. "cat", "sh"). */
|
|
16
|
+
command: string;
|
|
17
|
+
/** Arguments passed to the command. */
|
|
18
|
+
args: string[];
|
|
19
|
+
/**
|
|
20
|
+
* Environment variable overrides merged on top of the current process env.
|
|
21
|
+
* Pass {} to inherit the current environment without overrides.
|
|
22
|
+
*/
|
|
23
|
+
env: Record<string, string>;
|
|
24
|
+
/** Optional working directory for the child process. */
|
|
25
|
+
cwd?: string;
|
|
26
|
+
/**
|
|
27
|
+
* Optional sink for stderr lines from the child and for non-JSON drop
|
|
28
|
+
* warnings from the transport itself. Defaults to process.stderr.
|
|
29
|
+
*/
|
|
30
|
+
stderr?: (line: string) => void;
|
|
31
|
+
}
|
|
32
|
+
export interface ExitInfo {
|
|
33
|
+
/** Process exit code, or null if the process was killed by a signal. */
|
|
34
|
+
code: number | null;
|
|
35
|
+
/** Signal name if the process was killed by a signal, otherwise null. */
|
|
36
|
+
signal: string | null;
|
|
37
|
+
}
|
|
38
|
+
export declare class Transport {
|
|
39
|
+
private readonly opts;
|
|
40
|
+
private proc;
|
|
41
|
+
private readonly frameCallbacks;
|
|
42
|
+
private exitPromise;
|
|
43
|
+
constructor(opts: TransportOptions);
|
|
44
|
+
/**
|
|
45
|
+
* Spawn the child process and start reading its stdout/stderr.
|
|
46
|
+
*
|
|
47
|
+
* After this resolves, send() and terminate() are available.
|
|
48
|
+
* onFrame() callbacks may be registered before or after spawn().
|
|
49
|
+
*/
|
|
50
|
+
spawn(): Promise<void>;
|
|
51
|
+
/**
|
|
52
|
+
* Register a callback that is invoked with each parsed JSON frame received
|
|
53
|
+
* on the child's stdout. Callbacks may be registered before or after spawn().
|
|
54
|
+
*/
|
|
55
|
+
onFrame(cb: (obj: unknown) => void): void;
|
|
56
|
+
/**
|
|
57
|
+
* Serialize obj as a single NDJSON line and write it to the child's stdin.
|
|
58
|
+
* Pattern: json.dumps(obj) + '\n' (matches engine's NDJSON write side).
|
|
59
|
+
*/
|
|
60
|
+
send(obj: unknown): Promise<void>;
|
|
61
|
+
/**
|
|
62
|
+
* Send SIGTERM to the child process and await its exit.
|
|
63
|
+
*
|
|
64
|
+
* Returns ExitInfo with the final exit code and/or signal.
|
|
65
|
+
* Safe to call even if the process has already exited — will just
|
|
66
|
+
* return the already-resolved exit info.
|
|
67
|
+
*/
|
|
68
|
+
terminate(): Promise<ExitInfo>;
|
|
69
|
+
}
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* NDJSON subprocess transport.
|
|
3
|
+
*
|
|
4
|
+
* Spawns a child process and exchanges JSON frames over its stdio:
|
|
5
|
+
* - onFrame(cb): register a callback to receive parsed JSON objects from stdout
|
|
6
|
+
* - send(obj): write a JSON frame (NDJSON) to stdin
|
|
7
|
+
* - terminate(): send SIGTERM and await process exit
|
|
8
|
+
*
|
|
9
|
+
* Defensive requirement (MCP-style tolerance): non-JSON stdout lines are
|
|
10
|
+
* logged to the stderr sink (or process.stderr) and dropped silently.
|
|
11
|
+
*
|
|
12
|
+
* No JSON-RPC semantics here — that is Task 6.
|
|
13
|
+
*/
|
|
14
|
+
import { spawn } from "node:child_process";
|
|
15
|
+
import { createInterface } from "node:readline";
|
|
16
|
+
export class Transport {
|
|
17
|
+
opts;
|
|
18
|
+
proc = null;
|
|
19
|
+
frameCallbacks = [];
|
|
20
|
+
exitPromise = null;
|
|
21
|
+
constructor(opts) {
|
|
22
|
+
this.opts = opts;
|
|
23
|
+
}
|
|
24
|
+
/**
|
|
25
|
+
* Spawn the child process and start reading its stdout/stderr.
|
|
26
|
+
*
|
|
27
|
+
* After this resolves, send() and terminate() are available.
|
|
28
|
+
* onFrame() callbacks may be registered before or after spawn().
|
|
29
|
+
*/
|
|
30
|
+
async spawn() {
|
|
31
|
+
const proc = spawn(this.opts.command, this.opts.args, {
|
|
32
|
+
stdio: ["pipe", "pipe", "pipe"],
|
|
33
|
+
// Merge caller-supplied env on top of the current process environment.
|
|
34
|
+
env: { ...process.env, ...this.opts.env },
|
|
35
|
+
cwd: this.opts.cwd,
|
|
36
|
+
});
|
|
37
|
+
this.proc = proc;
|
|
38
|
+
// exitPromise resolves after the child process AND all its stdio streams
|
|
39
|
+
// have closed. The 'close' event fires AFTER readline has processed all
|
|
40
|
+
// buffered lines, so frames are guaranteed to be delivered before the
|
|
41
|
+
// promise resolves.
|
|
42
|
+
this.exitPromise = new Promise((resolve) => {
|
|
43
|
+
proc.on("close", (code, signal) => resolve({ code, signal }));
|
|
44
|
+
});
|
|
45
|
+
// Read stdout line by line; parse JSON; dispatch to registered callbacks.
|
|
46
|
+
const stdoutRl = createInterface({ input: proc.stdout });
|
|
47
|
+
stdoutRl.on("line", (line) => {
|
|
48
|
+
try {
|
|
49
|
+
const obj = JSON.parse(line);
|
|
50
|
+
for (const cb of this.frameCallbacks) {
|
|
51
|
+
cb(obj);
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
catch {
|
|
55
|
+
// Non-JSON line: log to stderr sink and drop silently.
|
|
56
|
+
const msg = `[transport] non-JSON stdout line dropped: ${line}`;
|
|
57
|
+
if (this.opts.stderr) {
|
|
58
|
+
this.opts.stderr(msg);
|
|
59
|
+
}
|
|
60
|
+
else {
|
|
61
|
+
process.stderr.write(msg + "\n");
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
});
|
|
65
|
+
// Drain child stderr to the optional sink.
|
|
66
|
+
const stderrRl = createInterface({ input: proc.stderr });
|
|
67
|
+
stderrRl.on("line", (line) => {
|
|
68
|
+
if (this.opts.stderr) {
|
|
69
|
+
this.opts.stderr(line);
|
|
70
|
+
}
|
|
71
|
+
});
|
|
72
|
+
}
|
|
73
|
+
/**
|
|
74
|
+
* Register a callback that is invoked with each parsed JSON frame received
|
|
75
|
+
* on the child's stdout. Callbacks may be registered before or after spawn().
|
|
76
|
+
*/
|
|
77
|
+
onFrame(cb) {
|
|
78
|
+
this.frameCallbacks.push(cb);
|
|
79
|
+
}
|
|
80
|
+
/**
|
|
81
|
+
* Serialize obj as a single NDJSON line and write it to the child's stdin.
|
|
82
|
+
* Pattern: json.dumps(obj) + '\n' (matches engine's NDJSON write side).
|
|
83
|
+
*/
|
|
84
|
+
async send(obj) {
|
|
85
|
+
return new Promise((resolve, reject) => {
|
|
86
|
+
const data = JSON.stringify(obj) + "\n";
|
|
87
|
+
this.proc.stdin.write(data, (err) => {
|
|
88
|
+
if (err)
|
|
89
|
+
reject(err);
|
|
90
|
+
else
|
|
91
|
+
resolve();
|
|
92
|
+
});
|
|
93
|
+
});
|
|
94
|
+
}
|
|
95
|
+
/**
|
|
96
|
+
* Send SIGTERM to the child process and await its exit.
|
|
97
|
+
*
|
|
98
|
+
* Returns ExitInfo with the final exit code and/or signal.
|
|
99
|
+
* Safe to call even if the process has already exited — will just
|
|
100
|
+
* return the already-resolved exit info.
|
|
101
|
+
*/
|
|
102
|
+
async terminate() {
|
|
103
|
+
if (this.proc) {
|
|
104
|
+
try {
|
|
105
|
+
this.proc.kill("SIGTERM");
|
|
106
|
+
}
|
|
107
|
+
catch {
|
|
108
|
+
// Process may have already exited; kill() failing is expected.
|
|
109
|
+
}
|
|
110
|
+
}
|
|
111
|
+
return this.exitPromise;
|
|
112
|
+
}
|
|
113
|
+
}
|
package/dist/types.d.ts
ADDED
|
@@ -0,0 +1,318 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Parameters for the ``agent/shutdown`` JSON-RPC method (none required).
|
|
3
|
+
*/
|
|
4
|
+
export interface AgentShutdownParams {
|
|
5
|
+
}
|
|
6
|
+
/**
|
|
7
|
+
* Result returned by the ``agent/shutdown`` JSON-RPC method (none required).
|
|
8
|
+
*/
|
|
9
|
+
export interface AgentShutdownResult {
|
|
10
|
+
}
|
|
11
|
+
/**
|
|
12
|
+
* Approval-flow capabilities: the approval action strings a party supports.
|
|
13
|
+
*/
|
|
14
|
+
export interface ApprovalCapability {
|
|
15
|
+
actions: string[];
|
|
16
|
+
}
|
|
17
|
+
/**
|
|
18
|
+
* Requests human (or automated) approval before proceeding.
|
|
19
|
+
*/
|
|
20
|
+
export interface ApprovalRequestNotification {
|
|
21
|
+
sessionId: string;
|
|
22
|
+
turnId: string;
|
|
23
|
+
approvalId: string;
|
|
24
|
+
kind: string;
|
|
25
|
+
payload: unknown;
|
|
26
|
+
timeoutMs: number;
|
|
27
|
+
}
|
|
28
|
+
/**
|
|
29
|
+
* Emitted when an approval request exceeds its timeout.
|
|
30
|
+
*/
|
|
31
|
+
export interface ApprovalTimeoutNotification {
|
|
32
|
+
sessionId: string;
|
|
33
|
+
turnId: string;
|
|
34
|
+
approvalId: string;
|
|
35
|
+
kind: string;
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* Parameters for the ``cache/info`` JSON-RPC method (none required).
|
|
39
|
+
*/
|
|
40
|
+
export interface CacheInfoParams {
|
|
41
|
+
}
|
|
42
|
+
/**
|
|
43
|
+
* Result returned by the ``cache/info`` JSON-RPC method.
|
|
44
|
+
*/
|
|
45
|
+
export interface CacheInfoResult {
|
|
46
|
+
cachePath: string;
|
|
47
|
+
preparedBundles: string[];
|
|
48
|
+
}
|
|
49
|
+
/**
|
|
50
|
+
* Capabilities advertised by the connecting client.
|
|
51
|
+
*/
|
|
52
|
+
export interface ClientCapabilities {
|
|
53
|
+
approval?: ApprovalCapability;
|
|
54
|
+
display?: DisplayCapability;
|
|
55
|
+
experimental?: {
|
|
56
|
+
[k: string]: unknown;
|
|
57
|
+
};
|
|
58
|
+
}
|
|
59
|
+
/**
|
|
60
|
+
* Approval-flow capabilities: the approval action strings a party supports.
|
|
61
|
+
*/
|
|
62
|
+
/**
|
|
63
|
+
* Display capabilities: the notification event types a party can handle.
|
|
64
|
+
*/
|
|
65
|
+
export interface DisplayCapability {
|
|
66
|
+
events: string[];
|
|
67
|
+
}
|
|
68
|
+
/**
|
|
69
|
+
* Identity of the connecting client.
|
|
70
|
+
*/
|
|
71
|
+
export interface ClientInfo {
|
|
72
|
+
name: string;
|
|
73
|
+
version: string;
|
|
74
|
+
}
|
|
75
|
+
/**
|
|
76
|
+
* Display capabilities: the notification event types a party can handle.
|
|
77
|
+
*/
|
|
78
|
+
/**
|
|
79
|
+
* Error event. ``turnId`` is optional for session-level errors.
|
|
80
|
+
*/
|
|
81
|
+
export interface ErrorNotification {
|
|
82
|
+
sessionId: string;
|
|
83
|
+
turnId?: string;
|
|
84
|
+
code: string;
|
|
85
|
+
message: string;
|
|
86
|
+
recoverable: boolean;
|
|
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
|
+
/**
|
|
105
|
+
* Parameters for the ``initialize`` JSON-RPC method.
|
|
106
|
+
*/
|
|
107
|
+
export interface InitializeParams {
|
|
108
|
+
protocolVersion: string;
|
|
109
|
+
clientInfo: ClientInfo;
|
|
110
|
+
capabilities: {
|
|
111
|
+
[k: string]: unknown;
|
|
112
|
+
};
|
|
113
|
+
sessionId?: string;
|
|
114
|
+
resume?: boolean;
|
|
115
|
+
providerOverride?: string;
|
|
116
|
+
cwd?: string;
|
|
117
|
+
mcpServers?: {
|
|
118
|
+
[k: string]: McpServerConfig;
|
|
119
|
+
};
|
|
120
|
+
host?: InitializeHostParams;
|
|
121
|
+
}
|
|
122
|
+
/**
|
|
123
|
+
* Identity of the connecting client.
|
|
124
|
+
*/
|
|
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
|
+
/**
|
|
147
|
+
* Result returned by the ``initialize`` JSON-RPC method.
|
|
148
|
+
*/
|
|
149
|
+
export interface InitializeResult {
|
|
150
|
+
capabilities: {
|
|
151
|
+
[k: string]: unknown;
|
|
152
|
+
};
|
|
153
|
+
serverInfo: ServerInfo;
|
|
154
|
+
sessionState: SessionState;
|
|
155
|
+
}
|
|
156
|
+
/**
|
|
157
|
+
* Identity of the agent server.
|
|
158
|
+
*/
|
|
159
|
+
export interface ServerInfo {
|
|
160
|
+
name: string;
|
|
161
|
+
version: string;
|
|
162
|
+
}
|
|
163
|
+
/**
|
|
164
|
+
* Returned session state after initialize or session/create.
|
|
165
|
+
*/
|
|
166
|
+
export interface SessionState {
|
|
167
|
+
sessionId: string;
|
|
168
|
+
resumed: boolean;
|
|
169
|
+
}
|
|
170
|
+
/**
|
|
171
|
+
* Per-server MCP configuration passed via ``initialize.params.mcpServers``.
|
|
172
|
+
*/
|
|
173
|
+
/**
|
|
174
|
+
* Arbitrary progress update. ``percent`` is optional (0-100).
|
|
175
|
+
*/
|
|
176
|
+
export interface ProgressNotification {
|
|
177
|
+
sessionId: string;
|
|
178
|
+
turnId: string;
|
|
179
|
+
message: string;
|
|
180
|
+
percent?: number;
|
|
181
|
+
}
|
|
182
|
+
/**
|
|
183
|
+
* Incremental text chunk from an in-progress turn.
|
|
184
|
+
*/
|
|
185
|
+
export interface ResultDeltaNotification {
|
|
186
|
+
sessionId: string;
|
|
187
|
+
turnId: string;
|
|
188
|
+
text: string;
|
|
189
|
+
}
|
|
190
|
+
/**
|
|
191
|
+
* Final text for a completed turn. ``usage`` may be omitted (e.g. L14 synthesis).
|
|
192
|
+
*/
|
|
193
|
+
export interface ResultFinalNotification {
|
|
194
|
+
sessionId: string;
|
|
195
|
+
turnId: string;
|
|
196
|
+
text: string;
|
|
197
|
+
usage?: unknown;
|
|
198
|
+
}
|
|
199
|
+
/**
|
|
200
|
+
* Capabilities advertised by the agent server.
|
|
201
|
+
*/
|
|
202
|
+
export interface ServerCapabilities {
|
|
203
|
+
approval?: ApprovalCapability;
|
|
204
|
+
display?: DisplayCapability;
|
|
205
|
+
experimental?: {
|
|
206
|
+
[k: string]: unknown;
|
|
207
|
+
};
|
|
208
|
+
}
|
|
209
|
+
/**
|
|
210
|
+
* Approval-flow capabilities: the approval action strings a party supports.
|
|
211
|
+
*/
|
|
212
|
+
/**
|
|
213
|
+
* Display capabilities: the notification event types a party can handle.
|
|
214
|
+
*/
|
|
215
|
+
/**
|
|
216
|
+
* Identity of the agent server.
|
|
217
|
+
*/
|
|
218
|
+
/**
|
|
219
|
+
* Parameters for the ``session/create`` JSON-RPC method.
|
|
220
|
+
*/
|
|
221
|
+
export interface SessionCreateParams {
|
|
222
|
+
sessionId: string;
|
|
223
|
+
resume?: boolean;
|
|
224
|
+
}
|
|
225
|
+
/**
|
|
226
|
+
* Result returned by the ``session/create`` JSON-RPC method.
|
|
227
|
+
*/
|
|
228
|
+
export interface SessionCreateResult {
|
|
229
|
+
sessionState: SessionState;
|
|
230
|
+
}
|
|
231
|
+
/**
|
|
232
|
+
* Returned session state after initialize or session/create.
|
|
233
|
+
*/
|
|
234
|
+
/**
|
|
235
|
+
* Parameters for the ``session/end`` JSON-RPC method.
|
|
236
|
+
*/
|
|
237
|
+
export interface SessionEndParams {
|
|
238
|
+
sessionId: string;
|
|
239
|
+
}
|
|
240
|
+
/**
|
|
241
|
+
* Result returned by the ``session/end`` JSON-RPC method.
|
|
242
|
+
*/
|
|
243
|
+
export interface SessionEndResult {
|
|
244
|
+
ended: boolean;
|
|
245
|
+
}
|
|
246
|
+
/**
|
|
247
|
+
* Returned session state after initialize or session/create.
|
|
248
|
+
*/
|
|
249
|
+
/**
|
|
250
|
+
* Incremental thinking/reasoning chunk (extended thinking models).
|
|
251
|
+
*/
|
|
252
|
+
export interface ThinkingDeltaNotification {
|
|
253
|
+
sessionId: string;
|
|
254
|
+
turnId: string;
|
|
255
|
+
text: string;
|
|
256
|
+
}
|
|
257
|
+
/**
|
|
258
|
+
* Final thinking/reasoning content for a turn.
|
|
259
|
+
*/
|
|
260
|
+
export interface ThinkingFinalNotification {
|
|
261
|
+
sessionId: string;
|
|
262
|
+
turnId: string;
|
|
263
|
+
text: string;
|
|
264
|
+
}
|
|
265
|
+
/**
|
|
266
|
+
* Emitted when a tool call finishes execution.
|
|
267
|
+
*/
|
|
268
|
+
export interface ToolCompletedNotification {
|
|
269
|
+
sessionId: string;
|
|
270
|
+
turnId: string;
|
|
271
|
+
toolCallId: string;
|
|
272
|
+
name: string;
|
|
273
|
+
result: unknown;
|
|
274
|
+
durationMs: number;
|
|
275
|
+
}
|
|
276
|
+
/**
|
|
277
|
+
* Emitted when a tool call begins execution.
|
|
278
|
+
*/
|
|
279
|
+
export interface ToolStartedNotification {
|
|
280
|
+
sessionId: string;
|
|
281
|
+
turnId: string;
|
|
282
|
+
toolCallId: string;
|
|
283
|
+
name: string;
|
|
284
|
+
args: unknown;
|
|
285
|
+
}
|
|
286
|
+
/**
|
|
287
|
+
* Parameters for the ``turn/submit`` JSON-RPC method.
|
|
288
|
+
*/
|
|
289
|
+
export interface TurnSubmitParams {
|
|
290
|
+
sessionId: string;
|
|
291
|
+
turnId: string;
|
|
292
|
+
prompt: string;
|
|
293
|
+
attachments?: {
|
|
294
|
+
[k: string]: unknown;
|
|
295
|
+
}[];
|
|
296
|
+
}
|
|
297
|
+
/**
|
|
298
|
+
* Result returned by the ``turn/submit`` JSON-RPC method.
|
|
299
|
+
*/
|
|
300
|
+
export interface TurnSubmitResult {
|
|
301
|
+
reply: string | null;
|
|
302
|
+
turnId: string;
|
|
303
|
+
sessionId: string;
|
|
304
|
+
finalEvent?: {
|
|
305
|
+
[k: string]: unknown;
|
|
306
|
+
};
|
|
307
|
+
}
|
|
308
|
+
/**
|
|
309
|
+
* Token usage and optional cost summary for a turn.
|
|
310
|
+
*/
|
|
311
|
+
export interface UsageNotification {
|
|
312
|
+
sessionId: string;
|
|
313
|
+
turnId: string;
|
|
314
|
+
inputTokens: number;
|
|
315
|
+
outputTokens: number;
|
|
316
|
+
cost?: number;
|
|
317
|
+
}
|
|
318
|
+
export type ErrorCode = "agent_not_ready" | "approval_denied" | "approval_protocol_violation" | "approval_timeout" | "approval_translation_failed" | "bundle_load_failed" | "config_validation" | "env_injection_rejected" | "internal" | "invalid_session" | "prompt_required" | "protocol_version_mismatch" | "provider_init_failed" | "provider_not_configured" | "runtime" | "session_not_found" | "spawn_failed" | "stale_session" | "tool_execution_failed" | "wire_protocol_violation";
|
package/dist/types.js
ADDED
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Protocol version check for the Amplifier Agent wrapper.
|
|
3
|
+
*
|
|
4
|
+
* checkProtocolVersion() compares the wrapper's compiled protocol version
|
|
5
|
+
* constant against the version reported by the engine binary.
|
|
6
|
+
*
|
|
7
|
+
* On mismatch it returns ok=false with a remediation hint.
|
|
8
|
+
* The check can be bypassed with allowSkew=true.
|
|
9
|
+
*/
|
|
10
|
+
/** Result when protocol versions match (or skew is allowed). */
|
|
11
|
+
export interface VersionCheckOk {
|
|
12
|
+
ok: true;
|
|
13
|
+
}
|
|
14
|
+
/** Result when protocol versions mismatch and skew is not allowed. */
|
|
15
|
+
export interface VersionCheckFail {
|
|
16
|
+
ok: false;
|
|
17
|
+
code: "protocol_version_mismatch";
|
|
18
|
+
remediation: string;
|
|
19
|
+
}
|
|
20
|
+
export type VersionCheckResult = VersionCheckOk | VersionCheckFail;
|
|
21
|
+
export interface CheckProtocolVersionOptions {
|
|
22
|
+
/** The protocol version compiled into the wrapper. */
|
|
23
|
+
wrapper: string;
|
|
24
|
+
/** The protocol version reported by the engine binary. */
|
|
25
|
+
engine: string;
|
|
26
|
+
/** If true, bypass the version check and always return ok=true. */
|
|
27
|
+
allowSkew?: boolean;
|
|
28
|
+
}
|
|
29
|
+
/**
|
|
30
|
+
* Compare wrapper and engine protocol versions.
|
|
31
|
+
*
|
|
32
|
+
* @returns VersionCheckOk if they match, or if allowSkew is true.
|
|
33
|
+
* @returns VersionCheckFail if they mismatch and allowSkew is false/unset.
|
|
34
|
+
*/
|
|
35
|
+
export declare function checkProtocolVersion(opts: CheckProtocolVersionOptions): VersionCheckResult;
|
package/dist/version.js
ADDED
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Protocol version check for the Amplifier Agent wrapper.
|
|
3
|
+
*
|
|
4
|
+
* checkProtocolVersion() compares the wrapper's compiled protocol version
|
|
5
|
+
* constant against the version reported by the engine binary.
|
|
6
|
+
*
|
|
7
|
+
* On mismatch it returns ok=false with a remediation hint.
|
|
8
|
+
* The check can be bypassed with allowSkew=true.
|
|
9
|
+
*/
|
|
10
|
+
/**
|
|
11
|
+
* Compare wrapper and engine protocol versions.
|
|
12
|
+
*
|
|
13
|
+
* @returns VersionCheckOk if they match, or if allowSkew is true.
|
|
14
|
+
* @returns VersionCheckFail if they mismatch and allowSkew is false/unset.
|
|
15
|
+
*/
|
|
16
|
+
export function checkProtocolVersion(opts) {
|
|
17
|
+
const { wrapper, engine, allowSkew = false } = opts;
|
|
18
|
+
if (allowSkew || wrapper === engine) {
|
|
19
|
+
return { ok: true };
|
|
20
|
+
}
|
|
21
|
+
return {
|
|
22
|
+
ok: false,
|
|
23
|
+
code: "protocol_version_mismatch",
|
|
24
|
+
remediation: `Protocol version mismatch: wrapper expects '${wrapper}' but engine reports '${engine}'. ` +
|
|
25
|
+
`Install a compatible engine version or set allowProtocolSkew: true / ` +
|
|
26
|
+
`AMPLIFIER_AGENT_ALLOW_PROTOCOL_SKEW=1 to allow-protocol-skew.`,
|
|
27
|
+
};
|
|
28
|
+
}
|