amplifier-agent-ts 0.6.1 → 0.6.2

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/index.d.ts CHANGED
@@ -7,7 +7,7 @@
7
7
  * environment, and constructs a `SessionHandle`. **No subprocess is spawned
8
8
  * at spawn-time** — the engine is launched per `submit()` (amendment §5.2).
9
9
  */
10
- export { AaaError, SessionHandle } from "./session.js";
10
+ export { AaaError, SessionHandle, DEFAULT_TIMEOUT_MS } 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";
@@ -109,7 +109,11 @@ export interface SpawnAgentParams {
109
109
  * priority chain.
110
110
  */
111
111
  mcpServers?: Record<string, McpServerConfig>;
112
- /** Per-submit timeout in ms (default: 10 minutes). */
112
+ /**
113
+ * Per-submit timeout in ms. No timeout is applied unless a positive value
114
+ * is provided; `undefined` or `0` disables the wall-clock hang timer.
115
+ * Pass `DEFAULT_TIMEOUT_MS` to opt into the original 10-minute cap.
116
+ */
113
117
  timeoutMs?: number;
114
118
  /**
115
119
  * Path to a host config file (Issue #1). Forwarded to the engine via
package/dist/index.js CHANGED
@@ -8,7 +8,7 @@
8
8
  * at spawn-time** — the engine is launched per `submit()` (amendment §5.2).
9
9
  */
10
10
  // Re-export public types and classes from sub-modules.
11
- export { AaaError, SessionHandle } from "./session.js";
11
+ export { AaaError, SessionHandle, DEFAULT_TIMEOUT_MS } from "./session.js";
12
12
  // ---------------------------------------------------------------------------
13
13
  // Public re-exports of wrapper internals (Issue #5).
14
14
  //
package/dist/session.d.ts CHANGED
@@ -12,7 +12,9 @@
12
12
  * cooperation).
13
13
  * 3. `{type:'result', text}` or `{type:'error', ...}` — yielded once when
14
14
  * the subprocess exits (`parseRunOutput` applied to stdout/stderr/exit)
15
- * OR when the configured `timeoutMs` elapses (synthesized `engine_hung`).
15
+ * OR when the configured `timeoutMs` (if a positive number) elapses
16
+ * (synthesized `engine_hung`). No timeout is armed when `timeoutMs` is
17
+ * `undefined` or `<= 0`.
16
18
  *
17
19
  * Lifecycle:
18
20
  * - `submit()` is one-shot per session (D10). A second call throws
@@ -146,7 +148,12 @@ export interface SessionHandleParams {
146
148
  approvalMode?: "yes" | "no" | "prompt";
147
149
  /** Protocol version the wrapper speaks (e.g. "0.3.0"). */
148
150
  protocolVersion: string;
149
- /** Per-submit timeout in milliseconds. Defaults to 10 minutes. */
151
+ /**
152
+ * Per-submit timeout in milliseconds. No timeout is applied unless a
153
+ * positive value is provided. `undefined` or `<= 0` disables the
154
+ * wall-clock hang timer entirely. Pass `DEFAULT_TIMEOUT_MS` to opt into
155
+ * the original 10-minute cap.
156
+ */
150
157
  timeoutMs?: number;
151
158
  /**
152
159
  * Optional override for the subprocess factory (Issue #3). When set, the
@@ -167,6 +174,15 @@ export interface SessionHandleParams {
167
174
  /** Bundle digest resolved at spawnAgent() time (Issue #7). */
168
175
  bundleDigest?: string;
169
176
  }
177
+ /**
178
+ * Default timeout value (10 minutes) exported for callers that want a
179
+ * wall-clock cap on individual turns. This constant is NOT applied
180
+ * automatically — pass it explicitly as `timeoutMs: DEFAULT_TIMEOUT_MS`
181
+ * to opt into the 10-minute limit.
182
+ *
183
+ * @public
184
+ */
185
+ export declare const DEFAULT_TIMEOUT_MS: number;
170
186
  /**
171
187
  * Wait for `child` to fire `exit`, or `ms` to elapse — whichever first.
172
188
  *
@@ -201,9 +217,9 @@ export declare class SessionHandle {
201
217
  * (iv) SC-B: spawn with `detached:true` so PID == PGID for group signals;
202
218
  * (v) accumulate stdout/stderr from chunks;
203
219
  * (vi) start a 2s activity ticker → queue;
204
- * (vii) race `exitPromise` vs `timeoutPromise`;
205
- * on timeout: cancel(), synthesize `engine_hung`;
206
- * on exit: parseRunOutput({stdout, stderr, exitCode});
220
+ * (vii) race `exitPromise` vs `timeoutPromise` (timer only armed when
221
+ * `timeoutMs > 0`); on timeout: cancel(), synthesize `engine_hung`;
222
+ * on exit: parseRunOutput({stdout, stderr, exitCode});
207
223
  * (viii) cleanup spill file after exit;
208
224
  * (ix) drain queue until the final event is yielded.
209
225
  */
package/dist/session.js CHANGED
@@ -12,7 +12,9 @@
12
12
  * cooperation).
13
13
  * 3. `{type:'result', text}` or `{type:'error', ...}` — yielded once when
14
14
  * the subprocess exits (`parseRunOutput` applied to stdout/stderr/exit)
15
- * OR when the configured `timeoutMs` elapses (synthesized `engine_hung`).
15
+ * OR when the configured `timeoutMs` (if a positive number) elapses
16
+ * (synthesized `engine_hung`). No timeout is armed when `timeoutMs` is
17
+ * `undefined` or `<= 0`.
16
18
  *
