graphlit-client 1.0.20260602001 → 1.0.20260605001

package/dist/client.d.ts

@@ -3250,6 +3250,17 @@ declare class Graphlit {
      * with `intermediateMessages` rather than a single tool-call list.
      */
     private detectTaskCompleteInMessages;
+    /**
+     * Treat a non-empty text-only turn as terminal when the caller explicitly
+     * opts into interactive completion semantics.
+     */
+    private detectTerminalTextCompletion;
+    /**
+     * Reconstruct terminal-text completion across resumed conversations. A
+     * text-only assistant turn is considered terminal if it was not followed by
+     * the harness' synthetic bare continuation prompt.
+     */
+    private detectPersistedTurnCompletionReason;
     /**
      * Run LLM-as-judge quality assessment on a completed agent run.
      */

package/dist/client.js

@@ -11,7 +11,7 @@ import { getServiceType, getModelName, getModelEnum, isAnthropicAdaptiveThinking
 import { StuckDetector } from "./helpers/stuck-detector.js";
 import { TurnEvaluator } from "./helpers/turn-evaluator.js";
 import { TokenBudgetTracker, truncateToolResult, windowToolRounds, estimateTokens, DEFAULT_CONTEXT_STRATEGY, } from "./helpers/context-management.js";
-import { ProviderError } from "./types/internal.js";
+import { isRetryableGraphQLTransportError, ProviderError, } from "./types/internal.js";
 import { UIEventAdapter } from "./streaming/ui-event-adapter.js";
 import { formatMessagesForOpenAI, formatMessagesForOpenAIResponsesInitialRound, extractInstructionsForOpenAIResponses, extractSystemInstructionParts, buildResponsesFunctionCallOutputItems, formatToolsForOpenAIResponses, formatMessagesForAnthropic, formatMessagesForGoogle, formatMessagesForMistral, formatMessagesForBedrock, } from "./streaming/llm-formatters.js";
 import { streamWithOpenAIResponses, } from "./streaming/openai-responses.js";
@@ -528,7 +528,9 @@ class Graphlit {
     }
     refreshClient() {
         this.client = undefined;
-        this.generateToken();
+        if (this.jwtSecret) {
+            this.generateToken();
+        }
         this.setupApolloClient();
     }
     setupApolloClient() {
@@ -548,28 +550,15 @@ class Graphlit {
                     // Check if we should retry this error
                     if (!error)
                         return false;
-                    // Check for network errors
-                    const hasNetworkError = !!error.networkError;
-                    if (!hasNetworkError)
-                        return false;
-                    // Get status code from different possible locations
-                    const statusCode = error.networkError?.statusCode ||
-                        error.networkError?.response?.status ||
-                        error.statusCode;
-                    // Check if status code is retryable
-                    if (statusCode && this.retryConfig.retryableStatusCodes) {
-                        const shouldRetry = this.retryConfig.retryableStatusCodes.includes(statusCode);
-                        // Call onRetry callback if provided
-                        if (shouldRetry &&
-                            this.retryConfig.onRetry &&
-                            _operation.getContext().retryCount !== undefined) {
-                            const attempt = _operation.getContext().retryCount + 1;
-                            this.retryConfig.onRetry(attempt, error, _operation);
-                        }
-                        return shouldRetry;
+                    const shouldRetry = isRetryableGraphQLTransportError(error, this.retryConfig.retryableStatusCodes);
+                    // Call onRetry callback if provided
+                    if (shouldRetry &&
+                        this.retryConfig.onRetry &&
+                        _operation.getContext().retryCount !== undefined) {
+                        const attempt = _operation.getContext().retryCount + 1;
+                        this.retryConfig.onRetry(attempt, error, _operation);
                     }
-                    // Default: retry on network errors without specific status codes
-                    return true;
+                    return shouldRetry;
                 },
             },
         });
@@ -7233,12 +7222,14 @@ class Graphlit {
         const turnResults = [];
         let totalToolCalls = 0;
         let status = "completed";
+        let completionReason;
         let finalMessage = "";
         let stuckPattern;
         let errorMessage;
         let lastContextWindow;
         let conversationId = options?.conversationId ?? "";
         let resolvedAgentId = agentId ?? "";
+        let resumedTurnCount = 0;
         // Accumulate token usage across all turns from conversation_completed events
         let accumulatedUsage = {
             promptTokens: 0,
@@ -7424,6 +7415,7 @@ class Graphlit {
                     }
                 }
             }
+            resumedTurnCount = turnResults.length;
             const fallbackSpecs = await this.resolveSpecificationReferences(fallbackReferences.filter((fallback) => fallback.id !== fullSpec?.id));
             // ── Phase 2: The Loop ──────────────────────────────────────────────
             let pendingStuckIntervention;
@@ -7643,6 +7635,7 @@ class Graphlit {
                 // records the terminal assistant/tool-call round, but does not execute
                 // the completion handler or start a follow-up filler round.
                 const taskCompleteThisTurn = this.detectTaskCompleteInMessages(loopResult.intermediateMessages);
+                const terminalTextThisTurn = this.detectTerminalTextCompletion(loopResult, options?.completionMode);
                 const trimmedMessage = loopResult.finalAssistantMessage;
                 // 8b. Complete conversation (persist turn)
                 if (trimmedMessage) {
@@ -7701,6 +7694,11 @@ class Graphlit {
                     toolCallCount: loopResult.toolCallCount,
                     durationMs: turnDuration,
                     taskComplete: taskCompleteThisTurn,
+                    completionReason: taskCompleteThisTurn
+                        ? "task_complete"
+                        : terminalTextThisTurn
+                            ? "terminal_text"
+                            : undefined,
                     contextWindowUsage: loopResult.contextWindow,
                     contextActions: loopResult.contextActions.length > 0
                         ? loopResult.contextActions
@@ -7718,9 +7716,10 @@ class Graphlit {
                 // 10. Notify callback
                 options?.onTurnComplete?.(turnResult);
                 // 11. Evaluate turn
-                // a. task_complete called?
-                if (taskCompleteThisTurn) {
+                // a. Terminal completion reached?
+                if (turnResult.completionReason) {
                     status = "completed";
+                    completionReason = turnResult.completionReason;
                     break;
                 }
                 // b/c. Error handling
@@ -7762,9 +7761,9 @@ class Graphlit {
             // status defaults to "completed", so we need a positive signal that
             // task_complete was actually called — otherwise hitting the turn cap
             // looks like success.
-            const taskCompleteWasCalled = turnResults.some((t) => t.taskComplete);
+            const runCompletedNaturally = turnResults.slice(resumedTurnCount).some((t) => t.taskComplete || t.completionReason === "terminal_text");
             if (status === "completed" &&
-                !taskCompleteWasCalled &&
+                !runCompletedNaturally &&
                 turnResults.length >= evaluator.adjustedMaxTurns) {
                 status = "budget_exhausted";
             }
@@ -7780,6 +7779,7 @@ class Graphlit {
                 conversationId,
                 status,
                 finalMessage,
+                completionReason,
                 turnResults,
                 totalToolCalls,
                 wallClockMs,
@@ -7805,6 +7805,7 @@ class Graphlit {
                 conversationId,
                 status,
                 finalMessage,
+                completionReason,
                 turnResults,
                 totalToolCalls,
                 wallClockMs: Date.now() - runStart,
@@ -7878,8 +7879,9 @@ class Graphlit {
                         toolNames.push(tc.name);
                 }
             }
-            // Check tool response messages for errors
+            // Check tool response messages for errors and locate the next user turn.
             const toolErrors = [];
+            let nextUserMsg;
             for (let j = i + 1; j < messages.length; j++) {
                 const respMsg = messages[j];
                 if (respMsg.role === Types.ConversationRoleTypes.Tool) {
@@ -7888,9 +7890,11 @@ class Graphlit {
                     }
                 }
                 else if (respMsg.role === Types.ConversationRoleTypes.User) {
+                    nextUserMsg = respMsg;
                     break; // Next turn
                 }
             }
+            const taskComplete = this.detectTaskComplete(assistantMsg.toolCalls);
             results.push({
                 turnNumber: turnNumber++,
                 prompt: msg.message || "",
@@ -7898,7 +7902,10 @@ class Graphlit {
                 toolCalls: [...new Set(toolNames)].sort(),
                 toolCallCount: toolNames.length,
                 durationMs: computePersistedToolRoundDurationMs(assistantMsg.toolCalls) ?? 0,
-                taskComplete: this.detectTaskComplete(assistantMsg.toolCalls),
+                taskComplete,
+                completionReason: taskComplete
+                    ? "task_complete"
+                    : this.detectPersistedTurnCompletionReason(assistantMsg, nextUserMsg),
                 errors: toolErrors.length > 0 ? toolErrors : undefined,
             });
         }
@@ -8035,6 +8042,40 @@ class Graphlit {
         }
         return false;
     }
+    /**
+     * Treat a non-empty text-only turn as terminal when the caller explicitly
+     * opts into interactive completion semantics.
+     */
+    detectTerminalTextCompletion(loopResult, completionMode) {
+        if (completionMode !== "allow_terminal_text") {
+            return false;
+        }
+        if (loopResult.toolCallCount !== 0) {
+            return false;
+        }
+        if (loopResult.errors.length > 0) {
+            return false;
+        }
+        return loopResult.finalAssistantMessage.trim().length > 0;
+    }
+    /**
+     * Reconstruct terminal-text completion across resumed conversations. A
+     * text-only assistant turn is considered terminal if it was not followed by
+     * the harness' synthetic bare continuation prompt.
+     */
+    detectPersistedTurnCompletionReason(assistantMessage, nextMessage) {
+        if ((assistantMessage.message || "").trim().length === 0) {
+            return undefined;
+        }
+        if ((assistantMessage.toolCalls?.length ?? 0) > 0) {
+            return undefined;
+        }
+        if (nextMessage?.role === Types.ConversationRoleTypes.User &&
+            (nextMessage.message || "").trim() === "Continue.") {
+            return undefined;
+        }
+        return "terminal_text";
+    }
     /**
      * Run LLM-as-judge quality assessment on a completed agent run.
      */
@@ -8114,6 +8155,7 @@ class Graphlit {
             conversationId: params.conversationId,
             status: params.status,
             finalMessage: params.finalMessage,
+            completionReason: params.completionReason,
             turns: params.turnResults.length,
             totalToolCalls: params.totalToolCalls,
             wallClockMs: params.wallClockMs,

package/dist/helpers/stuck-detector.js

@@ -41,7 +41,7 @@ const STUCK_WINDOW = 5; // Number of recent turns to examine
 const REPEAT_THRESHOLD = 3; // Minimum identical occurrences to detect a pattern
 const SIMILARITY_THRESHOLD = 0.9; // Trigram similarity threshold for "same" response
 const CONSECUTIVE_ERROR_THRESHOLD = 3; // Consecutive all-error turns
-const CONSECUTIVE_EMPTY_THRESHOLD = 2; // Consecutive empty (no tool, no task_complete) turns
+const CONSECUTIVE_EMPTY_THRESHOLD = 2; // Consecutive empty non-terminal turns
 /**
  * Stateful detector that tracks patterns across harness turns and identifies
  * when the agent is stuck in a loop.
@@ -69,7 +69,8 @@ export class StuckDetector {
         const allErrors = turn.toolCallCount > 0 &&
             (turn.errors?.length ?? 0) >= turn.toolCallCount;
         this.errorHistory.push(allErrors);
-        if (turn.toolCallCount === 0 && !turn.taskComplete) {
+        const turnCompleted = turn.taskComplete || turn.completionReason != null;
+        if (turn.toolCallCount === 0 && !turnCompleted) {
             this.emptyTurnCount++;
         }
         else {
@@ -113,7 +114,7 @@ export class StuckDetector {
                 return this.strike("error_loop");
             }
         }
-        // 4. Empty turns — 2+ consecutive turns with 0 tool calls and no task_complete
+        // 4. Empty turns — 2+ consecutive turns with 0 tool calls and no terminal completion
         if (this.emptyTurnCount >= CONSECUTIVE_EMPTY_THRESHOLD) {
             return this.strike("empty_turns");
         }

package/dist/types/agent.d.ts

@@ -118,6 +118,10 @@ export interface AgentError {
 }
 /** Terminal status of a runAgent execution. */
 export type HarnessStatus = "completed" | "budget_exhausted" | "stuck" | "error" | "cancelled";
+/** How a runAgent execution reached terminal completion. */
+export type RunCompletionReason = "task_complete" | "terminal_text";
+/** Policy controlling when text-only turns should be treated as terminal. */
+export type RunCompletionMode = "task_complete_only" | "allow_terminal_text";
 /** Per-turn data captured by the harness. */
 export interface TurnResult {
     turnNumber: number;
@@ -127,6 +131,7 @@ export interface TurnResult {
     toolCallCount: number;
     durationMs: number;
     taskComplete?: boolean;
+    completionReason?: RunCompletionReason;
     contextWindowUsage?: ContextWindowUsage;
     contextActions?: ContextManagementAction[];
     errors?: string[];
@@ -161,6 +166,7 @@ export interface RunAgentOptions {
     maxWallClockMs?: number;
     maxToolCalls?: number;
     windDownTurns?: number;
+    completionMode?: RunCompletionMode;
     onTurnComplete?: (turn: TurnResult) => void;
     onBudgetWarning?: (snapshot: BudgetSnapshot) => void;
     onStreamEvent?: (event: AgentStreamEvent) => void;
@@ -193,6 +199,7 @@ export interface RunAgentResult {
     conversationId: string;
     status: HarnessStatus;
     finalMessage: string;
+    completionReason?: RunCompletionReason;
     turns: number;
     totalToolCalls: number;
     wallClockMs: number;

package/dist/types/internal.d.ts

@@ -117,6 +117,19 @@ export declare class ProviderError extends Error {
  * Used as a catch-all after provider-specific error classification.
  */
 export declare function isRetryableServerError(error: any): boolean;
+/**
+ * Extract an HTTP status code from common Apollo/network error shapes.
+ */
+export declare function getErrorStatusCode(error: any): number | undefined;
+/**
+ * Detect retryable GraphQL transport errors from Apollo RetryLink.
+ *
+ * RetryLink can receive either:
+ * - an ApolloError with `networkError`
+ * - a raw HttpLink `ServerError` with `statusCode` / `response.status`
+ * - a nested network/cause error from undici/fetch
+ */
+export declare function isRetryableGraphQLTransportError(error: any, retryableStatusCodes?: number[]): boolean;
 /**
  * Detect rate-limit / overloaded errors across providers.
  */

package/dist/types/internal.js

@@ -37,6 +37,49 @@ export function isRetryableServerError(error) {
         msg.includes("bad gateway") ||
         msg.includes("gateway timeout"));
 }
+/**
+ * Extract an HTTP status code from common Apollo/network error shapes.
+ */
+export function getErrorStatusCode(error) {
+    if (!error || typeof error !== "object")
+        return undefined;
+    const status = typeof error.status === "number"
+        ? error.status
+        : typeof error.statusCode === "number"
+            ? error.statusCode
+            : undefined;
+    if (typeof status === "number")
+        return status;
+    const responseStatus = typeof error.response?.status === "number"
+        ? error.response.status
+        : undefined;
+    if (typeof responseStatus === "number")
+        return responseStatus;
+    return (getErrorStatusCode(error.networkError) ?? getErrorStatusCode(error.cause));
+}
+/**
+ * Detect retryable GraphQL transport errors from Apollo RetryLink.
+ *
+ * RetryLink can receive either:
+ * - an ApolloError with `networkError`
+ * - a raw HttpLink `ServerError` with `statusCode` / `response.status`
+ * - a nested network/cause error from undici/fetch
+ */
+export function isRetryableGraphQLTransportError(error, retryableStatusCodes = [429, 500, 502, 503, 504]) {
+    if (!error)
+        return false;
+    const statusCode = getErrorStatusCode(error);
+    if (typeof statusCode === "number") {
+        return retryableStatusCodes.includes(statusCode);
+    }
+    if (Array.isArray(error.graphQLErrors) && error.graphQLErrors.length > 0) {
+        return false;
+    }
+    return (!!error.networkError ||
+        isNetworkError(error) ||
+        isRetryableServerError(error) ||
+        isRetryableGraphQLTransportError(error.cause, retryableStatusCodes));
+}
 /**
  * Detect rate-limit / overloaded errors across providers.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphlit-client",
-  "version": "1.0.20260602001",
+  "version": "1.0.20260605001",
   "description": "Graphlit API Client for TypeScript",
   "type": "module",
   "main": "./dist/client.js",