@runtypelabs/sdk 4.8.1 → 4.10.0

package/dist/index.mjs

@@ -1,24 +1,4 @@
-var __defProp = Object.defineProperty;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-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 });
-};
-
 // src/stream-utils.ts
-var stream_utils_exports = {};
-__export(stream_utils_exports, {
-  flowErrorMessage: () => flowErrorMessage,
-  parseFinalBuffer: () => parseFinalBuffer,
-  parseSSEChunk: () => parseSSEChunk,
-  processStream: () => processStream,
-  stepDeltaText: () => stepDeltaText,
-  stepDisplayName: () => stepDisplayName,
-  streamEvents: () => streamEvents
-});
 function parseSSEChunk(chunk, buffer) {
   buffer += chunk;
   const lines = buffer.split("\n");
@@ -268,14 +248,8 @@ async function* streamEvents(response) {
     reader.releaseLock();
   }
 }
-var init_stream_utils = __esm({
-  "src/stream-utils.ts"() {
-    "use strict";
-  }
-});
 
 // src/flow-result.ts
-init_stream_utils();
 var FlowResult = class {
   constructor(response, summary) {
     this.consumed = false;
@@ -411,7 +385,6 @@ var FlowResult = class {
 };
 
 // src/flow-builder.ts
-init_stream_utils();
 async function validateInlineFlow(client, args, savedFlowHint) {
   if (args.existingFlowId) {
     throw new Error(
@@ -1121,20 +1094,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
@@ -1371,22 +1344,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;
       });
@@ -1397,28 +1370,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;
@@ -1426,8 +1620,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
@@ -1442,6 +1639,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)
    *
@@ -2127,9 +2351,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":
@@ -2139,10 +2362,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;
               }
@@ -2150,7 +2373,7 @@ var RuntypeFlowBuilder = class {
                 wrappedCallbacks.onFlowComplete?.(event);
                 break;
               case "flow_error":
-                wrappedCallbacks.onError?.(new Error(flowErrorMessage2(event)));
+                wrappedCallbacks.onError?.(new Error(flowErrorMessage(event)));
                 break;
             }
           }
@@ -2225,7 +2448,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 }
                 );
               }
             })
@@ -2258,15 +2482,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,
@@ -2284,8 +2508,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
@@ -2945,6 +3169,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
@@ -2952,10 +3178,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.
    *
@@ -3048,6 +3287,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;
@@ -3208,7 +3701,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;
     }
@@ -3235,7 +3728,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;
     }
@@ -3410,6 +3903,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
@@ -3632,8 +4151,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");
   }
@@ -3676,9 +4195,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
@@ -3688,18 +4207,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, "/");
@@ -5431,15 +5988,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 {
@@ -5944,6 +6501,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: {
@@ -5975,8 +6548,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,
@@ -5986,9 +6559,9 @@ function appendRuntimeToolsToAgentRequest(request, runtimeTools) {
     ...tool.config ? { config: tool.config } : {}
   }));
   return {
-    ...request,
+    ...request2,
     tools: {
-      ...request.tools,
+      ...request2.tools,
       runtimeTools: [...existing, ...converted]
     }
   };
