@kenkaiiii/gg-agent 5.68.0 → 5.69.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 {
@@ -343,6 +349,7 @@ interface AgentOptions {
     transportSessionId?: StreamOptions["transportSessionId"];
     projectId?: StreamOptions["projectId"];
     cacheRetention?: StreamOptions["cacheRetention"];
+    onContextPrepared?: StreamOptions["onContextPrepared"];
     /** Stable per-session cache routing key for providers that support it. */
     promptCacheKey?: StreamOptions["promptCacheKey"];
     /** Override the User-Agent sent with OAuth-authenticated Anthropic requests. */
@@ -370,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;
@@ -391,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
@@ -455,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[];
@@ -465,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 {
@@ -343,6 +349,7 @@ interface AgentOptions {
     transportSessionId?: StreamOptions["transportSessionId"];
     projectId?: StreamOptions["projectId"];
     cacheRetention?: StreamOptions["cacheRetention"];
+    onContextPrepared?: StreamOptions["onContextPrepared"];
     /** Stable per-session cache routing key for providers that support it. */
     promptCacheKey?: StreamOptions["promptCacheKey"];
     /** Override the User-Agent sent with OAuth-authenticated Anthropic requests. */
@@ -370,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;
@@ -391,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
@@ -455,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[];
@@ -465,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

@@ -220,6 +220,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) };
@@ -694,6 +717,7 @@ async function* agentLoop(messages, options) {
           transportSessionId: options.transportSessionId,
           projectId: liveProjectId,
           cacheRetention: options.cacheRetention,
+          onContextPrepared: options.onContextPrepared,
           promptCacheKey: options.promptCacheKey,
           serviceTier: options.serviceTier,
           supportsImages: options.supportsImages,
@@ -1369,10 +1393,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,
@@ -1381,7 +1409,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;
@@ -1555,8 +1591,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({
@@ -1570,6 +1610,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);
       }
@@ -1607,6 +1656,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",
@@ -1619,6 +1677,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 };
@@ -1626,6 +1737,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) {
@@ -1646,40 +1758,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();
@@ -1700,12 +1790,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();
@@ -1714,17 +1805,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)));
@@ -1742,12 +1824,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.`;
@@ -2043,6 +2126,7 @@ var Agent = class {
   options;
   steeringQueue = [];
   followUpQueue = [];
+  steeringListeners = /* @__PURE__ */ new Set();
   constructor(options) {
     this.options = options;
     if (options.system) {
@@ -2067,9 +2151,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) {
@@ -2089,6 +2178,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);