@runtypelabs/sdk 1.10.0 → 1.10.2

package/dist/index.d.cts

@@ -3172,6 +3172,8 @@ interface RunTaskToolTraceSlice {
     verificationPassed: boolean;
     verificationBlocked: boolean;
     localToolLoopGuardTriggered: boolean;
+    /** Per-file write counts for detecting excessive same-file rewrites */
+    writeCountByPath: Record<string, number>;
     forcedTurnEndReason?: string;
     bestCandidatePath?: string;
     bestCandidateReason?: string;
@@ -4257,7 +4259,7 @@ interface ExecuteWithLocalToolsOptions {
 /**
  * Status of a long-task agent run
  */
-type RunTaskStatus = 'running' | 'complete' | 'paused' | 'error' | 'budget_exceeded' | 'max_sessions';
+type RunTaskStatus = 'running' | 'complete' | 'paused' | 'error' | 'budget_exceeded' | 'max_sessions' | 'stalled';
 /**
  * A continuation point within a long-task run (for marathon resume).
  */
@@ -4389,6 +4391,10 @@ interface RunTaskState {
     workflowVariant?: string;
     /** Number of consecutive sessions where verification was blocked */
     consecutiveBlockedVerificationSessions?: number;
+    /** Reason the last TASK_COMPLETE claim was rejected (set when detected but not accepted) */
+    lastCompletionRejectionReason?: string;
+    /** Number of consecutive sessions with no tool actions (for stall detection) */
+    consecutiveEmptySessions?: number;
     /** Arbitrary bag for workflow-specific data */
     workflowState?: Record<string, unknown>;
 }
@@ -4426,7 +4432,7 @@ interface RunTaskContextCompactionEvent {
 }
 type RunTaskOnContextCompaction = (event: RunTaskContextCompactionEvent) => void | Promise<void>;
 interface RunTaskContextNoticeEvent {
-    kind: 'provider_native_compaction' | 'tool_definitions_warning';
+    kind: 'provider_native_compaction' | 'tool_definitions_warning' | 'server_network_retry';
     sessionIndex: number;
     model?: string;
     message: string;
@@ -4690,6 +4696,7 @@ declare class AgentsEndpoint {
     private hasSufficientResearchEvidence;
     private buildEffectiveSessionOutput;
     private canAcceptTaskCompletion;
+    private computeCompletionRejectionReason;
     private summarizeUnknownForTrace;
     private summarizeTextBlockForTrace;
     private parseVerificationResult;
@@ -4747,6 +4754,12 @@ declare class AgentsEndpoint {
      * ```
      */
     runTask(id: string, options: RunTaskOptions): Promise<RunTaskResult>;
+    /** Error message patterns from server-side sessions that indicate a transient network failure
+     *  (e.g. AI provider connection dropped). These are retried automatically. */
+    private static readonly RETRYABLE_SESSION_ERROR_PATTERNS;
+    /** Returns true if a server-side session error message indicates a transient
+     *  network failure that is safe to retry. */
+    static isRetryableSessionError(errorMessage?: string): boolean;
     /** Stop phrases that indicate the agent considers its task complete. */
     private static readonly STOP_PHRASES;
     /**

package/dist/index.d.ts

@@ -3172,6 +3172,8 @@ interface RunTaskToolTraceSlice {
     verificationPassed: boolean;
     verificationBlocked: boolean;
     localToolLoopGuardTriggered: boolean;
+    /** Per-file write counts for detecting excessive same-file rewrites */
+    writeCountByPath: Record<string, number>;
     forcedTurnEndReason?: string;
     bestCandidatePath?: string;
     bestCandidateReason?: string;
@@ -4257,7 +4259,7 @@ interface ExecuteWithLocalToolsOptions {
 /**
  * Status of a long-task agent run
  */
-type RunTaskStatus = 'running' | 'complete' | 'paused' | 'error' | 'budget_exceeded' | 'max_sessions';
+type RunTaskStatus = 'running' | 'complete' | 'paused' | 'error' | 'budget_exceeded' | 'max_sessions' | 'stalled';
 /**
  * A continuation point within a long-task run (for marathon resume).
  */
@@ -4389,6 +4391,10 @@ interface RunTaskState {
     workflowVariant?: string;
     /** Number of consecutive sessions where verification was blocked */
     consecutiveBlockedVerificationSessions?: number;
+    /** Reason the last TASK_COMPLETE claim was rejected (set when detected but not accepted) */
+    lastCompletionRejectionReason?: string;
+    /** Number of consecutive sessions with no tool actions (for stall detection) */
+    consecutiveEmptySessions?: number;
     /** Arbitrary bag for workflow-specific data */
     workflowState?: Record<string, unknown>;
 }
@@ -4426,7 +4432,7 @@ interface RunTaskContextCompactionEvent {
 }
 type RunTaskOnContextCompaction = (event: RunTaskContextCompactionEvent) => void | Promise<void>;
 interface RunTaskContextNoticeEvent {
-    kind: 'provider_native_compaction' | 'tool_definitions_warning';
+    kind: 'provider_native_compaction' | 'tool_definitions_warning' | 'server_network_retry';
     sessionIndex: number;
     model?: string;
     message: string;
@@ -4690,6 +4696,7 @@ declare class AgentsEndpoint {
     private hasSufficientResearchEvidence;
     private buildEffectiveSessionOutput;
     private canAcceptTaskCompletion;
+    private computeCompletionRejectionReason;
     private summarizeUnknownForTrace;
     private summarizeTextBlockForTrace;
     private parseVerificationResult;
@@ -4747,6 +4754,12 @@ declare class AgentsEndpoint {
      * ```
      */
     runTask(id: string, options: RunTaskOptions): Promise<RunTaskResult>;
+    /** Error message patterns from server-side sessions that indicate a transient network failure
+     *  (e.g. AI provider connection dropped). These are retried automatically. */
+    private static readonly RETRYABLE_SESSION_ERROR_PATTERNS;
+    /** Returns true if a server-side session error message indicates a transient
+     *  network failure that is safe to retry. */
+    static isRetryableSessionError(errorMessage?: string): boolean;
     /** Stop phrases that indicate the agent considers its task complete. */
     private static readonly STOP_PHRASES;
     /**

package/dist/{index.js → index.mjs}

@@ -2240,7 +2240,10 @@ function hasSufficientResearchEvidence(state) {
     return false;
   }
   if (state.isCreationTask) {
-    return (state.recentReadPaths?.length || 0) >= 1;
+    const hasReadFiles = (state.recentReadPaths?.length || 0) >= 1;
+    const isDiscoveryKey = (key) => key.startsWith("tree_directory:") || key.startsWith("list_directory:") || key === "server:tree_directory" || key === "server:list_directory";
+    const hasPerformedDiscovery = state.sessions.some((session) => session.actionKeys?.some(isDiscoveryKey)) || (state.recentActionKeys?.some(isDiscoveryKey) ?? false);
+    return hasReadFiles || hasPerformedDiscovery;
   }
   if (!state.bestCandidatePath) return false;
   const normalizedBestCandidatePath = normalizeCandidatePath(state.bestCandidatePath);
@@ -2455,6 +2458,21 @@ var researchPhase = {
     ].join("\n");
   },
   interceptToolCall(toolName, _args, ctx) {
+    if (ctx.state.isCreationTask && !isExternalTask(ctx.state)) {
+      const isWriteLikeTool = toolName === "write_file" || toolName === "edit_file" || toolName === "restore_file_checkpoint";
+      if (isWriteLikeTool) {
+        const normalizedPathArg2 = typeof _args.path === "string" && _args.path.trim() ? ctx.normalizePath(String(_args.path)) : void 0;
+        const normalizedPlanPath = ctx.state.planPath ? ctx.normalizePath(ctx.state.planPath) : void 0;
+        if (normalizedPathArg2 && normalizedPlanPath && normalizedPathArg2 !== normalizedPlanPath) {
+          return [
+            `Blocked by marathon research guard: ${toolName} cannot create product files during the research phase.`,
+            "Complete research first, then the system will advance you to planning.",
+            `You may write the plan to "${normalizedPlanPath}" once research is complete.`
+          ].join(" ");
+        }
+      }
+      return void 0;
+    }
     if (!isExternalTask(ctx.state)) {
       return void 0;
     }
@@ -2557,7 +2575,7 @@ var researchPhase = {
   },
   canAcceptCompletion(state, trace) {
     if (!isExternalTask(state)) {
-      return true;
+      return false;
     }
     return Boolean(state.planWritten || trace.planWritten);
   }
@@ -2611,7 +2629,7 @@ var planningPhase = {
   interceptToolCall(toolName, args, ctx) {
     const normalizedPathArg = typeof args.path === "string" && args.path.trim() ? ctx.normalizePath(String(args.path)) : void 0;
     const normalizedPlanPath = ctx.state.planPath ? ctx.normalizePath(ctx.state.planPath) : void 0;
-    const isWriteLikeTool = toolName === "write_file" || toolName === "restore_file_checkpoint";
+    const isWriteLikeTool = toolName === "write_file" || toolName === "edit_file" || toolName === "restore_file_checkpoint";
     if (isWriteLikeTool && normalizedPathArg && normalizedPlanPath && normalizedPathArg !== normalizedPlanPath) {
       return [
         `Blocked by marathon planning guard: ${toolName} must target the exact plan path during planning.`,
@@ -2685,9 +2703,11 @@ var executionPhase = {
       "Do not write the plan file first in execution. Make a real repo-file edit before you update the plan with progress.",
       "Do not create scratch or test files to probe the repo or tool behavior.",
       "write_file automatically checkpoints original repo files before overwriting them. If an edit regresses behavior, use restore_file_checkpoint on that file.",
-      "Read the target file and edit it with write_file. Update the plan file with progress after completing real edits.",
+      "Use edit_file for targeted changes instead of rewriting the entire file with write_file. edit_file takes old_string and new_string to surgically replace specific code.",
+      "Read the target file and edit it with edit_file (preferred) or write_file. Update the plan file with progress after completing real edits.",
       "Before large edits, read any already discovered supporting source/style files that power the target so you preserve existing behavior.",
-      "Prefer minimal diffs over rewrites. If you cannot verify related behavior, stop and record what is still unverified instead of rewriting blindly.",
+      "Prefer edit_file for small changes. Only use write_file when creating new files or when the changes are so extensive that a full rewrite is simpler.",
+      "After writing a file 2+ times, you MUST read it back to verify correctness before writing again.",
       'Use run_check for real verification before TASK_COMPLETE. Good examples: "pnpm lint", "pnpm exec tsc --noEmit", "pnpm test", or a focused vitest/pytest command.',
       "Broad discovery is only allowed if a read of the current target file fails."
     ];
@@ -2699,7 +2719,7 @@ var executionPhase = {
     const normalizedPathArg = typeof args.path === "string" && args.path.trim() ? ctx.normalizePath(String(args.path)) : void 0;
     const normalizedPlanPath = ctx.state.planPath ? ctx.normalizePath(ctx.state.planPath) : void 0;
     const normalizedBestCandidatePath = ctx.state.bestCandidatePath ? ctx.normalizePath(ctx.state.bestCandidatePath) : void 0;
-    const isWriteLikeTool = toolName === "write_file" || toolName === "restore_file_checkpoint";
+    const isWriteLikeTool = toolName === "write_file" || toolName === "edit_file" || toolName === "restore_file_checkpoint";
     if (normalizedBestCandidatePath && ctx.isDiscoveryTool(toolName) && !ctx.trace.bestCandidateReadFailed) {
       return [
         `Blocked by marathon execution guard: ${toolName} is disabled during execution.`,
@@ -2761,6 +2781,21 @@ var executionPhase = {
   },
   buildRecoveryMessage(state) {
     const recent = state.sessions.slice(-2);
+    if (recent.length >= 2 && recent.every(
+      (session) => session.hadTextOutput === true && session.wroteFiles !== true
+    )) {
+      const noToolActions = recent.every(
+        (session) => !session.wroteFiles && !session.verificationAttempted
+      );
+      if (noToolActions) {
+        return [
+          "Recovery instruction: You have been rejected from completing multiple times.",
+          "The likely reason is that verification has not passed.",
+          "Your next action must be run_check with a concrete command (e.g., syntax check, lint, or test).",
+          "Do NOT output TASK_COMPLETE again until verification passes."
+        ].join("\n");
+      }
+    }
     if (recent.length >= 2 && recent.every(
       (session) => session.verificationAttempted === true && session.wroteFiles !== true
     )) {
@@ -2809,6 +2844,18 @@ var executionPhase = {
     if (!ctx.trace.executionFileWritten && snapshot.consecutiveDiscoveryPauseCount >= 18) {
       return "execution is looping on discovery instead of editing repo files and ending the turn";
     }
+    const writeKeys = snapshot.recentActionKeys.filter((k) => k.startsWith("write_file:"));
+    if (writeKeys.length >= 4) {
+      const uniqueWriteTargets = new Set(writeKeys.map((k) => k.split(":").slice(1).join(":")));
+      if (uniqueWriteTargets.size === 1) {
+        return `write_file called ${writeKeys.length} times on the same file \u2014 read the file and verify before continuing`;
+      }
+    }
+    for (const [filePath, count] of Object.entries(ctx.trace.writeCountByPath)) {
+      if (count >= 4) {
+        return `same file rewritten ${count} times without verification (${filePath}) \u2014 read the file and verify before continuing`;
+      }
+    }
     return void 0;
   }
 };
@@ -4745,7 +4792,8 @@ var _AgentsEndpoint = class _AgentsEndpoint {
       verificationAttempted: false,
       verificationPassed: false,
       verificationBlocked: false,
-      localToolLoopGuardTriggered: false
+      localToolLoopGuardTriggered: false,
+      writeCountByPath: {}
     };
   }
   isDiscoveryLocalTool(toolName) {
@@ -4948,8 +4996,26 @@ var _AgentsEndpoint = class _AgentsEndpoint {
         sessionTrace
       );
     }
+    const phaseIndex = workflow.phases.findIndex((p) => p.name === state.workflowPhase);
+    const executionPhaseIndex = workflow.phases.findIndex((p) => p.name === "execution");
+    if (executionPhaseIndex >= 0 && phaseIndex < executionPhaseIndex) {
+      return false;
+    }
     return true;
   }
+  computeCompletionRejectionReason(state, trace) {
+    const reasons = [];
+    if (!state.planWritten) {
+      reasons.push("Plan file has not been written");
+    }
+    if (state.bestCandidatePath && !state.bestCandidateVerified && !trace.bestCandidateVerified) {
+      reasons.push("Best candidate file has not been verified (read back after writing)");
+    }
+    if (state.verificationRequired && !state.lastVerificationPassed && !trace.verificationPassed) {
+      reasons.push("Verification has not passed \u2014 run a verification command (run_check) before completing");
+    }
+    return reasons.length > 0 ? reasons.join("; ") : "Completion gates not satisfied for the current workflow phase";
+  }
   summarizeUnknownForTrace(value, maxLength = 180) {
     const text = typeof value === "string" ? value : value === void 0 ? "" : JSON.stringify(value);
     return text.replace(/\s+/g, " ").trim().slice(0, maxLength);
@@ -5263,7 +5329,7 @@ var _AgentsEndpoint = class _AgentsEndpoint {
           const pathArg = typeof args.path === "string" && args.path.trim() ? ` path=${String(args.path)}` : "";
           const queryArg = typeof args.query === "string" && args.query.trim() ? ` query="${String(args.query)}"` : "";
           const patternArg = typeof args.pattern === "string" && args.pattern.trim() ? ` pattern="${String(args.pattern)}"` : "";
-          const isWriteLikeTool = toolName === "write_file" || toolName === "restore_file_checkpoint";
+          const isWriteLikeTool = toolName === "write_file" || toolName === "edit_file" || toolName === "restore_file_checkpoint";
           const isVerificationTool = toolName === "run_check";
           const currentPhase = workflow.phases.find((p) => p.name === state.workflowPhase);
           if (currentPhase?.interceptToolCall) {
@@ -5318,8 +5384,10 @@ var _AgentsEndpoint = class _AgentsEndpoint {
             );
             throw error;
           }
-          if (isWriteLikeTool && normalizedPathArg) {
+          const writeResultIndicatesError = isWriteLikeTool && typeof result === "string" && result.startsWith("Error:");
+          if (isWriteLikeTool && normalizedPathArg && !writeResultIndicatesError) {
             trace.wroteFiles = true;
+            trace.writeCountByPath[normalizedPathArg] = (trace.writeCountByPath[normalizedPathArg] || 0) + 1;
             if (normalizedPlanPath && normalizedPathArg === normalizedPlanPath) {
               trace.planWritten = true;
             } else if (state.workflowPhase === "execution") {
@@ -5627,6 +5695,8 @@ var _AgentsEndpoint = class _AgentsEndpoint {
     const maxCost = options.maxCost;
     const useStream = options.stream ?? true;
     const workflow = options.workflow ?? defaultWorkflow;
+    const maxServerNetworkRetries = 3;
+    let consecutiveServerNetworkErrors = 0;
     const agent = await this.get(id);
     const taskName = typeof options.trackProgress === "string" ? options.trackProgress : options.trackProgress ? `${agent.name} task` : "";
     const resolvedTaskName = taskName || `${agent.name} task`;
@@ -5933,16 +6003,60 @@ var _AgentsEndpoint = class _AgentsEndpoint {
       if (state.sessions.length > 50) {
         state.sessions = state.sessions.slice(-50);
       }
+      if (sessionResult.stopReason !== "error") {
+        consecutiveServerNetworkErrors = 0;
+      }
       const detectedTaskCompletion = this.detectTaskCompletion(sessionResult.result);
       const acceptedTaskCompletion = detectedTaskCompletion && this.canAcceptTaskCompletion(sessionResult.result, state, sessionTrace, workflow);
+      if (detectedTaskCompletion && !acceptedTaskCompletion) {
+        state.lastCompletionRejectionReason = this.computeCompletionRejectionReason(state, sessionTrace);
+        if (state.verificationRequired && !state.lastVerificationPassed && !sessionTrace.verificationPassed && !sessionTrace.verificationAttempted) {
+          state.consecutiveBlockedVerificationSessions = (state.consecutiveBlockedVerificationSessions || 0) + 1;
+          if ((state.consecutiveBlockedVerificationSessions || 0) >= 2) {
+            state.verificationRequired = false;
+            state.lastVerificationPassed = true;
+            if (!state.planWritten) {
+              state.planWritten = true;
+            }
+            if (!state.bestCandidateVerified) {
+              state.bestCandidateVerified = true;
+            }
+          }
+        }
+      } else {
+        state.lastCompletionRejectionReason = void 0;
+      }
+      const sessionHadActions = sessionTrace.wroteFiles || sessionTrace.readFiles || sessionTrace.discoveryPerformed || sessionTrace.verificationAttempted;
+      if (sessionHadActions) {
+        state.consecutiveEmptySessions = 0;
+      } else {
+        state.consecutiveEmptySessions = (state.consecutiveEmptySessions || 0) + 1;
+      }
       if (sessionResult.stopReason === "complete" && !detectedTaskCompletion) {
         state.status = "complete";
       } else if (sessionResult.stopReason === "error") {
-        state.status = "error";
+        if (_AgentsEndpoint.isRetryableSessionError(sessionResult.error) && consecutiveServerNetworkErrors < maxServerNetworkRetries) {
+          consecutiveServerNetworkErrors++;
+          const delayMs = Math.min(
+            5e3 * Math.pow(2, consecutiveServerNetworkErrors - 1),
+            3e4
+          );
+          const delaySec = Math.round(delayMs / 1e3);
+          await this.emitContextNotice(options.onContextNotice, {
+            kind: "server_network_retry",
+            sessionIndex: session,
+            message: `Server network error: ${sessionResult.error}. Retrying in ${delaySec}s (attempt ${consecutiveServerNetworkErrors}/${maxServerNetworkRetries})...`
+          });
+          await new Promise((resolve) => setTimeout(resolve, delayMs));
+        } else {
+          state.status = "error";
+        }
       } else if (sessionResult.stopReason === "max_cost") {
         state.status = "budget_exceeded";
       } else if (acceptedTaskCompletion) {
         state.status = "complete";
+      } else if ((state.consecutiveEmptySessions || 0) >= 3) {
+        state.status = "stalled";
       } else if (maxCost && state.totalCost >= maxCost) {
         state.status = "budget_exceeded";
       } else if (session + 1 >= maxSessions) {
@@ -5971,6 +6085,15 @@ var _AgentsEndpoint = class _AgentsEndpoint {
       recordId
     };
   }
+  /** Returns true if a server-side session error message indicates a transient
+   *  network failure that is safe to retry. */
+  static isRetryableSessionError(errorMessage) {
+    if (!errorMessage) return false;
+    const lower = errorMessage.toLowerCase();
+    return _AgentsEndpoint.RETRYABLE_SESSION_ERROR_PATTERNS.some(
+      (pattern) => lower.includes(pattern)
+    );
+  }
   /**
    * Client-side fallback for detecting task completion in agent output.
    * Mirrors the API's detectAutoComplete() for non-loop agents that return 'end_turn'.
@@ -6575,6 +6698,7 @@ Do NOT redo any of the above work.`
     ).join("\n");
     if (state.messages && state.messages.length > 0) {
       const recoveryMessage2 = this.buildStuckTurnRecoveryMessage(state, wf);
+      const rejectionNotice = state.lastCompletionRejectionReason ? `TASK_COMPLETE was rejected because: ${state.lastCompletionRejectionReason}. Address this before signaling completion again.` : void 0;
       const continuationContent = [
         "Continue the task.",
         phaseBlock,
@@ -6586,6 +6710,7 @@ Do NOT redo any of the above work.`
         `Previous sessions:`,
         progressSummary,
         "",
+        ...rejectionNotice ? [rejectionNotice, ""] : [],
         ...recoveryMessage2 ? [recoveryMessage2, ""] : [],
         "Do not redo previous work. If the task is already complete, respond with TASK_COMPLETE."
       ].join("\n");
@@ -6646,6 +6771,7 @@ Do NOT redo any of the above work.`
       };
     }
     const recoveryMessage = this.buildStuckTurnRecoveryMessage(state, wf);
+    const fallbackRejectionNotice = state.lastCompletionRejectionReason ? `TASK_COMPLETE was rejected because: ${state.lastCompletionRejectionReason}. Address this before signaling completion again.` : void 0;
     const content = [
       originalMessage,
       phaseBlock,
@@ -6657,6 +6783,7 @@ Do NOT redo any of the above work.`
       `Previous sessions:`,
       progressSummary,
       "",
+      ...fallbackRejectionNotice ? [fallbackRejectionNotice, ""] : [],
       ...recoveryMessage ? [recoveryMessage, ""] : [],
       `Last output (do NOT repeat this \u2014 build on it):`,
       state.lastOutput.slice(0, 1e3),
@@ -6718,6 +6845,24 @@ Do NOT redo any of the above work.`
 };
 _AgentsEndpoint.AUTO_COMPACT_SUMMARY_PREFIX = "You are continuing a long-running task. Here is a compact summary of prior work:";
 _AgentsEndpoint.FORCED_COMPACT_SUMMARY_PREFIX = "You are continuing a previously completed task. Here is a summary of prior work:";
+/** Error message patterns from server-side sessions that indicate a transient network failure
+ *  (e.g. AI provider connection dropped). These are retried automatically. */
+_AgentsEndpoint.RETRYABLE_SESSION_ERROR_PATTERNS = [
+  "network connection lost",
+  "network error",
+  "fetch failed",
+  "connection reset",
+  "connection refused",
+  "connection closed",
+  "socket hang up",
+  "econnreset",
+  "econnrefused",
+  "econnaborted",
+  "etimedout",
+  "enetunreach",
+  "enotfound",
+  "request timeout"
+];
 /** Stop phrases that indicate the agent considers its task complete. */
 _AgentsEndpoint.STOP_PHRASES = [
   "DONE:",
@@ -8075,4 +8220,4 @@ export {
   sanitizeTaskSlug,
   streamEvents
 };
-//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.mjs.map