@@ -6064,21 +6637,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])
     };
   }
   /**
@@ -6108,13 +6681,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 } : {}
     });
   }
   /**
@@ -6210,45 +6784,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);
-        },
-        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`);
@@ -6363,15 +6986,68 @@ var _AgentsEndpoint = class _AgentsEndpoint {
           callbacks?.onAgentComplete?.(forcedCompleteEvent);
           return { completeEvent: forcedCompleteEvent, toolMessages };
         }
-        const resumeResponse = await this.client.requestStream(`/agents/${id}/resume`, {
-          method: "POST",
-          body: JSON.stringify({
+        if (abortSignal?.aborted) {
+          callbacks?.onLocalToolExecutionComplete?.({
             executionId,
-            toolOutputs: { [toolName]: toolResult },
-            streamResponse: true,
-            debugMode: data.debugMode
-          })
-        });
+            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,
+            toolCallId: toolId,
+            toolName,
+            parameters: parsedParams,
+            result: toolResult,
+            success: true,
+            completedAt: (/* @__PURE__ */ new Date()).toISOString(),
+            durationMs: Date.now() - localExecutionStartedAtMs
+          });
+          const interruptCompleteEvent = {
+            type: "agent_complete",
+            executionId,
+            seq: 0,
+            agentId: id,
+            success: true,
+            iterations: 1,
+            stopReason: "end_turn",
+            completedAt: (/* @__PURE__ */ new Date()).toISOString(),
+            // Carry the spend observed so far so the interrupted session's
+            // cost still lands in marathon totals and budget accounting
+            totalCost: lastKnownCost,
+            ...lastKnownTokens ? { totalTokens: lastKnownTokens } : {},
+            finalOutput: [
+              accumulatedOutput.trim(),
+              "Session ended early: user steering was queued and will be delivered at the start of the next session."
+            ].filter(Boolean).join("\n\n"),
+            duration: 0
+          };
+          callbacks?.onAgentComplete?.(interruptCompleteEvent);
+          return { completeEvent: interruptCompleteEvent, toolMessages };
+        }
+        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}`);
@@ -6389,6 +7065,7 @@ var _AgentsEndpoint = class _AgentsEndpoint {
         currentBody = resumeResponse.body;
         continue;
       }
+      if (abortSignal?.aborted) return finishAborted(lastSeenExecutionId);
       return null;
     }
   }
@@ -6660,7 +7337,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";
   }
@@ -6703,32 +7382,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.
+   */
+  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.
    */
-  compactToolResults(messages, newToolMessages, taskName, mode, window) {
-    if (mode === "full-inline") return;
+  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;
@@ -6764,10 +7482,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);
@@ -6889,6 +7617,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)
@@ -6908,10 +7637,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, "/") } : {}
     };
   }
@@ -7377,8 +8110,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);
@@ -7411,6 +8149,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(
@@ -7428,6 +8170,7 @@ var _AgentsEndpoint = class _AgentsEndpoint {
       if (session === 0 && !options.previousMessages) {
         state.originalMessage = options.message;
       }
+      const queuedSteeringMessages = options.getQueuedUserMessages?.() ?? [];
       const preparedSession = await this.prepareSessionContext(
         options.message,
         state,
@@ -7446,8 +8189,11 @@ 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
       );
       const { messages, requestContextManagement, pendingNativeCompactionEvent } = preparedSession;
       let sessionResult;
@@ -7474,7 +8220,9 @@ var _AgentsEndpoint = class _AgentsEndpoint {
             sessionLocalTools || options.localTools,
             sessionCallbacks,
             {
-              onLocalToolResult: this.createLocalToolLoopGuard(state, sessionTrace, workflow)
+              onLocalToolResult: this.createLocalToolLoopGuard(state, sessionTrace, workflow),
+              shouldInterrupt: options.hasQueuedUserMessages,
+              ...options.abortSignal ? { abortSignal: options.abortSignal } : {}
             },
             state.taskName
           );
@@ -7623,22 +8371,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.]`;
@@ -7658,7 +8397,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) {
@@ -7677,24 +8419,24 @@ var _AgentsEndpoint = class _AgentsEndpoint {
       }
       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";
         }
@@ -7709,6 +8451,9 @@ var _AgentsEndpoint = class _AgentsEndpoint {
       } 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);
       }
@@ -7785,6 +8530,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) => {
@@ -7803,12 +8551,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);
@@ -7816,13 +8566,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;
@@ -7876,13 +8628,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);
@@ -7900,6 +8663,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);
     }
@@ -7907,6 +8677,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,
@@ -7923,15 +8696,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) {
@@ -7971,16 +8755,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 [
       {
@@ -7997,16 +8798,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)}`
@@ -8020,7 +8816,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 [
@@ -8150,7 +8946,7 @@ Do NOT redo any of the above work.`
     );
     return prepared.messages;
   }
-  async prepareSessionContext(originalMessage, state, sessionIndex, maxSessions, localToolNames, continuationContext, workflow, builtinToolIds, compactionOptions) {
+  async prepareSessionContext(originalMessage, state, sessionIndex, maxSessions, localToolNames, continuationContext, workflow, builtinToolIds, compactionOptions, steeringMessages) {
     const wf = workflow ?? defaultWorkflow;
     const compactInstructions = compactionOptions?.compactInstructions;
     const resolvedStrategy = continuationContext?.compact ? "summary_fallback" : this.resolveCompactStrategy(compactionOptions?.compactStrategy, compactionOptions?.model);
@@ -8235,9 +9031,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, ""] : [];
     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.";
@@ -8245,6 +9055,7 @@ Do NOT redo any of the above work.`
       const userContent = [
         continuationGuardrail,
         "",
+        ...steeringLines,
         userMessage,
         phaseBlock,
         toolsBlock,
@@ -8260,9 +9071,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 || [],
@@ -8288,7 +9105,8 @@ Do NOT redo any of the above work.`
               reservedOutputTokens: breakdown.reservedOutputTokens,
               breakdown,
               onContextCompaction: compactionOptions?.onContextCompaction,
-              compactInstructions
+              compactInstructions,
+              artifactReferences: replayArtifactReferences
             }
           ),
           requestContextManagement