17
19
  * Lifecycle:
18
20
  * - `submit()` is one-shot per session (D10). A second call throws
@@ -48,8 +50,15 @@ export class AaaError extends Error {
48
50
  }
49
51
  }
50
52
  }
51
- /** Default subprocess timeout: 10 minutes. */
52
- const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
53
+ /**
54
+ * Default timeout value (10 minutes) exported for callers that want a
55
+ * wall-clock cap on individual turns. This constant is NOT applied
56
+ * automatically — pass it explicitly as `timeoutMs: DEFAULT_TIMEOUT_MS`
57
+ * to opt into the 10-minute limit.
58
+ *
59
+ * @public
60
+ */
61
+ export const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
53
62
  /** Activity ticker interval: 2 seconds (NC stuck-detection has 10s threshold). */
54
63
  const ACTIVITY_TICK_MS = 2000;
55
64
  /** Grace window between SIGTERM and SIGKILL in `cancel()`. */
@@ -131,9 +140,9 @@ export class SessionHandle {
131
140
  * (iv) SC-B: spawn with `detached:true` so PID == PGID for group signals;
132
141
  * (v) accumulate stdout/stderr from chunks;
133
142
  * (vi) start a 2s activity ticker → queue;
134
- * (vii) race `exitPromise` vs `timeoutPromise`;
135
- * on timeout: cancel(), synthesize `engine_hung`;
136
- * on exit: parseRunOutput({stdout, stderr, exitCode});
143
+ * (vii) race `exitPromise` vs `timeoutPromise` (timer only armed when
144
+ * `timeoutMs > 0`); on timeout: cancel(), synthesize `engine_hung`;
145
+ * on exit: parseRunOutput({stdout, stderr, exitCode});
137
146
  * (viii) cleanup spill file after exit;
138
147
  * (ix) drain queue until the final event is yielded.
139
148
  */
@@ -243,27 +252,32 @@ export class SessionHandle {
243
252
  if (!finalized)
244
253
  push({ type: "activity" });
245
254
  }, ACTIVITY_TICK_MS);
246
- // (vii) race exit vs timeout.
247
- const timeoutMs = this.params.timeoutMs ?? DEFAULT_TIMEOUT_MS;
248
- const timeoutHandle = setTimeout(() => {
249
- // Synthesize engine_hung before invoking cancel(), so the iterator
250
- // yields a terminal error even if SIGTERM/SIGKILL hangs.
251
- const tail = stderrTailOf(stderrBuf);
252
- finalize({
253
- type: "error",
254
- code: "engine_hung",
255
- classification: "engine",
256
- severity: "error",
257
- correlationId: "",
258
- message: `Engine subprocess hung past ${timeoutMs}ms timeout; SIGTERM/SIGKILL escalation invoked.`,
259
- ...(tail !== undefined ? { stderrTail: tail } : {}),
260
- retryable: false,
261
- });
262
- // Fire-and-forget: cancel races the next event-loop turn.
263
- void this.cancel();
264
- }, timeoutMs);
255
+ // (vii) race exit vs timeout (timer only armed when timeoutMs is a positive
256
+ // number; undefined/0/negative means no timeout is applied).
257
+ const timeoutMs = this.params.timeoutMs;
258
+ let timeoutHandle = null;
259
+ if (timeoutMs !== undefined && timeoutMs > 0) {
260
+ timeoutHandle = setTimeout(() => {
261
+ // Synthesize engine_hung before invoking cancel(), so the iterator
262
+ // yields a terminal error even if SIGTERM/SIGKILL hangs.
263
+ const tail = stderrTailOf(stderrBuf);
264
+ finalize({
265
+ type: "error",
266
+ code: "engine_hung",
267
+ classification: "engine",
268
+ severity: "error",
269
+ correlationId: "",
270
+ message: `Engine subprocess hung past ${timeoutMs}ms timeout; SIGTERM/SIGKILL escalation invoked.`,
271
+ ...(tail !== undefined ? { stderrTail: tail } : {}),
272
+ retryable: false,
273
+ });
274
+ // Fire-and-forget: cancel races the next event-loop turn.
275
+ void this.cancel();
276
+ }, timeoutMs);
277
+ }
265
278
  child.once("exit", (code, _signal) => {
266
- clearTimeout(timeoutHandle);
279
+ if (timeoutHandle !== null)
280
+ clearTimeout(timeoutHandle);
267
281
  if (finalized)
268
282
  return;
269
283
  const ev = parseRunOutput({
@@ -277,7 +291,8 @@ export class SessionHandle {
277
291
  // as transport-class failures; the test suite covers spawn-rejection at
278
292
  // this seam (binary missing → typed AaaError-shaped DisplayEvent).
279
293
  child.once("error", (err) => {
280
- clearTimeout(timeoutHandle);
294
+ if (timeoutHandle !== null)
295
+ clearTimeout(timeoutHandle);
281
296
  if (finalized)
282
297
  return;
283
298
  const tail = stderrTailOf(stderrBuf);
@@ -311,7 +326,8 @@ export class SessionHandle {
311
326
  finally {
312
327
  // (viii) cleanup ticker + spill file on every exit path.
313
328
  clearInterval(ticker);
314
- clearTimeout(timeoutHandle);
329
+ if (timeoutHandle !== null)
330
+ clearTimeout(timeoutHandle);
315
331
  await cleanupSpillFile(this.mcpSpillPath);
316
332
  this.mcpSpillPath = null;
317
333
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "amplifier-agent-ts",
3
- "version": "0.6.1",
3
+ "version": "0.6.2",
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": {