nuabase 3.0.1 → 3.1.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # nuabase
 
+## 3.1.0
+
+### Minor Changes
+
+- 8fdf585: `startAgentSession()` takes `env`, the environment `open` runs in on macOS, and `unsetEnv`, names the launcher unsets before starting the agent. A terminal app that `open` launches keeps `open`'s environment for every later window, so before this a server's own settings reached the user's other terminal sessions. It throws a `TypeError` for an `unsetEnv` entry that isn't a shell variable name.
+- 3700318: `nua.get()` and `nua.list()` take `signal`, an `AbortSignal` that cancels the call. A local agent's process is stopped, SIGINT then SIGKILL 2 seconds later, and the call returns once the process has exited. A call still waiting for a free agent process leaves the queue without starting one. A provider request is aborted. A cancelled call is not retried and fails with `cancelled: true`, a new field of every failed result.
+  
+  A local agent stopped by `timeoutMs` or `idleTimeoutMs` now also says how much it had printed and, for `timeoutMs`, how long before the stop it last printed, which tells a slow agent from a stuck one.
+- a7054ac: Local agents: `onOutput`, an option of `nua.get()` and `nua.list()`, passes on everything the agent prints while that call runs, unparsed, so an app can show its progress as a log. `idleTimeoutMs` stops an agent that prints nothing for 2 minutes (Claude Code and Pi; Codex has no idle limit, since it is quiet while it reasons), and `timeoutMs` now defaults to 10 minutes instead of 3. A timeout says which limit was hit, after how long, how to raise it, and the end of the agent's stderr. Claude Code now runs with `--output-format stream-json`, so it prints while it works; only its final result line is read.
+  
+  Also changed:
+  
+  - `timeoutMs` and `idleTimeoutMs` must be from 1 to 2147483647 ms (or `null` for no idle limit); `localAgent()`, `findLocalAgent()` and `with()` throw a `TypeError` otherwise. Before, a value such as `0`, `NaN` or `Infinity` stopped the agent at once.
+  - In `agent.with()`, a `timeoutMs` given as `undefined` now resets to the default, as every other option does, instead of keeping the agent's.
+  - `findLocalAgent()` reports an invalid option only once it has found an agent, not before it looks.
+- 36ce67b: Add `localAgentSetupGuide()` to `nuabase/local-agent`: plain text an app shows a user with no coding agent set up, saying the agent must be the CLI, how to install and sign in to each supported one, and a prompt that has a desktop or browser agent install one.
+
+### Patch Changes
+
+- de8f585: A headless Codex call turns off Codex's shell, its ChatGPT apps connector, plugins, image viewing and web search. In the read-only sandbox the shell could still read any file and the caller's environment, and the apps connector could browse the web and change the account, so a prompt carrying an injected instruction could reach them. Codex 0.154 accepts these feature names; an older Codex that lacks one fails the call with "Unknown feature flag".
+
 ## 3.0.1
 
 ### Patch Changes

package/README.md

@@ -110,6 +110,8 @@ if (address.success) console.log(address.data); // z.infer<typeof AddressSchema>
 * `input?: unknown` – Context or data to include with the prompt.
 * `output: { name: string; schema: ZodSchema }` – Identifier and Zod schema for the output.
 * `model?: ModelInput` – Override the client's default model for this call.
+* `onOutput?: (chunk, stream) => void` – On a local agent, gets everything the agent prints while this call runs, unparsed, as it arrives (`stream` is `'stdout'` or `'stderr'`), to show as a log. Chunks don't follow line boundaries, and a retry's output follows the earlier attempt's. Provider APIs print nothing, so it is never called.
+* `signal?: AbortSignal` – Cancels the call: a local agent's process is stopped (SIGINT, then SIGKILL 2 seconds later) and a provider request is aborted. A call waiting for a free agent process leaves the queue. The call then fails with `cancelled: true` and is not retried.
 
 ### `nua.list(prompt, options)`
 