@@ -8312,7 +9130,8 @@ Do NOT redo any of the above work.`
               reservedOutputTokens: breakdown.reservedOutputTokens,
               breakdown,
               onContextCompaction: compactionOptions?.onContextCompaction,
-              compactInstructions
+              compactInstructions,
+              artifactReferences: replayArtifactReferences
             }
           ),
           requestContextManagement
@@ -8347,6 +9166,7 @@ Do NOT redo any of the above work.`
       const recoveryMessage2 = this.buildStuckTurnRecoveryMessage(state, wf);
       const rejectionNotice = state.lastCompletionRejectionReason ? `TASK_COMPLETE was rejected because: ${state.lastCompletionRejectionReason}. Address this before signaling completion again.` : void 0;
       const continuationContent = [
+        ...steeringLines,
         "Continue the task.",
         phaseBlock,
         toolsBlock,
@@ -8362,23 +9182,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 || [],
@@ -8405,7 +9247,8 @@ Do NOT redo any of the above work.`
               reservedOutputTokens: breakdown.reservedOutputTokens,
               breakdown,
               onContextCompaction: compactionOptions?.onContextCompaction,
-              compactInstructions
+              compactInstructions,
+              artifactReferences: historyArtifactReferences
             }
           ),
           requestContextManagement
@@ -8420,6 +9263,7 @@ Do NOT redo any of the above work.`
     const recoveryMessage = this.buildStuckTurnRecoveryMessage(state, wf);
     const fallbackRejectionNotice = state.lastCompletionRejectionReason ? `TASK_COMPLETE was rejected because: ${state.lastCompletionRejectionReason}. Address this before signaling completion again.` : void 0;
     const content = [
+      ...steeringLines,
       originalMessage,
       phaseBlock,
       toolsBlock,
@@ -8878,6 +9722,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) {
@@ -8920,6 +9810,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);
@@ -8966,7 +9857,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) ?? {};
@@ -8980,12 +9871,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
       }
     };
@@ -9001,13 +9892,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":
@@ -9017,10 +9907,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;
               }
@@ -9028,7 +9918,7 @@ var RuntypeClient2 = class {
                 wrappedCallbacks.onFlowComplete?.(event);
                 break;
               case "flow_error":
-                wrappedCallbacks.onError?.(new Error(flowErrorMessage2(event)));
+                wrappedCallbacks.onError?.(new Error(flowErrorMessage(event)));
                 break;
             }
           }
@@ -9107,7 +9997,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 }
                 );
               }
             })
@@ -9171,6 +10062,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
    */
@@ -9271,7 +10177,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;
     }
@@ -9280,8 +10186,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,
@@ -9294,8 +10210,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;
     }
@@ -9341,9 +10257,6 @@ function createClient(config) {
   return new RuntypeClient2(config);
 }
 
-// src/index.ts
-init_stream_utils();
-
 // src/batch-builder.ts
 var BatchBuilder = class {
   constructor() {
@@ -9401,20 +10314,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
@@ -9571,32 +10484,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
@@ -10062,10 +10975,14 @@ var STEP_TYPE_TO_METHOD = {
   "memory-summary": "memorySummary"
 };
 export {
+  AgentDriftError,
+  AgentEnsureConflictError,
   AgentVersionsEndpoint,
   AgentsEndpoint,
+  AgentsNamespace,
   AnalyticsEndpoint,
   ApiKeysEndpoint,
+  AppsEndpoint,
   BatchBuilder,
   BatchesNamespace,
   BillingEndpoint,
@@ -10082,12 +10999,15 @@ export {
   EvalRunner,
   EvalsNamespace,
   FlowBuilder,
+  FlowDriftError,
+  FlowEnsureConflictError,
   FlowResult,
   FlowStepsEndpoint,
   FlowVersionsEndpoint,
   FlowsEndpoint,
   FlowsNamespace,
   IntegrationsEndpoint,
+  LEDGER_ARTIFACT_LINE_PREFIX,
   LogsEndpoint,
   ModelConfigsEndpoint,
   PromptRunner,
@@ -10111,19 +11031,29 @@ export {
   applyGeneratedRuntimeToolProposalToDispatchRequest,
   attachRuntimeToolsToDispatchRequest,
   buildGeneratedRuntimeToolGateOutput,
+  buildLedgerOffloadReference,
+  buildSendViewOffloadMarker,
+  computeAgentContentHash,
+  computeFlowContentHash,
   createClient,
   createExternalTool,
   defaultWorkflow,
+  defineAgent,
+  defineFlow,
   deployWorkflow,
   evaluateGeneratedRuntimeToolProposal,
+  extractDeclaredToolResultChars,
   gameWorkflow,
   getDefaultPlanPath,
   getLikelySupportingCandidatePaths,
   isDiscoveryToolName,
   isMarathonArtifactPath,
   isPreservationSensitiveTask,
+  normalizeAgentDefinition,
   normalizeCandidatePath,
   parseFinalBuffer,
+  parseLedgerArtifactRelativePath,
+  parseOffloadedOutputId,
   parseSSEChunk,
   processStream,
   sanitizeTaskSlug,