@kenkaiiii/gg-agent 5.25.0 → 5.26.1

package/dist/index.d.cts

@@ -87,6 +87,21 @@ interface AgentMaxTurnsEvent {
     totalTurns: number;
     maxTurns: number;
 }
+/**
+ * Emitted when the loop was about to stop on an exhausted turn budget but the
+ * host granted an extension instead. The effective budget is raised and the
+ * loop continues with a continuation prompt, so this is NOT terminal — unlike
+ * `max_turns`, which still fires if the extended budget is also spent.
+ */
+interface AgentTurnBudgetExtendedEvent {
+    type: "turn_budget_extended";
+    /** Turn number at which the budget was exhausted. */
+    turn: number;
+    /** New effective `maxTurns` after the extension. */
+    grantedTurns: number;
+    /** 1-based extension count for this run. */
+    extension: number;
+}
 /**
  * Warning signal emitted when a turn ended on a non-clean stop reason —
  * `max_tokens` (output clipped at the model's output-token limit), `refusal`,
@@ -148,7 +163,7 @@ interface AgentFollowUpMessageEvent {
     type: "follow_up_message";
     content: Message["content"];
 }
-type AgentEvent = AgentTextDeltaEvent | AgentThinkingDeltaEvent | AgentToolCallStartEvent | AgentToolCallUpdateEvent | AgentToolCallEndEvent | AgentToolCallDeltaEvent | AgentServerToolCallEvent | AgentServerToolResultEvent | AgentSteeringMessageEvent | AgentFollowUpMessageEvent | AgentRetryEvent | AgentTurnEndEvent | AgentDoneEvent | AgentMaxTurnsEvent | AgentTruncatedEvent | AgentErrorEvent;
+type AgentEvent = AgentTextDeltaEvent | AgentThinkingDeltaEvent | AgentToolCallStartEvent | AgentToolCallUpdateEvent | AgentToolCallEndEvent | AgentToolCallDeltaEvent | AgentServerToolCallEvent | AgentServerToolResultEvent | AgentSteeringMessageEvent | AgentFollowUpMessageEvent | AgentRetryEvent | AgentTurnEndEvent | AgentDoneEvent | AgentMaxTurnsEvent | AgentTurnBudgetExtendedEvent | AgentTruncatedEvent | AgentErrorEvent;
 interface TransformContextOptions {
     /** Force a transform after the provider reports context overflow. */
     force?: boolean;
