agent-accelerator 0.5.3 → 0.5.5

package/src/agent/agent.ts

@@ -1,7 +1,7 @@
-import type { AgentConfig, AgentRunOptions, MidSessionConfig, ToolChoiceOption, RetryPolicyConfig, Budget, BudgetState, InterruptedRun } from "../types/agent.ts";
+import type { AgentConfig, EditableAgentConfig, AgentRunOptions, MidSessionConfig, ToolChoiceOption, RetryPolicyConfig, Budget, BudgetState, InterruptedRun } from "../types/agent.ts";
 import type { TokenUsage } from "../types/core.ts";
 import type { ProviderRequestOptions } from "../types/model.ts";
-import { normalizeThinkingV2, resolveWhenBusy, normalizeWorkerTimeout } from "../tools/tool.ts";
+import { normalizeThinkingV2, resolveWhenBusy } from "../tools/tool.ts";
 import type { ToolDefinition, ToolResultRecord } from "../types/tool.ts";
 import { isSubagentResult } from "../tools/subagent-result.ts";
 import { CACHE_OPTIONS, type ThinkingLevel, type ThinkingConfig, type CacheOption, type ServiceTier } from "../types/core.ts";
@@ -10,8 +10,11 @@ import { AgentResponse, type StreamEvent } from "../types/response.ts";
 import { AssistantMessageEventStream } from "../streaming/event-stream.ts";
 import { AgentContext } from "./context.ts";
 import { resolveModel } from "../providers/registry.ts";
-import { buildAgentTools, createSubagentSpawnTool } from "./delegation.ts";
+import { buildAgentTools } from "./delegation.ts";
+import { createSubagentsTool } from "./subagents-tool.ts";
+import { WorkerRegistry } from "./workers.ts";
 import {
+  DEFAULT_MAX_DEPTH,
   normalizeToolMap,
   resolveDynamicModelInput,
   resolveMainModel,
@@ -22,6 +25,7 @@ import { resolveHome } from "../scheduler/store.ts";
 import { persistTelemetry } from "../telemetry-file.ts";
 import { lockFolder } from "../utils/durable.ts";
 import { createScheduledActionsTool, getDatetimeTool } from "../scheduler/tool.ts";
+import { applyEditable, assertModelAllowed, modelKey, toEditableConfig } from "./config-blocks.ts";
 import { assertNoToolCollisions } from "../tools/executor.ts";
 import { runAgentLoop, streamAgentLoop, unfinishedToolCalls, endsWithStop, accumulateUsage, type SteerEntry } from "./loop.ts";
 import { isRetryableRun, readRetryAfterMs, sleep } from "../utils/retry.ts";
@@ -34,7 +38,8 @@ import {
   listSubAgentTraceIdsForSessions,
   type SubAgentTrace,
 } from "./delegation.ts";
-import { saveSessionFile, sessionDirFor, loadSessionDir, findInvalidMessage, telemetryBus, type SessionRunMark, type SessionRunEnd, type SessionPending, type SessionToolRecord } from "../session/store.ts";
+import { addTurn, buildUsageReport, emptyUsage, mergeUsage, modelName, readUsage, type UsageNode, type UsageReport, type UsageTotals } from "../session/usage.ts";
+import { saveSessionFile, sessionDirFor, loadSessionDir, findInvalidMessage, priceUsage, telemetryBus, type SessionRunMark, type SessionRunEnd, type SessionPending, type SessionToolRecord } from "../session/store.ts";
 import { SessionJournal } from "../session/journal.ts";
 import { ToolLogs, type ToolLogWriter } from "../session/tool-log.ts";
 import { isLocalPathInput } from "../utils/safe-io.ts";
@@ -91,6 +96,8 @@ function resolveAgentLimits(config: { limits?: Record<string, unknown> }): Agent
   const raw = (config as { limits?: Record<string, unknown> }).limits ?? {};
   const num = (v: unknown): number | undefined =>
     typeof v === "number" && Number.isFinite(v) ? v : undefined;
+  // A network timeout: `0` or `Infinity` turns it off, any other number is milliseconds, anything else is unset (the default applies).
+  const timeout = (v: unknown): number | undefined => (typeof v === "number" && !Number.isNaN(v) ? v : undefined);
   return {
     ...(num(raw.maxTurns) !== undefined ? { maxTurns: Math.max(1, Math.floor(num(raw.maxTurns)!)) } : {}),
     ...(num(raw.deadlineMs) !== undefined ? { deadlineMs: num(raw.deadlineMs)! } : {}),
@@ -98,9 +105,9 @@ function resolveAgentLimits(config: { limits?: Record<string, unknown> }): Agent
       ? { maxToolCallsPerRun: Math.max(1, Math.floor(num(raw.maxToolCallsPerRun)!)) }
       : {}),
     ...(num(raw.maxTotalTokens) !== undefined ? { maxTotalTokens: Math.max(1, Math.floor(num(raw.maxTotalTokens)!)) } : {}),
-    requestTimeoutMs: num(raw.requestTimeoutMs) ?? 300_000,
-    firstByteTimeoutMs: num(raw.firstByteTimeoutMs) ?? 120_000,
-    streamIdleTimeoutMs: num(raw.streamIdleTimeoutMs) ?? 300_000,
+    requestTimeoutMs: timeout(raw.requestTimeoutMs) ?? 300_000,
+    firstByteTimeoutMs: timeout(raw.firstByteTimeoutMs) ?? 120_000,
+    streamIdleTimeoutMs: timeout(raw.streamIdleTimeoutMs) ?? 300_000,
   };
 }
 
