@runtypelabs/sdk 4.10.0 → 4.11.0

package/dist/index.mjs

@@ -4310,6 +4310,261 @@ function sanitizeTaskSlug(taskName) {
   return taskName.toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80);
 }
 
+// src/workflows/hook-registry.ts
+var BUILTIN_NAMESPACE = "builtin";
+var HOOK_REF_PATTERN = /^[a-z0-9_-]+:[a-z0-9_-]+$/;
+function isWorkflowHookRef(value) {
+  return typeof value === "string" && HOOK_REF_PATTERN.test(value);
+}
+var registry = /* @__PURE__ */ new Map();
+function registerWorkflowHook(name, entry) {
+  if (!isWorkflowHookRef(name)) {
+    throw new Error(
+      `Invalid workflow hook name "${name}": must be "<namespace>:<id>" using lowercase letters, digits, "-" or "_" (e.g. "acme:my-completion").`
+    );
+  }
+  if (name.startsWith(`${BUILTIN_NAMESPACE}:`)) {
+    throw new Error(
+      `Cannot register "${name}": the "builtin:" namespace is reserved. Register under your own namespace and reference it from the workflow config instead.`
+    );
+  }
+  registry.set(name, entry);
+}
+function registerBuiltinWorkflowHook(name, entry) {
+  if (!name.startsWith(`${BUILTIN_NAMESPACE}:`) || !isWorkflowHookRef(name)) {
+    throw new Error(`Builtin workflow hooks must be named "builtin:<id>" (got "${name}").`);
+  }
+  if (registry.has(name)) return;
+  registry.set(name, entry);
+}
+function resolveWorkflowHook(name, expectedKind) {
+  const entry = registry.get(name);
+  if (!entry) {
+    const known = listWorkflowHooks().filter((hook) => hook.kind === expectedKind).map((hook) => hook.name);
+    throw new Error(
+      `Unknown workflow hook "${name}". ` + (known.length > 0 ? `Registered '${expectedKind}' hooks: ${known.join(", ")}.` : `No '${expectedKind}' hooks are registered.`) + " Custom hooks must be registered (e.g. via a playbook plugin) before the workflow is compiled."
+    );
+  }
+  if (entry.kind !== expectedKind) {
+    throw new Error(
+      `Workflow hook "${name}" is registered as '${entry.kind}' but referenced from a '${expectedKind}' slot.`
+    );
+  }
+  return entry.fn;
+}
+function listWorkflowHooks() {
+  return [...registry.entries()].map(([name, entry]) => ({ name, kind: entry.kind }));
+}
+function unregisterWorkflowHook(name) {
+  if (name.startsWith(`${BUILTIN_NAMESPACE}:`)) return false;
+  return registry.delete(name);
+}
+
+// src/workflows/workflow-config.ts
+var DISCOVERY_TOOLS = /* @__PURE__ */ new Set([
+  "search_repo",
+  "glob_files",
+  "tree_directory",
+  "list_directory"
+]);
+var DEFAULT_RECOVERY_AFTER_EMPTY_SESSIONS = 2;
+function definePlaybook(playbook) {
+  return playbook;
+}
+function interpolateWorkflowTemplate(template, state) {
+  return template.replace(/\{\{(\w+)\}\}/g, (_match, key) => {
+    const value = state[key];
+    if (value === void 0 || value === null) return `{{${key}}}`;
+    return String(value);
+  });
+}
+function buildIsComplete(criteria, configName, milestoneName) {
+  if (!criteria) return () => false;
+  switch (criteria.type) {
+    case "evidence":
+      return (ctx) => {
+        const minFiles = criteria.minReadFiles ?? 1;
+        return (ctx.state.recentReadPaths?.length ?? 0) >= minFiles;
+      };
+    case "sessions": {
+      let baselineSessionCount;
+      return (ctx) => {
+        const minSessions = criteria.minSessions ?? 1;
+        if (baselineSessionCount === void 0) {
+          baselineSessionCount = ctx.state.sessions.length;
+        }
+        return ctx.state.sessions.length - baselineSessionCount >= minSessions;
+      };
+    }
+    case "planWritten":
+      return (ctx) => {
+        return ctx.trace.planWritten;
+      };
+    case "never":
+      return () => false;
+    default: {
+      if (isWorkflowHookRef(criteria.type)) {
+        return resolveWorkflowHook(criteria.type, "completion");
+      }
+      throw new Error(
+        `Workflow config '${configName}': milestone '${milestoneName}' has unknown completionCriteria.type "${criteria.type}" (expected evidence | sessions | planWritten | never, or a 'completion' hook reference).`
+      );
+    }
+  }
+}
+function buildPolicyIntercept(policy, configName, deps) {
+  if (!policy.blockedTools?.length && !policy.blockDiscoveryTools && !policy.allowedReadGlobs?.length && !policy.allowedWriteGlobs?.length && !policy.requirePlanBeforeWrite) {
+    return void 0;
+  }
+  const blockedSet = new Set(
+    (policy.blockedTools ?? []).map((t) => t.trim()).filter(Boolean)
+  );
+  const readGlobs = policy.allowedReadGlobs ?? [];
+  const writeGlobs = policy.allowedWriteGlobs ?? [];
+  const matchPathGlobs = deps.matchPathGlobs;
+  if ((readGlobs.length > 0 || writeGlobs.length > 0) && !matchPathGlobs) {
+    throw new Error(
+      `Workflow config '${configName}': policy uses allowedReadGlobs/allowedWriteGlobs but no glob matcher was provided to compileWorkflowConfig (pass deps.matchPathGlobs).`
+    );
+  }
+  return (toolName, args, ctx) => {
+    if (blockedSet.has(toolName)) {
+      return `Blocked by playbook policy: ${toolName} is not allowed for this task.`;
+    }
+    if (policy.blockDiscoveryTools && DISCOVERY_TOOLS.has(toolName)) {
+      return `Blocked by playbook policy: discovery tools are disabled for this task.`;
+    }
+    const pathArg = typeof args.path === "string" && args.path.trim() ? ctx.normalizePath(String(args.path)) : void 0;
+    if (pathArg) {
+      const isWrite = toolName === "write_file" || toolName === "restore_file_checkpoint";
+      const isRead = toolName === "read_file";
+      if (isRead && readGlobs.length > 0) {
+        const allowed = matchPathGlobs(pathArg, readGlobs);
+        if (!allowed) {
+          return `Blocked by playbook policy: ${toolName} path "${pathArg}" is outside allowed read globs: ${readGlobs.join(", ")}`;
+        }
+      }
+      if (isWrite && writeGlobs.length > 0) {
+        const planPath = ctx.state.planPath ? ctx.normalizePath(ctx.state.planPath) : void 0;
+        if (planPath && pathArg === planPath) {
+        } else {
+          const allowed = matchPathGlobs(pathArg, writeGlobs);
+          if (!allowed) {
+            return `Blocked by playbook policy: ${toolName} path "${pathArg}" is outside allowed write globs: ${writeGlobs.join(", ")}`;
+          }
+        }
+      }
+      if (isWrite && policy.requirePlanBeforeWrite && !ctx.state.planWritten && !ctx.trace.planWritten) {
+        const planPath = ctx.state.planPath ? ctx.normalizePath(ctx.state.planPath) : void 0;
+        if (!planPath || pathArg !== planPath) {
+          return `Blocked by playbook policy: write the plan before creating other files.`;
+        }
+      }
+    }
+    return void 0;
+  };
+}
+function buildPolicyGuidance(policy) {
+  if (!policy) return [];
+  const lines = [];
+  if (policy.requirePlanBeforeWrite) {
+    lines.push(
+      "Policy: write the plan file before any other file. Once the plan is written, other writes are allowed in the same turn."
+    );
+  }
+  if (policy.allowedWriteGlobs?.length) {
+    lines.push(
+      `Policy: file writes are only allowed for paths matching: ${policy.allowedWriteGlobs.join(", ")} (the plan file is always allowed).`
+    );
+  }
+  if (policy.outputRoot) {
+    lines.push(`Policy: create new files under "${policy.outputRoot.replace(/\/$/, "")}/".`);
+  }
+  if (policy.allowedReadGlobs?.length) {
+    lines.push(
+      `Policy: file reads are only allowed for paths matching: ${policy.allowedReadGlobs.join(", ")}.`
+    );
+  }
+  if (policy.blockDiscoveryTools) {
+    lines.push(
+      "Policy: broad discovery tools (search_repo, glob_files, tree_directory, list_directory) are disabled for this task."
+    );
+  }
+  if (policy.blockedTools?.length) {
+    lines.push(`Policy: these tools are disabled for this task: ${policy.blockedTools.join(", ")}.`);
+  }
+  return lines;
+}
+function resolveSlotHook(value, kind) {
+  if (value === void 0) return void 0;
+  if (typeof value === "function") return value;
+  return resolveWorkflowHook(value, kind);
+}
+function compileMilestone(milestone, config, policyIntercept, policyGuidance) {
+  const buildInstructions = typeof milestone.instructions === "function" ? milestone.instructions : isWorkflowHookRef(milestone.instructions) ? resolveWorkflowHook(milestone.instructions, "instructions") : (state) => {
+    const header = `--- Workflow Phase: ${milestone.name} ---`;
+    const desc = milestone.description ? `
+${milestone.description}` : "";
+    const instructions = interpolateWorkflowTemplate(
+      milestone.instructions,
+      state
+    );
+    return `${header}${desc}
+${instructions}`;
+  };
+  const guidanceHook = typeof milestone.toolGuidance === "function" ? milestone.toolGuidance : milestone.toolGuidance !== void 0 && isWorkflowHookRef(milestone.toolGuidance) ? resolveWorkflowHook(milestone.toolGuidance, "toolGuidance") : void 0;
+  const buildToolGuidance = (state) => {
+    const base = guidanceHook ? guidanceHook(state) : milestone.toolGuidance ?? [];
+    return policyGuidance.length > 0 ? [...base, ...policyGuidance] : base;
+  };
+  const customIntercept = resolveSlotHook(milestone.intercept, "intercept");
+  const interceptToolCall = policyIntercept && customIntercept ? (toolName, args, ctx) => policyIntercept(toolName, args, ctx) ?? customIntercept(toolName, args, ctx) : policyIntercept ?? customIntercept;
+  const transitionHook = typeof milestone.transitionSummary === "function" ? milestone.transitionSummary : milestone.transitionSummary !== void 0 && isWorkflowHookRef(milestone.transitionSummary) ? resolveWorkflowHook(milestone.transitionSummary, "transitionSummary") : void 0;
+  const buildTransitionSummary = milestone.transitionSummary === void 0 ? void 0 : transitionHook ?? ((state, nextPhaseName) => interpolateWorkflowTemplate(milestone.transitionSummary, state).replace(
+    /\{\{nextPhase\}\}/g,
+    nextPhaseName
+  ));
+  const recoveryHook = typeof milestone.recovery === "function" ? milestone.recovery : milestone.recovery !== void 0 && isWorkflowHookRef(milestone.recovery) ? resolveWorkflowHook(milestone.recovery, "recovery") : void 0;
+  const buildRecoveryMessage = milestone.recovery === void 0 ? void 0 : recoveryHook ?? ((state) => {
+    const inline = milestone.recovery;
+    const threshold = inline.afterEmptySessions ?? DEFAULT_RECOVERY_AFTER_EMPTY_SESSIONS;
+    if ((state.consecutiveEmptySessions ?? 0) < threshold) return void 0;
+    return interpolateWorkflowTemplate(inline.message, state);
+  });
+  const canAcceptCompletion = milestone.canAcceptCompletion === void 0 ? void 0 : typeof milestone.canAcceptCompletion === "function" ? milestone.canAcceptCompletion : isWorkflowHookRef(milestone.canAcceptCompletion) ? resolveWorkflowHook(milestone.canAcceptCompletion, "acceptCompletion") : () => milestone.canAcceptCompletion;
+  const isComplete = typeof milestone.completionCriteria === "function" ? milestone.completionCriteria : buildIsComplete(milestone.completionCriteria, config.name, milestone.name);
+  return {
+    name: milestone.name,
+    description: milestone.description,
+    buildInstructions,
+    buildToolGuidance,
+    isComplete,
+    ...interceptToolCall ? { interceptToolCall } : {},
+    ...buildTransitionSummary ? { buildTransitionSummary } : {},
+    ...buildRecoveryMessage ? { buildRecoveryMessage } : {},
+    ...milestone.forceEndTurn ? { shouldForceEndTurn: resolveSlotHook(milestone.forceEndTurn, "forceEndTurn") } : {},
+    ...canAcceptCompletion ? { canAcceptCompletion } : {}
+  };
+}
+function compileWorkflowConfig(config, deps = {}) {
+  const policyIntercept = config.policy ? buildPolicyIntercept(config.policy, config.name, deps) : void 0;
+  const policyGuidance = buildPolicyGuidance(config.policy);
+  const phases = config.milestones.map(
+    (milestone) => compileMilestone(milestone, config, policyIntercept, policyGuidance)
+  );
+  const classifyVariant4 = resolveSlotHook(config.classifyVariant, "classify");
+  const generateBootstrapContext2 = resolveSlotHook(config.bootstrap, "bootstrap");
+  const buildCandidateBlock2 = resolveSlotHook(config.candidateBlock, "candidateBlock");
+  return {
+    name: config.name,
+    phases,
+    ...config.stallPolicy ? { stallPolicy: config.stallPolicy } : {},
+    ...classifyVariant4 ? { classifyVariant: classifyVariant4 } : {},
+    ...generateBootstrapContext2 ? { generateBootstrapContext: generateBootstrapContext2 } : {},
+    ...buildCandidateBlock2 ? { buildCandidateBlock: buildCandidateBlock2 } : {}
+  };
+}
+
 // src/workflows/default-workflow.ts
 function isExternalTask(state) {
   return state.workflowVariant === "external";
@@ -4459,6 +4714,45 @@ function summarizeTextBlock(value, maxLines = 4) {
   if (!text) return "";
   return text.split("\n").map((line) => line.trim()).filter(Boolean).slice(0, maxLines).join(" | ").slice(0, 240);
 }
+function interceptProductWriteTarget(toolName, normalizedPathArg, ctx, guardLabel) {
+  const normalizedPlanPath = ctx.state.planPath ? ctx.normalizePath(ctx.state.planPath) : void 0;
+  const normalizedBestCandidatePath = ctx.state.bestCandidatePath ? ctx.normalizePath(ctx.state.bestCandidatePath) : void 0;
+  if (!ctx.state.isCreationTask && normalizedPathArg && normalizedPathArg !== normalizedPlanPath) {
+    const allowedWriteTargets = new Set(
+      [
+        normalizedPlanPath,
+        normalizedBestCandidatePath,
+        ...(ctx.state.recentReadPaths || []).map((readPath) => ctx.normalizePath(readPath)),
+        ...ctx.trace.readPaths.map((readPath) => ctx.normalizePath(readPath))
+      ].filter((value) => Boolean(value))
+    );
+    if (!allowedWriteTargets.has(normalizedPathArg)) {
+      return [
+        `Blocked by marathon ${guardLabel}: ${toolName} is limited to the confirmed target, the plan file, or files already discovered/read for this task.`,
+        `Do not create scratch files like "${normalizedPathArg}".`,
+        normalizedBestCandidatePath ? `Edit "${normalizedBestCandidatePath}" or another previously discovered repo file instead.` : "Read the current target file before writing."
+      ].join(" ");
+    }
+  }
+  if (ctx.state.isCreationTask && normalizedPathArg && normalizedPathArg !== normalizedPlanPath) {
+    const outputRoot = ctx.state.outputRoot ? ctx.state.outputRoot.trim().replace(/\\/g, "/").replace(/\/+/g, "/").replace(/\/$/, "") || void 0 : void 0;
+    if (!outputRoot) {
+      return [
+        `Blocked by marathon ${guardLabel}: creation tasks require outputRoot. Writes outside the plan are not allowed.`,
+        `Plan path: "${normalizedPlanPath}". Create files only under the configured output root.`
+      ].join(" ");
+    }
+    const rootPrefix = outputRoot + "/";
+    const isUnderRoot = normalizedPathArg === outputRoot || normalizedPathArg.startsWith(rootPrefix);
+    if (!isUnderRoot) {
+      return [
+        `Blocked by marathon ${guardLabel}: ${toolName} must target the plan or paths under outputRoot "${outputRoot}/".`,
+        `"${normalizedPathArg}" is outside the allowed output root.`
+      ].join(" ");
+    }
+  }
+  return void 0;
+}
 var researchPhase = {
   name: "research",
   description: "Inspect the repo and identify the correct target file",
@@ -4543,11 +4837,15 @@ var researchPhase = {
         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(" ");
+          const planWritten = ctx.trace.planWritten || Boolean(ctx.state.planWritten);
+          if (!planWritten) {
+            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 interceptProductWriteTarget(toolName, normalizedPathArg2, ctx, "research guard");
         }
       }
       return void 0;
@@ -4670,19 +4968,24 @@ var planningPhase = {
         "Research is complete. Write the implementation plan for building this from scratch.",
         `Write the plan markdown to exactly: ${planPath}`,
         "List the files you will create, their locations, purpose, and any dependencies to install.",
+        ...state.outputRoot ? [
+          `All new files must be created under "${state.outputRoot}" \u2014 writes outside that directory are blocked, so plan every file location inside it.`
+        ] : [],
         'Include a "Verification steps" section listing the concrete checks you will run before TASK_COMPLETE.',
-        "If the plan already exists, update that same plan file instead of creating a different one."
+        "If the plan already exists, update that same plan file instead of creating a different one.",
+        "Once the plan is written, you may begin creating the planned files in the same turn."
       ].join("\n");
     }
     return [
       "--- Workflow Phase: Planning ---",
       "Research is complete. Your current job is to write the implementation plan before any product-file edits.",
       `Write the plan markdown to exactly: ${planPath}`,
-      "Do NOT edit the target product file yet.",
+      "Do NOT edit the target product file before the plan exists.",
       "The plan should summarize UX findings, explain why the current best candidate is the right file, and list concrete execution steps.",
       'The plan must include a "Preserve existing functionality" section that lists current behaviors, linked files, integrations, and constraints that must keep working.',
       'The plan must include a "Verification steps" section listing the concrete checks you will run before TASK_COMPLETE.',
-      "If the plan already exists, update that same plan file instead of creating a different one."
+      "If the plan already exists, update that same plan file instead of creating a different one.",
+      "Once the plan is written, you may begin editing the target file in the same turn."
     ].join("\n");
   },
   buildToolGuidance(state) {
@@ -4710,10 +5013,14 @@ var planningPhase = {
     const normalizedPlanPath = ctx.state.planPath ? ctx.normalizePath(ctx.state.planPath) : void 0;
     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.`,
-        `Write the plan to "${normalizedPlanPath}" before editing any product files.`
-      ].join(" ");
+      const planWritten = ctx.trace.planWritten || Boolean(ctx.state.planWritten);
+      if (!planWritten) {
+        return [
+          `Blocked by marathon planning guard: ${toolName} must target the exact plan path during planning.`,
+          `Write the plan to "${normalizedPlanPath}" before editing any product files.`
+        ].join(" ");
+      }
+      return interceptProductWriteTarget(toolName, normalizedPathArg, ctx, "planning guard");
     }
     return void 0;
   },
@@ -4773,6 +5080,9 @@ var executionPhase = {
   },
   buildToolGuidance(state) {
     return [
+      ...state.isCreationTask && state.outputRoot ? [
+        `Creation guard: create new files under "${state.outputRoot}". Writes outside it are blocked \u2014 the plan file is the only exception.`
+      ] : [],
       ...state.bestCandidatePath ? [
         `Execution-phase guard: broad discovery tools (search_repo, glob_files, tree_directory, list_directory) are locked while executing against "${state.bestCandidatePath}".`
       ] : [
@@ -4814,40 +5124,13 @@ var executionPhase = {
           `After that, you may update "${normalizedPlanPath}" with progress.`
         ].join(" ");
       }
-      if (!ctx.state.isCreationTask && normalizedPathArg && normalizedPathArg !== normalizedPlanPath) {
-        const allowedWriteTargets = new Set(
-          [
-            normalizedPlanPath,
-            normalizedBestCandidatePath,
-            ...(ctx.state.recentReadPaths || []).map((readPath) => ctx.normalizePath(readPath)),
-            ...ctx.trace.readPaths.map((readPath) => ctx.normalizePath(readPath))
-          ].filter((value) => Boolean(value))
-        );
-        if (!allowedWriteTargets.has(normalizedPathArg)) {
-          return [
-            `Blocked by marathon execution guard: ${toolName} is limited to the confirmed target, the plan file, or files already discovered/read for this task.`,
-            `Do not create scratch files like "${normalizedPathArg}".`,
-            normalizedBestCandidatePath ? `Edit "${normalizedBestCandidatePath}" or another previously discovered repo file instead.` : "Read the current target file before writing."
-          ].join(" ");
-        }
-      }
-      if (ctx.state.isCreationTask && normalizedPathArg && normalizedPathArg !== normalizedPlanPath) {
-        const outputRoot = ctx.state.outputRoot ? ctx.state.outputRoot.trim().replace(/\\/g, "/").replace(/\/+/g, "/").replace(/\/$/, "") || void 0 : void 0;
-        if (!outputRoot) {
-          return [
-            `Blocked by marathon execution guard: creation tasks require outputRoot. Writes outside the plan are not allowed.`,
-            `Plan path: "${normalizedPlanPath}". Create files only under the configured output root.`
-          ].join(" ");
-        }
-        const rootPrefix = outputRoot + "/";
-        const isUnderRoot = normalizedPathArg === outputRoot || normalizedPathArg.startsWith(rootPrefix);
-        if (!isUnderRoot) {
-          return [
-            `Blocked by marathon execution guard: ${toolName} must target the plan or paths under outputRoot "${outputRoot}/".`,
-            `"${normalizedPathArg}" is outside the allowed output root.`
-          ].join(" ");
-        }
-      }
+      const writeTargetBlock = interceptProductWriteTarget(
+        toolName,
+        normalizedPathArg,
+        ctx,
+        "execution guard"
+      );
+      if (writeTargetBlock) return writeTargetBlock;
     }
     return void 0;
   },
@@ -5080,13 +5363,163 @@ function buildCandidateBlock(state) {
     ...state.bestCandidateReason ? [`Why: ${state.bestCandidateReason}`] : []
   ].join("\n");
 }
-var defaultWorkflow = {
+var builtinHooksRegistered = false;
+function ensureDefaultWorkflowHooks() {
+  if (builtinHooksRegistered) return;
+  builtinHooksRegistered = true;
+  registerBuiltinWorkflowHook("builtin:classify-task-variant", {
+    kind: "classify",
+    fn: classifyVariant
+  });
+  registerBuiltinWorkflowHook("builtin:repo-bootstrap-discovery", {
+    kind: "bootstrap",
+    fn: generateBootstrapContext
+  });
+  registerBuiltinWorkflowHook("builtin:best-candidate-block", {
+    kind: "candidateBlock",
+    fn: buildCandidateBlock
+  });
+  registerBuiltinWorkflowHook("builtin:research-instructions", {
+    kind: "instructions",
+    fn: researchPhase.buildInstructions
+  });
+  registerBuiltinWorkflowHook("builtin:research-tool-guidance", {
+    kind: "toolGuidance",
+    fn: researchPhase.buildToolGuidance
+  });
+  registerBuiltinWorkflowHook("builtin:research-complete", {
+    kind: "completion",
+    fn: researchPhase.isComplete
+  });
+  registerBuiltinWorkflowHook("builtin:research-transition-summary", {
+    kind: "transitionSummary",
+    fn: researchPhase.buildTransitionSummary
+  });
+  registerBuiltinWorkflowHook("builtin:research-guard", {
+    kind: "intercept",
+    fn: researchPhase.interceptToolCall
+  });
+  registerBuiltinWorkflowHook("builtin:research-recovery", {
+    kind: "recovery",
+    fn: researchPhase.buildRecoveryMessage
+  });
+  registerBuiltinWorkflowHook("builtin:research-force-end-turn", {
+    kind: "forceEndTurn",
+    fn: researchPhase.shouldForceEndTurn
+  });
+  registerBuiltinWorkflowHook("builtin:research-accept-completion", {
+    kind: "acceptCompletion",
+    fn: researchPhase.canAcceptCompletion
+  });
+  registerBuiltinWorkflowHook("builtin:planning-instructions", {
+    kind: "instructions",
+    fn: planningPhase.buildInstructions
+  });
+  registerBuiltinWorkflowHook("builtin:planning-tool-guidance", {
+    kind: "toolGuidance",
+    fn: planningPhase.buildToolGuidance
+  });
+  registerBuiltinWorkflowHook("builtin:planning-complete", {
+    kind: "completion",
+    fn: planningPhase.isComplete
+  });
+  registerBuiltinWorkflowHook("builtin:planning-transition-summary", {
+    kind: "transitionSummary",
+    fn: planningPhase.buildTransitionSummary
+  });
+  registerBuiltinWorkflowHook("builtin:planning-guard", {
+    kind: "intercept",
+    fn: planningPhase.interceptToolCall
+  });
+  registerBuiltinWorkflowHook("builtin:planning-recovery", {
+    kind: "recovery",
+    fn: planningPhase.buildRecoveryMessage
+  });
+  registerBuiltinWorkflowHook("builtin:planning-force-end-turn", {
+    kind: "forceEndTurn",
+    fn: planningPhase.shouldForceEndTurn
+  });
+  registerBuiltinWorkflowHook("builtin:execution-instructions", {
+    kind: "instructions",
+    fn: executionPhase.buildInstructions
+  });
+  registerBuiltinWorkflowHook("builtin:execution-tool-guidance", {
+    kind: "toolGuidance",
+    fn: executionPhase.buildToolGuidance
+  });
+  registerBuiltinWorkflowHook("builtin:execution-guard", {
+    kind: "intercept",
+    fn: executionPhase.interceptToolCall
+  });
+  registerBuiltinWorkflowHook("builtin:execution-recovery", {
+    kind: "recovery",
+    fn: executionPhase.buildRecoveryMessage
+  });
+  registerBuiltinWorkflowHook("builtin:execution-force-end-turn", {
+    kind: "forceEndTurn",
+    fn: executionPhase.shouldForceEndTurn
+  });
+  registerBuiltinWorkflowHook("builtin:execution-accept-completion", {
+    kind: "acceptCompletion",
+    fn: executionPhase.canAcceptCompletion
+  });
+}
+var defaultWorkflowConfig = {
   name: "default",
-  phases: [researchPhase, planningPhase, executionPhase],
-  classifyVariant,
-  generateBootstrapContext,
-  buildCandidateBlock
+  // Empty-session escalation. The counter only counts tool actions, so
+  // narration-only sessions ("I'll create the files now" with no tool calls)
+  // escalate here even though the phase recovery conditions keyed on
+  // hadTextOutput skip them: nudge after the first actionless session, signal
+  // model escalation after the second (a no-op unless the caller configured a
+  // fallback model), and stop as 'stalled' after the third — the same total
+  // session budget as before stallPolicy existed.
+  stallPolicy: { nudgeAfter: 1, escalateModelAfter: 2, stopAfter: 3 },
+  classifyVariant: "builtin:classify-task-variant",
+  bootstrap: "builtin:repo-bootstrap-discovery",
+  candidateBlock: "builtin:best-candidate-block",
+  milestones: [
+    {
+      name: "research",
+      description: "Inspect the repo and identify the correct target file",
+      instructions: "builtin:research-instructions",
+      toolGuidance: "builtin:research-tool-guidance",
+      completionCriteria: { type: "builtin:research-complete" },
+      intercept: "builtin:research-guard",
+      transitionSummary: "builtin:research-transition-summary",
+      recovery: "builtin:research-recovery",
+      forceEndTurn: "builtin:research-force-end-turn",
+      canAcceptCompletion: "builtin:research-accept-completion"
+    },
+    {
+      name: "planning",
+      description: "Write the implementation plan before editing product files",
+      instructions: "builtin:planning-instructions",
+      toolGuidance: "builtin:planning-tool-guidance",
+      completionCriteria: { type: "builtin:planning-complete" },
+      intercept: "builtin:planning-guard",
+      transitionSummary: "builtin:planning-transition-summary",
+      recovery: "builtin:planning-recovery",
+      forceEndTurn: "builtin:planning-force-end-turn"
+      // canAcceptCompletion intentionally absent: the hand-written planning
+      // phase never defined it, and the SDK accepts completion when the slot
+      // is undefined. Keep parity.
+    },
+    {
+      name: "execution",
+      description: "Execute the plan by editing target files",
+      instructions: "builtin:execution-instructions",
+      toolGuidance: "builtin:execution-tool-guidance",
+      // Execution never auto-advances; completion is agent-driven via TASK_COMPLETE
+      completionCriteria: { type: "never" },
+      intercept: "builtin:execution-guard",
+      recovery: "builtin:execution-recovery",
+      forceEndTurn: "builtin:execution-force-end-turn",
+      canAcceptCompletion: "builtin:execution-accept-completion"
+    }
+  ]
 };
+ensureDefaultWorkflowHooks();
+var defaultWorkflow = compileWorkflowConfig(defaultWorkflowConfig);
 
 // src/workflows/deploy-workflow.ts
 var scaffoldPhase = {
@@ -5498,6 +5931,34 @@ var gameWorkflow = {
   }
 };
 
+// src/workflows/stall-policy.ts
+var DEFAULT_STALL_STOP_AFTER = 3;
+function isPositiveInteger(value) {
+  return typeof value === "number" && Number.isInteger(value) && value >= 1;
+}
+function resolveStallStopAfter(policy) {
+  return isPositiveInteger(policy?.stopAfter) ? policy.stopAfter : DEFAULT_STALL_STOP_AFTER;
+}
+function shouldRequestModelEscalation(policy, consecutiveEmptySessions) {
+  const threshold = policy?.escalateModelAfter;
+  if (!isPositiveInteger(threshold)) return false;
+  return consecutiveEmptySessions === threshold;
+}
+function shouldInjectEmptySessionNudge(policy, consecutiveEmptySessions) {
+  const threshold = policy?.nudgeAfter;
+  if (!isPositiveInteger(threshold)) return false;
+  return consecutiveEmptySessions >= threshold;
+}
+function buildEmptySessionNudge(consecutiveEmptySessions) {
+  const sessionPhrase = consecutiveEmptySessions === 1 ? "Your previous session ended" : `Your previous ${consecutiveEmptySessions} sessions ended`;
+  return [
+    "Recovery instruction:",
+    `${sessionPhrase} without a single tool call. Describing what you plan to do does nothing \u2014 only tool calls make progress.`,
+    "Your next response MUST include at least one tool call (for example write_file, edit_file, read_file, or run_check) that advances the task.",
+    "If a previous tool call was blocked, re-read the block message and satisfy its requirement instead of ending the turn."
+  ].join("\n");
+}
+
 // src/endpoints.ts
 var FlowsEndpoint = class {
   constructor(client) {
@@ -8044,8 +8505,11 @@ var _AgentsEndpoint = class _AgentsEndpoint {
   }
   buildStuckTurnRecoveryMessage(state, workflow) {
     const currentPhase = workflow.phases.find((p) => p.name === state.workflowPhase);
-    if (currentPhase?.buildRecoveryMessage) {
-      return currentPhase.buildRecoveryMessage(state);
+    const phaseMessage = currentPhase?.buildRecoveryMessage?.(state);
+    if (phaseMessage) return phaseMessage;
+    const emptySessions = state.consecutiveEmptySessions || 0;
+    if (shouldInjectEmptySessionNudge(workflow.stallPolicy, emptySessions)) {
+      return buildEmptySessionNudge(emptySessions);
     }
     return void 0;
   }
@@ -8171,6 +8635,10 @@ var _AgentsEndpoint = class _AgentsEndpoint {
         state.originalMessage = options.message;
       }
       const queuedSteeringMessages = options.getQueuedUserMessages?.() ?? [];
+      if (queuedSteeringMessages.length > 0) {
+        state.consecutiveEmptySessions = 0;
+        state.stallEscalationRequested = void 0;
+      }
       const preparedSession = await this.prepareSessionContext(
         options.message,
         state,
@@ -8411,11 +8879,15 @@ var _AgentsEndpoint = class _AgentsEndpoint {
       } else {
         state.lastCompletionRejectionReason = void 0;
       }
-      const sessionHadActions = sessionTrace.wroteFiles || sessionTrace.readFiles || sessionTrace.discoveryPerformed || sessionTrace.verificationAttempted;
+      const sessionHadActions = sessionTrace.wroteFiles || sessionTrace.readFiles || sessionTrace.discoveryPerformed || sessionTrace.verificationAttempted || options.hasQueuedUserMessages?.() === true;
       if (sessionHadActions) {
         state.consecutiveEmptySessions = 0;
+        state.stallEscalationRequested = void 0;
       } else {
         state.consecutiveEmptySessions = (state.consecutiveEmptySessions || 0) + 1;
+        if (shouldRequestModelEscalation(workflow.stallPolicy, state.consecutiveEmptySessions)) {
+          state.stallEscalationRequested = true;
+        }
       }
       if (sessionResult.stopReason === "complete" && !detectedTaskCompletion) {
         const currentPhase = workflow.phases.find((p) => p.name === state.workflowPhase);
@@ -8444,7 +8916,7 @@ var _AgentsEndpoint = class _AgentsEndpoint {
         state.status = "budget_exceeded";
       } else if (acceptedTaskCompletion) {
         state.status = "complete";
-      } else if ((state.consecutiveEmptySessions || 0) >= 3) {
+      } else if ((state.consecutiveEmptySessions || 0) >= resolveStallStopAfter(workflow.stallPolicy)) {
         state.status = "stalled";
       } else if (maxCost && state.totalCost >= maxCost) {
         state.status = "budget_exceeded";
@@ -10993,6 +11465,8 @@ export {
   ClientTokensEndpoint,
   ContextTemplatesEndpoint,
   ConversationsEndpoint,
+  DEFAULT_RECOVERY_AFTER_EMPTY_SESSIONS,
+  DEFAULT_STALL_STOP_AFTER,
   DispatchEndpoint,
   EvalBuilder,
   EvalEndpoint,
@@ -11030,25 +11504,34 @@ export {
   UsersEndpoint,
   applyGeneratedRuntimeToolProposalToDispatchRequest,
   attachRuntimeToolsToDispatchRequest,
+  buildEmptySessionNudge,
   buildGeneratedRuntimeToolGateOutput,
   buildLedgerOffloadReference,
+  buildPolicyGuidance,
   buildSendViewOffloadMarker,
+  compileWorkflowConfig,
   computeAgentContentHash,
   computeFlowContentHash,
   createClient,
   createExternalTool,
   defaultWorkflow,
+  defaultWorkflowConfig,
   defineAgent,
   defineFlow,
+  definePlaybook,
   deployWorkflow,
+  ensureDefaultWorkflowHooks,
   evaluateGeneratedRuntimeToolProposal,
   extractDeclaredToolResultChars,
   gameWorkflow,
   getDefaultPlanPath,
   getLikelySupportingCandidatePaths,
+  interpolateWorkflowTemplate,
   isDiscoveryToolName,
   isMarathonArtifactPath,
   isPreservationSensitiveTask,
+  isWorkflowHookRef,
+  listWorkflowHooks,
   normalizeAgentDefinition,
   normalizeCandidatePath,
   parseFinalBuffer,
@@ -11056,6 +11539,12 @@ export {
   parseOffloadedOutputId,
   parseSSEChunk,
   processStream,
+  registerWorkflowHook,
+  resolveStallStopAfter,
+  resolveWorkflowHook,
   sanitizeTaskSlug,
-  streamEvents
+  shouldInjectEmptySessionNudge,
+  shouldRequestModelEscalation,
+  streamEvents,
+  unregisterWorkflowHook
 };