@runtypelabs/sdk 4.9.0 → 4.11.0

package/dist/index.cjs

@@ -3,9 +3,6 @@ var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __esm = (fn, res) => function __init() {
-  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
-};
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
@@ -20,17 +17,113 @@ var __copyProps = (to, from, except, desc) => {
 };
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
-// src/stream-utils.ts
-var stream_utils_exports = {};
-__export(stream_utils_exports, {
-  flowErrorMessage: () => flowErrorMessage,
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AgentDriftError: () => AgentDriftError,
+  AgentEnsureConflictError: () => AgentEnsureConflictError,
+  AgentVersionsEndpoint: () => AgentVersionsEndpoint,
+  AgentsEndpoint: () => AgentsEndpoint,
+  AgentsNamespace: () => AgentsNamespace,
+  AnalyticsEndpoint: () => AnalyticsEndpoint,
+  ApiKeysEndpoint: () => ApiKeysEndpoint,
+  AppsEndpoint: () => AppsEndpoint,
+  BatchBuilder: () => BatchBuilder,
+  BatchesNamespace: () => BatchesNamespace,
+  BillingEndpoint: () => BillingEndpoint,
+  ChatEndpoint: () => ChatEndpoint,
+  ClientBatchBuilder: () => ClientBatchBuilder,
+  ClientEvalBuilder: () => ClientEvalBuilder,
+  ClientFlowBuilder: () => ClientFlowBuilder,
+  ClientTokensEndpoint: () => ClientTokensEndpoint,
+  ContextTemplatesEndpoint: () => ContextTemplatesEndpoint,
+  ConversationsEndpoint: () => ConversationsEndpoint,
+  DEFAULT_RECOVERY_AFTER_EMPTY_SESSIONS: () => DEFAULT_RECOVERY_AFTER_EMPTY_SESSIONS,
+  DEFAULT_STALL_STOP_AFTER: () => DEFAULT_STALL_STOP_AFTER,
+  DispatchEndpoint: () => DispatchEndpoint,
+  EvalBuilder: () => EvalBuilder,
+  EvalEndpoint: () => EvalEndpoint,
+  EvalRunner: () => EvalRunner,
+  EvalsNamespace: () => EvalsNamespace,
+  FlowBuilder: () => FlowBuilder,
+  FlowDriftError: () => FlowDriftError,
+  FlowEnsureConflictError: () => FlowEnsureConflictError,
+  FlowResult: () => FlowResult,
+  FlowStepsEndpoint: () => FlowStepsEndpoint,
+  FlowVersionsEndpoint: () => FlowVersionsEndpoint,
+  FlowsEndpoint: () => FlowsEndpoint,
+  FlowsNamespace: () => FlowsNamespace,
+  IntegrationsEndpoint: () => IntegrationsEndpoint,
+  LEDGER_ARTIFACT_LINE_PREFIX: () => LEDGER_ARTIFACT_LINE_PREFIX,
+  LogsEndpoint: () => LogsEndpoint,
+  ModelConfigsEndpoint: () => ModelConfigsEndpoint,
+  PromptRunner: () => PromptRunner,
+  PromptsEndpoint: () => PromptsEndpoint,
+  PromptsNamespace: () => PromptsNamespace,
+  ProviderKeysEndpoint: () => ProviderKeysEndpoint,
+  RecordsEndpoint: () => RecordsEndpoint,
+  Runtype: () => Runtype,
+  RuntypeApiError: () => RuntypeApiError,
+  RuntypeClient: () => RuntypeClient2,
+  RuntypeFlowBuilder: () => RuntypeFlowBuilder,
+  STEP_FIELD_REGISTRY: () => STEP_FIELD_REGISTRY,
+  STEP_TYPE_TO_METHOD: () => STEP_TYPE_TO_METHOD,
+  SchedulesEndpoint: () => SchedulesEndpoint,
+  SecretsEndpoint: () => SecretsEndpoint,
+  SkillProposalsNamespace: () => SkillProposalsNamespace,
+  SkillsNamespace: () => SkillsNamespace,
+  SurfacesEndpoint: () => SurfacesEndpoint,
+  ToolsEndpoint: () => ToolsEndpoint,
+  UsersEndpoint: () => UsersEndpoint,
+  applyGeneratedRuntimeToolProposalToDispatchRequest: () => applyGeneratedRuntimeToolProposalToDispatchRequest,
+  attachRuntimeToolsToDispatchRequest: () => attachRuntimeToolsToDispatchRequest,
+  buildEmptySessionNudge: () => buildEmptySessionNudge,
+  buildGeneratedRuntimeToolGateOutput: () => buildGeneratedRuntimeToolGateOutput,
+  buildLedgerOffloadReference: () => buildLedgerOffloadReference,
+  buildPolicyGuidance: () => buildPolicyGuidance,
+  buildSendViewOffloadMarker: () => buildSendViewOffloadMarker,
+  compileWorkflowConfig: () => compileWorkflowConfig,
+  computeAgentContentHash: () => computeAgentContentHash,
+  computeFlowContentHash: () => computeFlowContentHash,
+  createClient: () => createClient,
+  createExternalTool: () => createExternalTool,
+  defaultWorkflow: () => defaultWorkflow,
+  defaultWorkflowConfig: () => defaultWorkflowConfig,
+  defineAgent: () => defineAgent,
+  defineFlow: () => defineFlow,
+  definePlaybook: () => definePlaybook,
+  deployWorkflow: () => deployWorkflow,
+  ensureDefaultWorkflowHooks: () => ensureDefaultWorkflowHooks,
+  evaluateGeneratedRuntimeToolProposal: () => evaluateGeneratedRuntimeToolProposal,
+  extractDeclaredToolResultChars: () => extractDeclaredToolResultChars,
+  gameWorkflow: () => gameWorkflow,
+  getDefaultPlanPath: () => getDefaultPlanPath,
+  getLikelySupportingCandidatePaths: () => getLikelySupportingCandidatePaths,
+  interpolateWorkflowTemplate: () => interpolateWorkflowTemplate,
+  isDiscoveryToolName: () => isDiscoveryToolName,
+  isMarathonArtifactPath: () => isMarathonArtifactPath,
+  isPreservationSensitiveTask: () => isPreservationSensitiveTask,
+  isWorkflowHookRef: () => isWorkflowHookRef,
+  listWorkflowHooks: () => listWorkflowHooks,
+  normalizeAgentDefinition: () => normalizeAgentDefinition,
+  normalizeCandidatePath: () => normalizeCandidatePath,
   parseFinalBuffer: () => parseFinalBuffer,
+  parseLedgerArtifactRelativePath: () => parseLedgerArtifactRelativePath,
+  parseOffloadedOutputId: () => parseOffloadedOutputId,
   parseSSEChunk: () => parseSSEChunk,
   processStream: () => processStream,
-  stepDeltaText: () => stepDeltaText,
-  stepDisplayName: () => stepDisplayName,
-  streamEvents: () => streamEvents
+  registerWorkflowHook: () => registerWorkflowHook,
+  resolveStallStopAfter: () => resolveStallStopAfter,
+  resolveWorkflowHook: () => resolveWorkflowHook,
+  sanitizeTaskSlug: () => sanitizeTaskSlug,
+  shouldInjectEmptySessionNudge: () => shouldInjectEmptySessionNudge,
+  shouldRequestModelEscalation: () => shouldRequestModelEscalation,
+  streamEvents: () => streamEvents,
+  unregisterWorkflowHook: () => unregisterWorkflowHook
 });
+module.exports = __toCommonJS(index_exports);
+
+// src/stream-utils.ts
 function parseSSEChunk(chunk, buffer) {
   buffer += chunk;
   const lines = buffer.split("\n");
@@ -280,86 +373,8 @@ async function* streamEvents(response) {
     reader.releaseLock();
   }
 }
-var init_stream_utils = __esm({
-  "src/stream-utils.ts"() {
-    "use strict";
-  }
-});
-
-// src/index.ts
-var index_exports = {};
-__export(index_exports, {
-  AgentVersionsEndpoint: () => AgentVersionsEndpoint,
-  AgentsEndpoint: () => AgentsEndpoint,
-  AnalyticsEndpoint: () => AnalyticsEndpoint,
-  ApiKeysEndpoint: () => ApiKeysEndpoint,
-  BatchBuilder: () => BatchBuilder,
-  BatchesNamespace: () => BatchesNamespace,
-  BillingEndpoint: () => BillingEndpoint,
-  ChatEndpoint: () => ChatEndpoint,
-  ClientBatchBuilder: () => ClientBatchBuilder,
-  ClientEvalBuilder: () => ClientEvalBuilder,
-  ClientFlowBuilder: () => ClientFlowBuilder,
-  ClientTokensEndpoint: () => ClientTokensEndpoint,
-  ContextTemplatesEndpoint: () => ContextTemplatesEndpoint,
-  ConversationsEndpoint: () => ConversationsEndpoint,
-  DispatchEndpoint: () => DispatchEndpoint,
-  EvalBuilder: () => EvalBuilder,
-  EvalEndpoint: () => EvalEndpoint,
-  EvalRunner: () => EvalRunner,
-  EvalsNamespace: () => EvalsNamespace,
-  FlowBuilder: () => FlowBuilder,
-  FlowResult: () => FlowResult,
-  FlowStepsEndpoint: () => FlowStepsEndpoint,
-  FlowVersionsEndpoint: () => FlowVersionsEndpoint,
-  FlowsEndpoint: () => FlowsEndpoint,
-  FlowsNamespace: () => FlowsNamespace,
-  IntegrationsEndpoint: () => IntegrationsEndpoint,
-  LogsEndpoint: () => LogsEndpoint,
-  ModelConfigsEndpoint: () => ModelConfigsEndpoint,
-  PromptRunner: () => PromptRunner,
-  PromptsEndpoint: () => PromptsEndpoint,
-  PromptsNamespace: () => PromptsNamespace,
-  ProviderKeysEndpoint: () => ProviderKeysEndpoint,
-  RecordsEndpoint: () => RecordsEndpoint,
-  Runtype: () => Runtype,
-  RuntypeApiError: () => RuntypeApiError,
-  RuntypeClient: () => RuntypeClient2,
-  RuntypeFlowBuilder: () => RuntypeFlowBuilder,
-  STEP_FIELD_REGISTRY: () => STEP_FIELD_REGISTRY,
-  STEP_TYPE_TO_METHOD: () => STEP_TYPE_TO_METHOD,
-  SchedulesEndpoint: () => SchedulesEndpoint,
-  SecretsEndpoint: () => SecretsEndpoint,
-  SkillProposalsNamespace: () => SkillProposalsNamespace,
-  SkillsNamespace: () => SkillsNamespace,
-  SurfacesEndpoint: () => SurfacesEndpoint,
-  ToolsEndpoint: () => ToolsEndpoint,
-  UsersEndpoint: () => UsersEndpoint,
-  applyGeneratedRuntimeToolProposalToDispatchRequest: () => applyGeneratedRuntimeToolProposalToDispatchRequest,
-  attachRuntimeToolsToDispatchRequest: () => attachRuntimeToolsToDispatchRequest,
-  buildGeneratedRuntimeToolGateOutput: () => buildGeneratedRuntimeToolGateOutput,
-  createClient: () => createClient,
-  createExternalTool: () => createExternalTool,
-  defaultWorkflow: () => defaultWorkflow,
-  deployWorkflow: () => deployWorkflow,
-  evaluateGeneratedRuntimeToolProposal: () => evaluateGeneratedRuntimeToolProposal,
-  gameWorkflow: () => gameWorkflow,
-  getDefaultPlanPath: () => getDefaultPlanPath,
-  getLikelySupportingCandidatePaths: () => getLikelySupportingCandidatePaths,
-  isDiscoveryToolName: () => isDiscoveryToolName,
-  isMarathonArtifactPath: () => isMarathonArtifactPath,
-  isPreservationSensitiveTask: () => isPreservationSensitiveTask,
-  normalizeCandidatePath: () => normalizeCandidatePath,
-  parseFinalBuffer: () => parseFinalBuffer,
-  parseSSEChunk: () => parseSSEChunk,
-  processStream: () => processStream,
-  sanitizeTaskSlug: () => sanitizeTaskSlug,
-  streamEvents: () => streamEvents
-});
-module.exports = __toCommonJS(index_exports);
 
 // src/flow-result.ts
