@kenkaiiii/gg-agent 5.68.1 → 5.70.0

package/dist/index.d.cts

@@ -103,6 +103,12 @@ interface AgentTool<T extends z.ZodType = z.ZodType> extends Tool {
      * message — becomes unreachable.
      */
     timeoutMs?: number;
+    /**
+     * Whether a mid-run steering message may preempt this tool. Defaults to
+     * true, except for atomic file mutators (`edit`, `write`, …) which always
+     * run to completion so they are never left half-applied.
+     */
+    interruptible?: boolean;
     execute: (args: z.infer<T>, context: ToolContext) => ToolExecuteResult | Promise<ToolExecuteResult>;
 }
 interface AgentTextDeltaEvent {
@@ -371,6 +377,14 @@ interface AgentOptions {
      *  against parallel fan-outs injecting huge uncached context in one turn;
      *  the largest results are trimmed (water-filling) with a re-run notice. */
     maxTurnToolResultChars?: number;
+    /** Optional post-processing of a SUCCESSFUL tool result (after redaction,
+     *  before the tool_call_end event and the provider context). Return the
+     *  content unchanged to leave it alone. A throw is ignored (original kept).
+     *  Used e.g. to append a warning to untrusted-content results. */
+    transformToolResult?: (call: {
+        name: string;
+        args: Record<string, unknown>;
+    }, content: ToolResultContent) => ToolResultContent;
     /** Max consecutive pause_turn continuations before stopping (default: 5).
      *  Prevents infinite loops when server-side tools keep pausing. */
     maxContinuations?: number;
@@ -392,6 +406,15 @@ interface AgentOptions {
      * on read.
      */
     getSteeringMessages?: () => Promise<Message[] | null> | Message[] | null;
+    /**
+     * Instant interrupt (codex `instant_interrupt`): subscribe to "a steering
+     * message just arrived". While tools are running, the listener preempts
+     * interruptible tools (their AbortSignal fires; unfinished calls get an
+     * "Interrupted" error result) and the loop drains steering and continues.
+     * Distinct from `signal` (the Stop button), which ends the run. Returns an
+     * unsubscribe function.
+     */
+    onSteeringAvailable?: (listener: () => void) => () => void;
     /**
      * Polled when the agent would otherwise stop (no tool calls, no steering).
      * Returns messages to inject and continue the loop. Lower priority than
@@ -456,6 +479,7 @@ declare class Agent {
     private options;
     private steeringQueue;
     private followUpQueue;
+    private steeringListeners;
     constructor(options: AgentOptions);
     /** Snapshot of the current message history. Used for session persistence. */
     getMessages(): Message[];
@@ -466,7 +490,11 @@ declare class Agent {
      */
     setSignal(signal: AbortSignal | undefined): void;
     get running(): boolean;
-    /** Queue a steering message for injection after current tool execution completes. */
+    /**
+     * Queue a steering message. Instant interrupt: if tools are running, the
+     * interruptible ones are preempted right away and the message is injected
+     * before the next model call (the turn continues — unlike abort/Stop).
+     */
     steer(msg: Message): void;
     /** Queue a follow-up message for injection when the agent would otherwise stop. */
     followUp(msg: Message): void;

package/dist/index.d.ts

@@ -103,6 +103,12 @@ interface AgentTool<T extends z.ZodType = z.ZodType> extends Tool {
      * message — becomes unreachable.
      */
     timeoutMs?: number;
+    /**
+     * Whether a mid-run steering message may preempt this tool. Defaults to
+     * true, except for atomic file mutators (`edit`, `write`, …) which always
+     * run to completion so they are never left half-applied.
+     */
+    interruptible?: boolean;
     execute: (args: z.infer<T>, context: ToolContext) => ToolExecuteResult | Promise<ToolExecuteResult>;
 }
 interface AgentTextDeltaEvent {
@@ -371,6 +377,14 @@ interface AgentOptions {
      *  against parallel fan-outs injecting huge uncached context in one turn;
      *  the largest results are trimmed (water-filling) with a re-run notice. */
     maxTurnToolResultChars?: number;
+    /** Optional post-processing of a SUCCESSFUL tool result (after redaction,
+     *  before the tool_call_end event and the provider context). Return the
+     *  content unchanged to leave it alone. A throw is ignored (original kept).
+     *  Used e.g. to append a warning to untrusted-content results. */
+    transformToolResult?: (call: {
+        name: string;
+        args: Record<string, unknown>;
+    }, content: ToolResultContent) => ToolResultContent;
     /** Max consecutive pause_turn continuations before stopping (default: 5).
      *  Prevents infinite loops when server-side tools keep pausing. */
     maxContinuations?: number;
@@ -392,6 +406,15 @@ interface AgentOptions {
      * on read.
      */
     getSteeringMessages?: () => Promise<Message[] | null> | Message[] | null;
+    /**
+     * Instant interrupt (codex `instant_interrupt`): subscribe to "a steering
+     * message just arrived". While tools are running, the listener preempts
+     * interruptible tools (their AbortSignal fires; unfinished calls get an
+     * "Interrupted" error result) and the loop drains steering and continues.
+     * Distinct from `signal` (the Stop button), which ends the run. Returns an
+     * unsubscribe function.
+     */
+    onSteeringAvailable?: (listener: () => void) => () => void;
     /**
      * Polled when the agent would otherwise stop (no tool calls, no steering).
      * Returns messages to inject and continue the loop. Lower priority than
@@ -456,6 +479,7 @@ declare class Agent {
     private options;
     private steeringQueue;
     private followUpQueue;
+    private steeringListeners;
     constructor(options: AgentOptions);
     /** Snapshot of the current message history. Used for session persistence. */
     getMessages(): Message[];
@@ -466,7 +490,11 @@ declare class Agent {
      */
     setSignal(signal: AbortSignal | undefined): void;
     get running(): boolean;
-    /** Queue a steering message for injection after current tool execution completes. */
+    /**
+     * Queue a steering message. Instant interrupt: if tools are running, the
+     * interruptible ones are preempted right away and the message is injected
+     * before the next model call (the turn continues — unlike abort/Stop).
+     */
     steer(msg: Message): void;
     /** Queue a follow-up message for injection when the agent would otherwise stop. */
     followUp(msg: Message): void;

package/dist/index.js

@@ -36,6 +36,107 @@ function isLocalBackendUrl(baseUrl) {
   return false;
 }
 
+// src/tool-call-hints.ts
+import { resolveToolSchema } from "@kenkaiiii/gg-ai";
+function normalizeName(name) {
+  return name.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+function editDistance(a, b) {
+  let beforePrevious = [];
+  let previous = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    const current = [i];
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      let distance = Math.min(
+        (previous[j] ?? 0) + 1,
+        (current[j - 1] ?? 0) + 1,
+        (previous[j - 1] ?? 0) + cost
+      );
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+        distance = Math.min(distance, (beforePrevious[j - 2] ?? 0) + 1);
+      }
+      current[j] = distance;
+    }
+    beforePrevious = previous;
+    previous = current;
+  }
+  return previous[b.length] ?? 0;
+}
+function closestName(name, candidates) {
+  const target = normalizeName(name);
+  if (!target) return void 0;
+  const limit = Math.min(3, Math.max(1, Math.floor(target.length / 3)));
+  let best;
+  for (const candidate of [...candidates].sort()) {
+    if (candidate === name) continue;
+    const distance = editDistance(target, normalizeName(candidate));
+    if (distance > limit) continue;
+    if (!best || distance < best.distance) best = { name: candidate, distance };
+  }
+  return best?.name;
+}
+function unknownToolMessage(name, available) {
+  const suggestion = closestName(name, available);
+  if (suggestion) return `Unknown tool: ${name}. Did you mean \`${suggestion}\`?`;
+  const names = [...available].sort();
+  const listed = names.length > 40 ? `${names.slice(0, 40).join(", ")}, \u2026` : names.join(", ");
+  const searchHint = available.includes("tool_search") ? " If the capability is not listed, call `tool_search` to load it." : "";
+  return `Unknown tool: ${name}. Available tools: ${listed}.${searchHint}`;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function typeLabel(node) {
+  if (!isRecord(node)) return "any";
+  if (Array.isArray(node.enum)) {
+    return node.enum.map((value) => JSON.stringify(value)).join(" | ");
+  }
+  const variants = node.anyOf ?? node.oneOf;
+  if (Array.isArray(variants)) {
+    return [...new Set(variants.map(typeLabel))].filter((t) => t !== "null").join(" | ") || "any";
+  }
+  if (node.type === "array") return `${typeLabel(node.items)}[]`;
+  if (Array.isArray(node.type)) {
+    return node.type.filter((t) => t !== "null").join(" | ") || "any";
+  }
+  return typeof node.type === "string" ? node.type : "any";
+}
+function objectShape(tool) {
+  let schema;
+  try {
+    schema = resolveToolSchema(tool);
+  } catch {
+    return void 0;
+  }
+  if (!isRecord(schema) || !isRecord(schema.properties)) return void 0;
+  const required = new Set(
+    Array.isArray(schema.required) ? schema.required.filter((r) => typeof r === "string") : []
+  );
+  return { properties: schema.properties, required };
+}
+function argumentHints(tool, args) {
+  const shape = objectShape(tool);
+  if (!shape) return "";
+  const names = Object.keys(shape.properties);
+  if (names.length === 0) return `Expected arguments: none.`;
+  const fields = names.map((name) => {
+    const optional = shape.required.has(name) ? "" : "?";
+    return `${name}${optional}: ${typeLabel(shape.properties[name])}`;
+  });
+  const lines = [`Expected arguments: { ${fields.join(", ")} }`];
+  if (isRecord(args)) {
+    for (const key of Object.keys(args).sort()) {
+      if (key in shape.properties) continue;
+      const suggestion = closestName(key, names);
+      lines.push(
+        suggestion ? `Unknown field \`${key}\` \u2014 did you mean \`${suggestion}\`?` : `Unknown field \`${key}\` is not a parameter of this tool.`
+      );
+    }
+  }
+  return lines.join("\n");
+}
+
 // src/output-ceiling.ts
 var TTL_MS = 24 * 60 * 60 * 1e3;
 var MIN_PLAUSIBLE_CEILING = 256;
@@ -220,6 +321,29 @@ ${rule.reminder.trim()}
 // src/agent-loop.ts
 var DEFAULT_MAX_TURNS = 300;
 var DEFAULT_TOOL_TIMEOUT_MS = 3e5;
+var PREEMPT_GRACE_MS = 500;
+var STEER_INTERRUPTED_TEXT = "Interrupted: the user sent a new message.";
+var ATOMIC_TOOL_NAMES = /* @__PURE__ */ new Set(["edit", "write", "multi_edit", "apply_patch", "notebook_edit"]);
+function isInterruptibleTool(tool, name) {
+  if (tool?.interruptible !== void 0) return tool.interruptible;
+  return !ATOMIC_TOOL_NAMES.has(name);
+}
+function markSteerInterrupted(record) {
+  const content = record.content;
+  let next;
+  if (typeof content === "string") {
+    next = content.trim() ? `${STEER_INTERRUPTED_TEXT}
+Partial output:
+${content}` : STEER_INTERRUPTED_TEXT;
+  } else {
+    next = [
+      { type: "text", text: `${STEER_INTERRUPTED_TEXT}
+Partial output:` },
+      ...content
+    ];
+  }
+  return { toolCallId: record.toolCallId, content: next, isError: true };
+}
 var _toolRedaction;
 function toolRedactionOptions() {
   _toolRedaction ??= { secrets: environmentSecrets(process.env) };
@@ -1370,10 +1494,14 @@ async function* agentLoop(messages, options) {
         fatalToolArgumentRecoverable = recoverable;
         fatalToolArgumentToolName = toolName;
       };
+      const preempt = new AbortController();
+      const unsubscribeSteering = options.onSteeringAvailable?.(() => preempt.abort());
       const executionOptions = {
         signal: options.signal,
+        preemptSignal: options.onSteeringAvailable ? preempt.signal : void 0,
         maxToolResultChars: options.maxToolResultChars,
         maxTurnToolResultChars: options.maxTurnToolResultChars,
+        transformToolResult: options.transformToolResult,
         toolMap,
         invalidToolArgumentCounts,
         markFatalToolArgumentError,
@@ -1382,7 +1510,15 @@ async function* agentLoop(messages, options) {
       const hasSequentialToolCall = toolCalls.some(
         (toolCall) => toolMap.get(toolCall.name)?.executionMode === "sequential"
       );
-      const executionResult = hasSequentialToolCall ? yield* executeToolCallsMixed(toolCalls, toolResults, executionOptions) : yield* executeToolCallsParallel(toolCalls, toolResults, executionOptions);
+      let executionResult;
+      try {
+        executionResult = hasSequentialToolCall ? yield* executeToolCallsMixed(toolCalls, toolResults, executionOptions) : yield* executeToolCallsParallel(toolCalls, toolResults, executionOptions);
+      } finally {
+        unsubscribeSteering?.();
+      }
+      if (executionResult.preempted) {
+        diag("steer_preempted_tools", { turn, provider: options.provider, model: options.model });
+      }
       messages.push({ role: "tool", content: executionResult.toolResults });
       yield { type: "checkpoint", turn };
       const toolsAborted = executionResult.aborted;
@@ -1539,7 +1675,7 @@ async function executeSingleToolCall(toolCall, options, pushEvent) {
     options.seenToolCalls.add(signature);
   }
   if (!tool) {
-    resultContent = `Unknown tool: ${toolCall.name}`;
+    resultContent = unknownToolMessage(toolCall.name, [...options.toolMap.keys()]);
     isError = true;
   } else {
     try {
@@ -1556,8 +1692,12 @@ async function executeSingleToolCall(toolCall, options, pushEvent) {
       }
       const callerSignal = options.signal;
       const toolTimeout = AbortSignal.timeout(tool.timeoutMs ?? DEFAULT_TOOL_TIMEOUT_MS);
+      const preemptSignal = isInterruptibleTool(tool, toolCall.name) ? options.preemptSignal : void 0;
+      const toolSignals = [callerSignal, toolTimeout, preemptSignal].filter(
+        (s) => s !== void 0
+      );
       const ctx = {
-        signal: callerSignal ? AbortSignal.any([callerSignal, toolTimeout]) : toolTimeout,
+        signal: toolSignals.length === 1 ? toolTimeout : AbortSignal.any(toolSignals),
         toolCallId: toolCall.id,
         onUpdate: (update) => {
           pushEvent({
@@ -1571,6 +1711,15 @@ async function executeSingleToolCall(toolCall, options, pushEvent) {
       const normalized = normalizeToolResult(raw);
       resultContent = redactValue(normalized.content, toolRedactionOptions());
       details = redactValue(normalized.details, toolRedactionOptions());
+      if (options.transformToolResult) {
+        try {
+          resultContent = options.transformToolResult(
+            { name: toolCall.name, args: toolCall.args },
+            resultContent
+          );
+        } catch {
+        }
+      }
       for (const key of options.invalidToolArgumentCounts.keys()) {
         if (key.startsWith(`${toolCall.name}:`)) options.invalidToolArgumentCounts.delete(key);
       }
@@ -1582,8 +1731,10 @@ async function executeSingleToolCall(toolCall, options, pushEvent) {
         const failureCount = (options.invalidToolArgumentCounts.get(failureKey) ?? 0) + 1;
         options.invalidToolArgumentCounts.set(failureKey, failureCount);
         invalidArgAttempt = failureCount;
+        const hints = argumentHints(tool, toolCall.args);
         resultContent = `Invalid arguments for tool \`${toolCall.name}\`:
-` + prettyError + "\nRe-issue the call with each field as the correct type.";
+` + prettyError + (hints ? `
+${hints}` : "") + "\nRe-issue the call with each field as the correct type.";
         if (failureCount >= 3) {
           const recoverable = Object.keys(toolCall.args ?? {}).length === 0;
           options.markFatalToolArgumentError(
@@ -1608,6 +1759,15 @@ async function executeSingleToolCall(toolCall, options, pushEvent) {
   }
   resultContent = redactValue(resultContent, toolRedactionOptions());
   details = redactValue(details, toolRedactionOptions());
+  if (options.preemptSignal?.aborted && isInterruptibleTool(options.toolMap.get(toolCall.name), toolCall.name)) {
+    const marked = markSteerInterrupted({
+      toolCallId: toolCall.id,
+      content: resultContent,
+      isError
+    });
+    resultContent = marked.content;
+    isError = true;
+  }
   const durationMs = Date.now() - startTime;
   pushEvent({
     type: "tool_call_end",
@@ -1620,6 +1780,59 @@ async function executeSingleToolCall(toolCall, options, pushEvent) {
   });
   return { toolCallId: toolCall.id, content: resultContent, isError };
 }
+function createPreemptTracker(options, eventStream, state, resultsById, dispatchedIds) {
+  const running = /* @__PURE__ */ new Map();
+  let graceTimer;
+  const preemptSignal = options.preemptSignal;
+  const abandon = () => {
+    graceTimer = void 0;
+    for (const [id, entry] of running) {
+      if (!entry.interruptible || resultsById.has(id)) continue;
+      resultsById.set(id, { toolCallId: id, content: STEER_INTERRUPTED_TEXT, isError: true });
+      pushToolEvent(eventStream, state, {
+        type: "tool_call_end",
+        toolCallId: id,
+        result: STEER_INTERRUPTED_TEXT,
+        isError: true,
+        durationMs: Date.now() - entry.startedAt
+      });
+      running.delete(id);
+    }
+    if (running.size === 0) eventStream.close();
+  };
+  const onPreempt = () => {
+    if (graceTimer === void 0) graceTimer = setTimeout(abandon, PREEMPT_GRACE_MS);
+  };
+  preemptSignal?.addEventListener("abort", onPreempt, { once: true });
+  return {
+    async run(toolCall) {
+      if (options.preemptSignal?.aborted) return;
+      dispatchedIds.add(toolCall.id);
+      const interruptible = isInterruptibleTool(options.toolMap.get(toolCall.name), toolCall.name);
+      running.set(toolCall.id, { toolCall, interruptible, startedAt: Date.now() });
+      const record = await executeSingleToolCall(
+        toolCall,
+        options,
+        (event) => pushToolEvent(eventStream, state, event)
+      );
+      running.delete(toolCall.id);
+      if (resultsById.has(toolCall.id)) return;
+      const alreadyMarked = typeof record.content === "string" ? record.content.startsWith(STEER_INTERRUPTED_TEXT) : record.content[0]?.type === "text" && record.content[0].text.startsWith(STEER_INTERRUPTED_TEXT);
+      resultsById.set(
+        toolCall.id,
+        interruptible && preemptSignal?.aborted && !alreadyMarked ? markSteerInterrupted(record) : record
+      );
+      if (preemptSignal?.aborted && graceTimer === void 0 && running.size === 0) {
+        eventStream.close();
+      }
+    },
+    preempted: () => preemptSignal?.aborted === true,
+    dispose: () => {
+      if (graceTimer !== void 0) clearTimeout(graceTimer);
+      preemptSignal?.removeEventListener("abort", onPreempt);
+    }
+  };
+}
 async function* executeToolCallsMixed(toolCalls, initialToolResults, options) {
   const eventStream = new EventStream();
   const state = { finalized: false };
@@ -1627,6 +1840,7 @@ async function* executeToolCallsMixed(toolCalls, initialToolResults, options) {
   const dispatchedIds = /* @__PURE__ */ new Set();
   const abortHandler = () => eventStream.abort(new Error("aborted"));
   options.signal?.addEventListener("abort", abortHandler, { once: true });
+  const tracker = createPreemptTracker(options, eventStream, state, resultsById, dispatchedIds);
   const phases = [];
   let currentParallel = [];
   for (const toolCall of toolCalls) {
@@ -1647,40 +1861,18 @@ async function* executeToolCallsMixed(toolCalls, initialToolResults, options) {
   void (async () => {
     try {
       for (const phase of phases) {
-        if (options.signal?.aborted) break;
+        if (options.signal?.aborted || options.preemptSignal?.aborted) break;
         if (phase.sequential) {
           const signature = JSON.stringify([
             phase.sequential.name,
             canonicalToolArgs(phase.sequential.args)
           ]);
           if (!options.seenToolCalls.has(signature)) options.seenToolCalls.clear();
-          dispatchedIds.add(phase.sequential.id);
-          const record = await executeSingleToolCall(
-            phase.sequential,
-            options,
-            (event) => pushToolEvent(eventStream, state, event)
-          );
-          resultsById.set(record.toolCallId, record);
+          await tracker.run(phase.sequential);
         } else if (phase.parallel.length === 1) {
-          dispatchedIds.add(phase.parallel[0].id);
-          const record = await executeSingleToolCall(
-            phase.parallel[0],
-            options,
-            (event) => pushToolEvent(eventStream, state, event)
-          );
-          resultsById.set(record.toolCallId, record);
+          await tracker.run(phase.parallel[0]);
         } else {
-          await Promise.all(
-            phase.parallel.map(async (toolCall) => {
-              dispatchedIds.add(toolCall.id);
-              const record = await executeSingleToolCall(
-                toolCall,
-                options,
-                (event) => pushToolEvent(eventStream, state, event)
-              );
-              resultsById.set(record.toolCallId, record);
-            })
-          );
+          await Promise.all(phase.parallel.map((toolCall) => tracker.run(toolCall)));
         }
       }
       if (!state.finalized) eventStream.close();
@@ -1701,12 +1893,13 @@ async function* executeToolCallsMixed(toolCalls, initialToolResults, options) {
     }
   } finally {
     options.signal?.removeEventListener("abort", abortHandler);
+    tracker.dispose();
     state.finalized = true;
   }
   const toolResults = buildToolResults(initialToolResults, toolCalls, resultsById, dispatchedIds);
   capToolResults(toolResults, options.maxToolResultChars);
   capTurnToolResults(toolResults, options.maxTurnToolResultChars);
-  return { toolResults, aborted };
+  return { toolResults, aborted, preempted: !aborted && tracker.preempted() };
 }
 async function* executeToolCallsParallel(toolCalls, initialToolResults, options) {
   const eventStream = new EventStream();
@@ -1715,17 +1908,8 @@ async function* executeToolCallsParallel(toolCalls, initialToolResults, options)
   const dispatchedIds = /* @__PURE__ */ new Set();
   const abortHandler = () => eventStream.abort(new Error("aborted"));
   options.signal?.addEventListener("abort", abortHandler, { once: true });
-  Promise.all(
-    toolCalls.map(async (toolCall) => {
-      dispatchedIds.add(toolCall.id);
-      const record = await executeSingleToolCall(
-        toolCall,
-        options,
-        (event) => pushToolEvent(eventStream, state, event)
-      );
-      resultsById.set(record.toolCallId, record);
-    })
-  ).then(() => {
+  const tracker = createPreemptTracker(options, eventStream, state, resultsById, dispatchedIds);
+  Promise.all(toolCalls.map((toolCall) => tracker.run(toolCall))).then(() => {
     if (!state.finalized) eventStream.close();
   }).catch((err) => {
     if (!state.finalized) eventStream.abort(err instanceof Error ? err : new Error(String(err)));
@@ -1743,12 +1927,13 @@ async function* executeToolCallsParallel(toolCalls, initialToolResults, options)
     }
   } finally {
     options.signal?.removeEventListener("abort", abortHandler);
+    tracker.dispose();
     state.finalized = true;
   }
   const toolResults = buildToolResults(initialToolResults, toolCalls, resultsById, dispatchedIds);
   capToolResults(toolResults, options.maxToolResultChars);
   capTurnToolResults(toolResults, options.maxTurnToolResultChars);
-  return { toolResults, aborted };
+  return { toolResults, aborted, preempted: !aborted && tracker.preempted() };
 }
 function cancelledBeforeStartText(name) {
   return `\`${name}\` was cancelled before it started, so it had no effect. Safe to retry.`;
@@ -2044,6 +2229,7 @@ var Agent = class {
   options;
   steeringQueue = [];
   followUpQueue = [];
+  steeringListeners = /* @__PURE__ */ new Set();
   constructor(options) {
     this.options = options;
     if (options.system) {
@@ -2068,9 +2254,14 @@ var Agent = class {
   get running() {
     return this._running;
   }
-  /** Queue a steering message for injection after current tool execution completes. */
+  /**
+   * Queue a steering message. Instant interrupt: if tools are running, the
+   * interruptible ones are preempted right away and the message is injected
+   * before the next model call (the turn continues — unlike abort/Stop).
+   */
   steer(msg) {
     this.steeringQueue.push(msg);
+    for (const listener of [...this.steeringListeners]) listener();
   }
   /** Queue a follow-up message for injection when the agent would otherwise stop. */
   followUp(msg) {
@@ -2090,6 +2281,14 @@ var Agent = class {
         const all = [...callerResult ?? [], ...queued];
         return all.length > 0 ? all : null;
       },
+      onSteeringAvailable: (listener) => {
+        this.steeringListeners.add(listener);
+        const unsubscribeCaller = this.options.onSteeringAvailable?.(listener);
+        return () => {
+          this.steeringListeners.delete(listener);
+          unsubscribeCaller?.();
+        };
+      },
       getFollowUpMessages: async () => {
         const callerResult = await this.options.getFollowUpMessages?.() ?? [];
         const queued = this.followUpQueue.splice(0);