@runtypelabs/sdk 1.8.1 → 1.8.2

package/dist/index.d.cts

@@ -3099,6 +3099,7 @@ interface RunTaskStateSlice {
     originalMessage?: string;
     workflowPhase?: string;
     workflowVariant?: string;
+    /** Suggested markdown artifact path for the task */
     planPath?: string;
     planWritten?: boolean;
     bestCandidatePath?: string;
@@ -4267,7 +4268,7 @@ interface RunTaskState {
     bootstrapContext?: string;
     /** Current structured marathon workflow phase (widened to string for custom workflows) */
     workflowPhase?: string;
-    /** Suggested markdown plan path for the task */
+    /** Suggested markdown artifact path for the task */
     planPath?: string;
     /** Whether the planning artifact has been written */
     planWritten?: boolean;
@@ -4611,6 +4612,7 @@ declare class AgentsEndpoint {
     private readonly TOOL_OUTPUT_INLINE_THRESHOLD;
     private offloadToolResult;
     private getDefaultPlanPath;
+    private getDefaultExternalReportPath;
     private dirnameOfCandidatePath;
     private joinCandidatePath;
     private scoreCandidatePath;

package/dist/index.d.ts

@@ -3099,6 +3099,7 @@ interface RunTaskStateSlice {
     originalMessage?: string;
     workflowPhase?: string;
     workflowVariant?: string;
+    /** Suggested markdown artifact path for the task */
     planPath?: string;
     planWritten?: boolean;
     bestCandidatePath?: string;
@@ -4267,7 +4268,7 @@ interface RunTaskState {
     bootstrapContext?: string;
     /** Current structured marathon workflow phase (widened to string for custom workflows) */
     workflowPhase?: string;
-    /** Suggested markdown plan path for the task */
+    /** Suggested markdown artifact path for the task */
     planPath?: string;
     /** Whether the planning artifact has been written */
     planWritten?: boolean;
@@ -4611,6 +4612,7 @@ declare class AgentsEndpoint {
     private readonly TOOL_OUTPUT_INLINE_THRESHOLD;
     private offloadToolResult;
     private getDefaultPlanPath;
+    private getDefaultExternalReportPath;
     private dirnameOfCandidatePath;
     private joinCandidatePath;
     private scoreCandidatePath;

package/dist/index.js

@@ -2223,12 +2223,22 @@ function getDefaultPlanPath(taskName) {
   const slug = sanitizeTaskSlug(taskName || "task");
   return `.runtype/marathons/${slug}/plan.md`;
 }
+function getDefaultExternalReportPath(taskName) {
+  const slug = sanitizeTaskSlug(taskName || "task");
+  return `${slug}.md`;
+}
 function sanitizeTaskSlug(taskName) {
   return taskName.toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80);
 }
 
 // src/workflows/default-workflow.ts
+function isExternalTask(state) {
+  return state.workflowVariant === "external";
+}
 function hasSufficientResearchEvidence(state) {
+  if (isExternalTask(state)) {
+    return false;
+  }
   if (state.isCreationTask) {
     return (state.recentReadPaths?.length || 0) >= 1;
   }
@@ -2372,6 +2382,17 @@ var researchPhase = {
   description: "Inspect the repo and identify the correct target file",
   buildInstructions(state) {
     const planPath = state.planPath || getDefaultPlanPath(state.taskName);
+    const reportPath = state.planPath || getDefaultExternalReportPath(state.taskName);
+    if (isExternalTask(state)) {
+      return [
+        "--- Workflow Phase: Research ---",
+        "This is an external web research task, not a repository editing task.",
+        "Research the requested website or external source directly using built-in web tools first.",
+        "Do NOT inspect the local repo or search for a target file unless the user explicitly asks for local workspace changes.",
+        `Write the final markdown report to exactly: ${reportPath}`,
+        "Do NOT end with TASK_COMPLETE until that markdown file has been written."
+      ].join("\n");
+    }
     if (state.isCreationTask) {
       return [
         "--- Workflow Phase: Research ---",
@@ -2391,6 +2412,15 @@ var researchPhase = {
     ].join("\n");
   },
   buildToolGuidance(state) {
+    if (isExternalTask(state)) {
+      const reportPath = state.planPath || getDefaultExternalReportPath(state.taskName);
+      return [
+        "This is a web/external research task.",
+        "Start with built-in web tools such as firecrawl or web search, not local repo discovery tools.",
+        "Do not call search_repo, glob_files, tree_directory, list_directory, or read_file unless the user explicitly asked you to inspect local files.",
+        `Use write_file to save the final markdown report to exactly: ${reportPath}.`
+      ];
+    }
     if (state.isCreationTask) {
       return [
         "This is a creation task \u2014 you are building new files, not editing existing ones.",
@@ -2424,10 +2454,45 @@ var researchPhase = {
       `Next step: write the plan markdown to ${state.planPath} before editing the product file.`
     ].join("\n");
   },
-  interceptToolCall() {
+  interceptToolCall(toolName, _args, ctx) {
+    if (!isExternalTask(ctx.state)) {
+      return void 0;
+    }
+    const normalizedPathArg = typeof _args.path === "string" && _args.path.trim() ? ctx.normalizePath(String(_args.path)) : void 0;
+    const normalizedReportPath = ctx.normalizePath(
+      ctx.state.planPath || getDefaultExternalReportPath(ctx.state.taskName)
+    );
+    if (ctx.isDiscoveryTool(toolName) || toolName === "read_file" || toolName === "restore_file_checkpoint") {
+      return [
+        `Blocked by marathon external research guard: ${toolName} is disabled for web research tasks.`,
+        "Research the requested external source with built-in web tools instead.",
+        "Use local file tools only if the user explicitly asked for workspace inspection or if you are saving the final deliverable."
+      ].join(" ");
+    }
+    if (toolName === "write_file" && normalizedPathArg && normalizedPathArg !== normalizedReportPath) {
+      return [
+        `Blocked by marathon external research guard: write_file must target "${normalizedReportPath}".`,
+        "Save the final markdown report to the required workspace path before TASK_COMPLETE."
+      ].join(" ");
+    }
     return void 0;
   },
   buildRecoveryMessage(state) {
+    if (isExternalTask(state)) {
+      const recent2 = state.sessions.slice(-2);
+      const reportPath = state.planPath || getDefaultExternalReportPath(state.taskName);
+      if (recent2.length < 2 || !recent2.every((session) => session.wroteFiles === false)) {
+        return void 0;
+      }
+      const repeatedSameActions2 = hasRepeatedSameActions(state.sessions);
+      return [
+        "Recovery instruction:",
+        "This web research task is missing its required markdown artifact.",
+        `Your next action must be write_file to "${reportPath}" with the final findings in markdown.`,
+        "Do not end with TASK_COMPLETE until that file has been written.",
+        ...repeatedSameActions2 ? ["You are repeating the same actions; break the loop by writing the final report now."] : []
+      ].join("\n");
+    }
     const recent = state.sessions.slice(-2);
     const normalizedPlanPath = typeof state.planPath === "string" && state.planPath.trim() ? normalizeCandidatePath(state.planPath) : void 0;
     const recentPlanOnlyLoop = Boolean(normalizedPlanPath) && recent.length === 2 && recent.every((session) => {
@@ -2471,6 +2536,12 @@ var researchPhase = {
     ].join("\n");
   },
   shouldForceEndTurn(snapshot, ctx) {
+    if (isExternalTask(ctx.state)) {
+      if (ctx.isDiscoveryTool(snapshot.toolName) && snapshot.actionKeyCount >= 2) {
+        return "this web research task is looping on local repo discovery instead of using external tools";
+      }
+      return void 0;
+    }
     const state = ctx.state;
     const sufficientResearch = hasSufficientResearchEvidence(state);
     if (sufficientResearch && snapshot.discoveryPauseCount >= 12) {
@@ -2483,6 +2554,12 @@ var researchPhase = {
       return "this session exceeded the discovery-tool budget without ending the turn";
     }
     return void 0;
+  },
+  canAcceptCompletion(state, trace) {
+    if (!isExternalTask(state)) {
+      return true;
+    }
+    return Boolean(state.planWritten || trace.planWritten);
   }
 };
 var planningPhase = {
@@ -2709,6 +2786,65 @@ var executionPhase = {
 };
 function classifyVariant(message) {
   const lower = message.toLowerCase();
+  const externalVerbs = [
+    "fetch",
+    "browse",
+    "scrape",
+    "crawl",
+    "download",
+    "visit",
+    "navigate to",
+    "go to",
+    "open the",
+    "look up",
+    "search for",
+    "find out",
+    "check out",
+    "pull up"
+  ];
+  const externalTargets = [
+    "http://",
+    "https://",
+    "www.",
+    ".com",
+    ".org",
+    ".io",
+    ".net",
+    ".dev",
+    "website",
+    "webpage",
+    "web page",
+    "home page",
+    "homepage",
+    "hacker news",
+    "reddit",
+    "twitter",
+    "github.com",
+    "firecrawl",
+    "exa_search"
+  ];
+  const hasExternalVerb = externalVerbs.some((v) => lower.includes(v));
+  const hasExternalTarget = externalTargets.some((t) => lower.includes(t));
+  const modificationVerbs = [
+    "fix",
+    "update",
+    "change",
+    "modify",
+    "edit",
+    "refactor",
+    "improve",
+    "add to",
+    "remove",
+    "delete",
+    "rename",
+    "migrate"
+  ];
+  const hasModificationVerb = modificationVerbs.some(
+    (v) => lower.startsWith(v) || new RegExp(`\\b${v}\\b`).test(lower)
+  );
+  if (hasExternalVerb && hasExternalTarget && !hasModificationVerb) {
+    return "external";
+  }
   const creationPatterns = [
     /^create\b/,
     /^build\b/,
@@ -2729,30 +2865,13 @@ function classifyVariant(message) {
     /^new\b/
   ];
   const hasCreationStart = creationPatterns.some((p) => p.test(lower));
-  const modificationVerbs = [
-    "fix",
-    "update",
-    "change",
-    "modify",
-    "edit",
-    "refactor",
-    "improve",
-    "add to",
-    "remove",
-    "delete",
-    "rename",
-    "migrate"
-  ];
-  const hasModificationVerb = modificationVerbs.some(
-    (v) => lower.startsWith(v) || new RegExp(`\\b${v}\\b`).test(lower)
-  );
   if (hasCreationStart && !hasModificationVerb) {
     return "create";
   }
   return "modify";
 }
 async function generateBootstrapContext(message, localTools, variant) {
-  if (variant === "create") return void 0;
+  if (variant === "create" || variant === "external") return void 0;
   if (!localTools) return void 0;
   const searchTool = localTools.search_repo;
   const globTool = localTools.glob_files;
@@ -2788,7 +2907,7 @@ async function generateBootstrapContext(message, localTools, variant) {
   return ["Bootstrap repo hints:", ...lines].join("\n").slice(0, 1500);
 }
 function buildCandidateBlock(state) {
-  if (!state.bestCandidatePath || state.isCreationTask) return "";
+  if (!state.bestCandidatePath || state.isCreationTask || isExternalTask(state)) return "";
   return [
     "",
     "--- Best Candidate ---",
@@ -4875,8 +4994,10 @@ var _AgentsEndpoint = class _AgentsEndpoint {
     return `[${toolName} output (${resultStr.length} chars) saved to ${filePath} \u2014 use read_file to retrieve if needed]`;
   }
   getDefaultPlanPath(taskName) {
-    const slug = this.sanitizeTaskSlug(taskName || "task");
-    return `.runtype/marathons/${slug}/plan.md`;
+    return getDefaultPlanPath(taskName);
+  }
+  getDefaultExternalReportPath(taskName) {
+    return getDefaultExternalReportPath(taskName);
   }
   dirnameOfCandidatePath(candidatePath) {
     const normalized = this.normalizeCandidatePath(candidatePath);
@@ -4982,7 +5103,10 @@ var _AgentsEndpoint = class _AgentsEndpoint {
   }
   sanitizeResumeState(resumeState, taskName) {
     if (!resumeState) return void 0;
-    const planPath = typeof resumeState.planPath === "string" && resumeState.planPath.trim() ? this.normalizeCandidatePath(resumeState.planPath) : this.getDefaultPlanPath(taskName);
+    const workflowVariant = resumeState.workflowVariant;
+    const defaultPlanPath = workflowVariant === "external" ? this.getDefaultExternalReportPath(taskName) : this.getDefaultPlanPath(taskName);
+    const planPath = typeof resumeState.planPath === "string" && resumeState.planPath.trim() ? this.normalizeCandidatePath(resumeState.planPath) : defaultPlanPath;
+    const migratedPlanPath = workflowVariant === "external" && planPath === this.getDefaultPlanPath(taskName) ? this.getDefaultExternalReportPath(taskName) : planPath;
     const candidatePaths = this.dedupeNormalizedCandidatePaths(resumeState.candidatePaths);
     const recentReadPaths = this.dedupeNormalizedCandidatePaths(resumeState.recentReadPaths);
     const normalizedBestCandidatePath = typeof resumeState.bestCandidatePath === "string" && resumeState.bestCandidatePath.trim() ? this.normalizeCandidatePath(resumeState.bestCandidatePath) : void 0;
@@ -4993,7 +5117,7 @@ var _AgentsEndpoint = class _AgentsEndpoint {
     return {
       ...resumeState,
       workflowPhase,
-      planPath,
+      planPath: migratedPlanPath,
       planWritten: Boolean(resumeState.planWritten),
       bestCandidatePath,
       bestCandidateReason: bestCandidatePath ? resumeState.bestCandidateReason : void 0,
@@ -5419,13 +5543,14 @@ var _AgentsEndpoint = class _AgentsEndpoint {
     const taskName = typeof options.trackProgress === "string" ? options.trackProgress : options.trackProgress ? `${agent.name} task` : "";
     const resolvedTaskName = taskName || `${agent.name} task`;
     const seededResumeState = this.sanitizeResumeState(options.resumeState, resolvedTaskName);
+    const classifiedVariant = seededResumeState?.workflowVariant ?? workflow.classifyVariant?.(options.message);
     const state = {
       agentId: id,
       agentName: agent.name,
       taskName: resolvedTaskName,
       status: "running",
       workflowPhase: seededResumeState?.workflowPhase || workflow.phases[0]?.name || "research",
-      planPath: seededResumeState?.planPath || this.getDefaultPlanPath(resolvedTaskName),
+      planPath: seededResumeState?.planPath || (classifiedVariant === "external" ? this.getDefaultExternalReportPath(resolvedTaskName) : this.getDefaultPlanPath(resolvedTaskName)),
       planWritten: seededResumeState?.planWritten || false,
       bestCandidateNeedsVerification: seededResumeState?.bestCandidateNeedsVerification || false,
       bestCandidateVerified: seededResumeState?.bestCandidateVerified || false,
@@ -5448,7 +5573,7 @@ var _AgentsEndpoint = class _AgentsEndpoint {
       ...seededResumeState?.recentReadPaths ? { recentReadPaths: seededResumeState.recentReadPaths } : {},
       ...seededResumeState?.recentActionKeys ? { recentActionKeys: seededResumeState.recentActionKeys } : {}
     };
-    state.workflowVariant = seededResumeState?.workflowVariant ?? workflow.classifyVariant?.(options.message);
+    state.workflowVariant = classifiedVariant;
     state.isCreationTask = seededResumeState?.isCreationTask ?? state.workflowVariant === "create";
     this.updateWorkflowPhase(state, this.createEmptyToolTrace(), workflow);
     let recordId;
@@ -5466,7 +5591,7 @@ var _AgentsEndpoint = class _AgentsEndpoint {
         state.bootstrapContext = await this.generateBootstrapDiscoveryContext(
           options.message,
           options.localTools,
-          state.isCreationTask
+          state.isCreationTask || state.workflowVariant === "external"
         );
       }
       const bootstrapCandidate = this.extractBestCandidateFromBootstrapContext(state.bootstrapContext);
@@ -5692,13 +5817,15 @@ var _AgentsEndpoint = class _AgentsEndpoint {
       if (state.sessions.length > 50) {
         state.sessions = state.sessions.slice(-50);
       }
-      if (sessionResult.stopReason === "complete") {
+      const detectedTaskCompletion = this.detectTaskCompletion(sessionResult.result);
+      const acceptedTaskCompletion = detectedTaskCompletion && this.canAcceptTaskCompletion(sessionResult.result, state, sessionTrace, workflow);
+      if (sessionResult.stopReason === "complete" && !detectedTaskCompletion) {
         state.status = "complete";
       } else if (sessionResult.stopReason === "error") {
         state.status = "error";
       } else if (sessionResult.stopReason === "max_cost") {
         state.status = "budget_exceeded";
-      } else if (this.canAcceptTaskCompletion(sessionResult.result, state, sessionTrace, workflow)) {
+      } else if (acceptedTaskCompletion) {
         state.status = "complete";
       } else if (maxCost && state.totalCost >= maxCost) {
         state.status = "budget_exceeded";
@@ -6021,7 +6148,7 @@ Do NOT redo any of the above work.`
       "",
       "Changed Files / Candidate Paths",
       ...candidatePaths.length > 0 ? candidatePaths.map((candidatePath) => `- ${candidatePath}`) : ["- No candidate paths recorded yet."],
-      ...state.planPath ? [`- Plan path: ${state.planPath}`] : [],
+      ...state.planPath ? [`- ${state.workflowVariant === "external" ? "Report path" : "Plan path"}: ${state.planPath}`] : [],
       ...state.planWritten ? ["- Planning artifact has been written."] : [],
       ...state.bestCandidateReason ? [`- Best candidate rationale: ${state.bestCandidateReason}`] : [],
       "",
@@ -6112,25 +6239,34 @@ Do NOT redo any of the above work.`
     const currentPhase = wf.phases.find((p) => p.name === state.workflowPhase);
     const toolGuidanceLines = currentPhase?.buildToolGuidance(state) ?? [];
     const isDeployWorkflow = wf.name === "deploy";
+    const isExternalTask2 = state.workflowVariant === "external";
+    const requiredArtifactPath = state.planPath;
     const localToolsBlock = localToolNames?.length ? [
       "",
       "--- Local Tools ---",
       `You have access to tools (${localToolNames.join(", ")}) that execute directly on the user's machine.`,
-      ...isDeployWorkflow ? ["Use deploy_sandbox to deploy code and get a live preview URL."] : [
+      ...isDeployWorkflow ? ["Use deploy_sandbox to deploy code and get a live preview URL."] : isExternalTask2 ? [
+        "This is a web/external research task. Do not inspect or edit the local repository unless the user explicitly asked for workspace changes.",
+        ...requiredArtifactPath ? [`Write the final markdown findings to exactly: ${requiredArtifactPath}`] : []
+      ] : [
         "Use these tools to inspect the existing repository and make real file edits \u2014 not just code in your response."
       ],
       ...toolGuidanceLines,
-      ...isDeployWorkflow ? [] : ["Always use write_file to save your output so the user can run it immediately."]
+      ...isDeployWorkflow ? [] : isExternalTask2 ? ["Use write_file only if you want to save the final deliverable into the workspace."] : ["Always use write_file to save your output so the user can run it immediately."]
     ].join("\n") : "";
     const builtinToolNames = builtinToolIds?.map((id) => id.replace(/^builtin:/, ""));
     const builtinToolsBlock = builtinToolNames?.length ? [
       "",
       "--- Built-in Tools ---",
       `You have access to built-in tools (${builtinToolNames.join(", ")}) for web search, web scraping, image generation, and other capabilities.`,
-      "Use these tools when the task requires information from the web, generating images, or other capabilities beyond local file operations."
+      isExternalTask2 ? "This task targets an external site or source. Start with these built-in tools before considering any local file tools." : "Use these tools when the task requires information from the web, generating images, or other capabilities beyond local file operations."
     ].join("\n") : "";
     const toolsBlock = localToolsBlock + builtinToolsBlock;
-    const bootstrapBlock = state.bootstrapContext ? ["", "--- Initial Repository Discovery ---", state.bootstrapContext].join("\n") : "";
+    const bootstrapBlock = state.bootstrapContext ? [
+      "",
+      isExternalTask2 ? "--- Initial Research Context ---" : "--- Initial Repository Discovery ---",
+      state.bootstrapContext
+    ].join("\n") : "";
     const phaseBlock = ["", this.buildPhaseInstructions(state, wf)].join("\n");
     const candidateBlock = wf.buildCandidateBlock?.(state) ?? "";
     const multiSessionInstruction = `This is a multi-session task (session ${sessionIndex + 1}/${maxSessions}). When you have fully completed the task, end your response with TASK_COMPLETE on its own line.`;