@@ -133,6 +135,8 @@ if (result.success) {
 * `primaryKey: string` – Unique key on each input object. Each output row carries it, so you can match rows to inputs.
 * `output: { name: string; schema: ZodSchema }` – Property name and Zod schema attached to each returned row.
 * `model?: ModelInput` – Override the client's default model for this call.
+* `onOutput?: (chunk, stream) => void` – As for `get()`.
+* `signal?: AbortSignal` – As for `get()`.
 
 ---
 
@@ -210,12 +214,13 @@ const agents = await detectLocalAgents();
 | `binaryPath` | `string` | Looked up on `PATH` | Path to executable (`localAgent` only). On Windows, point to a native executable (`.cmd` shims are not supported). |
 | `model` | `string` | Agent's default | The agent's own model name for calls that name no model. Claude Code accepts aliases (`'haiku'`, `'sonnet'`, `'opus'`), and so does a per-call `model: { alias }`. Codex and Pi have no aliases: Codex uses its own model names; Pi uses `'provider/id'` (e.g., `'openrouter/z-ai/glm-5.3-flash'`). |
 | `effort` | `'low' \| 'medium' \| 'high'` | Agent's default | How hard the model thinks, as the CLI's own setting: Claude Code `--effort`, Codex `model_reasoning_effort`, Pi `--thinking`. |
-| `timeoutMs` | `number` | `180000` | Maximum execution time per call in milliseconds. |
+| `timeoutMs` | `number` | `600000` | Maximum execution time per call in milliseconds, from 1 to 2147483647. |
+| `idleTimeoutMs` | `number \| null` | `120000`; none for Codex | Stops the agent when it prints nothing for this many milliseconds (1 to 2147483647), so a stuck agent fails early and a slow one still finishes. `null` for no limit. Codex has none by default: it prints nothing while it reasons. |
 | `concurrency` | `number` | `2` | Maximum concurrent agent processes. |
 | `auth` | `'subscription' \| 'inherit'` | `'subscription'` | `'subscription'` strips env vars like `ANTHROPIC_API_KEY` and `OPENAI_API_KEY` so calls bill your logged-in plan instead of API keys. |
 | `logger` | object | `console` | Object with `debug`, `info`, `warn`, and `error` methods for call and retry logs. |
 
-`agent.with({ model, effort, timeoutMs })` returns the same agent with other call options. It shares the agent's executable, environment, logger and `concurrency` limit, so one `localAgent()` per CLI can serve casts on several of its models without running more processes at once than the limit allows. Options left out keep the agent's; a `model` or `effort` given as `undefined` is the CLI's default.
+`agent.with({ model, effort, timeoutMs, idleTimeoutMs })` returns the same agent with other call options. It shares the agent's executable, environment, logger and `concurrency` limit, so one `localAgent()` per CLI can serve casts on several of its models without running more processes at once than the limit allows. Options left out keep the agent's; an option given as `undefined` takes its default.
 
 ```ts
 const codex = localAgent({ agent: 'codex', concurrency: 2 });
@@ -224,6 +229,16 @@ const careful = Nua.direct({ localAgent: codex.with({ model: 'gpt-5.6-sol', time
 // Both run on the same two processes at most.
 ```
 
+To show a call's progress, pass `onOutput` with the call. What the agent prints is its own JSON lines, which nuabase passes on as they are:
+
+```ts
+const result = await nua.get(prompt, { output: { name: 'chart', schema }, onOutput: (chunk) => res.write(chunk) });
+```
+
+> **Note:** This sends the agent's output to the browser unfiltered: its reasoning, the prompt and input data it echoes, and details of the machine it runs on, such as working directories and how it is logged in. That suits a local-first app, where the server, the agent and the browser are all on the user's own machine and the user is the only one watching. A server that others reach should filter the output, or show only progress such as a count of characters, before passing it on.
+
+When a call is stopped by `timeoutMs` or `idleTimeoutMs`, its error says which limit stopped it, how much the agent had printed and when it last printed, so a slow agent can be told from a stuck one. A call stopped by either limit is not retried, so `timeoutMs` bounds how long it runs. A transient failure is retried, and each attempt may take up to `timeoutMs`.
+
 > **Note:** Local agent calls count against your personal subscription limits. Check each vendor's terms before exposing local-agent execution to end users.
 
 ### Interactive Agent Sessions (Node.js only)
@@ -258,7 +273,9 @@ switch (session.kind) {
 
 It writes the prompt to its own file (`0600`) and a launcher (`0700`) that passes it to the agent as one argument after `--`. Quotes, backticks and `$NAMES` in the prompt reach the agent as written, and the prompt can't set the agent's flags or run commands. Neither file is ever overwritten or deleted. On macOS the launcher opens in a new window of the user's terminal app (`open`, which needs no Automation permission).
 
-Expected failures come back as `kind: 'refused'`, with nothing written: Windows, which can't run the launcher (`unsupported_platform`); a prompt of 128 KiB or more on Linux, which caps a single argument at that size (`prompt_too_long`); and an agent that isn't on `PATH` when no `binaryPath` is given (`agent_not_found`). It throws only for an unknown `agent` or a `name` already used.
+Expected failures come back as `kind: 'refused'`, with nothing written: Windows, which can't run the launcher (`unsupported_platform`); a prompt of 128 KiB or more on Linux, which caps a single argument at that size (`prompt_too_long`); and an agent that isn't on `PATH` when no `binaryPath` is given (`agent_not_found`). It throws only for an unknown `agent`, an `unsetEnv` entry that isn't a shell variable name, or a `name` already used.
+
+On macOS, `open` passes its environment to a terminal app it launches, and every later window of that app inherits it. A server whose environment holds its own settings (ports, secrets, a data directory) passes `env` without them, so they don't reach the user's other terminal sessions, and `unsetEnv` with their names, so the launcher unsets them in a terminal that already holds them.
 
 `agentSessionMode(platform?)` says beforehand how a session would start, for showing the right button: `'terminal'` on macOS, `'command'` on other POSIX systems, `'none'` on Windows.
 
@@ -273,6 +290,8 @@ Expected failures come back as `kind: 'refused'`, with nothing written: Windows,
 | `dir` | `string` | Required | Where both files are written. Created if missing. |
 | `name` | `string` | `<UTC time>-<agent>-<4 hex digits>` | The files' name without extension. Neither file may exist yet. |
 | `platform` | `NodeJS.Platform` | `process.platform` | The platform the launcher is for. |
+| `env` | `NodeJS.ProcessEnv` | `process.env` | The environment `open` runs in on macOS, which a terminal app it launches keeps for every window. |
+| `unsetEnv` | `string[]` | None | Variables the launcher unsets before starting the agent. |
 
 ---
 
@@ -311,6 +330,7 @@ The call rejects (throws) only for invalid arguments, before anything is sent: a
 | --- | --- | --- |
 | `success` | `false` | Request failed (see retries below). |
 | `error` | `string` | Error description. |
+| `cancelled` | `boolean` | `true` when the call's `signal` cancelled it. |
 | `source` | `'direct'` | Indicates the request executed in-process. |
 | `latencyMs` | `number` | Time elapsed until failure in milliseconds. |
 

package/dist/chunks/{local-agent-Bj-QKikS.d.cts → local-agent-CPIXKS41.d.cts}

@@ -76,8 +76,9 @@ type AttemptFailure = {
      * - transient: another attempt may succeed.
      * - fatal: every attempt will fail the same way (bad API key, not logged in, out of quota, timed out).
      * - schema-rejected: the engine refused the native schema; the in-prompt prompt may still work.
+     * - cancelled: the caller's signal aborted it.
      */
-    kind: "transient" | "fatal" | "schema-rejected";
+    kind: "transient" | "fatal" | "schema-rejected" | "cancelled";
     message: string;
 };
 type AttemptOutcome = {
@@ -89,6 +90,20 @@ type AttemptOutcome = {
     kind: "failed";
     failure: AttemptFailure;
 };
+/**
+ * Gets what an engine prints while it answers, unparsed, as it arrives: a
+ * coding agent's own output, to show as a log while a call runs. Chunks are
+ * UTF-8 text that doesn't follow line boundaries; a retry's output follows the
+ * earlier attempt's. Engines that print nothing, such as LLM providers' APIs,
+ * never call it.
+ */
+type EngineOutputListener = (chunk: string, stream: "stdout" | "stderr") => void;
+/** What one cast's caller hands each of its attempts. */
+type AttemptControls = {
+    onOutput?: EngineOutputListener;
+    /** Cancels the attempt: an agent process is stopped, an HTTP request aborted. */
+    signal?: AbortSignal;
+};
 /**
  * Answers prompts on one model: an LLM provider's HTTP API, or a coding-agent
  * CLI on this machine. Expected failures come back as outcomes, not exceptions.
@@ -96,7 +111,7 @@ type AttemptOutcome = {
 interface LlmEngine {
     /** The envelope schema in the form this engine enforces natively, or null if it cannot. */
     nativeSchema(envelopeSchema: JsonSchema): JsonSchema | null;
-    attempt(request: AttemptRequest): Promise<AttemptOutcome>;
+    attempt(request: AttemptRequest, controls?: AttemptControls): Promise<AttemptOutcome>;
 }
 
 type ProviderModel = {
@@ -145,10 +160,27 @@ type AgentProcessResult = {
     exitCode: number | null;
     stdout: string;
     stderr: string;
-    timedOut: boolean;
+    /** Why the process was stopped before it finished; null when it wasn't. */
+    stopped: AgentProcessStop | null;
     /** Contents of the requested output files; undefined when a file was not written. */
     outputFiles: Record<string, string | undefined>;
 };
+/**
+ * What stopped a process: the limit on the whole run ("total") or on going
+ * quiet ("idle"), which was `limitMs`, or the caller's AbortSignal ("signal").
+ */
+type AgentProcessStopCause = {
+    by: "total" | "idle";
+    limitMs: number;
+} | {
+    by: "signal";
+};
+/** What stopped a process, and when, in milliseconds from its start. */
+type AgentProcessStop = AgentProcessStopCause & {
+    afterMs: number;
+    /** When it last printed; null when it printed nothing. */
+    lastOutputAtMs: number | null;
+};
 /** What an agent's output says about one attempt. */
 type AgentReply = {
     kind: "answered";
@@ -192,6 +224,11 @@ interface AgentAdapter {
     binaryName: string;
     /** Env vars that would make the CLI bill an API key instead of the user's subscription. */
     apiKeyEnvVars: string[];
+    /**
+     * How long the CLI may print nothing before it counts as stuck, or null when
+     * it can be quiet for long stretches while working, as Codex is while it reasons.
+     */
+    idleTimeoutMs: number | null;
     /** The CLI's own model name for each model alias it has an equivalent for. */
     modelAliases: Partial<Record<ModelAliasName, string>>;
     /** The envelope schema in the form this CLI accepts, or null if it can't enforce it. */
@@ -214,7 +251,10 @@ declare class Semaphore {
     private active;
     private readonly waiting;
     constructor(limit: number);
-    run<T>(task: () => Promise<T>): Promise<T>;
+    /** Rejects with the signal's reason, without running `task`, when `signal` aborts while it waits. */
+    run<T>(task: () => Promise<T>, signal?: AbortSignal): Promise<T>;
+    /** Resolves once a finishing task hands over its place. */
+    private waitForTurn;
 }
 
 /** How to run one installed agent's processes. Set up once and shared by all its engines. */
@@ -227,16 +267,21 @@ type AgentRunner = {
     limiter: Semaphore;
     logger: Logger;
 };
-/** How one engine's attempts run: the CLI's options and how long each may take. */
-type AgentCall = AgentCallOptions & {
-    /** Per-attempt limit. */
-    timeoutMs: number;
-};
 
-/** What `LocalAgent.with()` changes: how its casts run, not which processes run them. */
+/**
+ * How a local agent's casts run, not which processes run them: what
+ * localAgent() sets and `LocalAgent.with()` changes. An option left out, or
+ * given as undefined, takes its default.
+ */
 type LocalAgentCallOptions = AgentCallOptions & {
-    /** Per-call limit in milliseconds. */
+    /** Per-call limit in milliseconds. Defaults to 600000. */
     timeoutMs?: number;
+    /**
+     * How long, in milliseconds, the agent may print nothing before it is
+     * stopped as stuck; null for no limit. Defaults to the agent's own limit,
+     * which is none for an agent that is quiet while it works.
+     */
+    idleTimeoutMs?: number | null;
 };
 /**
  * A coding-agent CLI on this machine, set up once and ready to run casts.
@@ -244,18 +289,15 @@ type LocalAgentCallOptions = AgentCallOptions & {
  */
 declare class LocalAgent implements EngineRouter {
     private readonly runner;
-    /** How calls that name no model run. */
-    private readonly call;
     readonly agent: LocalAgentId;
     readonly logger: Logger;
-    constructor(runner: AgentRunner, 
     /** How calls that name no model run. */
-    call: AgentCall);
+    private readonly call;
+    constructor(runner: AgentRunner, options: LocalAgentCallOptions);
     /**
      * The same agent with other call options, sharing this one's executable,
      * environment, logger and limit on processes running at once. Options left
-     * out keep this agent's; a model or effort given as undefined is the CLI's
-     * default.
+     * out keep this agent's; an option given as undefined takes its default.
      */
     with(options: LocalAgentCallOptions): LocalAgent;
     /**
@@ -266,5 +308,5 @@ declare class LocalAgent implements EngineRouter {
     private routeTo;
 }
 
-export { LocalAgent as a, LOCAL_AGENT_IDS as f, isLocalAgentId as i };
-export type { AnswerOrigin as A, LlmProviderId as L, ModelInput as M, NormalizedUsage as N, SchemaEnforcementKind as S, LocalAgentId as b, AgentEffort as c, Logger as d, SessionApproval as e, LocalAgentCallOptions as g };
+export { LocalAgent as a, LOCAL_AGENT_IDS as g, isLocalAgentId as i };
+export type { AnswerOrigin as A, EngineOutputListener as E, LlmProviderId as L, ModelInput as M, NormalizedUsage as N, SchemaEnforcementKind as S, LocalAgentId as b, LocalAgentCallOptions as c, Logger as d, SessionApproval as e, AgentEffort as f };

package/dist/chunks/{local-agent-Bj-QKikS.d.mts → local-agent-CPIXKS41.d.mts}

@@ -76,8 +76,9 @@ type AttemptFailure = {
      * - transient: another attempt may succeed.
      * - fatal: every attempt will fail the same way (bad API key, not logged in, out of quota, timed out).
      * - schema-rejected: the engine refused the native schema; the in-prompt prompt may still work.
+     * - cancelled: the caller's signal aborted it.
      */
-    kind: "transient" | "fatal" | "schema-rejected";
+    kind: "transient" | "fatal" | "schema-rejected" | "cancelled";
     message: string;
 };
 type AttemptOutcome = {
@@ -89,6 +90,20 @@ type AttemptOutcome = {
     kind: "failed";
     failure: AttemptFailure;
 };
+/**
+ * Gets what an engine prints while it answers, unparsed, as it arrives: a
+ * coding agent's own output, to show as a log while a call runs. Chunks are
+ * UTF-8 text that doesn't follow line boundaries; a retry's output follows the
+ * earlier attempt's. Engines that print nothing, such as LLM providers' APIs,
+ * never call it.
+ */
+type EngineOutputListener = (chunk: string, stream: "stdout" | "stderr") => void;
+/** What one cast's caller hands each of its attempts. */
+type AttemptControls = {
+    onOutput?: EngineOutputListener;
+    /** Cancels the attempt: an agent process is stopped, an HTTP request aborted. */
+    signal?: AbortSignal;
+};
 /**
  * Answers prompts on one model: an LLM provider's HTTP API, or a coding-agent
  * CLI on this machine. Expected failures come back as outcomes, not exceptions.
@@ -96,7 +111,7 @@ type AttemptOutcome = {
 interface LlmEngine {
     /** The envelope schema in the form this engine enforces natively, or null if it cannot. */
     nativeSchema(envelopeSchema: JsonSchema): JsonSchema | null;
-    attempt(request: AttemptRequest): Promise<AttemptOutcome>;
+    attempt(request: AttemptRequest, controls?: AttemptControls): Promise<AttemptOutcome>;
 }
 
 type ProviderModel = {
@@ -145,10 +160,27 @@ type AgentProcessResult = {
     exitCode: number | null;
     stdout: string;
     stderr: string;
-    timedOut: boolean;
+    /** Why the process was stopped before it finished; null when it wasn't. */
+    stopped: AgentProcessStop | null;
     /** Contents of the requested output files; undefined when a file was not written. */
     outputFiles: Record<string, string | undefined>;
 };
+/**
+ * What stopped a process: the limit on the whole run ("total") or on going
+ * quiet ("idle"), which was `limitMs`, or the caller's AbortSignal ("signal").
+ */
+type AgentProcessStopCause = {
+    by: "total" | "idle";
+    limitMs: number;
+} | {
+    by: "signal";
+};
+/** What stopped a process, and when, in milliseconds from its start. */
+type AgentProcessStop = AgentProcessStopCause & {
+    afterMs: number;
+    /** When it last printed; null when it printed nothing. */
+    lastOutputAtMs: number | null;
+};
 /** What an agent's output says about one attempt. */
 type AgentReply = {
     kind: "answered";
@@ -192,6 +224,11 @@ interface AgentAdapter {
     binaryName: string;
     /** Env vars that would make the CLI bill an API key instead of the user's subscription. */
     apiKeyEnvVars: string[];
+    /**
+     * How long the CLI may print nothing before it counts as stuck, or null when
+     * it can be quiet for long stretches while working, as Codex is while it reasons.
+     */
+    idleTimeoutMs: number | null;
     /** The CLI's own model name for each model alias it has an equivalent for. */
     modelAliases: Partial<Record<ModelAliasName, string>>;
     /** The envelope schema in the form this CLI accepts, or null if it can't enforce it. */
@@ -214,7 +251,10 @@ declare class Semaphore {
     private active;
     private readonly waiting;
     constructor(limit: number);
-    run<T>(task: () => Promise<T>): Promise<T>;
+    /** Rejects with the signal's reason, without running `task`, when `signal` aborts while it waits. */
+    run<T>(task: () => Promise<T>, signal?: AbortSignal): Promise<T>;
+    /** Resolves once a finishing task hands over its place. */
+    private waitForTurn;
 }
 
 /** How to run one installed agent's processes. Set up once and shared by all its engines. */
@@ -227,16 +267,21 @@ type AgentRunner = {
     limiter: Semaphore;
     logger: Logger;
 };
-/** How one engine's attempts run: the CLI's options and how long each may take. */
-type AgentCall = AgentCallOptions & {
-    /** Per-attempt limit. */
-    timeoutMs: number;
-};
 
-/** What `LocalAgent.with()` changes: how its casts run, not which processes run them. */
+/**
+ * How a local agent's casts run, not which processes run them: what
+ * localAgent() sets and `LocalAgent.with()` changes. An option left out, or
+ * given as undefined, takes its default.
+ */
 type LocalAgentCallOptions = AgentCallOptions & {
-    /** Per-call limit in milliseconds. */
+    /** Per-call limit in milliseconds. Defaults to 600000. */
     timeoutMs?: number;
+    /**
+     * How long, in milliseconds, the agent may print nothing before it is
+     * stopped as stuck; null for no limit. Defaults to the agent's own limit,
+     * which is none for an agent that is quiet while it works.
+     */
+    idleTimeoutMs?: number | null;
 };
 /**
  * A coding-agent CLI on this machine, set up once and ready to run casts.
@@ -244,18 +289,15 @@ type LocalAgentCallOptions = AgentCallOptions & {
  */
 declare class LocalAgent implements EngineRouter {
     private readonly runner;
-    /** How calls that name no model run. */
-    private readonly call;
     readonly agent: LocalAgentId;
     readonly logger: Logger;
-    constructor(runner: AgentRunner, 
     /** How calls that name no model run. */
-    call: AgentCall);
+    private readonly call;
+    constructor(runner: AgentRunner, options: LocalAgentCallOptions);
     /**
      * The same agent with other call options, sharing this one's executable,
      * environment, logger and limit on processes running at once. Options left
-     * out keep this agent's; a model or effort given as undefined is the CLI's
-     * default.
+     * out keep this agent's; an option given as undefined takes its default.
      */
     with(options: LocalAgentCallOptions): LocalAgent;
     /**
@@ -266,5 +308,5 @@ declare class LocalAgent implements EngineRouter {
     private routeTo;
 }
 
-export { LocalAgent as a, LOCAL_AGENT_IDS as f, isLocalAgentId as i };
-export type { AnswerOrigin as A, LlmProviderId as L, ModelInput as M, NormalizedUsage as N, SchemaEnforcementKind as S, LocalAgentId as b, AgentEffort as c, Logger as d, SessionApproval as e, LocalAgentCallOptions as g };
+export { LocalAgent as a, LOCAL_AGENT_IDS as g, isLocalAgentId as i };
+export type { AnswerOrigin as A, EngineOutputListener as E, LlmProviderId as L, ModelInput as M, NormalizedUsage as N, SchemaEnforcementKind as S, LocalAgentId as b, LocalAgentCallOptions as c, Logger as d, SessionApproval as e, AgentEffort as f };

package/dist/cjs/index.cjs

@@ -294,21 +294,27 @@ function renderPrompt(cast, enforcement) {
 }
 
 function refusedCast(reason) {
-  return { success: false, error: reason, reason, attempts: 0 };
+  return { success: false, error: reason, reason, attempts: 0, cancelled: false };
 }
 const RETRY_DELAYS_MS = [1e3, 2e3];
 const MAX_ATTEMPTS = RETRY_DELAYS_MS.length + 1;
-async function runCast(engine, request, logger) {
+async function runCast(engine, request, logger, controls = {}) {
   const validate = validatorFor(request.schema);
   let plan = planAttempt(request, chooseEnforcement(engine, request.jsonSchema));
   let lastFailure = { error: "", prompt: plan.prompt };
   for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
-    const outcome = await engine.attempt({
-      prompt: plan.prompt.full,
-      reusablePrefix: plan.prompt.reusablePrefix,
-      maxTokens: request.maxTokens,
-      enforcement: plan.enforcement
-    });
+    if (controls.signal?.aborted) {
+      return cancelledCast(attempt - 1, attempt > 1 ? lastFailure.prompt : void 0);
+    }
+    const outcome = await engine.attempt(
+      {
+        prompt: plan.prompt.full,
+        reusablePrefix: plan.prompt.reusablePrefix,
+        maxTokens: request.maxTokens,
+        enforcement: plan.enforcement
+      },
+      controls
+    );
     const verdict = judgeOutcome(outcome, validate);
     if (verdict.kind === "accept") {
       return {
@@ -321,7 +327,17 @@ async function runCast(engine, request, logger) {
       };
     }
     if (verdict.kind === "give-up") {
-      return { success: false, error: verdict.error, reason: verdict.error, attempts: attempt, prompt: plan.prompt };
+      return {
+        success: false,
+        error: verdict.error,
+        reason: verdict.error,
+        attempts: attempt,
+        cancelled: false,
+        prompt: plan.prompt
+      };
+    }
+    if (verdict.kind === "cancelled") {
+      return cancelledCast(attempt, plan.prompt);
     }
     lastFailure = { error: verdict.error, prompt: plan.prompt };
     if (verdict.kind === "retry-in-prompt") {
@@ -335,7 +351,7 @@ async function runCast(engine, request, logger) {
     if (attempt < MAX_ATTEMPTS) {
       const delayMs = RETRY_DELAYS_MS[attempt - 1];
       logger.warn("LLM call attempt failed; retrying", { attempt, delayMs, error: verdict.error });
-      await delay(delayMs);
+      await delay(delayMs, controls.signal);
     }
   }
   return {
@@ -343,6 +359,7 @@ async function runCast(engine, request, logger) {
     error: `LLM call failed after ${MAX_ATTEMPTS} attempts. Last error: ${lastFailure.error}`,
     reason: lastFailure.error,
     attempts: MAX_ATTEMPTS,
+    cancelled: false,
     prompt: lastFailure.prompt
   };
 }
@@ -387,6 +404,8 @@ function verdictForFailure(failure) {
       return { kind: "retry-in-prompt", error: failure.message };
     case "fatal":
       return { kind: "give-up", error: failure.message };
+    case "cancelled":
+      return { kind: "cancelled" };
   }
 }
 function readAnswer(answer) {
@@ -422,8 +441,20 @@ function readStructuredAnswer(envelope) {
 function errorMessage(error) {
   return error instanceof Error ? error.message : String(error);
 }
-function delay(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+function cancelledCast(attempts, prompt) {
+  const reason = "The call was cancelled.";
+  return { success: false, error: reason, reason, attempts, cancelled: true, prompt };
+}
+function delay(ms, signal) {
+  return new Promise((resolve) => {
+    const done = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", done);
+      resolve();
+    };
+    const timer = setTimeout(done, ms);
+    signal?.addEventListener("abort", done, { once: true });
+  });
 }
 
 const DEFAULT_MAX_TOKENS = 4096;
@@ -446,7 +477,10 @@ class NuaLlmClient {
       jsonSchema,
       maxTokens: params.maxTokens ?? DEFAULT_MAX_TOKENS
     };
-    return runCast(route.engine, request, this.engines.logger);
+    return runCast(route.engine, request, this.engines.logger, {
+      onOutput: params.onOutput,
+      signal: params.signal
+    });
   }
   async castArray(params) {
     const { primaryKey, outputName, schema } = params.output;
@@ -469,7 +503,10 @@ class NuaLlmClient {
       jsonSchema,
       maxTokens: params.maxTokens ?? DEFAULT_MAX_TOKENS
     };
-    return runCast(route.engine, request, this.engines.logger);
+    return runCast(route.engine, request, this.engines.logger, {
+      onOutput: params.onOutput,
+      signal: params.signal
+    });
   }
 }
 
@@ -904,7 +941,8 @@ async function callProvider(call, logger) {
     const response = await fetch(request.url, {
       method,
       headers: request.headers ?? {},
-      body: toFetchableBody(request.body)
+      body: toFetchableBody(request.body),
+      signal: call.signal
     });
     status = response.status;
     const reply = await call.parseResponse(response);
@@ -950,7 +988,7 @@ class HttpEngine {
     if (!providerConfigs[provider].strictSchemaModels?.has(model)) return null;
     return strictJsonSchema.toStrictSchema(envelopeSchema);
   }
-  async attempt(request) {
+  async attempt(request, { signal } = {}) {
     const { provider, model, apiKey } = this.target;
     const config = providerConfigs[provider];
     const responseSchema = request.enforcement.kind === "native" ? request.enforcement.schema : void 0;
@@ -971,11 +1009,15 @@ class HttpEngine {
         ),
         parseResponse: config.parseResponse,
         responseLength: (reply) => reply.text.length,
-        usage: (reply) => reply.usage
+        usage: (reply) => reply.usage,
+        signal
       },
       this.logger
     );
     if (call.kind === "failed") {
+      if (signal?.aborted) {
+        return { kind: "failed", failure: { kind: "cancelled", message: "The call was cancelled." } };
+      }
       return { kind: "failed", failure: failureForStatus(call.status, call.message, responseSchema !== void 0) };
     }
     const answer = responseSchema ? readEnvelope(call.reply.text) : { kind: "text", text: call.reply.text };
@@ -1078,7 +1120,9 @@ class Nua {
     const result = await this.client.castValue({
       model: options?.model,
       input: { prompt, data: options?.input ?? null },
-      output: { name: outputName, schema: outputSchema }
+      output: { name: outputName, schema: outputSchema },
+      onOutput: options?.onOutput,
+      signal: options?.signal
     });
     return toDirectResult(result, Date.now() - startTime);
   }
@@ -1101,7 +1145,9 @@ class Nua {
     const result = await this.client.castArray({
       model: options.model,
       input: { prompt, data: options.input },
-      output
+      output,
+      onOutput: options.onOutput,
+      signal: options.signal
     });
     return toDirectResult(result, Date.now() - startTime);
   }
@@ -1114,8 +1160,8 @@ function enginesFor(config) {
 }
 function toDirectResult(result, latencyMs) {
   if (!result.success) {
-    const { error, reason, attempts } = result;
-    return { success: false, error, reason, attempts, source: "direct", latencyMs };
+    const { error, reason, attempts, cancelled } = result;
+    return { success: false, error, reason, attempts, cancelled, source: "direct", latencyMs };
   }
   return {
     success: true,