-init_stream_utils();
 var FlowResult = class {
   constructor(response, summary) {
     this.consumed = false;
@@ -495,7 +510,6 @@ var FlowResult = class {
 };
 
 // src/flow-builder.ts
-init_stream_utils();
 async function validateInlineFlow(client, args, savedFlowHint) {
   if (args.existingFlowId) {
     throw new Error(
@@ -1205,20 +1219,20 @@ var FlowBuilder = class {
    */
   build() {
     const flow = this.existingFlowId ? { id: this.existingFlowId } : { name: this.flowConfig.name, steps: this.steps };
-    const request = { flow };
+    const request2 = { flow };
     if (this.recordConfig) {
-      request.record = this.recordConfig;
+      request2.record = this.recordConfig;
     }
     if (this.messagesConfig) {
-      request.messages = this.messagesConfig;
+      request2.messages = this.messagesConfig;
     }
     if (this.inputsConfig) {
-      request.inputs = this.inputsConfig;
+      request2.inputs = this.inputsConfig;
     }
     if (Object.keys(this.optionsConfig).length > 0) {
-      request.options = this.optionsConfig;
+      request2.options = this.optionsConfig;
     }
-    return request;
+    return request2;
   }
   /**
    * Validate this prospective flow against the public validation endpoint
@@ -1455,22 +1469,22 @@ function resolveBatchExecutionId(pausedTools) {
   return "";
 }
 
-// src/flows-namespace.ts
-function isRecord(value) {
+// src/flows-ensure.ts
+function isPlainObject(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
-function normalizeConfig(config) {
-  if (!isRecord(config)) return {};
+function normalizeConfigForHash(config) {
+  if (!isPlainObject(config)) return {};
   const normalized = {};
   for (const key of Object.keys(config).sort()) {
     const value = config[key];
     if (value === void 0) continue;
     if (value !== null && typeof value === "object" && !Array.isArray(value)) {
-      normalized[key] = normalizeConfig(value);
+      normalized[key] = normalizeConfigForHash(value);
     } else if (Array.isArray(value)) {
       normalized[key] = value.map((item) => {
         if (item !== null && typeof item === "object" && !Array.isArray(item)) {
-          return normalizeConfig(item);
+          return normalizeConfigForHash(item);
         }
         return item;
       });
@@ -1481,28 +1495,249 @@ function normalizeConfig(config) {
   return normalized;
 }
 function normalizeStepForHash(step) {
-  const stepObj = isRecord(step) ? step : {};
+  const stepObj = isPlainObject(step) ? step : {};
   return {
     type: typeof stepObj.type === "string" ? stepObj.type : "",
     name: typeof stepObj.name === "string" ? stepObj.name : "",
     enabled: stepObj.enabled !== false,
     ...typeof stepObj.when === "string" ? { when: stepObj.when } : {},
-    config: normalizeConfig(stepObj.config),
+    config: normalizeConfigForHash(stepObj.config),
     order: typeof stepObj.order === "number" ? stepObj.order : 0
   };
 }
 async function computeFlowContentHash(steps) {
   const normalized = [...steps].sort((a, b) => {
-    const orderA = isRecord(a) && typeof a.order === "number" ? a.order : 0;
-    const orderB = isRecord(b) && typeof b.order === "number" ? b.order : 0;
+    const orderA = isPlainObject(a) && typeof a.order === "number" ? a.order : 0;
+    const orderB = isPlainObject(b) && typeof b.order === "number" ? b.order : 0;
     return orderA - orderB;
   }).map(normalizeStepForHash);
   const serialized = JSON.stringify(normalized);
   const encoded = new TextEncoder().encode(serialized);
   const hashBuffer = await crypto.subtle.digest("SHA-256", encoded);
-  const hashArray = new Uint8Array(hashBuffer);
-  return Array.from(hashArray).map((b) => b.toString(16).padStart(2, "0")).join("");
+  return Array.from(new Uint8Array(hashBuffer)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+var DEFINE_FLOW_TOP_LEVEL_KEYS = /* @__PURE__ */ new Set(["name", "steps"]);
+var DEFINE_FLOW_STEP_KEYS = /* @__PURE__ */ new Set([
+  "type",
+  "name",
+  "order",
+  "enabled",
+  "when",
+  "config"
+]);
+function collectStepNonPortableToolRefs(config, path) {
+  const found = [];
+  const tools = config.tools;
+  const isAccountScoped = (ref) => typeof ref === "string" && ref.startsWith("tool_");
+  const scanArray = (value, subPath) => {
+    if (!Array.isArray(value)) return;
+    value.forEach((ref, i) => {
+      if (isAccountScoped(ref)) found.push(`${subPath}[${i}]`);
+    });
+  };
+  const scanKeys = (value, subPath) => {
+    if (!isPlainObject(value)) return;
+    for (const key of Object.keys(value)) {
+      if (isAccountScoped(key)) found.push(`${subPath}.${key}`);
+    }
+  };
+  if (isPlainObject(tools)) {
+    scanArray(tools.toolIds, `${path}.tools.toolIds`);
+    scanKeys(tools.toolConfigs, `${path}.tools.toolConfigs`);
+    scanKeys(tools.perToolLimits, `${path}.tools.perToolLimits`);
+    if (isPlainObject(tools.approval)) {
+      scanArray(tools.approval.require, `${path}.tools.approval.require`);
+    }
+    if (isPlainObject(tools.subagentConfig)) {
+      scanArray(tools.subagentConfig.toolPool, `${path}.tools.subagentConfig.toolPool`);
+    }
+    if (isPlainObject(tools.codeModeConfig)) {
+      scanArray(tools.codeModeConfig.toolPool, `${path}.tools.codeModeConfig.toolPool`);
+    }
+  }
+  for (const branch of ["trueSteps", "falseSteps"]) {
+    const nested = config[branch];
+    if (!Array.isArray(nested)) continue;
+    nested.forEach((nestedStep, i) => {
+      if (isPlainObject(nestedStep) && isPlainObject(nestedStep.config)) {
+        found.push(
+          ...collectStepNonPortableToolRefs(
+            nestedStep.config,
+            `${path}.${branch}[${i}].config`
+          )
+        );
+      }
+    });
+  }
+  return found;
+}
+function defineFlow(input) {
+  if (!input || typeof input !== "object") {
+    throw new Error("defineFlow requires a definition object");
+  }
+  if (typeof input.name !== "string" || input.name.length === 0) {
+    throw new Error('defineFlow requires a non-empty string "name"');
+  }
+  const unknownKeys = Object.keys(input).filter((key) => !DEFINE_FLOW_TOP_LEVEL_KEYS.has(key));
+  if (unknownKeys.length > 0) {
+    throw new Error(
+      `defineFlow: unknown field(s): ${unknownKeys.join(", ")}. Allowed fields are name and steps. (Description is not part of the v1 ensure surface.)`
+    );
+  }
+  if (!Array.isArray(input.steps) || input.steps.length === 0) {
+    throw new Error('defineFlow requires a non-empty "steps" array');
+  }
+  const steps = input.steps.map((step, index) => {
+    if (!isPlainObject(step)) {
+      throw new Error(`defineFlow: steps[${index}] must be an object`);
+    }
+    if (typeof step.type !== "string" || step.type.length === 0) {
+      throw new Error(`defineFlow: steps[${index}] requires a non-empty string "type"`);
+    }
+    if (typeof step.name !== "string" || step.name.length === 0) {
+      throw new Error(`defineFlow: steps[${index}] requires a non-empty string "name"`);
+    }
+    const unknownStepKeys = Object.keys(step).filter((key) => !DEFINE_FLOW_STEP_KEYS.has(key));
+    if (unknownStepKeys.length > 0) {
+      throw new Error(
+        `defineFlow: steps[${index}] has unknown field(s): ${unknownStepKeys.join(", ")}. Allowed step fields are type, name, order, enabled, when, config. (Step ids are server artifacts and not part of a portable definition.)`
+      );
+    }
+    const config = isPlainObject(step.config) ? step.config : void 0;
+    if (config) {
+      const nonPortable = collectStepNonPortableToolRefs(config, `steps[${index}].config`);
+      if (nonPortable.length > 0) {
+        throw new Error(
+          `defineFlow: account-scoped tool reference(s) at ${nonPortable.join(", ")}. Definitions must be environment-portable \u2014 tool_\u2026 IDs belong to one account/environment. Use builtin:/platform:/mcp: references instead. Name-based resolution of saved tools is a planned follow-up.`
+        );
+      }
+    }
+    return {
+      type: step.type,
+      name: step.name,
+      // Explicit 1-based order (the flow builder's convention) so the local
+      // probe hash agrees with the server's persisted step order.
+      order: typeof step.order === "number" ? step.order : index + 1,
+      ...step.enabled !== void 0 ? { enabled: step.enabled } : {},
+      ...typeof step.when === "string" ? { when: step.when } : {},
+      ...config ? { config } : {}
+    };
+  });
+  return { name: input.name, steps };
+}
+var FlowEnsureConflictError = class extends Error {
+  constructor(body) {
+    super(body.error ?? `Flow ensure conflict: ${body.code}`);
+    this.name = "FlowEnsureConflictError";
+    this.code = body.code;
+    this.lastModifiedSource = body.lastModifiedSource;
+    this.modifiedAt = body.modifiedAt;
+    this.currentHash = body.currentHash;
+  }
+};
+var FlowDriftError = class extends Error {
+  constructor(plan) {
+    super(
+      `Flow "${plan.flowId ?? "definition"}" drifted: plan is '${plan.changes}' (changed: ${plan.changedKeys.join(", ") || "n/a"}). Run client.flows.pull(name) to absorb the remote edit into your repo, or re-run ensure to converge.`
+    );
+    this.name = "FlowDriftError";
+    this.plan = plan;
+  }
+};
+function parseRequestError(err) {
+  if (!(err instanceof Error)) return { status: null, body: null };
+  const match = err.message.match(/^API request failed: (\d{3}) .*? - ([\s\S]*)$/);
+  if (!match) return { status: null, body: null };
+  try {
+    return { status: Number(match[1]), body: JSON.parse(match[2]) };
+  } catch {
+    return { status: Number(match[1]), body: null };
+  }
+}
+function toConflictError(err) {
+  const { status, body } = parseRequestError(err);
+  if (status !== 409 || !isPlainObject(body)) return null;
+  const code = body.code;
+  if (code !== "external_modification" && code !== "remote_changed") return null;
+  return new FlowEnsureConflictError(
+    body
+  );
+}
+var serverHashMemo = /* @__PURE__ */ new WeakMap();
+function memoFor(client) {
+  let memo = serverHashMemo.get(client);
+  if (!memo) {
+    memo = /* @__PURE__ */ new Map();
+    serverHashMemo.set(client, memo);
+  }
+  return memo;
+}
+function memoize(memo, memoKey, result) {
+  if (result.result !== "plan") memo.set(memoKey, result.contentHash);
+}
+async function request(client, body) {
+  try {
+    return await client.post(
+      "/flows/ensure",
+      body
+    );
+  } catch (err) {
+    const conflict = toConflictError(err);
+    if (conflict) throw conflict;
+    throw err;
+  }
+}
+async function ensureFlow(client, definition, options = {}) {
+  const { dryRun, onConflict, release, expectedRemoteHash, expectNoChanges } = options;
+  const passthrough = {
+    ...onConflict ? { onConflict } : {},
+    ...release ? { release } : {},
+    ...expectedRemoteHash ? { expectedRemoteHash } : {}
+  };
+  if (dryRun || expectNoChanges) {
+    const plan = await request(client, {
+      name: definition.name,
+      definition,
+      dryRun: true,
+      ...passthrough
+    });
+    if (plan.result !== "plan") {
+      throw new Error(`Expected a plan result from dryRun, got '${plan.result}'`);
+    }
+    if (expectNoChanges && plan.changes !== "none") {
+      throw new FlowDriftError(plan);
+    }
+    return plan;
+  }
+  const memo = memoFor(client);
+  const localHash = await computeFlowContentHash(definition.steps);
+  const memoKey = `${definition.name} ${localHash}`;
+  const contentHash = memo.get(memoKey) ?? localHash;
+  const probe = await request(client, {
+    name: definition.name,
+    contentHash,
+    ...passthrough
+  });
+  if (probe.result !== "definitionRequired") {
+    memoize(memo, memoKey, probe);
+    return probe;
+  }
+  const converged = await request(client, {
+    name: definition.name,
+    definition,
+    ...passthrough
+  });
+  if (converged.result === "definitionRequired") {
+    throw new Error("Server reported definitionRequired for a full-definition request");
+  }
+  memoize(memo, memoKey, converged);
+  return converged;
+}
+async function pullFlow(client, name) {
+  return client.get("/flows/pull", { name });
 }
+
+// src/flows-namespace.ts
 var FlowsNamespace = class {
   constructor(getClient) {
     this.getClient = getClient;
@@ -1510,8 +1745,11 @@ var FlowsNamespace = class {
   /**
    * Create or update a flow by name (upsert mode)
    *
-   * The recommended pattern for code-first flow management.
-   * Creates the flow if it doesn't exist, updates if steps changed.
+   * The recommended pattern for code-first flow management when you want to
+   * save AND run in one dispatch. For a deploy-time, non-executing converge
+   * (CI/CD config-as-code), use {@link ensure} instead — upsert and ensure
+   * are siblings, not versions of each other: upsert is the runtime verb
+   * (save-and-run), ensure is the deploy verb (converge only).
    *
    * @example
    * ```typescript
@@ -1526,6 +1764,33 @@ var FlowsNamespace = class {
   upsert(config) {
     return new RuntypeFlowBuilder(this.getClient, "upsert", config);
   }
+  /**
+   * Idempotently converge a `defineFlow` definition onto the platform —
+   * the deploy-time, non-executing sibling of {@link upsert}. Hash-first:
+   * the steady state is one tiny probe request. Creates an immutable version
+   * snapshot on every change; never deletes; never executes the flow.
+   *
+   * @example
+   * ```typescript
+   * const def = defineFlow({ name: 'Onboarding Digest', steps: [...] })
+   *
+   * // Converge (CI/deploy).
+   * const result = await Runtype.flows.ensure(def)
+   *
+   * // PR drift gate.
+   * await Runtype.flows.ensure(def, { expectNoChanges: true })
+   * ```
+   */
+  async ensure(definition, options = {}) {
+    return ensureFlow(this.getClient(), definition, options);
+  }
+  /**
+   * Pull the canonical definition + provenance for a flow by name — the
+   * absorb-drift direction of the ensure protocol.
+   */
+  async pull(name) {
+    return pullFlow(this.getClient(), name);
+  }
   /**
    * Create a virtual flow (one-off, not saved)
    *
@@ -2211,9 +2476,8 @@ var RuntypeFlowBuilder = class {
           onFlowComplete: (event) => callbacks?.onFlowComplete?.(event),
           onError: (error) => callbacks?.onError?.(error)
         };
-        const { streamEvents: streamEvents2, stepDeltaText: stepDeltaText2, stepDisplayName: stepDisplayName2, flowErrorMessage: flowErrorMessage2 } = await Promise.resolve().then(() => (init_stream_utils(), stream_utils_exports));
         try {
-          for await (const event of streamEvents2(response)) {
+          for await (const event of streamEvents(response)) {
             collectLocalToolAwait(pausedTools, event);
             switch (event.type) {
               case "flow_start":
@@ -2223,10 +2487,10 @@ var RuntypeFlowBuilder = class {
                 wrappedCallbacks.onStepStart?.(event);
                 break;
               case "step_delta":
-                wrappedCallbacks.onStepDelta?.(stepDeltaText2(event), event);
+                wrappedCallbacks.onStepDelta?.(stepDeltaText(event), event);
                 break;
               case "step_complete": {
-                accumulatedSummary.results?.set(stepDisplayName2(event), event.result);
+                accumulatedSummary.results?.set(stepDisplayName(event), event.result);
                 wrappedCallbacks.onStepComplete?.(event.result, event);
                 break;
               }
@@ -2234,7 +2498,7 @@ var RuntypeFlowBuilder = class {
                 wrappedCallbacks.onFlowComplete?.(event);
                 break;
               case "flow_error":
-                wrappedCallbacks.onError?.(new Error(flowErrorMessage2(event)));
+                wrappedCallbacks.onError?.(new Error(flowErrorMessage(event)));
                 break;
             }
           }
@@ -2309,7 +2573,8 @@ var RuntypeFlowBuilder = class {
                 return [toolName, await localTools[toolName](parameters)];
               } catch (error) {
                 throw new Error(
-                  `Error executing local tool "${toolName}": ${error instanceof Error ? error.message : String(error)}`
+                  `Error executing local tool "${toolName}": ${error instanceof Error ? error.message : String(error)}`,
+                  { cause: error }
                 );
               }
             })
@@ -2342,15 +2607,15 @@ var RuntypeFlowBuilder = class {
   build() {
     const flowMode = this.mode === "existing" ? "existing" : this.mode;
     const flow = this.existingFlowId ? { id: this.existingFlowId } : { name: this.flowConfig.name, steps: this.steps };
-    const request = { flow };
+    const request2 = { flow };
     if (this.recordConfig) {
-      request.record = this.recordConfig;
+      request2.record = this.recordConfig;
     }
     if (this.messagesConfig) {
-      request.messages = this.messagesConfig;
+      request2.messages = this.messagesConfig;
     }
     if (this.inputsConfig) {
-      request.inputs = this.inputsConfig;
+      request2.inputs = this.inputsConfig;
     }
     const options = {
       flowMode,
@@ -2368,8 +2633,8 @@ var RuntypeFlowBuilder = class {
     if (this.mode === "upsert" && Object.keys(this.upsertOptions).length > 0) {
       options.upsertOptions = this.upsertOptions;
     }
-    request.options = options;
-    return request;
+    request2.options = options;
+    return request2;
   }
   /**
    * Validate this prospective flow against the public validation endpoint
@@ -3029,6 +3294,8 @@ var SkillsNamespace = class {
   }
   /**
    * List skills for the authenticated owner, optionally filtered by status.
+   * Returns just the rows (one page); pass `cursor`/`limit` to page, or use
+   * {@link listPage} when you need the pagination envelope.
    *
    * @example
    * ```typescript
@@ -3036,10 +3303,23 @@ var SkillsNamespace = class {
    * ```
    */
   async list(params) {
-    const client = this.getClient();
-    const res = await client.get("/skills", params);
+    const res = await this.listPage(params);
     return res.data;
   }
+  /**
+   * List skills with the cursor-pagination envelope (mirrors the tools list
+   * shape: `{ data, pagination }`).
+   *
+   * @example
+   * ```typescript
+   * const page1 = await Runtype.skills.listPage({ limit: 50, includeCount: true })
+   * const page2 = await Runtype.skills.listPage({ limit: 50, cursor: page1.pagination?.nextCursor ?? undefined })
+   * ```
+   */
+  async listPage(params) {
+    const client = this.getClient();
+    return client.get("/skills", params);
+  }
   /**
    * Get a skill and its full version history.
    *
@@ -3132,6 +3412,260 @@ var SkillsNamespace = class {
   }
 };
 
+// src/agents-namespace.ts
+var AGENT_CONFIG_KEYS = [
+  "model",
+  "systemPrompt",
+  "temperature",
+  "topP",
+  "topK",
+  "frequencyPenalty",
+  "presencePenalty",
+  "seed",
+  "tools",
+  "reasoning",
+  "advisor",
+  "loopConfig",
+  "voice",
+  "errorHandling",
+  "artifacts",
+  "loggingPolicy",
+  "temporal",
+  "memory"
+];
+var AGENT_CONFIG_KEY_LIST = [...AGENT_CONFIG_KEYS].sort();
+function isPlainObject2(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function normalizeValue(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => normalizeValue(item));
+  }
+  if (isPlainObject2(value)) {
+    const normalized = {};
+    for (const key of Object.keys(value).sort()) {
+      const entry = value[key];
+      if (entry === void 0 || entry === null) continue;
+      normalized[key] = normalizeValue(entry);
+    }
+    return normalized;
+  }
+  return value;
+}
+function normalizeAgentDefinition(definition) {
+  const config = {};
+  const rawConfig = isPlainObject2(definition.config) ? definition.config : {};
+  for (const key of AGENT_CONFIG_KEY_LIST) {
+    const value = rawConfig[key];
+    if (value === void 0 || value === null) continue;
+    config[key] = normalizeValue(value);
+  }
+  return {
+    name: definition.name,
+    ...definition.description ? { description: definition.description } : {},
+    ...definition.icon ? { icon: definition.icon } : {},
+    config
+  };
+}
+async function computeAgentContentHash(definition) {
+  const serialized = JSON.stringify(normalizeAgentDefinition(definition));
+  const encoded = new TextEncoder().encode(serialized);
+  const hashBuffer = await crypto.subtle.digest("SHA-256", encoded);
+  return Array.from(new Uint8Array(hashBuffer)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+var DEFINE_TOP_LEVEL_KEYS = /* @__PURE__ */ new Set(["name", "description", "icon", ...AGENT_CONFIG_KEYS]);
+function collectNonPortableToolRefs(config) {
+  const tools = config.tools;
+  if (!isPlainObject2(tools)) return [];
+  const found = [];
+  const isAccountScoped = (ref) => typeof ref === "string" && ref.startsWith("tool_");
+  const scanArray = (value, path) => {
+    if (!Array.isArray(value)) return;
+    value.forEach((ref, i) => {
+      if (isAccountScoped(ref)) found.push(`${path}[${i}]`);
+    });
+  };
+  const scanKeys = (value, path) => {
+    if (!isPlainObject2(value)) return;
+    for (const key of Object.keys(value)) {
+      if (isAccountScoped(key)) found.push(`${path}.${key}`);
+    }
+  };
+  scanArray(tools.toolIds, "tools.toolIds");
+  scanKeys(tools.toolConfigs, "tools.toolConfigs");
+  scanKeys(tools.perToolLimits, "tools.perToolLimits");
+  if (isPlainObject2(tools.approval)) scanArray(tools.approval.require, "tools.approval.require");
+  if (isPlainObject2(tools.subagentConfig)) {
+    scanArray(tools.subagentConfig.toolPool, "tools.subagentConfig.toolPool");
+  }
+  if (isPlainObject2(tools.codeModeConfig)) {
+    scanArray(tools.codeModeConfig.toolPool, "tools.codeModeConfig.toolPool");
+  }
+  return found;
+}
+function defineAgent(input) {
+  if (!input || typeof input !== "object") {
+    throw new Error("defineAgent requires a definition object");
+  }
+  if (typeof input.name !== "string" || input.name.length === 0) {
+    throw new Error('defineAgent requires a non-empty string "name"');
+  }
+  const unknownKeys = Object.keys(input).filter((key) => !DEFINE_TOP_LEVEL_KEYS.has(key));
+  if (unknownKeys.length > 0) {
+    throw new Error(
+      `defineAgent: unknown field(s): ${unknownKeys.join(", ")}. Allowed fields are name, description, icon, and the agent runtime config surface (${AGENT_CONFIG_KEY_LIST.join(", ")}).`
+    );
+  }
+  const config = {};
+  for (const key of AGENT_CONFIG_KEYS) {
+    const value = input[key];
+    if (value !== void 0) config[key] = value;
+  }
+  const nonPortable = collectNonPortableToolRefs(config);
+  if (nonPortable.length > 0) {
+    throw new Error(
+      `defineAgent: account-scoped tool reference(s) at ${nonPortable.join(", ")}. Definitions must be environment-portable \u2014 tool_\u2026 IDs belong to one account/environment. Use builtin:/platform:/mcp: references instead. Name-based resolution of saved tools is a planned follow-up.`
+    );
+  }
+  return {
+    name: input.name,
+    ...input.description !== void 0 ? { description: input.description } : {},
+    ...input.icon !== void 0 ? { icon: input.icon } : {},
+    config
+  };
+}
+var AgentEnsureConflictError = class extends Error {
+  constructor(body) {
+    super(body.error ?? `Agent ensure conflict: ${body.code}`);
+    this.name = "AgentEnsureConflictError";
+    this.code = body.code;
+    this.lastModifiedSource = body.lastModifiedSource;
+    this.modifiedAt = body.modifiedAt;
+    this.currentHash = body.currentHash;
+  }
+};
+var AgentDriftError = class extends Error {
+  constructor(plan) {
+    super(
+      `Agent "${plan.agentId ?? "definition"}" drifted: plan is '${plan.changes}' (changed: ${plan.changedKeys.join(", ") || "n/a"}). Run client.agents.pull(name) to absorb the remote edit into your repo, or re-run ensure to converge.`
+    );
+    this.name = "AgentDriftError";
+    this.plan = plan;
+  }
+};
+function parseRequestError2(err) {
+  if (!(err instanceof Error)) return { status: null, body: null };
+  const match = err.message.match(/^API request failed: (\d{3}) .*? - ([\s\S]*)$/);
+  if (!match) return { status: null, body: null };
+  try {
+    return { status: Number(match[1]), body: JSON.parse(match[2]) };
+  } catch {
+    return { status: Number(match[1]), body: null };
+  }
+}
+function toConflictError2(err) {
+  const { status, body } = parseRequestError2(err);
+  if (status !== 409 || !isPlainObject2(body)) return null;
+  const code = body.code;
+  if (code !== "external_modification" && code !== "remote_changed") return null;
+  return new AgentEnsureConflictError(
+    body
+  );
+}
+var serverHashMemo2 = /* @__PURE__ */ new WeakMap();
+function memoFor2(client) {
+  let memo = serverHashMemo2.get(client);
+  if (!memo) {
+    memo = /* @__PURE__ */ new Map();
+    serverHashMemo2.set(client, memo);
+  }
+  return memo;
+}
+var AgentsNamespace = class {
+  constructor(getClient) {
+    this.getClient = getClient;
+  }
+  /**
+   * Idempotently converge a definition onto the platform. Hash-first: probes
+   * with a content hash, and only ships the full definition when the server
+   * reports a miss (`definitionRequired`). Creates an immutable version
+   * snapshot on every change; never deletes.
+   */
+  async ensure(definition, options = {}) {
+    const client = this.getClient();
+    const { dryRun, onConflict, release, expectedRemoteHash, expectNoChanges } = options;
+    const passthrough = {
+      ...onConflict ? { onConflict } : {},
+      ...release ? { release } : {},
+      ...expectedRemoteHash ? { expectedRemoteHash } : {}
+    };
+    if (dryRun || expectNoChanges) {
+      const plan = await this.request(client, {
+        name: definition.name,
+        definition,
+        dryRun: true,
+        ...passthrough
+      });
+      if (plan.result !== "plan") {
+        throw new Error(`Expected a plan result from dryRun, got '${plan.result}'`);
+      }
+      if (expectNoChanges && plan.changes !== "none") {
+        throw new AgentDriftError(plan);
+      }
+      return plan;
+    }
+    const memo = memoFor2(client);
+    const localHash = await computeAgentContentHash({
+      ...definition,
+      config: definition.config
+    });
+    const memoKey = `${definition.name}\0${localHash}`;
+    const contentHash = memo.get(memoKey) ?? localHash;
+    const probe = await this.request(client, {
+      name: definition.name,
+      contentHash,
+      ...passthrough
+    });
+    if (probe.result !== "definitionRequired") {
+      this.memoize(memo, memoKey, probe);
+      return probe;
+    }
+    const converged = await this.request(client, {
+      name: definition.name,
+      definition,
+      ...passthrough
+    });
+    if (converged.result === "definitionRequired") {
+      throw new Error("Server reported definitionRequired for a full-definition request");
+    }
+    this.memoize(memo, memoKey, converged);
+    return converged;
+  }
+  /**
+   * Pull the canonical definition + provenance for an agent by name — the
+   * absorb-drift direction. The contentHash reflects the live agent state.
+   */
+  async pull(name) {
+    const client = this.getClient();
+    return client.get("/agents/pull", { name });
+  }
+  memoize(memo, memoKey, result) {
+    if (result.result !== "plan") memo.set(memoKey, result.contentHash);
+  }
+  async request(client, body) {
+    try {
+      return await client.post(
+        "/agents/ensure",
+        body
+      );
+    } catch (err) {
+      const conflict = toConflictError2(err);
+      if (conflict) throw conflict;
+      throw err;
+    }
+  }
+};
+
 // src/transform.ts
 function transformResponse(data) {
   return data;
@@ -3292,7 +3826,7 @@ var RuntypeClient = class {
     } catch (error) {
       clearTimeout(timeoutId);
       if (error instanceof Error && error.name === "AbortError") {
-        throw new Error(`Request timeout after ${this.timeout}ms`);
+        throw new Error(`Request timeout after ${this.timeout}ms`, { cause: error });
       }
       throw error;
     }
@@ -3319,7 +3853,7 @@ var RuntypeClient = class {
     } catch (error) {
       clearTimeout(timeoutId);
       if (error instanceof Error && error.name === "AbortError") {
-        throw new Error(`Request timeout after ${this.timeout}ms`);
+        throw new Error(`Request timeout after ${this.timeout}ms`, { cause: error });
       }
       throw error;
     }
@@ -3494,6 +4028,32 @@ var Runtype = class {
   static get skills() {
     return new SkillsNamespace(() => this.getClient());
   }
+  /**
+   * Agents namespace - Agent config-as-code (define / ensure / pull)
+   *
+   * @example
+   * ```typescript
+   * import { defineAgent, Runtype } from '@runtypelabs/sdk'
+   *
+   * const assistant = defineAgent({
+   *   name: 'Pricing Assistant',
+   *   model: 'claude-sonnet-4-6',
+   *   systemPrompt: renderPrompt(pricingData),
+   * })
+   *
+   * // Converge at deploy time (idempotent; one tiny probe in steady state)
+   * await Runtype.agents.ensure(assistant)
+   *
+   * // CI drift gate
+   * await Runtype.agents.ensure(assistant, { expectNoChanges: true })
+   *
+   * // Absorb a dashboard edit back into the repo
+   * const { definition } = await Runtype.agents.pull('Pricing Assistant')
+   * ```
+   */
+  static get agents() {
+    return new AgentsNamespace(() => this.getClient());
+  }
 };
 
 // src/generated-tool-gate.ts
@@ -3716,8 +4276,8 @@ function buildGeneratedRuntimeToolGateOutput(proposal, options = {}) {
     ...decision.tool ? { tool: decision.tool } : {}
   };
 }
-function attachRuntimeToolsToDispatchRequest(request, runtimeTools, options = {}) {
-  const stepList = request.flow.steps;
+function attachRuntimeToolsToDispatchRequest(request2, runtimeTools, options = {}) {
+  const stepList = request2.flow.steps;
   if (!stepList || !Array.isArray(stepList) || stepList.length === 0) {
     throw new Error("Cannot attach runtime tools: dispatch request must include flow.steps");
   }
@@ -3760,9 +4320,9 @@ function attachRuntimeToolsToDispatchRequest(request, runtimeTools, options = {}
     }
   };
   return {
-    ...request,
+    ...request2,
     flow: {
-      ...request.flow,
+      ...request2.flow,
       // `clonedSteps` is a structural clone of `request.flow.steps` (already
       // `FlowStepDefinition[]`); only the prompt step's `config.tools` was
       // merged, so every step's `type` discriminant is preserved. The clone is
@@ -3772,18 +4332,56 @@ function attachRuntimeToolsToDispatchRequest(request, runtimeTools, options = {}
     }
   };
 }
-function applyGeneratedRuntimeToolProposalToDispatchRequest(request, proposal, options = {}) {
+function applyGeneratedRuntimeToolProposalToDispatchRequest(request2, proposal, options = {}) {
   const decision = evaluateGeneratedRuntimeToolProposal(proposal, options.gate);
   if (!decision.approved || !decision.tool) {
-    return { decision, request };
+    return { decision, request: request2 };
   }
-  const nextRequest = attachRuntimeToolsToDispatchRequest(request, [decision.tool], options.attach);
+  const nextRequest = attachRuntimeToolsToDispatchRequest(request2, [decision.tool], options.attach);
   return {
     decision,
     request: nextRequest
   };
 }
 
+// src/offload-markers.ts
+var LEDGER_ARTIFACT_LINE_PREFIX = "Ledger artifact: ";
+function formatChars(charLength) {
+  return charLength.toLocaleString("en-US");
+}
+function buildSendViewOffloadMarker(details) {
+  return `[${details.toolName} output (${formatChars(details.charLength)} chars) saved to ${details.filePath} \u2014 use read_file to retrieve if needed]`;
+}
+function buildLedgerOffloadReference(details) {
+  return [
+    `[Output offloaded as ${details.outputId} \u2014 ${formatChars(details.charLength)} chars stored in the marathon context ledger]`,
+    `${LEDGER_ARTIFACT_LINE_PREFIX}${details.relativePath}`,
+    `Preview: ${details.preview}${details.truncated ? "..." : ""}`,
+    "",
+    `Use read_offloaded_output with id "${details.outputId}" to retrieve the full output if needed.`
+  ].join("\n");
+}
+var DECLARED_CHARS_PATTERNS = [
+  /—\s*([\d,]+)\s+chars?\s+(?:stored|saved)/i,
+  /\(([\d,]+)\s+chars?\)\s+saved/i
+];
+function extractDeclaredToolResultChars(value) {
+  if (typeof value !== "string") return void 0;
+  for (const pattern of DECLARED_CHARS_PATTERNS) {
+    const match = pattern.exec(value);
+    if (!match?.[1]) continue;
+    const parsed = Number.parseInt(match[1].replace(/,/g, ""), 10);
+    if (Number.isFinite(parsed) && parsed > 0) return parsed;
+  }
+  return void 0;
+}
+function parseOffloadedOutputId(value) {
+  return /\bread_offloaded_output\s+with\s+id\s+"([^"]+)"/i.exec(value)?.[1] || /\[Output offloaded as\s+([a-zA-Z0-9_-]+)/i.exec(value)?.[1] || void 0;
+}
+function parseLedgerArtifactRelativePath(value) {
+  return value.split("\n").find((line) => line.startsWith(LEDGER_ARTIFACT_LINE_PREFIX))?.slice(LEDGER_ARTIFACT_LINE_PREFIX.length).trim();
+}
+
 // src/workflow-utils.ts
 function normalizeCandidatePath(candidatePath) {
   return candidatePath.trim().replace(/\\/g, "/").replace(/^\.?\//, "").replace(/\/+/g, "/");
@@ -3815,26 +4413,281 @@ function isPreservationSensitiveTask(state) {
     "visual"
   ].some((keyword) => prompt.includes(keyword));
 }
-function getLikelySupportingCandidatePaths(bestCandidatePath, candidatePaths) {
-  if (!bestCandidatePath || !candidatePaths || candidatePaths.length === 0) return [];
-  const normalizedBestCandidatePath = normalizeCandidatePath(bestCandidatePath);
-  const bestCandidateSegments = normalizedBestCandidatePath.split("/").filter(Boolean);
-  const relatedRoot = bestCandidateSegments.length >= 2 ? `${bestCandidateSegments[0]}/${bestCandidateSegments[1]}/` : bestCandidateSegments.length === 1 ? `${bestCandidateSegments[0]}/` : "";
-  const bestCandidateDir = normalizedBestCandidatePath.includes("/") ? `${normalizedBestCandidatePath.slice(0, normalizedBestCandidatePath.lastIndexOf("/"))}/` : "";
-  return candidatePaths.map((candidatePath) => normalizeCandidatePath(candidatePath)).filter(
-    (candidatePath) => candidatePath && candidatePath !== normalizedBestCandidatePath && !isMarathonArtifactPath(candidatePath) && (bestCandidateDir && candidatePath.startsWith(bestCandidateDir) || relatedRoot && candidatePath.startsWith(relatedRoot))
-  );
+function getLikelySupportingCandidatePaths(bestCandidatePath, candidatePaths) {
+  if (!bestCandidatePath || !candidatePaths || candidatePaths.length === 0) return [];
+  const normalizedBestCandidatePath = normalizeCandidatePath(bestCandidatePath);
+  const bestCandidateSegments = normalizedBestCandidatePath.split("/").filter(Boolean);
+  const relatedRoot = bestCandidateSegments.length >= 2 ? `${bestCandidateSegments[0]}/${bestCandidateSegments[1]}/` : bestCandidateSegments.length === 1 ? `${bestCandidateSegments[0]}/` : "";
+  const bestCandidateDir = normalizedBestCandidatePath.includes("/") ? `${normalizedBestCandidatePath.slice(0, normalizedBestCandidatePath.lastIndexOf("/"))}/` : "";
+  return candidatePaths.map((candidatePath) => normalizeCandidatePath(candidatePath)).filter(
+    (candidatePath) => candidatePath && candidatePath !== normalizedBestCandidatePath && !isMarathonArtifactPath(candidatePath) && (bestCandidateDir && candidatePath.startsWith(bestCandidateDir) || relatedRoot && candidatePath.startsWith(relatedRoot))
+  );
+}
+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/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 getDefaultPlanPath(taskName) {
-  const slug = sanitizeTaskSlug(taskName || "task");
-  return `.runtype/marathons/${slug}/plan.md`;
+function resolveSlotHook(value, kind) {
+  if (value === void 0) return void 0;
+  if (typeof value === "function") return value;
+  return resolveWorkflowHook(value, kind);
 }
-function getDefaultExternalReportPath(taskName) {
-  const slug = sanitizeTaskSlug(taskName || "task");
-  return `${slug}.md`;
+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 sanitizeTaskSlug(taskName) {
-  return taskName.toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80);
+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
@@ -3986,6 +4839,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",
@@ -4070,11 +4962,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;
@@ -4197,19 +5093,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) {
@@ -4237,10 +5138,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;
   },
@@ -4300,6 +5205,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}".`
       ] : [
@@ -4341,40 +5249,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;
   },
@@ -4607,13 +5488,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 = {
@@ -5025,6 +6056,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) {
@@ -5515,15 +6574,15 @@ var DispatchEndpoint = class {
    * Attach approved runtime tools to a prompt step in a redispatch request.
    * Returns a new request object and does not mutate the original.
    */
-  attachApprovedRuntimeTools(request, runtimeTools, options) {
-    return attachRuntimeToolsToDispatchRequest(request, runtimeTools, options);
+  attachApprovedRuntimeTools(request2, runtimeTools, options) {
+    return attachRuntimeToolsToDispatchRequest(request2, runtimeTools, options);
   }
   /**
    * Validate a generated runtime tool proposal and attach it to the redispatch
    * request if approved, in one call.
    */
-  applyGeneratedRuntimeToolProposal(request, proposal, options) {
-    return applyGeneratedRuntimeToolProposalToDispatchRequest(request, proposal, options);
+  applyGeneratedRuntimeToolProposal(request2, proposal, options) {
+    return applyGeneratedRuntimeToolProposalToDispatchRequest(request2, proposal, options);
   }
 };
 var ChatEndpoint = class {
@@ -6028,6 +7087,22 @@ async function processAgentStream(body, callbacks) {
     reader.releaseLock();
   }
 }
+function sleepWithAbort(delayMs, signal) {
+  return new Promise((resolve) => {
+    const onAbort = () => {
+      clearTimeout(timer);
+      resolve();
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, delayMs);
+    if (signal) {
+      if (signal.aborted) onAbort();
+      else signal.addEventListener("abort", onAbort, { once: true });
+    }
+  });
+}
 var GENERATED_RUNTIME_TOOL_PROPOSAL_SCHEMA = {
   type: "object",
   properties: {
@@ -6059,8 +7134,8 @@ var GENERATED_RUNTIME_TOOL_PROPOSAL_SCHEMA = {
   },
   required: ["name", "description", "toolType", "parametersSchema", "config"]
 };
-function appendRuntimeToolsToAgentRequest(request, runtimeTools) {
-  const existing = request.tools?.runtimeTools || [];
+function appendRuntimeToolsToAgentRequest(request2, runtimeTools) {
+  const existing = request2.tools?.runtimeTools || [];
   const existingNames = new Set(existing.map((tool) => tool.name));
   const converted = runtimeTools.filter((tool) => !existingNames.has(tool.name)).map((tool) => ({
     name: tool.name,
@@ -6070,9 +7145,9 @@ function appendRuntimeToolsToAgentRequest(request, runtimeTools) {
     ...tool.config ? { config: tool.config } : {}
   }));
   return {
-    ...request,
+    ...request2,
     tools: {
-      ...request.tools,
+      ...request2.tools,
       runtimeTools: [...existing, ...converted]
     }
   };
@@ -6148,21 +7223,21 @@ var _AgentsEndpoint = class _AgentsEndpoint {
    * Attach approved runtime tools to an agent execute request.
    * Returns a new request object and does not mutate the original.
    */
-  attachApprovedRuntimeTools(request, runtimeTools) {
-    return appendRuntimeToolsToAgentRequest(request, runtimeTools);
+  attachApprovedRuntimeTools(request2, runtimeTools) {
+    return appendRuntimeToolsToAgentRequest(request2, runtimeTools);
   }
   /**
    * Validate a generated runtime tool proposal and append it to an agent execute
    * request if approved, in one call.
    */
-  applyGeneratedRuntimeToolProposal(request, proposal, options) {
+  applyGeneratedRuntimeToolProposal(request2, proposal, options) {
     const decision = evaluateGeneratedRuntimeToolProposal(proposal, options);
     if (!decision.approved || !decision.tool) {
-      return { decision, request };
+      return { decision, request: request2 };
     }
     return {
       decision,
-      request: appendRuntimeToolsToAgentRequest(request, [decision.tool])
+      request: appendRuntimeToolsToAgentRequest(request2, [decision.tool])
     };
   }
   /**
@@ -6192,13 +7267,14 @@ var _AgentsEndpoint = class _AgentsEndpoint {
    * // ...
    * ```
    */
-  async executeStream(id, data) {
+  async executeStream(id, data, init) {
     return this.client.requestStream(`/agents/${id}/execute`, {
       method: "POST",
       body: JSON.stringify({
         ...data,
         streamResponse: true
-      })
+      }),
+      ...init?.signal ? { signal: init.signal } : {}
     });
   }
   /**
@@ -6294,56 +7370,94 @@ var _AgentsEndpoint = class _AgentsEndpoint {
         runtimeTools: [...data.tools?.runtimeTools || [], ...runtimeTools]
       }
     };
-    const response = await this.executeStream(id, requestData);
-    if (!response.ok) {
-      const error = await response.json().catch(() => ({ error: "Unknown error" }));
-      throw new Error(error.error || `HTTP ${response.status}`);
-    }
-    let currentBody = response.body;
+    const abortSignal = options?.abortSignal;
     let accumulatedOutput = "";
     let lastKnownCost = 0;
     let lastKnownTokens;
+    let lastSeenExecutionId = "";
     let pauseCount = 0;
     let discoveryPauseCount = 0;
     let consecutiveDiscoveryPauseCount = 0;
     const toolNameCounts = {};
     let recentActionKeys = [];
     const toolMessages = [];
+    const finishAborted = (executionId) => {
+      const abortCompleteEvent = {
+        type: "agent_complete",
+        executionId,
+        seq: 0,
+        agentId: id,
+        success: true,
+        iterations: 1,
+        stopReason: "end_turn",
+        completedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        totalCost: lastKnownCost,
+        ...lastKnownTokens ? { totalTokens: lastKnownTokens } : {},
+        finalOutput: [accumulatedOutput.trim(), "Session aborted by user request."].filter(Boolean).join("\n\n"),
+        duration: 0
+      };
+      callbacks?.onAgentComplete?.(abortCompleteEvent);
+      return { completeEvent: abortCompleteEvent, toolMessages };
+    };
+    let response;
+    try {
+      response = await this.executeStream(id, requestData, {
+        ...abortSignal ? { signal: abortSignal } : {}
+      });
+    } catch (error) {
+      if (abortSignal?.aborted) return finishAborted(lastSeenExecutionId);
+      throw error;
+    }
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({ error: "Unknown error" }));
+      throw new Error(error.error || `HTTP ${response.status}`);
+    }
+    let currentBody = response.body;
     while (true) {
       let pausedEvent = null;
       let completeEvent = null;
-      await processAgentStream(currentBody, {
-        ...callbacks,
-        onTurnDelta: (event) => {
-          if (event.contentType === "text") {
-            accumulatedOutput += event.delta;
-          }
-          callbacks?.onTurnDelta?.(event);
-        },
-        onTurnComplete: (event) => {
-          if (typeof event.cost === "number") {
-            lastKnownCost = event.cost;
-          }
-          if (event.tokens) {
-            lastKnownTokens = event.tokens;
-          }
-          callbacks?.onTurnComplete?.(event);
-        },
-        onAgentPaused: (event) => {
-          pausedEvent = event;
-          callbacks?.onAgentPaused?.(event);
-        },
-        onAgentComplete: (event) => {
-          if (!event.finalOutput && accumulatedOutput) {
-            event.finalOutput = accumulatedOutput;
+      try {
+        await processAgentStream(currentBody, {
+          ...callbacks,
+          onAgentStart: (event) => {
+            lastSeenExecutionId = event.executionId;
+            callbacks?.onAgentStart?.(event);
+          },
+          onTurnDelta: (event) => {
+            if (event.contentType === "text") {
+              accumulatedOutput += event.delta;
+            }
+            callbacks?.onTurnDelta?.(event);
+          },
+          onTurnComplete: (event) => {
+            if (typeof event.cost === "number") {
+              lastKnownCost = event.cost;
+            }
+            if (event.tokens) {
+              lastKnownTokens = event.tokens;
+            }
+            callbacks?.onTurnComplete?.(event);
+          },
+          onAgentPaused: (event) => {
+            pausedEvent = event;
+            callbacks?.onAgentPaused?.(event);
+          },
+          onAgentComplete: (event) => {
+            if (!event.finalOutput && accumulatedOutput) {
+              event.finalOutput = accumulatedOutput;
+            }
+            completeEvent = event;
+            callbacks?.onAgentComplete?.(event);
           }
-          completeEvent = event;
-          callbacks?.onAgentComplete?.(event);
-        }
-      });
+        });
+      } catch (error) {
+        if (abortSignal?.aborted) return finishAborted(lastSeenExecutionId);
+        throw error;
+      }
       if (completeEvent) return { completeEvent, toolMessages };
       if (pausedEvent) {
         const { toolName, toolId, parameters, executionId } = pausedEvent;
+        lastSeenExecutionId = executionId;
         const toolDef = localTools[toolName];
         if (!toolDef) {
           throw new Error(`Local tool "${toolName}" required but not provided`);
@@ -6458,6 +7572,19 @@ var _AgentsEndpoint = class _AgentsEndpoint {
           callbacks?.onAgentComplete?.(forcedCompleteEvent);
           return { completeEvent: forcedCompleteEvent, toolMessages };
         }
+        if (abortSignal?.aborted) {
+          callbacks?.onLocalToolExecutionComplete?.({
+            executionId,
+            toolCallId: toolId,
+            toolName,
+            parameters: parsedParams,
+            result: toolResult,
+            success: true,
+            completedAt: (/* @__PURE__ */ new Date()).toISOString(),
+            durationMs: Date.now() - localExecutionStartedAtMs
+          });
+          return finishAborted(executionId);
+        }
         if (options?.shouldInterrupt?.()) {
           callbacks?.onLocalToolExecutionComplete?.({
             executionId,
@@ -6491,15 +7618,22 @@ var _AgentsEndpoint = class _AgentsEndpoint {
           callbacks?.onAgentComplete?.(interruptCompleteEvent);
           return { completeEvent: interruptCompleteEvent, toolMessages };
         }
-        const resumeResponse = await this.client.requestStream(`/agents/${id}/resume`, {
-          method: "POST",
-          body: JSON.stringify({
-            executionId,
-            toolOutputs: { [toolName]: toolResult },
-            streamResponse: true,
-            debugMode: data.debugMode
-          })
-        });
+        let resumeResponse;
+        try {
+          resumeResponse = await this.client.requestStream(`/agents/${id}/resume`, {
+            method: "POST",
+            body: JSON.stringify({
+              executionId,
+              toolOutputs: { [toolName]: toolResult },
+              streamResponse: true,
+              debugMode: data.debugMode
+            }),
+            ...abortSignal ? { signal: abortSignal } : {}
+          });
+        } catch (error) {
+          if (abortSignal?.aborted) return finishAborted(executionId);
+          throw error;
+        }
         if (!resumeResponse.ok) {
           const error = await resumeResponse.json().catch(() => ({ error: "Unknown error" }));
           throw new Error(error.error || `HTTP ${resumeResponse.status}`);
@@ -6517,6 +7651,7 @@ var _AgentsEndpoint = class _AgentsEndpoint {
         currentBody = resumeResponse.body;
         continue;
       }
+      if (abortSignal?.aborted) return finishAborted(lastSeenExecutionId);
       return null;
     }
   }
@@ -6788,7 +7923,9 @@ var _AgentsEndpoint = class _AgentsEndpoint {
       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");
+      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";
   }
@@ -6831,32 +7968,71 @@ var _AgentsEndpoint = class _AgentsEndpoint {
     );
   }
   /**
-   * Compact old tool results based on context mode and window setting.
-   * Modifies messages in-place.
+   * Resolve the replay window: the base index sliced off the full history and
+   * the durable summary message that stands in for everything before it.
+   * The base is honored ONLY when the latest summary actually exists —
+   * slicing history with no summary substitute would silently drop prior
+   * context (defensive against states that carried a base but lost their
+   * summaries). The base is also clamped so a stale pointer (fork truncation,
+   * trimmed legacy state) never slices past the end of the array.
    */
-  compactToolResults(messages, newToolMessages, taskName, mode, window) {
-    if (mode === "full-inline") return;
+  resolveWindowReplay(state, messageCount) {
+    const base = state.contextWindowBaseIndex ?? 0;
+    if (!Number.isFinite(base) || base <= 0) {
+      return { windowBase: 0, windowSummaryMessages: [] };
+    }
+    const summaries = state.contextCompactionSummaries;
+    const latest = summaries?.[summaries.length - 1];
+    if (!latest) {
+      return { windowBase: 0, windowSummaryMessages: [] };
+    }
+    return {
+      windowBase: Math.min(Math.floor(base), messageCount),
+      windowSummaryMessages: [{ role: "system", content: latest.content }]
+    };
+  }
+  /**
+   * Derive the message view sent to the model based on context mode and window
+   * setting. This never mutates persisted marathon history; masking/offloading
+   * is a send-time view over the full-fidelity ledger/history.
+   */
+  deriveToolContextMessages(messages, taskName, mode, window) {
+    if (mode === "full-inline") return [...messages];
+    const maskMessage = (msg) => ({
+      ...msg,
+      toolResults: (msg.toolResults ?? []).map((tr) => this.compactOneResult(tr, taskName, mode))
+    });
+    const view = [...messages];
     if (window === "session") {
-      for (const msg of messages) {
+      const lastUserIndex = view.reduce(
+        (lastIndex, message, index) => message.role === "user" ? index : lastIndex,
+        -1
+      );
+      for (let index = 0; index < view.length; index++) {
+        if (lastUserIndex >= 0 && index > lastUserIndex) continue;
+        const msg = view[index];
+        if (!msg) continue;
         if (msg.role === "tool" && msg.toolResults) {
-          msg.toolResults = msg.toolResults.map((tr) => this.compactOneResult(tr, taskName, mode));
+          view[index] = maskMessage(msg);
         }
       }
     } else {
-      const newToolResultCount = newToolMessages.filter((m) => m.role === "tool").length;
-      const keepInlineFromExisting = Math.max(0, window - newToolResultCount);
       const toolResultIndices = [];
-      for (let i = 0; i < messages.length; i++) {
-        if (messages[i].role === "tool" && messages[i].toolResults) {
+      for (let i = 0; i < view.length; i++) {
+        const message = view[i];
+        if (message?.role === "tool" && message.toolResults) {
           toolResultIndices.push(i);
         }
       }
-      const compactUpTo = toolResultIndices.length - keepInlineFromExisting;
+      const compactUpTo = toolResultIndices.length - window;
       for (let j = 0; j < compactUpTo && j < toolResultIndices.length; j++) {
-        const msg = messages[toolResultIndices[j]];
-        msg.toolResults = msg.toolResults.map((tr) => this.compactOneResult(tr, taskName, mode));
+        const index = toolResultIndices[j];
+        const msg = index === void 0 ? void 0 : view[index];
+        if (!msg) continue;
+        view[index] = maskMessage(msg);
       }
     }
+    return view;
   }
   compactOneResult(tr, taskName, mode) {
     if (typeof tr.result === "string" && tr.result.startsWith("[")) return tr;
@@ -6892,10 +8068,20 @@ var _AgentsEndpoint = class _AgentsEndpoint {
     }
     const slug = this.sanitizeTaskSlug(taskName || "task");
     const dir = `.runtype/marathons/${slug}/tool-outputs`;
-    fs.mkdirSync(dir, { recursive: true });
     const filePath = `${dir}/${toolCallId}.txt`;
-    fs.writeFileSync(filePath, resultStr, "utf-8");
-    return `[${toolName} output (${resultStr.length} chars) saved to ${filePath} \u2014 use read_file to retrieve if needed]`;
+    try {
+      if (!fs.existsSync(filePath)) {
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(filePath, resultStr, "utf-8");
+      }
+    } catch {
+      return result;
+    }
+    return buildSendViewOffloadMarker({
+      toolName,
+      charLength: resultStr.length,
+      filePath
+    });
   }
   getDefaultPlanPath(taskName) {
     return getDefaultPlanPath(taskName);
@@ -7017,6 +8203,7 @@ var _AgentsEndpoint = class _AgentsEndpoint {
     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 contextCompactionSummaries = (resumeState.contextCompactionSummaries ?? []).slice(-20);
     const normalizedBestCandidatePath = typeof resumeState.bestCandidatePath === "string" && resumeState.bestCandidatePath.trim() ? this.normalizeCandidatePath(resumeState.bestCandidatePath) : void 0;
     const bestCandidatePath = normalizedBestCandidatePath && !this.isMarathonArtifactPath(normalizedBestCandidatePath) ? normalizedBestCandidatePath : [...candidatePaths, ...recentReadPaths].sort(
       (left, right) => this.scoreCandidatePath(right) - this.scoreCandidatePath(left)
@@ -7036,10 +8223,14 @@ var _AgentsEndpoint = class _AgentsEndpoint {
       bestCandidateVerified: Boolean(resumeState.bestCandidateVerified),
       ...resumeState.verificationRequired !== void 0 ? { verificationRequired: resumeState.verificationRequired } : {},
       lastVerificationPassed: Boolean(resumeState.lastVerificationPassed),
-      ...resumeState.consecutiveBlockedVerificationSessions !== void 0 ? { consecutiveBlockedVerificationSessions: resumeState.consecutiveBlockedVerificationSessions } : {},
+      ...resumeState.consecutiveBlockedVerificationSessions !== void 0 ? {
+        consecutiveBlockedVerificationSessions: resumeState.consecutiveBlockedVerificationSessions
+      } : {},
       ...resumeState.isCreationTask !== void 0 ? { isCreationTask: resumeState.isCreationTask } : {},
       ...resumeState.workflowVariant !== void 0 ? { workflowVariant: resumeState.workflowVariant } : {},
       ...resumeState.workflowState !== void 0 ? { workflowState: resumeState.workflowState } : {},
+      ...contextCompactionSummaries.length ? { contextCompactionSummaries } : {},
+      ...typeof resumeState.contextWindowBaseIndex === "number" && Number.isFinite(resumeState.contextWindowBaseIndex) && resumeState.contextWindowBaseIndex > 0 ? { contextWindowBaseIndex: Math.floor(resumeState.contextWindowBaseIndex) } : {},
       ...typeof resumeState.outputRoot === "string" && resumeState.outputRoot.trim() ? { outputRoot: resumeState.outputRoot.trim().replace(/\\/g, "/").replace(/\/+/g, "/") } : {}
     };
   }
@@ -7439,8 +8630,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;
   }
@@ -7505,8 +8699,13 @@ var _AgentsEndpoint = class _AgentsEndpoint {
       } : {},
       ...seededResumeState?.candidatePaths ? { candidatePaths: seededResumeState.candidatePaths } : {},
       ...seededResumeState?.recentReadPaths ? { recentReadPaths: seededResumeState.recentReadPaths } : {},
-      ...seededResumeState?.recentActionKeys ? { recentActionKeys: seededResumeState.recentActionKeys } : {}
+      ...seededResumeState?.recentActionKeys ? { recentActionKeys: seededResumeState.recentActionKeys } : {},
+      ...seededResumeState?.contextCompactionSummaries?.length ? { contextCompactionSummaries: seededResumeState.contextCompactionSummaries } : {},
+      ...typeof seededResumeState?.contextWindowBaseIndex === "number" ? { contextWindowBaseIndex: seededResumeState.contextWindowBaseIndex } : {}
     };
+    if (options.previousMessages && options.previousMessages.length > 0) {
+      state.messages = options.previousMessages.map((message) => structuredClone(message));
+    }
     state.workflowVariant = classifiedVariant;
     state.isCreationTask = seededResumeState?.isCreationTask ?? state.workflowVariant === "create";
     state.outputRoot = seededResumeState?.outputRoot ?? (state.isCreationTask ? "public/" : void 0);
@@ -7539,6 +8738,10 @@ var _AgentsEndpoint = class _AgentsEndpoint {
       }
     }
     for (let session = 0; session < maxSessions; session++) {
+      if (options.abortSignal?.aborted) {
+        state.status = "paused";
+        break;
+      }
       const phaseAtSessionStart = state.workflowPhase;
       const sessionTrace = this.createEmptyToolTrace();
       const sessionLocalTools = this.wrapLocalToolsForTrace(
@@ -7557,6 +8760,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,
@@ -7575,7 +8782,9 @@ var _AgentsEndpoint = class _AgentsEndpoint {
           localTools: options.localTools,
           builtinToolSchemas,
           onContextCompaction: options.onContextCompaction,
-          onContextNotice: options.onContextNotice
+          onContextNotice: options.onContextNotice,
+          toolContextMode: options.toolContextMode || "hot-tail",
+          toolWindow: options.toolWindow ?? "session"
         },
         queuedSteeringMessages
       );
@@ -7605,7 +8814,8 @@ var _AgentsEndpoint = class _AgentsEndpoint {
             sessionCallbacks,
             {
               onLocalToolResult: this.createLocalToolLoopGuard(state, sessionTrace, workflow),
-              shouldInterrupt: options.hasQueuedUserMessages
+              shouldInterrupt: options.hasQueuedUserMessages,
+              ...options.abortSignal ? { abortSignal: options.abortSignal } : {}
             },
             state.taskName
           );
@@ -7754,22 +8964,13 @@ var _AgentsEndpoint = class _AgentsEndpoint {
         }
       }
       if (!state.messages) state.messages = [];
-      if (this.isCompactHistoryMessageSet(messages)) {
-        state.messages = [...messages];
-      } else if (state.messages.length > 0 && messages.length > state.messages.length) {
-        const newMessages = messages.slice(state.messages.length);
-        state.messages.push(...newMessages);
-      } else {
+      const sentUserMessage = messages[messages.length - 1];
+      if (sentUserMessage?.role === "user") {
+        state.messages.push(sentUserMessage);
+      } else if (state.messages.length === 0) {
         state.messages.push(...messages);
       }
       if (sessionToolMessages.length > 0) {
-        this.compactToolResults(
-          state.messages,
-          sessionToolMessages,
-          state.taskName,
-          options.toolContextMode || "hot-tail",
-          options.toolWindow ?? "session"
-        );
         state.messages.push(...sessionToolMessages);
       }
       const assistantContent = effectiveSessionOutput || `[Session ${session + 1} completed (${sessionResult.stopReason}). No text output captured.]`;
@@ -7789,7 +8990,10 @@ var _AgentsEndpoint = class _AgentsEndpoint {
         workflow
       );
       if (detectedTaskCompletion && !acceptedTaskCompletion) {
-        state.lastCompletionRejectionReason = this.computeCompletionRejectionReason(state, sessionTrace);
+        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) {
@@ -7800,32 +9004,36 @@ 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);
-        const gatesSatisfied = currentPhase?.canAcceptCompletion ? currentPhase.canAcceptCompletion(state, sessionTrace) : true;
+        const gatesSatisfied = currentPhase?.canAcceptCompletion ? currentPhase.canAcceptCompletion(
+          state,
+          sessionTrace
+        ) : true;
         if (gatesSatisfied) {
           state.status = "complete";
         }
       } else if (sessionResult.stopReason === "error") {
         if (_AgentsEndpoint.isRetryableSessionError(sessionResult.error) && consecutiveServerNetworkErrors < maxServerNetworkRetries) {
           consecutiveServerNetworkErrors++;
-          const delayMs = Math.min(
-            5e3 * Math.pow(2, consecutiveServerNetworkErrors - 1),
-            3e4
-          );
+          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));
+          await sleepWithAbort(delayMs, options.abortSignal);
         } else {
           state.status = "error";
         }
@@ -7833,13 +9041,16 @@ 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";
       } else if (session + 1 >= maxSessions) {
         state.status = "max_sessions";
       }
+      if (options.abortSignal?.aborted) {
+        state.status = "paused";
+      }
       if (options.trackProgress) {
         recordId = await this.syncProgressRecord(state, recordId);
       }
@@ -7916,6 +9127,9 @@ var _AgentsEndpoint = class _AgentsEndpoint {
       return 0;
     }
   }
+  extractDeclaredToolResultChars(value) {
+    return extractDeclaredToolResultChars(value);
+  }
   estimateMessageContentTokens(content) {
     if (typeof content === "string") return this.estimateTextTokens(content);
     return content.reduce((total, part) => {
@@ -7934,12 +9148,14 @@ var _AgentsEndpoint = class _AgentsEndpoint {
       0
     );
   }
-  estimateToolResultTokens(toolResults) {
+  estimateToolResultTokens(toolResults, options) {
     if (!toolResults || toolResults.length === 0) return 0;
-    return toolResults.reduce(
-      (sum, toolResult) => sum + 12 + this.estimateTextTokens(toolResult.toolName) + this.estimateUnknownTokens(toolResult.result),
-      0
-    );
+    return toolResults.reduce((sum, toolResult) => {
+      const resultTokens = this.estimateUnknownTokens(toolResult.result);
+      const declaredChars = options?.useDeclaredSize ? this.extractDeclaredToolResultChars(toolResult.result) : void 0;
+      const declaredTokens = typeof declaredChars === "number" ? Math.ceil(declaredChars / 4) : 0;
+      return sum + 12 + this.estimateTextTokens(toolResult.toolName) + Math.max(resultTokens, declaredTokens);
+    }, 0);
   }
   estimateMessageTokens(message) {
     return 6 + this.estimateMessageContentTokens(message.content) + this.estimateToolCallTokens(message.toolCalls) + this.estimateToolResultTokens(message.toolResults);
@@ -7947,13 +9163,15 @@ var _AgentsEndpoint = class _AgentsEndpoint {
   estimateConversationTokens(messages) {
     return messages.reduce((sum, message) => sum + this.estimateMessageTokens(message), 0);
   }
-  estimateConversationBreakdown(messages) {
+  estimateConversationBreakdown(messages, options) {
     let historyTokens = 0;
     let toolOutputTokens = 0;
     for (const message of messages) {
       const contentTokens = this.estimateMessageContentTokens(message.content);
       const toolCallTokens = this.estimateToolCallTokens(message.toolCalls);
-      const toolResultTokens = this.estimateToolResultTokens(message.toolResults);
+      const toolResultTokens = this.estimateToolResultTokens(message.toolResults, {
+        useDeclaredSize: options?.useDeclaredToolResultSizes
+      });
       const messageTotal = 6 + contentTokens + toolCallTokens + toolResultTokens;
       if (message.role === "tool") {
         toolOutputTokens += messageTotal;
@@ -8007,13 +9225,24 @@ var _AgentsEndpoint = class _AgentsEndpoint {
     const compactInstructions = config.compactInstructions;
     return typeof compactInstructions === "string" && compactInstructions.trim() ? compactInstructions.trim() : void 0;
   }
-  extractArtifactReferences(state) {
+  extractArtifactReferencesFromMessages(messages = []) {
     const references = /* @__PURE__ */ new Set();
     const offloadPrefix = "[Output saved to ";
-    for (const message of state.messages ?? []) {
+    const ledgerArtifactPrefix = LEDGER_ARTIFACT_LINE_PREFIX;
+    const savedToPattern = /saved to\s+([^—\]\n]+?)(?:\s+—|\]|\n|$)/gi;
+    for (const message of messages) {
       if (!message.toolResults) continue;
       for (const toolResult of message.toolResults) {
         if (typeof toolResult.result !== "string") continue;
+        for (const line of toolResult.result.split("\n")) {
+          if (line.startsWith(ledgerArtifactPrefix)) {
+            references.add(line.slice(ledgerArtifactPrefix.length).trim());
+          }
+        }
+        for (const match of toolResult.result.matchAll(savedToPattern)) {
+          const pathText = match[1]?.trim();
+          if (pathText) references.add(pathText);
+        }
         let startIndex = 0;
         while (startIndex < toolResult.result.length) {
           const prefixIndex = toolResult.result.indexOf(offloadPrefix, startIndex);
@@ -8031,6 +9260,13 @@ var _AgentsEndpoint = class _AgentsEndpoint {
         }
       }
     }
+    return Array.from(references);
+  }
+  extractArtifactReferences(state, additionalReferences = []) {
+    const references = /* @__PURE__ */ new Set([
+      ...this.extractArtifactReferencesFromMessages(state.messages ?? []),
+      ...additionalReferences
+    ]);
     if (state.planPath) {
       references.add(state.planPath);
     }
@@ -8038,6 +9274,9 @@ var _AgentsEndpoint = class _AgentsEndpoint {
   }
   buildContextBudgetBreakdown(details) {
     const conversationBreakdown = this.estimateConversationBreakdown(details.historyMessages);
+    const sourceConversationBreakdown = details.sourceHistoryMessages ? this.estimateConversationBreakdown(details.sourceHistoryMessages, {
+      useDeclaredToolResultSizes: true
+    }) : conversationBreakdown;
     const currentTurnTokens = this.estimateTextTokens(details.currentTurnContent);
     const toolDefinitionTokens = this.estimateToolDefinitionTokens(
       details.localTools,
@@ -8054,15 +9293,26 @@ ${details.summaryText}
 
 Do NOT redo any of the above work.`
     ) : void 0;
+    const sendEstimatedInputTokens = conversationBreakdown.estimatedInputTokens + currentTurnTokens + toolDefinitionTokens;
+    const estimatedInputTokens = sourceConversationBreakdown.estimatedInputTokens + currentTurnTokens + toolDefinitionTokens;
+    const toolOutputReductionTokens = Math.max(
+      0,
+      sourceConversationBreakdown.toolOutputTokens - conversationBreakdown.toolOutputTokens
+    );
     return {
-      historyTokens: conversationBreakdown.historyTokens,
-      toolOutputTokens: conversationBreakdown.toolOutputTokens,
+      historyTokens: sourceConversationBreakdown.historyTokens,
+      toolOutputTokens: sourceConversationBreakdown.toolOutputTokens,
       currentTurnTokens,
       toolDefinitionTokens,
       ...summaryTokens ? { summaryTokens } : {},
       ...reservedOutputTokens ? { reservedOutputTokens } : {},
       ...effectiveInputBudgetTokens ? { effectiveInputBudgetTokens } : {},
-      estimatedInputTokens: conversationBreakdown.estimatedInputTokens + currentTurnTokens + toolDefinitionTokens
+      ...toolOutputReductionTokens > 0 ? {
+        sendEstimatedInputTokens,
+        sendToolOutputTokens: conversationBreakdown.toolOutputTokens,
+        toolOutputReductionTokens
+      } : {},
+      estimatedInputTokens
     };
   }
   async emitContextCompactionEvent(onContextCompaction, event) {
@@ -8102,16 +9352,33 @@ Do NOT redo any of the above work.`
       state,
       userContent,
       details.compactInstructions,
-      details.mode
+      details.mode,
+      details.artifactReferences
     );
+    const summaryMessage = compactMessages[0];
+    if (summaryMessage?.role === "system" && typeof summaryMessage.content === "string") {
+      const existingSummaries = state.contextCompactionSummaries ?? [];
+      state.contextCompactionSummaries = [
+        ...existingSummaries,
+        {
+          id: `ctx_${sessionIndex + 1}_${existingSummaries.length + 1}`,
+          sessionIndex: sessionIndex + 1,
+          mode: details.mode,
+          strategy: details.strategy,
+          content: summaryMessage.content,
+          createdAt: (/* @__PURE__ */ new Date()).toISOString()
+        }
+      ].slice(-20);
+    }
+    state.contextWindowBaseIndex = state.messages?.length ?? 0;
     await this.emitContextCompactionEvent(details.onContextCompaction, {
       phase: "complete",
       ...baseEvent
     });
     return compactMessages;
   }
-  buildCompactHistoryMessages(state, userContent, compactInstructions, mode = "auto") {
-    const summary = this.generateCompactSummary(state, compactInstructions);
+  buildCompactHistoryMessages(state, userContent, compactInstructions, mode = "auto", artifactReferences) {
+    const summary = this.generateCompactSummary(state, compactInstructions, artifactReferences);
     const prefix = mode === "forced" ? this.getForcedCompactionSummaryPrefix(state) : _AgentsEndpoint.AUTO_COMPACT_SUMMARY_PREFIX;
     return [
       {
@@ -8128,16 +9395,11 @@ Do NOT redo any of the above work.`
       }
     ];
   }
-  isCompactHistoryMessageSet(messages) {
-    if (messages.length === 0) return false;
-    const firstMessage = messages[0];
-    return firstMessage?.role === "system" && typeof firstMessage.content === "string" && (firstMessage.content.startsWith(_AgentsEndpoint.AUTO_COMPACT_SUMMARY_PREFIX) || firstMessage.content.startsWith(_AgentsEndpoint.RESUMED_COMPACT_SUMMARY_PREFIX) || firstMessage.content.startsWith(_AgentsEndpoint.COMPLETED_COMPACT_SUMMARY_PREFIX));
-  }
   /**
    * Generate a compact summary of prior work for continuation context.
    * Used when compact mode is enabled to keep token usage low.
    */
-  generateCompactSummary(state, compactInstructions) {
+  generateCompactSummary(state, compactInstructions, additionalArtifactReferences = []) {
     const recentSessions = (state.sessions ?? []).slice(-5);
     const sessionSummaries = recentSessions.map(
       (session) => `- Session ${session.index}: ${session.stopReason} ($${session.cost.toFixed(4)}) ${session.outputPreview.slice(0, 160)}`
@@ -8151,7 +9413,7 @@ Do NOT redo any of the above work.`
       )
     ).slice(0, 8);
     const verificationSummary = state.bestCandidateVerified ? "Latest candidate verified." : state.bestCandidateNeedsVerification ? "Latest candidate still needs verification." : state.lastVerificationPassed ? "Latest verification passed." : state.verificationRequired ? "Verification is still required." : "No verification requirement recorded.";
-    const artifactReferences = this.extractArtifactReferences(state);
+    const artifactReferences = this.extractArtifactReferences(state, additionalArtifactReferences);
     const pendingNextStep = state.lastStopReason === "complete" ? "Confirm nothing else remains before declaring the task complete." : `Continue the ${state.workflowPhase || "research"} phase without redoing prior work.`;
     const instructions = compactInstructions || this.buildDefaultCompactInstructions();
     return [
@@ -8366,14 +9628,23 @@ Do NOT redo any of the above work.`
     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.`;
-    const steeringLines = steeringMessages && steeringMessages.length > 0 ? [
-      "--- User steering (queued during the previous session) ---",
-      ...steeringMessages,
-      ""
-    ] : [];
+    const steeringLines = steeringMessages && steeringMessages.length > 0 ? ["--- User steering (queued during the previous session) ---", ...steeringMessages, ""] : [];
     if (continuationContext && sessionIndex === 0) {
-      const replayHistoryMessages = this.sanitizeReplayHistoryMessages(
-        continuationContext.previousMessages
+      const resumeWindow = this.resolveWindowReplay(
+        state,
+        continuationContext.previousMessages.length
+      );
+      const sourceReplayHistoryMessages = [
+        ...resumeWindow.windowSummaryMessages,
+        ...this.sanitizeReplayHistoryMessages(
+          continuationContext.previousMessages.slice(resumeWindow.windowBase)
+        )
+      ];
+      const replayHistoryMessages = this.deriveToolContextMessages(
+        sourceReplayHistoryMessages,
+        state.taskName,
+        compactionOptions?.toolContextMode || "hot-tail",
+        compactionOptions?.toolWindow ?? "session"
       );
       const continuationGuardrail = this.buildContinuationGuardrail(state);
       const defaultContinueMessage = "Continue the task. Review your prior work above and proceed with any remaining work. If everything is already complete, respond with TASK_COMPLETE.";
@@ -8397,9 +9668,15 @@ Do NOT redo any of the above work.`
           content: userContent
         }
       ];
-      const summaryText = this.generateCompactSummary(state, compactInstructions);
+      const replayArtifactReferences = this.extractArtifactReferencesFromMessages(replayHistoryMessages);
+      const summaryText = this.generateCompactSummary(
+        state,
+        compactInstructions,
+        replayArtifactReferences
+      );
       const breakdown = this.buildContextBudgetBreakdown({
         historyMessages: replayHistoryMessages,
+        sourceHistoryMessages: sourceReplayHistoryMessages,
         currentTurnContent: userContent,
         localTools: compactionOptions?.localTools,
         builtinToolSchemas: compactionOptions?.builtinToolSchemas || [],
@@ -8425,7 +9702,8 @@ Do NOT redo any of the above work.`
               reservedOutputTokens: breakdown.reservedOutputTokens,
               breakdown,
               onContextCompaction: compactionOptions?.onContextCompaction,
-              compactInstructions
+              compactInstructions,
+              artifactReferences: replayArtifactReferences
             }
           ),
           requestContextManagement
@@ -8449,7 +9727,8 @@ Do NOT redo any of the above work.`
               reservedOutputTokens: breakdown.reservedOutputTokens,
               breakdown,
               onContextCompaction: compactionOptions?.onContextCompaction,
-              compactInstructions
+              compactInstructions,
+              artifactReferences: replayArtifactReferences
             }
           ),
           requestContextManagement
@@ -8500,23 +9779,45 @@ Do NOT redo any of the above work.`
         "Do not redo previous work. If the task is already complete, respond with TASK_COMPLETE."
       ].join("\n");
       const MAX_HISTORY_MESSAGES = 60;
-      let historyMessages = this.sanitizeReplayHistoryMessages(state.messages);
-      if (historyMessages.length > MAX_HISTORY_MESSAGES) {
-        const trimmedHistory = this.trimReplayHistoryMessages(historyMessages, MAX_HISTORY_MESSAGES);
-        historyMessages = trimmedHistory.historyMessages;
+      const { windowBase, windowSummaryMessages } = this.resolveWindowReplay(
+        state,
+        state.messages.length
+      );
+      let sourceHistoryMessages = this.sanitizeReplayHistoryMessages(
+        state.messages.slice(windowBase)
+      );
+      if (sourceHistoryMessages.length > MAX_HISTORY_MESSAGES) {
+        const trimmedHistory = this.trimReplayHistoryMessages(
+          sourceHistoryMessages,
+          MAX_HISTORY_MESSAGES
+        );
+        sourceHistoryMessages = trimmedHistory.historyMessages;
         if (trimmedHistory.trimmedCount > 0) {
-          historyMessages = [
+          sourceHistoryMessages = [
             {
               role: "system",
               content: `[${trimmedHistory.trimmedCount} earlier messages trimmed to stay within context limits. Original task: ${(state.originalMessage || originalMessage).slice(0, 500)}]`
             },
-            ...historyMessages
+            ...sourceHistoryMessages
           ];
         }
       }
-      const summaryText = this.generateCompactSummary(state, compactInstructions);
+      sourceHistoryMessages = [...windowSummaryMessages, ...sourceHistoryMessages];
+      const historyMessages = this.deriveToolContextMessages(
+        sourceHistoryMessages,
+        state.taskName,
+        compactionOptions?.toolContextMode || "hot-tail",
+        compactionOptions?.toolWindow ?? "session"
+      );
+      const historyArtifactReferences = this.extractArtifactReferencesFromMessages(historyMessages);
+      const summaryText = this.generateCompactSummary(
+        state,
+        compactInstructions,
+        historyArtifactReferences
+      );
       const breakdown = this.buildContextBudgetBreakdown({
         historyMessages,
+        sourceHistoryMessages,
         currentTurnContent: continuationContent,
         localTools: compactionOptions?.localTools,
         builtinToolSchemas: compactionOptions?.builtinToolSchemas || [],
@@ -8543,7 +9844,8 @@ Do NOT redo any of the above work.`
               reservedOutputTokens: breakdown.reservedOutputTokens,
               breakdown,
               onContextCompaction: compactionOptions?.onContextCompaction,
-              compactInstructions
+              compactInstructions,
+              artifactReferences: historyArtifactReferences
             }
           ),
           requestContextManagement
@@ -9017,6 +10319,52 @@ var BillingEndpoint = class {
     return this.client.get("/billing/spend-analytics", params);
   }
 };
+var AppsEndpoint = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** List apps for the authenticated owner, newest first. */
+  async list() {
+    return this.client.get("/apps");
+  }
+  /** Get an app by id, including its URL and active version pointer. */
+  async get(id) {
+    return this.client.get(`/apps/${id}`);
+  }
+  /** Create an app. A client token scoped to the app origin is auto-provisioned. */
+  async create(data) {
+    return this.client.post("/apps", data);
+  }
+  /** Update name, description, visibility, or status (suspended serves 410). */
+  async update(id, data) {
+    return this.client.patch(`/apps/${id}`, data);
+  }
+  /** Delete an app, its versions, and its hosting. Irreversible. */
+  async delete(id) {
+    return this.client.delete(`/apps/${id}`);
+  }
+  /** List an app's versions, newest first. */
+  async listVersions(id) {
+    return this.client.get(`/apps/${id}/versions`);
+  }
+  /** Upload a zipped bundle (raw application/zip body) as a new version. */
+  async uploadVersion(id, zipBytes) {
+    return this.client.postBinary(`/apps/${id}/versions`, zipBytes, "application/zip");
+  }
+  /**
+   * Upload a bundle from in-memory file maps (the API zips server-side).
+   * Text files in `files`, binary files base64-encoded in `filesBase64`.
+   */
+  async uploadVersionFiles(id, data) {
+    return this.client.post(`/apps/${id}/versions`, data);
+  }
+  /** Activate an uploaded version (deploy or rollback). */
+  async activate(id, versionId) {
+    return this.client.post(`/apps/${id}/activate`, {
+      versionId
+    });
+  }
+};
 
 // src/client.ts
 function isObjectRecord(value) {
@@ -9059,6 +10407,7 @@ var RuntypeClient2 = class {
     this.clientTokens = new ClientTokensEndpoint(this);
     this.agents = new AgentsEndpoint(this);
     this.secrets = new SecretsEndpoint(this);
+    this.apps = new AppsEndpoint(this);
     this.schedules = new SchedulesEndpoint(this);
     this.surfaces = new SurfacesEndpoint(this);
     this.conversations = new ConversationsEndpoint(this);
@@ -9105,7 +10454,7 @@ var RuntypeClient2 = class {
   clearApiKey() {
     delete this.headers.Authorization;
   }
-  async runWithLocalTools(request, localTools, arg3, arg4) {
+  async runWithLocalTools(request2, localTools, arg3, arg4) {
     const isOptionsObject = (val) => typeof val === "object" && val !== null && "scope" in val;
     const callbacks = isOptionsObject(arg3) ? void 0 : arg3;
     const options = (isOptionsObject(arg3) ? arg3 : arg4) ?? {};
@@ -9119,12 +10468,12 @@ var RuntypeClient2 = class {
       ...entry.pageOrigin ? { pageOrigin: entry.pageOrigin } : {}
     })) : [];
     const modifiedRequest = {
-      ...request,
+      ...request2,
       ...derivedClientTools.length > 0 ? {
-        clientTools: [...request.clientTools ?? [], ...derivedClientTools]
+        clientTools: [...request2.clientTools ?? [], ...derivedClientTools]
       } : {},
       options: {
-        ...request.options || {},
+        ...request2.options || {},
         streamResponse: isStreaming
       }
     };
@@ -9140,13 +10489,12 @@ var RuntypeClient2 = class {
           onFlowComplete: (event) => callbacks?.onFlowComplete?.(event),
           onError: (error) => callbacks?.onError?.(error)
         };
-        const { streamEvents: streamEvents2, stepDeltaText: stepDeltaText2, stepDisplayName: stepDisplayName2, flowErrorMessage: flowErrorMessage2 } = await Promise.resolve().then(() => (init_stream_utils(), stream_utils_exports));
         const summary = {
           results: /* @__PURE__ */ new Map(),
           success: true
         };
         try {
-          for await (const event of streamEvents2(response)) {
+          for await (const event of streamEvents(response)) {
             collectLocalToolAwait(pausedTools, event);
             switch (event.type) {
               case "flow_start":
@@ -9156,10 +10504,10 @@ var RuntypeClient2 = class {
                 wrappedCallbacks.onStepStart?.(event);
                 break;
               case "step_delta":
-                wrappedCallbacks.onStepDelta?.(stepDeltaText2(event), event);
+                wrappedCallbacks.onStepDelta?.(stepDeltaText(event), event);
                 break;
               case "step_complete": {
-                summary.results?.set(stepDisplayName2(event), event.result);
+                summary.results?.set(stepDisplayName(event), event.result);
                 wrappedCallbacks.onStepComplete?.(event.result, event);
                 break;
               }
@@ -9167,7 +10515,7 @@ var RuntypeClient2 = class {
                 wrappedCallbacks.onFlowComplete?.(event);
                 break;
               case "flow_error":
-                wrappedCallbacks.onError?.(new Error(flowErrorMessage2(event)));
+                wrappedCallbacks.onError?.(new Error(flowErrorMessage(event)));
                 break;
             }
           }
@@ -9246,7 +10594,8 @@ var RuntypeClient2 = class {
                 return [toolName, await handler(parameters)];
               } catch (error) {
                 throw new Error(
-                  `Error executing local tool "${toolName}": ${error instanceof Error ? error.message : String(error)}`
+                  `Error executing local tool "${toolName}": ${error instanceof Error ? error.message : String(error)}`,
+                  { cause: error }
                 );
               }
             })
@@ -9310,6 +10659,21 @@ var RuntypeClient2 = class {
     });
     return transformResponse(response);
   }
+  /**
+   * POST request with a raw binary body (e.g. application/zip bundle uploads).
+   */
+  async postBinary(path, body, contentType) {
+    const url = this.buildUrl(path);
+    const headers = { ...this.headers, "Content-Type": contentType };
+    const response = await this.makeRequest(url, {
+      method: "POST",
+      headers,
+      // TS 5.7 types Uint8Array over ArrayBufferLike, which no longer
+      // overlaps DOM BodyInit; the runtime value is a valid fetch body.
+      body
+    });
+    return transformResponse(response);
+  }
   /**
    * Generic request that returns raw Response for streaming
    */
@@ -9410,7 +10774,7 @@ var RuntypeClient2 = class {
     } catch (error) {
       if (timeoutId) clearTimeout(timeoutId);
       if (timeoutId && error instanceof Error && error.name === "AbortError") {
-        throw new Error(`Request timeout after ${this.timeout}ms`);
+        throw new Error(`Request timeout after ${this.timeout}ms`, { cause: error });
       }
       throw error;
     }
@@ -9419,8 +10783,18 @@ var RuntypeClient2 = class {
    * Make HTTP request that returns raw Response (for streaming)
    */
   async makeRawRequest(url, options) {
-    const controller = this.timeout === null ? null : new AbortController();
+    const callerSignal = options.signal ?? null;
+    const controller = this.timeout === null && !callerSignal ? null : new AbortController();
     const timeoutId = controller && this.timeout !== null ? setTimeout(() => controller.abort(), this.timeout) : null;
+    if (callerSignal && controller) {
+      if (callerSignal.aborted) {
+        controller.abort(callerSignal.reason);
+      } else {
+        callerSignal.addEventListener("abort", () => controller.abort(callerSignal.reason), {
+          once: true
+        });
+      }
+    }
     try {
       const response = await fetch(url, {
         ...options,
@@ -9433,8 +10807,8 @@ var RuntypeClient2 = class {
       return response;
     } catch (error) {
       if (timeoutId) clearTimeout(timeoutId);
-      if (timeoutId && error instanceof Error && error.name === "AbortError") {
-        throw new Error(`Request timeout after ${this.timeout}ms`);
+      if (timeoutId && error instanceof Error && error.name === "AbortError" && !callerSignal?.aborted) {
+        throw new Error(`Request timeout after ${this.timeout}ms`, { cause: error });
       }
       throw error;
     }
@@ -9480,9 +10854,6 @@ function createClient(config) {
   return new RuntypeClient2(config);
 }
 
-// src/index.ts
-init_stream_utils();
-
 // src/batch-builder.ts
 var BatchBuilder = class {
   constructor() {
@@ -9540,20 +10911,20 @@ var BatchBuilder = class {
     if (!this.recordType) {
       throw new Error("BatchBuilder: recordType is required. Call .forRecordType(type) first.");
     }
-    const request = {
+    const request2 = {
       flowId: this.flowId,
       recordType: this.recordType
     };
     if (Object.keys(this.batchOptions).length > 0) {
-      request.options = this.batchOptions;
+      request2.options = this.batchOptions;
     }
     if (this.filterConfig) {
-      request.filter = this.filterConfig;
+      request2.filter = this.filterConfig;
     }
     if (this.limitConfig !== void 0) {
-      request.limit = this.limitConfig;
+      request2.limit = this.limitConfig;
     }
-    return request;
+    return request2;
   }
   /**
    * Execute the batch operation
@@ -9710,32 +11081,32 @@ var EvalBuilder = class {
         "EvalBuilder: records are required. Call .forRecordType(type) or .withRecords([...]) first."
       );
     }
-    const request = {};
+    const request2 = {};
     if (this.flowId) {
-      request.flowId = this.flowId;
+      request2.flowId = this.flowId;
     } else if (this.virtualFlow) {
-      request.flow = this.virtualFlow;
+      request2.flow = this.virtualFlow;
     }
     if (this.recordType) {
-      request.recordType = this.recordType;
+      request2.recordType = this.recordType;
     } else if (this.inlineRecords) {
-      request.records = this.inlineRecords;
+      request2.records = this.inlineRecords;
     }
     if (this.modelOverrides) {
-      request.modelOverrides = this.modelOverrides;
+      request2.modelOverrides = this.modelOverrides;
     } else if (this.modelConfigs) {
-      request.modelConfigs = this.modelConfigs;
+      request2.modelConfigs = this.modelConfigs;
     }
     if (Object.keys(this.evalOptions).length > 0) {
-      request.options = this.evalOptions;
+      request2.options = this.evalOptions;
     }
     if (this.filterConfig) {
-      request.filter = this.filterConfig;
+      request2.filter = this.filterConfig;
     }
     if (this.limitConfig !== void 0) {
-      request.limit = this.limitConfig;
+      request2.limit = this.limitConfig;
     }
-    return request;
+    return request2;
   }
   /**
    * Execute the evaluation
@@ -10202,10 +11573,14 @@ var STEP_TYPE_TO_METHOD = {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AgentDriftError,
+  AgentEnsureConflictError,
   AgentVersionsEndpoint,
   AgentsEndpoint,
+  AgentsNamespace,
   AnalyticsEndpoint,
   ApiKeysEndpoint,
+  AppsEndpoint,
   BatchBuilder,
   BatchesNamespace,
   BillingEndpoint,
@@ -10216,18 +11591,23 @@ var STEP_TYPE_TO_METHOD = {
   ClientTokensEndpoint,
   ContextTemplatesEndpoint,
   ConversationsEndpoint,
+  DEFAULT_RECOVERY_AFTER_EMPTY_SESSIONS,
+  DEFAULT_STALL_STOP_AFTER,
   DispatchEndpoint,
   EvalBuilder,
   EvalEndpoint,
   EvalRunner,
   EvalsNamespace,
   FlowBuilder,
+  FlowDriftError,
+  FlowEnsureConflictError,
   FlowResult,
   FlowStepsEndpoint,
   FlowVersionsEndpoint,
   FlowsEndpoint,
   FlowsNamespace,
   IntegrationsEndpoint,
+  LEDGER_ARTIFACT_LINE_PREFIX,
   LogsEndpoint,
   ModelConfigsEndpoint,
   PromptRunner,
@@ -10250,22 +11630,47 @@ var STEP_TYPE_TO_METHOD = {
   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,
+  parseLedgerArtifactRelativePath,
+  parseOffloadedOutputId,
   parseSSEChunk,
   processStream,
+  registerWorkflowHook,
+  resolveStallStopAfter,
+  resolveWorkflowHook,
   sanitizeTaskSlug,
-  streamEvents
+  shouldInjectEmptySessionNudge,
+  shouldRequestModelEscalation,
+  streamEvents,
+  unregisterWorkflowHook
 });