@@ -168,6 +183,12 @@ interface AgentOptions {
     /** Control whether tools may/must be called, or select a named tool when supported. */
     toolChoice?: StreamOptions["toolChoice"];
     maxTurns?: number;
+    /**
+     * How many times `onTurnBudgetExhausted` may grant extra turns in one run.
+     * Each grant raises the effective budget by the original `maxTurns`.
+     * Default: 2. Set 0 to disable extensions entirely.
+     */
+    maxTurnExtensions?: number;
     maxTokens?: number;
     temperature?: number;
     thinking?: StreamOptions["thinking"];
@@ -234,6 +255,18 @@ interface AgentOptions {
      * on read.
      */
     getFollowUpMessages?: () => Promise<Message[] | null> | Message[] | null;
+    /**
+     * Consulted when a tool-running turn exhausts the turn budget mid-task,
+     * before the loop emits the terminal `max_turns` event. Return true to grant
+     * another `maxTurns` worth of turns; false (the default when unset) keeps
+     * today's hard cut-off. Hosts should only grant on evidence of progress —
+     * extending a spinning agent just buys it more tokens to spin with.
+     */
+    onTurnBudgetExhausted?: (ctx: {
+        turn: number;
+        maxTurns: number;
+        extension: number;
+    }) => Promise<boolean> | boolean;
 }
 interface AgentResult {
     message: AssistantMessage;

package/dist/index.d.ts

@@ -87,6 +87,21 @@ interface AgentMaxTurnsEvent {
     totalTurns: number;
     maxTurns: number;
 }
+/**
+ * Emitted when the loop was about to stop on an exhausted turn budget but the
+ * host granted an extension instead. The effective budget is raised and the
+ * loop continues with a continuation prompt, so this is NOT terminal — unlike
+ * `max_turns`, which still fires if the extended budget is also spent.
+ */
+interface AgentTurnBudgetExtendedEvent {
+    type: "turn_budget_extended";
+    /** Turn number at which the budget was exhausted. */
+    turn: number;
+    /** New effective `maxTurns` after the extension. */
+    grantedTurns: number;
+    /** 1-based extension count for this run. */
+    extension: number;
+}
 /**
  * Warning signal emitted when a turn ended on a non-clean stop reason —
  * `max_tokens` (output clipped at the model's output-token limit), `refusal`,
@@ -148,7 +163,7 @@ interface AgentFollowUpMessageEvent {
     type: "follow_up_message";
     content: Message["content"];
 }
-type AgentEvent = AgentTextDeltaEvent | AgentThinkingDeltaEvent | AgentToolCallStartEvent | AgentToolCallUpdateEvent | AgentToolCallEndEvent | AgentToolCallDeltaEvent | AgentServerToolCallEvent | AgentServerToolResultEvent | AgentSteeringMessageEvent | AgentFollowUpMessageEvent | AgentRetryEvent | AgentTurnEndEvent | AgentDoneEvent | AgentMaxTurnsEvent | AgentTruncatedEvent | AgentErrorEvent;
+type AgentEvent = AgentTextDeltaEvent | AgentThinkingDeltaEvent | AgentToolCallStartEvent | AgentToolCallUpdateEvent | AgentToolCallEndEvent | AgentToolCallDeltaEvent | AgentServerToolCallEvent | AgentServerToolResultEvent | AgentSteeringMessageEvent | AgentFollowUpMessageEvent | AgentRetryEvent | AgentTurnEndEvent | AgentDoneEvent | AgentMaxTurnsEvent | AgentTurnBudgetExtendedEvent | AgentTruncatedEvent | AgentErrorEvent;
 interface TransformContextOptions {
     /** Force a transform after the provider reports context overflow. */
     force?: boolean;
@@ -168,6 +183,12 @@ interface AgentOptions {
     /** Control whether tools may/must be called, or select a named tool when supported. */
     toolChoice?: StreamOptions["toolChoice"];
     maxTurns?: number;
+    /**
+     * How many times `onTurnBudgetExhausted` may grant extra turns in one run.
+     * Each grant raises the effective budget by the original `maxTurns`.
+     * Default: 2. Set 0 to disable extensions entirely.
+     */
+    maxTurnExtensions?: number;
     maxTokens?: number;
     temperature?: number;
     thinking?: StreamOptions["thinking"];
@@ -234,6 +255,18 @@ interface AgentOptions {
      * on read.
      */
     getFollowUpMessages?: () => Promise<Message[] | null> | Message[] | null;
+    /**
+     * Consulted when a tool-running turn exhausts the turn budget mid-task,
+     * before the loop emits the terminal `max_turns` event. Return true to grant
+     * another `maxTurns` worth of turns; false (the default when unset) keeps
+     * today's hard cut-off. Hosts should only grant on evidence of progress —
+     * extending a spinning agent just buys it more tokens to spin with.
+     */
+    onTurnBudgetExhausted?: (ctx: {
+        turn: number;
+        maxTurns: number;
+        extension: number;
+    }) => Promise<boolean> | boolean;
 }
 interface AgentResult {
     message: AssistantMessage;

package/dist/index.js

@@ -191,6 +191,9 @@ function isTransportFailure(err) {
   }
   return false;
 }
+function turnBudgetContinuationPrompt() {
+  return "[You reached the turn limit for this segment but the work is not finished, so you have been granted more turns. Before continuing, state in one or two sentences what is already done and what remains, then keep going from there \u2014 do not restart work that is already complete.]";
+}
 function abortableSleep(ms, signal) {
   if (signal?.aborted) {
     return Promise.reject(new DOMException("Aborted", "AbortError"));
@@ -210,6 +213,9 @@ function abortableSleep(ms, signal) {
 }
 async function* agentLoop(messages, options) {
   const maxTurns = options.maxTurns ?? DEFAULT_MAX_TURNS;
+  let effectiveMaxTurns = maxTurns;
+  const maxTurnExtensions = Math.max(0, options.maxTurnExtensions ?? 2);
+  let turnExtensions = 0;
   const maxContinuations = options.maxContinuations ?? 5;
   let toolMap = new Map((options.tools ?? []).map((t) => [t.name, t]));
   const totalUsage = { inputTokens: 0, outputTokens: 0 };
@@ -262,7 +268,7 @@ async function* agentLoop(messages, options) {
   let firstProviderEventAt;
   let providerDurationMs = 0;
   try {
-    while (turn < maxTurns) {
+    while (turn < effectiveMaxTurns) {
       options.signal?.throwIfAborted();
       turn++;
       if (logicalTurnStartedAt === 0) logicalTurnStartedAt = Date.now();
@@ -975,8 +981,46 @@ async function* agentLoop(messages, options) {
           }
         }
       }
-      if (turn >= maxTurns) {
-        hitMaxTurns = true;
+      if (turn >= effectiveMaxTurns) {
+        let extended = false;
+        if (options.onTurnBudgetExhausted && turnExtensions < maxTurnExtensions) {
+          const extension = turnExtensions + 1;
+          let granted = false;
+          try {
+            granted = await options.onTurnBudgetExhausted({
+              turn,
+              maxTurns: effectiveMaxTurns,
+              extension
+            });
+          } catch {
+            granted = false;
+          }
+          if (granted) {
+            turnExtensions = extension;
+            effectiveMaxTurns += maxTurns;
+            extended = true;
+            diag("turn_budget_extended", {
+              turn,
+              grantedTurns: effectiveMaxTurns,
+              extension,
+              provider: options.provider,
+              model: options.model
+            });
+            yield {
+              type: "turn_budget_extended",
+              turn,
+              grantedTurns: effectiveMaxTurns,
+              extension
+            };
+            messages.push({
+              role: "user",
+              content: turnBudgetContinuationPrompt()
+            });
+          }
+        }
+        if (!extended) {
+          hitMaxTurns = true;
+        }
       }
     }
   } finally {
@@ -992,14 +1036,15 @@ async function* agentLoop(messages, options) {
   if (hitMaxTurns) {
     diag("max_turns_reached", {
       turn,
-      maxTurns,
+      maxTurns: effectiveMaxTurns,
+      extensions: turnExtensions,
       provider: options.provider,
       model: options.model
     });
     yield {
       type: "max_turns",
       totalTurns: turn,
-      maxTurns
+      maxTurns: effectiveMaxTurns
     };
   }
   yield {