@@ -161,12 +168,18 @@ export class Agent {
   readonly dynamicSubagents?: {
     enabled: boolean;
     model?: string | any;
+    /** Open workers at once; `Infinity` (the default) = no limit. */
     maxSpawn: number;
     thinkingLevel?: ThinkingLevel;
     tools: Record<string, ToolDefinition>;
-    timeout: number;
+    /** Longest a scheduled run may take, in ms; `Infinity` (the default) = no limit. */
+    workerTimeoutMs: number;
     /** Scheduled actions (`scheduled_actions` + `get_datetime` tools) are on. */
     allowScheduledActions: boolean;
+    /** Levels of workers allowed below this agent; `Infinity` (the default) = no limit. */
+    maxDepth: number;
+    /** Per-run spending cap of each worker (unset = unlimited). */
+    workerBudget?: { maxCostUsd?: number; maxTotalTokens?: number };
   };
   /** Home folder for everything written to disk (`sessions/`, `scheduled_actions/`, `telemetry/`). */
   readonly home: string;
@@ -249,6 +262,8 @@ export class Agent {
     deferredStream?: AssistantMessageEventStream;
     resolve: (res: AgentResponse) => void;
     reject: (err: unknown) => void;
+    /** Put here by `interrupt(message)`: runs before every other waiting prompt. */
+    urgent?: boolean;
   }> = [];
   /** Named session contexts for `sessionId` runs (Q-19a, LRU 100 + TTL). */
   private sessions = new Map<string, { context: AgentContext; lastAccess: number }>();
@@ -263,6 +278,8 @@ export class Agent {
   readonly runMarks: SessionRunMark[] = [];
   /** Tool calls finished in the current run; saved the moment each finishes so a crash never repeats them. @internal */
   readonly toolRecords: SessionToolRecord[] = [];
+  /** What this agent spent on its OWN model calls (workers keep their own); saved with the session. @internal */
+  readonly usageTotals: UsageTotals = emptyUsage();
   /** The run in flight (its mark has no ending yet, but it is not "interrupted"). */
   private activeMark?: SessionRunMark;
   /** What to do with a cut-off run at construction (see `AgentConfig.resume`). */
@@ -271,6 +288,7 @@ export class Agent {
   private readonly runRetries: number;
   /** The resume in flight, so a second `resume()` returns the same promise. */
   private resuming?: Promise<AgentResponse | undefined>;
+  private workerRegistry?: WorkerRegistry;
 
   /**
    * Creates an agent and registers its model, tools, cache, and delegation settings.
@@ -300,6 +318,7 @@ export class Agent {
     // ModelProviderInstance {model,apiKey,...} and ModelSpec {id,provider}.
     const { modelStringOrSpec, rawModel } = resolveMainModel(config.model);
     this.modelStringOrSpec = modelStringOrSpec as string | any;
+    assertModelAllowed(config.allowedModels, modelKey(modelStringOrSpec));
     const dynRaw = config.dynamicSubagents;
     // Unified worker-model chain: dynamicSubagents.model > subagentModel > SUB_AGENT_MODEL.
     const dynModel = resolveDynamicModelInput(dynRaw, config.subagentModel);
@@ -307,18 +326,45 @@ export class Agent {
     const dynEnabled = dynRaw ? (dynRaw.enabled ?? true) : false;
     if (dynRaw) {
       const dynTools = normalizeToolMap((dynRaw as { tools?: Record<string, ToolDefinition> | ToolDefinition[] }).tools);
-      const rawMax = (dynRaw as any)?.maxSpawn;
-      const maxSpawn = Number.isFinite(rawMax) ? Math.max(1, Math.floor(rawMax as number)) : 4;
-      // `workerTimeoutMs ?? timeout`, or -1 when `modelMaySetTimeout` (see normalizeWorkerTimeout).
-      const timeout = normalizeWorkerTimeout(dynRaw as { timeout?: number; workerTimeoutMs?: number; modelMaySetTimeout?: boolean });
+      const rawDepth = (dynRaw as { maxDepth?: unknown }).maxDepth;
+      // Depth is unlimited unless the developer sets a cap (a whole number >= 1; Infinity also means unlimited).
+      if (rawDepth !== undefined && rawDepth !== Infinity && !(Number.isInteger(rawDepth) && (rawDepth as number) >= 1)) {
+        throw new ConfigError(`[Agent Accelerator] Invalid dynamicSubagents.maxDepth ${JSON.stringify(rawDepth)}: expected a whole number >= 1, or omit it for no limit; set dynamicSubagents.enabled: false to turn workers off.`);
+      }
+      const rawBudget = (dynRaw as { workerBudget?: { maxCostUsd?: unknown; maxTotalTokens?: unknown } }).workerBudget;
+      for (const key of ["maxCostUsd", "maxTotalTokens"] as const) {
+        const v = rawBudget?.[key];
+        if (v !== undefined && !(typeof v === "number" && Number.isFinite(v) && v > 0)) {
+          throw new ConfigError(`[Agent Accelerator] Invalid dynamicSubagents.workerBudget.${key} ${JSON.stringify(v)}: expected a number greater than 0, or omit it for no limit.`);
+        }
+      }
+      // Open workers are unlimited unless the developer sets a cap (a number >= 1; Infinity also means unlimited).
+      const rawMax = (dynRaw as { maxSpawn?: unknown }).maxSpawn;
+      if (rawMax !== undefined && (typeof rawMax !== "number" || Number.isNaN(rawMax))) {
+        throw new ConfigError(`[Agent Accelerator] Invalid dynamicSubagents.maxSpawn ${JSON.stringify(rawMax)}: expected a whole number >= 1, or omit it for no limit.`);
+      }
+      const maxSpawn = rawMax === undefined || rawMax === Infinity ? Infinity : Math.max(1, Math.floor(rawMax));
+      // Only scheduled actions are timed: no limit unless the developer sets one (0 and Infinity mean none).
+      for (const removed of ["timeout", "modelMaySetTimeout"]) {
+        if ((dynRaw as Record<string, unknown>)[removed] !== undefined) {
+          throw new ConfigError(`[Agent Accelerator] dynamicSubagents.${removed} was removed: set dynamicSubagents.workerTimeoutMs (the longest a scheduled run may take, optional) and let each scheduled action carry its own timeoutMs.`);
+        }
+      }
+      const rawTimeout = (dynRaw as { workerTimeoutMs?: unknown }).workerTimeoutMs;
+      if (rawTimeout !== undefined && (typeof rawTimeout !== "number" || Number.isNaN(rawTimeout) || rawTimeout < 0)) {
+        throw new ConfigError(`[Agent Accelerator] Invalid dynamicSubagents.workerTimeoutMs ${JSON.stringify(rawTimeout)}: expected a number of milliseconds > 0, or omit it (0 and Infinity mean no limit).`);
+      }
+      const workerTimeoutMs = !rawTimeout ? Infinity : Math.max(1, Math.floor(rawTimeout));
       this.dynamicSubagents = {
         enabled: dynEnabled,
         model: dynModel as string | any | undefined,
         maxSpawn,
         thinkingLevel: (dynRaw as any)?.thinkingLevel,
         tools: dynTools,
-        timeout,
+        workerTimeoutMs,
         allowScheduledActions: dynRaw.allowScheduledActions === true,
+        maxDepth: (rawDepth as number | undefined) ?? DEFAULT_MAX_DEPTH,
+        ...(rawBudget ? { workerBudget: { ...(rawBudget as { maxCostUsd?: number; maxTotalTokens?: number }) } } : {}),
       };
     }
     this.apiKey = (rawModel as any)?.apiKey || config.apiKey;
@@ -438,8 +484,8 @@ export class Agent {
       );
     }
     if (dyn?.enabled === true) {
-      const spawnTool = createSubagentSpawnTool(this);
-      this.tools[spawnTool.name || "spawn_subagents"] = spawnTool;
+      const subagentsTool = createSubagentsTool(this);
+      this.tools[subagentsTool.name || "subagents"] = subagentsTool;
     }
     if (dyn?.allowScheduledActions) {
       // Fixed by config, so the tool set (and the prompt cache) stays stable.
@@ -459,6 +505,11 @@ export class Agent {
     }
   }
 
+  /** The persistent sub-agent workers of this agent: `spawn`, `message`, `close`, `list`, `turns` (see `WorkerRegistry`). */
+  get workers(): WorkerRegistry {
+    return (this.workerRegistry ??= new WorkerRegistry(this));
+  }
+
   // Loads a persisted session that a crash cut off (a run without an ending) or that still had waiting prompts, so it can be resumed; true when there is something to resume; in: the session folder of `persist.dir`, out: context, runMarks, toolRecords, pendingQueue.
   private recoverSession(): boolean {
     const root = this.persistConfig?.dir;
@@ -475,6 +526,7 @@ export class Agent {
     if (!(session.runs ?? []).some((r) => !r.end) && waiting.length === 0) return false;
     this.context.messages = session.messages;
     this.runMarks.splice(0, this.runMarks.length, ...(session.runs ?? []));
+    this.restoreUsage(session.usage);
     const open = new Set(unfinishedToolCalls(this.context.messages).map((c) => c.id));
     this.toolRecords.splice(0, this.toolRecords.length, ...(session.tools ?? []).filter((t) => open.has(t.id)));
     for (const w of waiting) {
@@ -489,6 +541,42 @@ export class Agent {
     return true;
   }
 
+  // Puts saved spending totals back after a restart or import (zeros when the file has none); in: a loaded session's `usage`, out: this.usageTotals.
+  private restoreUsage(saved: unknown): void {
+    Object.assign(this.usageTotals, readUsage(saved));
+  }
+
+  // Records one model call of THIS agent (priced per turn, with the service tier); in: the loop's onTurnUsage, out: this.usageTotals (saved by the next persist).
+  private recordTurnUsage(usage: TokenUsage, spec: Parameters<typeof priceUsage>[1]): void {
+    addTurn(this.usageTotals, usage, priceUsage(usage, spec, this.serviceTier ? { serviceTier: this.serviceTier } : undefined));
+  }
+
+  /** Adds another agent's spending to this one (a fixed worker's per-call copy into its template). @internal */
+  absorbUsage(other: UsageTotals): void {
+    mergeUsage(this.usageTotals, other);
+  }
+
+  /**
+   * What this agent and every worker below it spent: per agent and per worker (tokens, cache hits, thinking, exact
+   * cost per turn) plus a whole-session total, with nothing counted twice. `agent` is this agent's own model calls;
+   * workers (open, closed, nested, and rebuilt from disk after a restart) and fixed `subagents` workers are listed
+   * below it. Spending of one-shot scheduled-action workers is in their run files, not here.
+   */
+  usageReport(): UsageReport {
+    return buildUsageReport({ id: this.sessionId, name: this.name, model: modelName(this.modelStringOrSpec), totals: this.usageTotals }, [...this.workers.usageNodes(), ...this.fixedWorkerNodes()]);
+  }
+
+  // The `subagents: [...]` workers as usage nodes (their per-call copies' spending is merged into them); in: the constructor config, out: usageReport.
+  private fixedWorkerNodes(): UsageNode[] {
+    const nodes: UsageNode[] = [];
+    for (const entry of this.forkConfig.subagents ?? []) {
+      const worker = "agent" in entry ? entry.agent : entry;
+      const name = "agent" in entry ? entry.name : worker.name;
+      nodes.push({ id: name, name, model: modelName(worker.modelStringOrSpec), status: "fixed", totals: worker.usageTotals, workers: [] });
+    }
+    return nodes;
+  }
+
   // Says on the telemetry bus that resuming (or a prompt that was waiting) failed; in: a rejected resume, out: telemetryBus.
   private reportResumeFailure(err: unknown): void {
     telemetryBus.emitWarning("agent.resume_failed", `[Agent Accelerator] Resuming session ${this.sessionId} failed: ${err instanceof Error ? err.message : String(err)}`, { sessionId: this.sessionId });
@@ -579,26 +667,6 @@ export class Agent {
         "3. Once your reasoning is complete, output your final response or function calls directly in the standard response output.";
       out = out ? `${out}\n\n${guidance}` : guidance;
     }
-    if (this.dynamicSubagents?.enabled === true && !out.includes("[Dynamic Sub-Agents]")) {
-      const dyn = this.dynamicSubagents;
-      const toolNames = Object.keys(dyn.tools);
-      const timeoutNote =
-        dyn.timeout === -1
-          ? "Timeout policy: set a per-sub-agent timeoutMs (ms) for each task; omit it for no limit."
-          : dyn.timeout === 0
-            ? "Timeout policy: workers run with no time limit."
-            : `Timeout policy: every worker is limited to ${dyn.timeout}ms; per-task timeouts are ignored.`;
-      const policy =
-        "[Dynamic Sub-Agents]\n" +
-        `1. You may spawn at most ${dyn.maxSpawn} sub-agent(s) per spawn_subagents call. Extra tasks beyond ${dyn.maxSpawn} are ignored.\n` +
-        "2. Workers are stateless: each receives one task, returns its result, then shuts down. No conversation history is kept.\n" +
-        "3. You cannot choose worker models or reasoning levels — they are fixed by the developer.\n" +
-        (toolNames.length > 0
-          ? `4. Worker-available tools: ${toolNames.join(", ")}. Grant each worker ONLY the tools its task needs via the per-task tools list; omit it for no tools.\n`
-          : "4. No worker tools are available; omit the per-task tools list.\n") +
-        `5. ${timeoutNote}`;
-      out = out ? `${out}\n\n${policy}` : policy;
-    }
     return out || undefined;
   }
 
@@ -759,22 +827,46 @@ export class Agent {
   }
 
   /**
-   * Interrupts the active run immediately (STOP. Do this instead).
-   * Cancels the active stream and aborts provider/tool/sub-agent work via
-   * the run's internal `AbortController`. No-op when idle. The interrupted
-   * run rejects with `AbortError`; queued follow-ups still run afterwards.
+   * Stops the active run now (STOP.) and, given a message, starts it next (STOP. Do this instead). The provider
+   * request is aborted (connection closed, so the provider stops generating where it can), the stream is cancelled, and
+   * running tools and workers get the abort signal; the interrupted run rejects with `AbortError` and keeps its partial
+   * history. `interrupt()` and `interrupt(error)` only stop (no-op when idle) and return nothing. `interrupt(message)`
+   * also runs `message` as the next run, ahead of queued follow-ups, in every `midSession` mode, and resolves with that
+   * run's response; when idle it simply runs the message. For a stream use `stream(message, { enqueue: "interrupt" })`.
    */
-  interrupt(reason?: unknown): void {
+  interrupt(reason?: Error): void;
+  interrupt(message: string | ContentPart[], options?: AgentRunOptions): Promise<AgentResponse>;
+  interrupt(arg?: Error | string | ContentPart[], options?: AgentRunOptions): void | Promise<AgentResponse> {
+    if (typeof arg === "string" || Array.isArray(arg)) {
+      if (options?.stream === true) {
+        throw new Error('[Agent Accelerator] interrupt(message) is non-streaming. Use stream(prompt, { enqueue: "interrupt" }) for a streaming interrupt.');
+      }
+      return this.run(arg, { ...options, enqueue: "interrupt" });
+    }
+    this.abortActive(arg instanceof Error ? arg : undefined);
+  }
+
+  // Aborts the active run (provider request, tools, workers, stream) through its own controller; no-op when idle; in: interrupt and queueUrgent, out: the run settles as AbortError.
+  private abortActive(reason?: Error): void {
     const active = this.currentRun;
     if (!active) return;
     try {
-      active.abortController.abort(reason instanceof Error ? reason : new Error("Agent interrupted"));
+      active.abortController.abort(reason ?? new Error("Agent interrupted"));
     } catch {}
     try {
       active.outerStream?.cancel(reason);
     } catch {}
   }
 
+  // Puts a prompt ahead of everything waiting (behind earlier interrupts) and aborts the active run, so it starts as soon as that run has settled; ignores midSession mode and maxQueued; in: run()/stream() with enqueue "interrupt", out: pendingQueue + the abort.
+  private queueUrgent(entry: Agent["pendingQueue"][number]): void {
+    entry.urgent = true;
+    const firstOrdinary = this.pendingQueue.findIndex((e) => !e.urgent);
+    this.pendingQueue.splice(firstOrdinary < 0 ? this.pendingQueue.length : firstOrdinary, 0, entry);
+    this.persistNow();
+    this.abortActive();
+  }
+
   /**
    * Steers the active turn (While you're doing that, change direction).
    * The current provider/tool work finishes first, then `prompt` is injected
@@ -963,7 +1055,9 @@ export class Agent {
             reject: entry.settle?.reject ?? (() => {}),
           });
         }
-        this.pendingQueue.unshift(...lateSteers);
+        // ...but behind an interrupt(message), which is the newest and most urgent instruction.
+        const firstOrdinary = this.pendingQueue.findIndex((e) => !e.urgent);
+        this.pendingQueue.splice(firstOrdinary < 0 ? this.pendingQueue.length : firstOrdinary, 0, ...lateSteers);
       } catch {}
     }
     this.persistNow();
@@ -1059,6 +1153,24 @@ export class Agent {
     return copy;
   }
 
+  /**
+   * The part of this agent that an agent may edit, as plain JSON: `{ model, instructions, tools }` (`model` is the
+   * `provider/model` string, never a key; `tools` are the names of the tools you passed in `tools`). Store it, show it
+   * to the model, and rebuild with {@link Agent.fromConfig}.
+   */
+  toConfig(): Required<EditableAgentConfig> {
+    return toEditableConfig(this.modelStringOrSpec, this.instructions, this.forkConfig.tools);
+  }
+
+  /**
+   * Builds an Agent from your full `base` config with an agent's edits applied. Only `model`, `instructions` and
+   * `tools` of `editable` count (other keys are ignored with a `config.not_editable` warning); `tools` are names picked
+   * from `base.tools`, an unknown name throws; `base.allowedModels` is enforced. Keys and limits always come from `base`.
+   */
+  static fromConfig(editable: EditableAgentConfig, base: AgentConfig): Agent {
+    return new Agent(applyEditable(editable, base));
+  }
+
   /** Budgets are per run: counters restart whenever a new run begins. */
   private resetBudgetState(): void {
     if (this.budget) this.budgetState = { spawned: 0, totalTokens: 0, totalCostUsd: 0, startedAtMs: nowMs() };
@@ -1161,6 +1273,7 @@ export class Agent {
         ...(this.captureRaw !== undefined ? { captureRaw: this.captureRaw } : {}),
         ...(this.budget ? { enforceBudget: (u?: TokenUsage) => this.enforceBudget(u) } : {}),
         onProgress: () => this.persistNow(),
+        onTurnUsage: (u: TokenUsage, spec: Parameters<typeof priceUsage>[1]) => this.recordTurnUsage(u, spec),
         onToolResult: (r: ToolResultRecord) => this.recordTool(r),
         openToolLog: (call: { name: string }, sid: string | undefined) => this.openToolLog(call, sid),
         ...(resumeMark ? { resume: { stored: this.storedToolResults() } } : {}),
@@ -1251,6 +1364,7 @@ export class Agent {
       ...(this.captureRaw !== undefined ? { captureRaw: this.captureRaw } : {}),
       ...(this.budget ? { enforceBudget: (u?: TokenUsage) => this.enforceBudget(u) } : {}),
       onProgress: () => this.persistNow(),
+      onTurnUsage: (u: TokenUsage, spec: Parameters<typeof priceUsage>[1]) => this.recordTurnUsage(u, spec),
       onToolResult: (r: ToolResultRecord) => this.recordTool(r),
       openToolLog: (call: { name: string }, sid: string | undefined) => this.openToolLog(call, sid),
       steerInbox,
@@ -1501,6 +1615,7 @@ export class Agent {
     }
     this.context.thoughtSignatures = [];
     this.runMarks.splice(0, this.runMarks.length, ...(data.runs ?? []).filter((r) => r.i < this.context.messages.length));
+    this.restoreUsage(data.usage);
     if (data.systemPrompt) {
       this.context.systemPrompt = data.systemPrompt;
     } else {
@@ -1641,8 +1756,11 @@ export class Agent {
       return s;
     }
 
-    // Mid-session: busy agent serializes via steer (same turn) or queue (next turn).
+    // Mid-session: busy agent serializes via steer (same turn) or queue (next turn), or stops the active run and starts this prompt (interrupt).
     if (this.currentRun) {
+      if (options?.enqueue === "interrupt") {
+        return new Promise<AgentResponse>((resolve, reject) => this.queueUrgent({ prompt, options, isStream: false, resolve, reject }));
+      }
       const enforced = this.midSessionConfig.mode;
       const requested = options?.enqueue;
       if (requested && (enforced === "steer" || enforced === "queue") && requested !== enforced) {
@@ -1756,13 +1874,14 @@ export class Agent {
     // Mid-session: busy agent serializes via steer (same turn) or queue (next turn).
     if (this.currentRun) {
       const enforcedStream = this.midSessionConfig.mode;
-      const requestedStream = options?.enqueue;
+      const urgent = options?.enqueue === "interrupt"; // stops the active run and goes first, in every mode and whatever the queue holds
+      const requestedStream = options?.enqueue === "interrupt" ? undefined : options?.enqueue;
       if (requestedStream && (enforcedStream === "steer" || enforcedStream === "queue") && requestedStream !== enforcedStream) {
         throw new Error(
           `[Agent Accelerator] enqueue "${requestedStream}" is disabled by midSession.mode "${enforcedStream}". Use ${enforcedStream}() or set mode to "auto"/"${requestedStream}".`
         );
       }
-      const mode = this.resolveEnqueueMode(requestedStream);
+      const mode = urgent ? "queue" : this.resolveEnqueueMode(requestedStream);
       if (mode === "steer") {
         this.assertPromptValid(prompt);
         this.assertSteerRoom(this.currentRun.steerInbox);
@@ -1795,14 +1914,14 @@ export class Agent {
         }
         return stub;
       }
-      if (this.midSessionConfig.mode === "steer") {
+      if (!urgent && this.midSessionConfig.mode === "steer") {
         throw new Error(
           '[Agent Accelerator] enqueue "queue" is disabled by midSession.mode "steer". Use steer() or set mode to "auto"/"queue".'
         );
       }
       this.assertPromptValid(prompt);
       const max = this.midSessionConfig.maxQueued ?? 20;
-      if (this.pendingQueue.length >= max) {
+      if (!urgent && this.pendingQueue.length >= max) {
         throw new Error(
           `[Agent Accelerator] Queue is full (${this.pendingQueue.length}/${max}). Wait for the active run to finish or increase midSession.maxQueued.`
         );
@@ -1810,13 +1929,15 @@ export class Agent {
       const deferred = new AssistantMessageEventStream();
       this.wireStreamCallbacks(deferred, options);
       // Notify the active stream (if any) that a follow-up was queued.
-      try {
-        this.currentRun.outerStream?.push({
-          type: "queued",
-          queuedPrompt: this.previewPrompt(prompt),
-          queueLength: this.pendingQueue.length + 1,
-        } as any);
-      } catch {}
+      if (!urgent) {
+        try {
+          this.currentRun.outerStream?.push({
+            type: "queued",
+            queuedPrompt: this.previewPrompt(prompt),
+            queueLength: this.pendingQueue.length + 1,
+          } as any);
+        } catch {}
+      }
       const queuedEntry: {
         prompt: string | ContentPart[];
         options?: AgentRunOptions;
@@ -1852,8 +1973,12 @@ export class Agent {
           }
         } catch {}
       });
-      this.pendingQueue.push(queuedEntry as any);
-      this.persistNow();
+      if (urgent) {
+        this.queueUrgent(queuedEntry as Agent["pendingQueue"][number]);
+      } else {
+        this.pendingQueue.push(queuedEntry as any);
+        this.persistNow();
+      }
       // Attach deferred completion to queued promise without exposing it.
       // Real events are piped in pumpQueue() when the turn starts.
       void done.then(

package/src/agent/config-blocks.ts

@@ -0,0 +1,80 @@
+import type { AgentConfig, EditableAgentConfig } from "../types/agent.ts";
+import type { ToolDefinition } from "../types/tool.ts";
+import { ConfigError } from "../types/errors.ts";
+import { telemetryBus } from "../session/store.ts";
+import { normalizeToolMap } from "./worker.ts";
+
+// The building blocks for self-improving agents (RSI): an agent may edit ONLY `model`, `instructions` and `tools`;
+// everything else (limits, budgets, cache, thinking, keys, ...) stays with the developer who wrote `base`.
+
+const EDITABLE_FIELDS = ["model", "instructions", "tools"] as const;
+
+// The model as a plain `provider/id` string (a string stays as written, a ModelSpec becomes `provider/id`); in: Agent.modelStringOrSpec or a base `model`, out: toConfig, the allowedModels check, applyEditable.
+export function modelKey(model: unknown): string | undefined {
+  if (typeof model === "string") return model.trim() || undefined;
+  const m = model as { model?: unknown; id?: unknown; provider?: unknown } | null | undefined;
+  if (m && typeof m.model === "string") return m.model.trim() || undefined;
+  if (m && typeof m.id === "string" && typeof m.provider === "string") return `${m.provider}/${m.id}`;
+  return undefined;
+}
+
+// Throws when `allowedModels` is set and the model is not in it (entries are compared as written, e.g. "google/gemini-3.5-flash"); in: AgentConfig.allowedModels + the model, out: the Agent constructor and applyEditable.
+export function assertModelAllowed(allowed: unknown, model: string | undefined): void {
+  if (allowed === undefined) return;
+  if (!Array.isArray(allowed) || allowed.length === 0 || allowed.some((m) => typeof m !== "string" || !m.trim())) {
+    throw new ConfigError(`[Agent Accelerator] Invalid allowedModels ${JSON.stringify(allowed)}: expected a non-empty list of "provider/model" strings, or omit it to allow any model.`);
+  }
+  if (!model || !allowed.includes(model)) {
+    throw new ConfigError(`[Agent Accelerator] Model ${JSON.stringify(model ?? null)} is not in allowedModels. Allowed: ${allowed.map((m) => JSON.stringify(m)).join(", ")}.`);
+  }
+}
+
+// The editable part of an agent as plain JSON; in: the Agent's model, instructions and the developer's tool list (not the built-in delegation/scheduler tools), out: Agent.toConfig.
+export function toEditableConfig(model: unknown, instructions: string, tools: AgentConfig["tools"]): Required<EditableAgentConfig> {
+  return { model: modelKey(model) ?? "", instructions, tools: Object.keys(normalizeToolMap(tools)) };
+}
+
+// Merges what an agent edited into the developer's config: only model/instructions/tools can change; tools are names picked from base.tools; the model is checked against allowedModels when the Agent is built; in: Agent.fromConfig args, out: the AgentConfig for `new Agent`.
+export function applyEditable(editable: EditableAgentConfig, base: AgentConfig): AgentConfig {
+  if (!editable || typeof editable !== "object" || Array.isArray(editable)) {
+    throw new ConfigError(`[Agent Accelerator] Invalid editable config ${JSON.stringify(editable)}: expected an object like { model, instructions, tools } (see Agent.toConfig()).`);
+  }
+  const e = editable as Record<string, unknown>;
+  const ignored = Object.keys(e).filter((k) => !(EDITABLE_FIELDS as readonly string[]).includes(k) && e[k] !== undefined);
+  if (ignored.length > 0) {
+    telemetryBus.emitWarning(
+      "config.not_editable",
+      `[Agent Accelerator] Ignored ${ignored.map((k) => `"${k}"`).join(", ")} in the editable config: an agent can change only ${EDITABLE_FIELDS.join(", ")}. The rest comes from the developer's config.`,
+      { fields: ignored }
+    );
+  }
+  const out: AgentConfig = { ...base };
+  if (e.model !== undefined) {
+    const next = typeof e.model === "string" ? e.model.trim() : "";
+    if (!next) throw new ConfigError(`[Agent Accelerator] Invalid editable model ${JSON.stringify(e.model)}: expected a "provider/model" string.`);
+    // A model helper's key and base URL belong to its own provider: they are never sent to another one.
+    const prev = base.model as { model?: unknown; apiKey?: string; baseUrl?: string } | string | undefined;
+    const sameProvider = next.includes("/") && next.split("/")[0] === modelKey(prev)?.split("/")[0];
+    out.model = prev && typeof prev === "object" && typeof prev.model === "string"
+      ? { ...prev, model: next, ...(sameProvider ? {} : { apiKey: undefined, baseUrl: undefined }) }
+      : next;
+  }
+  if (e.instructions !== undefined) {
+    if (typeof e.instructions !== "string") throw new ConfigError(`[Agent Accelerator] Invalid editable instructions: expected a string, got ${typeof e.instructions}.`);
+    out.instructions = e.instructions;
+  }
+  if (e.tools !== undefined) {
+    if (!Array.isArray(e.tools) || e.tools.some((n) => typeof n !== "string")) {
+      throw new ConfigError(`[Agent Accelerator] Invalid editable tools ${JSON.stringify(e.tools)}: expected a list of tool names from the developer's tool pool.`);
+    }
+    const pool = normalizeToolMap(base.tools);
+    const unknown = (e.tools as string[]).filter((n) => !Object.hasOwn(pool, n));
+    if (unknown.length > 0) {
+      throw new ConfigError(`[Agent Accelerator] Unknown tool ${unknown.map((n) => JSON.stringify(n)).join(", ")} in the editable config. Available: ${Object.keys(pool).map((n) => JSON.stringify(n)).join(", ") || "none"}.`);
+    }
+    const picked: Record<string, ToolDefinition> = {};
+    for (const n of e.tools as string[]) picked[n] = pool[n]!;
+    out.tools = picked;
+  }
+  return out; // allowedModels is enforced by the Agent constructor
+}

package/src/agent/context.ts

@@ -11,7 +11,7 @@ function fail(message: string): never {
 }
 
 /** Deep clone that preserves Uint8Array/ArrayBuffer media (structuredClone may be absent). */
-function deepCloneValue<T>(value: T): T {
+export function deepCloneValue<T>(value: T): T {
   if (value instanceof Uint8Array) return new Uint8Array(value) as T;
   if (value instanceof ArrayBuffer) return value.slice(0) as T;
   if (Array.isArray(value)) return value.map((v) => deepCloneValue(v)) as T;