@deepagents/context 3.0.1 → 3.1.0

package/dist/index.js

@@ -1038,10 +1038,10 @@ ${rendered.split("\n").slice(1).join("\n")}`;
         return `${this.#pad(depth)}-`;
       }
       const lines = entries.split("\n");
-      const first = lines[0].trimStart();
+      const first2 = lines[0].trimStart();
       const rest = lines.slice(1).join("\n");
-      return rest ? `${this.#pad(depth)}- ${first}
-${rest}` : `${this.#pad(depth)}- ${first}`;
+      return rest ? `${this.#pad(depth)}- ${first2}
+${rest}` : `${this.#pad(depth)}- ${first2}`;
     }
     return `${this.#pad(depth)}- ${this.#formatValue(item)}`;
   }
@@ -1168,12 +1168,10 @@ function getReminderMetadataRecords(metadata) {
     (item) => isRecord(item) && typeof item.partIndex === "number" && typeof item.start === "number" && typeof item.end === "number"
   );
 }
-function reminderTargetOf(record) {
-  return record.target === "tool-output" ? "tool-output" : "user";
-}
 function normalizeReminderTarget(target) {
   if (target === void 0 || target === "user") return "user";
   if (target === "tool-output") return "tool-output";
+  if (target === "steer") return "steer";
   throw new Error(`Unsupported reminder target: ${String(target)}`);
 }
 function isConditionalReminderOptions(options) {
@@ -1204,7 +1202,7 @@ function isOutputAvailableToolPart(part) {
   return isStaticToolUIPart(part) && part.state === "output-available";
 }
 function isToolOutputReminderEnvelope(value) {
-  return isRecord(value) && typeof value.systemReminder === "string";
+  return isRecord(value) && "result" in value && typeof value.systemReminder === "string" && value.systemReminder.startsWith(SYSTEM_REMINDER_OPEN_TAG);
 }
 function stripTextByRanges(text, ranges) {
   if (ranges.length === 0) {
@@ -1233,43 +1231,22 @@ function stripTextByRanges(text, ranges) {
   return output.trimEnd();
 }
 function stripReminders(message2) {
+  if (isSyntheticSteerMessage(message2)) {
+    return stripSyntheticSteerMessage(message2);
+  }
   const reminderRecords = getReminderMetadataRecords(
     isRecord(message2.metadata) ? message2.metadata : void 0
   );
   const rangesByPartIndex = /* @__PURE__ */ new Map();
-  const toolRemindersByPartIndex = /* @__PURE__ */ new Map();
   for (const range of reminderRecords) {
-    if (reminderTargetOf(range) === "tool-output") {
-      const records = toolRemindersByPartIndex.get(range.partIndex) ?? [];
-      records.push(range);
-      toolRemindersByPartIndex.set(range.partIndex, records);
-      continue;
-    }
     const partRanges = rangesByPartIndex.get(range.partIndex) ?? [];
     partRanges.push({ start: range.start, end: range.end });
     rangesByPartIndex.set(range.partIndex, partRanges);
   }
   const strippedParts = message2.parts.flatMap((part, partIndex) => {
     const clonedPart = { ...part };
-    const toolReminderRecords = toolRemindersByPartIndex.get(partIndex);
-    if (toolReminderRecords !== void 0 && isOutputAvailableToolPart(clonedPart)) {
-      if (typeof clonedPart.output === "string") {
-        return [
-          {
-            ...clonedPart,
-            output: stripTextByRanges(
-              clonedPart.output,
-              toolReminderRecords.map((record) => ({
-                start: record.start,
-                end: record.end
-              }))
-            )
-          }
-        ];
-      }
-      if (isToolOutputReminderEnvelope(clonedPart.output)) {
-        return [{ ...clonedPart, output: clonedPart.output.result }];
-      }
+    if (isOutputAvailableToolPart(clonedPart) && isToolOutputReminderEnvelope(clonedPart.output)) {
+      return [{ ...clonedPart, output: clonedPart.output.result }];
     }
     const ranges = rangesByPartIndex.get(partIndex);
     if (clonedPart.type !== "text" || ranges === void 0) {
@@ -1409,64 +1386,12 @@ function applyReminderToMessage(message2, item, ctx) {
   }
   return item.asPart ? applyPartReminder(message2, resolved.text) : applyInlineReminder(message2, resolved.text);
 }
-function findSingleOutputAvailableToolPart(message2) {
-  let match = null;
-  for (let partIndex = 0; partIndex < message2.parts.length; partIndex++) {
-    const part = message2.parts[partIndex];
-    if (!isOutputAvailableToolPart(part)) continue;
-    if (match) return null;
-    match = { partIndex, part };
-  }
-  return match;
-}
-function applyToolOutputRemindersToMessage(message2, reminders) {
-  if (reminders.length === 0) return [];
-  const target = findSingleOutputAvailableToolPart(message2);
-  if (!target) return [];
-  for (const reminder2 of reminders) {
-    if (reminder2.metadata) {
-      mergeMessageMetadata(message2, reminder2.metadata);
-    }
-  }
-  const added = [];
-  if (typeof target.part.output === "string") {
-    let output = target.part.output;
-    for (const reminder2 of reminders) {
-      const reminderText = formatTaggedReminder(reminder2.text);
-      const start = output.length;
-      output = `${output}${reminderText}`;
-      added.push({
-        id: generateId2(),
-        text: reminder2.text,
-        target: "tool-output",
-        partIndex: target.partIndex,
-        start,
-        end: start + reminderText.length,
-        mode: "tool-output"
-      });
-    }
-    message2.parts[target.partIndex] = {
-      ...target.part,
-      output
-    };
-    return added;
-  }
-  message2.parts[target.partIndex] = {
-    ...target.part,
-    output: {
-      result: target.part.output,
-      systemReminder: reminders.map((reminder2) => reminder2.text).join("\n")
-    }
+function applyRemindersToToolOutput(output, texts) {
+  if (texts.length === 0) return output;
+  return {
+    result: output === void 0 ? null : output,
+    systemReminder: formatTaggedReminder(texts.join("\n"))
   };
-  return reminders.map((reminder2) => ({
-    id: generateId2(),
-    text: reminder2.text,
-    target: "tool-output",
-    partIndex: target.partIndex,
-    start: 0,
-    end: 0,
-    mode: "tool-output"
-  }));
 }
 function mergeReminderMetadata(message2, addedReminders) {
   if (addedReminders.length === 0) return;
@@ -1497,7 +1422,7 @@ function reminder(textOrFragment, options) {
     };
   }
   if (target !== "user") {
-    throw new Error('Reminder target "tool-output" requires a when predicate');
+    throw new Error(`Reminder target "${target}" requires a when predicate`);
   }
   const text = normalizeImmediateReminderText(textOrFragment);
   if (typeof text === "string") {
@@ -1541,6 +1466,48 @@ function user(content, ...reminders) {
     }
   };
 }
+function synthesizeSteerUserMessage(text, firedAt, onceIds = []) {
+  const texts = Array.isArray(text) ? text : [text];
+  for (const value of texts) assertReminderText(value);
+  return {
+    id: generateId2(),
+    role: "user",
+    parts: texts.map((value) => ({
+      type: "text",
+      text: formatTaggedReminder(value)
+    })),
+    metadata: {
+      synthetic: {
+        source: "steer-reminder",
+        firedAt,
+        ...onceIds.length > 0 ? { onceIds } : {}
+      }
+    }
+  };
+}
+function isSyntheticSteerMessage(message2) {
+  const meta = message2.metadata;
+  if (!isRecord(meta)) return false;
+  const synthetic = meta.synthetic;
+  if (!isRecord(synthetic)) return false;
+  return synthetic.source === "steer-reminder";
+}
+function stripSyntheticSteerMessage(message2) {
+  const next = {
+    ...message2,
+    parts: message2.parts.filter((part) => part.type !== "text")
+  };
+  if (isRecord(message2.metadata)) {
+    const metadata = { ...message2.metadata };
+    delete metadata.synthetic;
+    if (Object.keys(metadata).length > 0) {
+      next.metadata = metadata;
+    } else {
+      delete next.metadata;
+    }
+  }
+  return next;
+}
 
 // packages/context/src/lib/guardrail.ts
 function pass(part) {
@@ -1607,7 +1574,10 @@ var Agent = class _Agent {
   sandbox;
   constructor(options) {
     this.#options = options;
-    this.tools = { ...options.sandbox.tools, ...options.tools || {} };
+    this.tools = wrapToolsWithOutputReminders(
+      { ...options.sandbox.tools, ...options.tools || {} },
+      options.context
+    );
     this.context = options.context;
     this.model = options.model;
     this.sandbox = options.sandbox;
@@ -1714,6 +1684,7 @@ var Agent = class _Agent {
         config?.abortSignal
       ),
       stopWhen: stepCountIs(200),
+      prepareStep: context.createSteerPrepareStep(),
       experimental_transform: config?.transform ?? smoothStream(),
       tools: this.tools,
       experimental_context: contextVariables,
@@ -1750,9 +1721,14 @@ var Agent = class _Agent {
         generateId: assistantMsgId ? () => assistantMsgId : generateId3,
         onStepFinish: async ({ responseMessage }) => {
           if (!stepSaved) return;
-          const normalizedMessage = assistantMsgId ? { ...responseMessage, id: assistantMsgId } : responseMessage;
-          context.set(assistant(normalizedMessage));
-          await context.save({ branch: false });
+          const head = await context.headMessage();
+          if (head?.name === "assistant") {
+            await context.writeAssistantSegment(responseMessage);
+          } else {
+            const message2 = assistantMsgId ? { ...responseMessage, id: assistantMsgId } : responseMessage;
+            context.set(assistant(message2));
+            await context.save({ branch: false });
+          }
           stepSaved.resolve();
           stepSaved = null;
         },
@@ -1959,6 +1935,29 @@ ${details}
     });
   }
 };
+function wrapToolsWithOutputReminders(tools, context) {
+  if (!context) return tools;
+  const wrapped = {};
+  for (const [name, toolDef] of Object.entries(tools)) {
+    const execute = toolDef.execute;
+    if (typeof execute !== "function") {
+      wrapped[name] = toolDef;
+      continue;
+    }
+    wrapped[name] = {
+      ...toolDef,
+      execute: async (input, options) => {
+        const result = await execute.call(toolDef, input, options);
+        if (isAsyncIterable(result)) return result;
+        return context.applyToolOutputReminders(result);
+      }
+    };
+  }
+  return wrapped;
+}
+function isAsyncIterable(value) {
+  return typeof value === "object" && value !== null && Symbol.asyncIterator in value && typeof value[Symbol.asyncIterator] === "function";
+}
 function agent(options) {
   return new Agent(options);
 }
@@ -2062,6 +2061,7 @@ import { z as z2 } from "zod";
 
 // packages/context/src/lib/engine.ts
 import {
+  convertToModelMessages as convertToModelMessages2,
   generateId as generateId4,
   validateUIMessages
 } from "ai";
@@ -2097,30 +2097,41 @@ var ChainSummaryBuilder = class {
   #lastMessage;
   #lastAssistantMessage;
   #lastAssistantMessages = [];
+  #firedOnceIds = /* @__PURE__ */ new Set();
   ingestStored(msg) {
     this.#messageCount++;
     if (msg.name === "assistant") {
-      const message2 = requireUIMessage(
+      const message3 = requireUIMessage(
         msg.data,
         `Stored assistant message "${msg.id}"`
       );
-      this.#lastAssistantMessage = message2;
-      this.#lastAssistantMessages.push(message2);
+      this.#lastAssistantMessage = message3;
+      this.#lastAssistantMessages.push(message3);
       return;
     }
     if (msg.name !== "user") {
       return;
     }
-    this.#turn++;
-    this.#lastMessageAt = msg.createdAt;
-    this.#lastMessage = requireUIMessage(
+    const message2 = requireUIMessage(
       msg.data,
       `Stored user message "${msg.id}"`
     );
+    if (isSyntheticSteerMessage(message2)) {
+      for (const id of message2.metadata.synthetic.onceIds ?? []) {
+        this.#firedOnceIds.add(id);
+      }
+      return;
+    }
+    this.#turn++;
+    this.#lastMessageAt = msg.createdAt;
+    this.#lastMessage = message2;
   }
   ingestPending(fragment2) {
     this.#messageCount++;
-    if (fragment2.name === "user") this.#turn++;
+    if (fragment2.name !== "user") return;
+    const encoded = fragment2.codec?.encode();
+    if (encoded && isSyntheticSteerMessage(encoded)) return;
+    this.#turn++;
   }
   build() {
     return {
@@ -2129,7 +2140,8 @@ var ChainSummaryBuilder = class {
       lastMessageAt: this.#lastMessageAt,
       lastMessage: this.#lastMessage,
       lastAssistantMessage: this.#lastAssistantMessage,
-      lastAssistantMessages: this.#lastAssistantMessages
+      lastAssistantMessages: this.#lastAssistantMessages,
+      firedOnceIds: this.#firedOnceIds
     };
   }
 };
@@ -2338,7 +2350,7 @@ var GeneratorResolver = class {
   async resolve(value, ctx) {
     const iterable = value(ctx);
     const collected = [];
-    if (isAsyncIterable(iterable)) {
+    if (isAsyncIterable2(iterable)) {
       for await (const chunk of iterable) {
         pushLimited(collected, chunk, this.#maxItems, this.name);
       }
@@ -2350,7 +2362,7 @@ var GeneratorResolver = class {
     return collected;
   }
 };
-function isAsyncIterable(value) {
+function isAsyncIterable2(value) {
   return typeof value === "object" && value !== null && Symbol.asyncIterator in value;
 }
 function pushLimited(collected, chunk, maxItems, resolverName) {
@@ -2388,7 +2400,7 @@ var IterableResolver = class {
   async resolve(value, _ctx) {
     const iterable = value;
     const collected = [];
-    if (isAsyncIterable2(iterable)) {
+    if (isAsyncIterable3(iterable)) {
       for await (const chunk of iterable) {
         pushLimited2(collected, chunk, this.#maxItems, this.name);
       }
@@ -2400,7 +2412,7 @@ var IterableResolver = class {
     return collected;
   }
 };
-function isAsyncIterable2(value) {
+function isAsyncIterable3(value) {
   return typeof value === "object" && value !== null && Symbol.asyncIterator in value;
 }
 function pushLimited2(collected, chunk, maxItems, resolverName) {
@@ -2556,6 +2568,54 @@ function defaultResolvers() {
   ];
 }
 
+// packages/context/src/lib/save/reminder-eval.ts
+async function evaluateFiredReminders(configs, whenCtx) {
+  if (configs.length === 0) return [];
+  const collectors = configs.map(() => /* @__PURE__ */ new Set());
+  const whenResults = await Promise.allSettled(
+    // Wrap in an async thunk so a synchronously-throwing predicate becomes a
+    // rejected promise (allSettled cannot catch a throw inside the map itself).
+    configs.map(
+      async (config, i) => config.when({ ...whenCtx, onceCollector: collectors[i] })
+    )
+  );
+  const fired = [];
+  for (let i = 0; i < configs.length; i++) {
+    const result = whenResults[i];
+    if (result.status === "rejected") {
+      console.warn("reminder when() predicate threw; treating as not fired", {
+        reason: result.reason
+      });
+      continue;
+    }
+    if (result.value === true) {
+      fired.push({ config: configs[i], onceIds: [...collectors[i]] });
+    }
+  }
+  if (fired.length === 0) return [];
+  const resolutions = await Promise.allSettled(
+    fired.map(({ config }) => resolveReminderAsync(config, whenCtx))
+  );
+  const matched = [];
+  for (let i = 0; i < fired.length; i++) {
+    const result = resolutions[i];
+    if (result.status === "rejected") {
+      console.warn("reminder text resolver threw; skipping reminder", {
+        reason: result.reason
+      });
+      continue;
+    }
+    if (result.value) {
+      matched.push({
+        config: fired[i].config,
+        resolved: result.value,
+        onceIds: fired[i].onceIds
+      });
+    }
+  }
+  return matched;
+}
+
 // packages/context/src/lib/save/save-pipeline.ts
 var SavePipeline = class {
   #engine;
@@ -2581,65 +2641,49 @@ var SavePipeline = class {
     }
     return this;
   }
-  async evaluateReminders(handlers) {
-    const conditional = this.#fragments.filter(isConditionalReminder);
-    if (conditional.length === 0) return this;
-    const configsByTarget = /* @__PURE__ */ new Map();
-    for (const fragment2 of conditional) {
-      const config = fragment2.metadata.reminder;
-      const target = config.target;
-      const list = configsByTarget.get(target) ?? [];
-      list.push(config);
-      configsByTarget.set(target, list);
-    }
-    const chain = await this.#engine.getChainSummary();
-    const base = this.#engine.buildBaseWhenCtx(chain);
-    const sharedUserMessage = this.#encodePendingUserMessage();
-    for (const handler of handlers) {
-      const configs = configsByTarget.get(handler.target);
-      if (!configs || configs.length === 0) continue;
-      const prepared = handler.prepare({
-        pending: this.#pending,
-        base,
-        chain,
-        sharedUserMessage
-      });
-      if (!prepared) continue;
-      const whenResults = await Promise.all(
-        configs.map((config) => config.when(prepared.whenCtx))
-      );
-      const fired = configs.filter((_, i) => whenResults[i]);
-      if (fired.length === 0) continue;
-      const resolvedOrNull = await Promise.all(
-        fired.map((config) => resolveReminderAsync(config, prepared.whenCtx))
-      );
-      const matched = [];
-      for (let i = 0; i < resolvedOrNull.length; i++) {
-        const resolution = resolvedOrNull[i];
-        if (resolution)
-          matched.push({ config: fired[i], resolved: resolution });
-      }
-      if (matched.length === 0) continue;
-      handler.apply({
-        pending: this.#pending,
-        carrier: prepared.carrier,
-        fired: matched.map((m) => m.config),
-        resolved: matched.map((m) => m.resolved)
-      });
-    }
-    return this;
-  }
-  #encodePendingUserMessage() {
+  /**
+   * Fold any fired `target: 'user'` conditional reminders into the last pending
+   * user message. `steer` reminders fire mid-loop via the engine's prepareStep
+   * hook and `tool-output` reminders wrap at tool-execution time, so neither is
+   * handled here — the save pipeline only carries user-message reminders.
+   */
+  async evaluateUserReminders() {
+    const configs = this.#fragments.filter(isConditionalReminder).map((fragment3) => fragment3.metadata.reminder).filter((config) => config.target === "user");
+    if (configs.length === 0) return this;
     const fragmentIndex = this.#pending.findLastIndex(
       (fragment3) => fragment3.name === "user"
     );
-    if (fragmentIndex < 0) return void 0;
+    if (fragmentIndex < 0) return this;
     const fragment2 = this.#pending[fragmentIndex];
-    if (!fragment2.codec) return void 0;
-    return requireUserUIMessage(
+    if (!fragment2.codec) return this;
+    const message2 = requireUserUIMessage(
       fragment2.codec.encode(),
       `Pending user fragment "${fragment2.name}"`
     );
+    const chain = await this.#engine.getChainSummary();
+    const whenCtx = {
+      ...this.#engine.buildBaseWhenCtx(chain),
+      content: extractPlainText(message2),
+      currentMessage: message2,
+      lastAssistantMessage: chain.lastAssistantMessage,
+      lastAssistantMessages: chain.lastAssistantMessages
+    };
+    const matched = await evaluateFiredReminders(configs, whenCtx);
+    if (matched.length === 0) return this;
+    const reminders = matched.map((m) => ({
+      text: m.resolved.text,
+      asPart: m.config.asPart,
+      target: "user",
+      metadata: m.resolved.metadata
+    }));
+    const originalId = fragment2.id;
+    const recreated = user(
+      originalId ? { ...message2, id: originalId } : message2,
+      ...reminders
+    );
+    if (originalId) recreated.id = originalId;
+    this.#pending[fragmentIndex] = recreated;
+    return this;
   }
   async persist() {
     let parentId = this.#engine.getActiveBranch().headMessageId;
@@ -2680,108 +2724,6 @@ var SavePipeline = class {
   }
 };
 
-// packages/context/src/lib/save/tool-output-target-handler.ts
-var ToolOutputTargetHandler = class {
-  target = "tool-output";
-  prepare({
-    pending,
-    base,
-    chain,
-    sharedUserMessage
-  }) {
-    const fragmentIndex = pending.findLastIndex(
-      (fragment3) => fragment3.name === "assistant"
-    );
-    if (fragmentIndex < 0) return null;
-    const fragment2 = pending[fragmentIndex];
-    if (!fragment2.codec) return null;
-    const currentMessage = sharedUserMessage ?? chain.lastMessage;
-    if (!currentMessage) return null;
-    const message2 = requireUIMessage(
-      fragment2.codec.encode(),
-      `Pending assistant fragment "${fragment2.name}"`
-    );
-    if (!findSingleOutputAvailableToolPart(message2)) return null;
-    return {
-      whenCtx: {
-        ...base,
-        content: extractPlainText(currentMessage),
-        currentMessage,
-        lastAssistantMessage: message2,
-        lastAssistantMessages: [
-          ...chain.lastAssistantMessages ?? [],
-          message2
-        ]
-      },
-      carrier: { message: message2, fragmentIndex }
-    };
-  }
-  apply({ pending, carrier, resolved }) {
-    const reminders = resolved.map((resolution) => ({
-      text: resolution.text,
-      metadata: resolution.metadata
-    }));
-    const metadata = applyToolOutputRemindersToMessage(
-      carrier.message,
-      reminders
-    );
-    mergeReminderMetadata(carrier.message, metadata);
-    const originalId = pending[carrier.fragmentIndex].id;
-    const message2 = originalId ? { ...carrier.message, id: originalId } : carrier.message;
-    const updated = assistant(message2);
-    if (originalId) updated.id = originalId;
-    pending[carrier.fragmentIndex] = updated;
-  }
-};
-
-// packages/context/src/lib/save/user-target-handler.ts
-var UserTargetHandler = class {
-  target = "user";
-  prepare({
-    pending,
-    base,
-    chain
-  }) {
-    const fragmentIndex = pending.findLastIndex(
-      (fragment3) => fragment3.name === "user"
-    );
-    if (fragmentIndex < 0) return null;
-    const fragment2 = pending[fragmentIndex];
-    if (!fragment2.codec) return null;
-    const message2 = requireUserUIMessage(
-      fragment2.codec.encode(),
-      `Pending user fragment "${fragment2.name}"`
-    );
-    return {
-      whenCtx: {
-        ...base,
-        content: extractPlainText(message2),
-        currentMessage: message2,
-        lastAssistantMessage: chain.lastAssistantMessage,
-        lastAssistantMessages: chain.lastAssistantMessages
-      },
-      carrier: { message: message2, fragmentIndex },
-      sharedUserMessage: message2
-    };
-  }
-  apply({ pending, carrier, fired, resolved }) {
-    const reminders = resolved.map((resolution, i) => ({
-      text: resolution.text,
-      asPart: fired[i].asPart,
-      target: "user",
-      metadata: resolution.metadata
-    }));
-    const originalId = pending[carrier.fragmentIndex].id;
-    const message2 = requireUserUIMessage(
-      originalId ? { ...carrier.message, id: originalId } : carrier.message,
-      "Pending user reminder carrier"
-    );
-    const recreated = user(message2, ...reminders);
-    if (originalId) recreated.id = originalId;
-    pending[carrier.fragmentIndex] = recreated;
-  }
-};
-
 // packages/context/src/lib/store/sqlite.store.ts
 import { DatabaseSync } from "node:sqlite";
 
@@ -3402,6 +3344,23 @@ function isSkillPathMapping(value) {
 function isEmptyAssistantPlaceholder(message2) {
   return message2.role === "assistant" && message2.parts.length === 0;
 }
+function stepStartPartIndices(parts) {
+  const indices = [];
+  for (let i = 0; i < parts.length; i++) {
+    if (parts[i].type === "step-start") indices.push(i);
+  }
+  return indices;
+}
+function spliceSteerMessages(messages, fired) {
+  const ordered = [...fired].sort((a, b) => a.spliceIndex - b.spliceIndex);
+  const out = [...messages];
+  let offset = 0;
+  for (const fire of ordered) {
+    out.splice(fire.spliceIndex + offset, 0, ...fire.synthModel);
+    offset += fire.synthModel.length;
+  }
+  return out;
+}
 var ContextEngine = class _ContextEngine {
   /** Non-message fragments (role, hints, etc.) - not persisted in graph */
   #fragments = [];
@@ -3765,15 +3724,211 @@ var ContextEngine = class _ContextEngine {
       this.#fragments
     );
     await pipeline.applyUpdateBranching(options?.branch ?? true);
-    await pipeline.evaluateReminders(this.#reminderHandlers);
+    await pipeline.evaluateUserReminders();
     const result = await pipeline.persist();
     this.#pendingMessages = [];
     return result;
   }
-  #reminderHandlers = [
-    new UserTargetHandler(),
-    new ToolOutputTargetHandler()
-  ];
+  #currentSteerSession;
+  /**
+   * Build the `prepareStep` hook that injects steer reminders mid-loop.
+   *
+   * Semantics are "inject once, persist": when a steer reminder's predicate
+   * fires (only after the model has produced ≥1 step with content — the mid-loop
+   * gate), its `<system-reminder>` user message is spliced into the model prompt
+   * at the step boundary where it fired AND re-spliced on every subsequent step,
+   * so the model keeps seeing it for the rest of the loop.
+   *
+   * Firing is edge-triggered with a post-fire re-sample: each fire resets the
+   * elapsed reference (`lastSyntheticAt`), then the config is immediately
+   * re-evaluated against the reset context — self-resetting predicates like
+   * `elapsedExceeds` read false and re-arm (so they recur every N within one
+   * stream), while constant predicates like `everyNTurns` read true and disarm
+   * (so they fire once per stream). Any later false sample re-arms a config.
+   * All state is closure-local (a fresh SteerSession per call), so overlapping
+   * streams / guardrail retries never share a cursor.
+   *
+   * The session is also consumed by writeAssistantSegment, which carves the
+   * streamed assistant message into the matching `[assistant, steer, assistant]`
+   * split — so the stored chain reproduces exactly the prompt the model saw
+   * (store/prompt parity).
+   */
+  createSteerPrepareStep() {
+    const session = {
+      firedOnceIds: /* @__PURE__ */ new Set(),
+      fired: [],
+      currentSegStart: 0,
+      materialized: 0
+    };
+    this.#currentSteerSession = session;
+    return async ({ steps, stepNumber, messages }) => {
+      const priorStep = stepNumber >= 1 ? steps[stepNumber - 1] : void 0;
+      const canFire = (priorStep?.content?.length ?? 0) > 0;
+      if (canFire) {
+        const configs = this.#steerConfigs();
+        if (configs.length > 0) {
+          const whenCtx = await this.#steerWhenCtx(session);
+          const matched = await evaluateFiredReminders(configs, whenCtx);
+          if (matched.length > 0) {
+            const onceIds = [...new Set(matched.flatMap((m) => m.onceIds))];
+            for (const id of onceIds) session.firedOnceIds.add(id);
+            const synth = synthesizeSteerUserMessage(
+              matched.map((m) => m.resolved.text),
+              Date.now(),
+              onceIds
+            );
+            const synthModel = await convertToModelMessages2([synth], {
+              ignoreIncompleteToolCalls: true
+            });
+            session.fired.push({
+              afterStep: stepNumber - 1,
+              spliceIndex: messages.length,
+              synth,
+              synthModel
+            });
+          }
+        }
+      }
+      if (session.fired.length === 0) return void 0;
+      return {
+        messages: spliceSteerMessages(
+          messages,
+          session.fired
+        )
+      };
+    };
+  }
+  /**
+   * Persist the streamed assistant message, carving it into the steer split when
+   * steer reminders fired this turn.
+   *
+   * Called from chat()'s onStepFinish/onFinish (and the guardrail path) with the
+   * cumulative response message. Segment boundaries come from the `step-start`
+   * markers in the message itself — no cross-track store read — so the carve is
+   * race-free. Idempotent: finalized segments keep stable ids; the open segment
+   * is updated in place. With no active steer it degrades to a plain in-place
+   * write of the whole message to the reserved head.
+   */
+  async writeAssistantSegment(message2) {
+    const head = await this.headMessage();
+    if (head?.name !== "assistant") {
+      throw new Error(
+        "writeAssistantSegment: expected an assistant message at chain head."
+      );
+    }
+    const session = this.#currentSteerSession;
+    if (!session || session.fired.length === 0) {
+      this.set(assistant({ ...message2, id: head.id }));
+      await this.save({ branch: false });
+      return;
+    }
+    if (session.currentSegId === void 0) {
+      session.currentSegId = head.id;
+      session.currentSegStart = 0;
+    }
+    const stepStarts = stepStartPartIndices(message2.parts);
+    while (session.materialized < session.fired.length) {
+      const fire = session.fired[session.materialized];
+      const boundary = stepStarts[fire.afterStep + 1];
+      if (boundary === void 0) break;
+      this.set(
+        assistant({
+          id: session.currentSegId,
+          role: "assistant",
+          parts: message2.parts.slice(session.currentSegStart, boundary)
+        })
+      );
+      this.set(user(fire.synth));
+      session.currentSegId = generateId4();
+      session.currentSegStart = boundary;
+      session.materialized++;
+    }
+    this.set(
+      assistant({
+        ...message2,
+        id: session.currentSegId,
+        parts: message2.parts.slice(session.currentSegStart)
+      })
+    );
+    await this.save({ branch: false });
+  }
+  #steerConfigs() {
+    return this.#fragments.filter(isConditionalReminder).map((fragment2) => fragment2.metadata.reminder).filter((config) => config.target === "steer");
+  }
+  async #steerWhenCtx(session) {
+    await this.#ensureInitialized();
+    if (!session.whenBase) {
+      const chain = await this.#getChainContext();
+      const base2 = this.#asSavePipelineEngine().buildBaseWhenCtx(chain);
+      const currentMessage2 = chain.lastMessage;
+      if (!currentMessage2) {
+        throw new Error(
+          "steer reminders require a user message earlier in the turn"
+        );
+      }
+      session.whenBase = {
+        base: base2,
+        content: extractPlainText(currentMessage2),
+        currentMessage: currentMessage2,
+        lastAssistantMessage: chain.lastAssistantMessage,
+        lastAssistantMessages: chain.lastAssistantMessages,
+        chainFiredOnceIds: chain.firedOnceIds
+      };
+    }
+    const {
+      base,
+      content,
+      currentMessage,
+      lastAssistantMessage,
+      lastAssistantMessages,
+      chainFiredOnceIds
+    } = session.whenBase;
+    const elapsed = base.lastMessageAt !== void 0 ? Date.now() - base.lastMessageAt : void 0;
+    return {
+      ...base,
+      elapsed,
+      content,
+      currentMessage,
+      lastAssistantMessage,
+      lastAssistantMessages,
+      firedOnceIds: /* @__PURE__ */ new Set([...chainFiredOnceIds, ...session.firedOnceIds])
+    };
+  }
+  /**
+   * Evaluate `target: 'tool-output'` reminders against a tool's raw result and
+   * return the (possibly wrapped) output.
+   *
+   * Called by the agent's tool wrapper right after each `execute()` resolves —
+   * upstream of both the model and the store, so the next model step and the
+   * persisted chain see the exact same wrapped value (store/prompt parity).
+   *
+   * Returns the output unchanged when no tool-output reminder fires. Without a
+   * persisted user message there is no turn context to evaluate against
+   * (e.g. asTool forks that set a pending user without saving), so the output
+   * passes through untouched.
+   */
+  async applyToolOutputReminders(output) {
+    const configs = this.#fragments.filter(isConditionalReminder).map((fragment2) => fragment2.metadata.reminder).filter((config) => config.target === "tool-output");
+    if (configs.length === 0) return output;
+    await this.#ensureInitialized();
+    const chain = await this.#getChainContext();
+    const currentMessage = chain.lastMessage;
+    if (!currentMessage) return output;
+    const base = this.#asSavePipelineEngine().buildBaseWhenCtx(chain);
+    const whenCtx = {
+      ...base,
+      content: extractPlainText(currentMessage),
+      currentMessage,
+      lastAssistantMessage: chain.lastAssistantMessage,
+      lastAssistantMessages: chain.lastAssistantMessages
+    };
+    const matched = await evaluateFiredReminders(configs, whenCtx);
+    if (matched.length === 0) return output;
+    return applyRemindersToToolOutput(
+      output,
+      matched.map((m) => m.resolved.text)
+    );
+  }
   #asSavePipelineEngine() {
     return {
       store: this.#store,
@@ -4689,7 +4844,6 @@ var defaultChatMessageMetadata = ({
 };
 async function chat(agent2, options = {}) {
   const context = agent2.context;
-  const sandbox = agent2.sandbox;
   if (!context) {
     throw new Error(
       "Agent is missing a context. Provide context when creating the agent."
@@ -4701,7 +4855,7 @@ async function chat(agent2, options = {}) {
       "chat: expected an assistant message at head. Call context.continue(input) before chat()."
     );
   }
-  const assistantMsgId = head.id;
+  const initialAssistantMsgId = head.id;
   const uiMessages = await context.getMessages();
   const streamContextVariables = options.contextVariables === void 0 ? {} : options.contextVariables;
   const [title, result] = await Promise.all([
@@ -4723,42 +4877,30 @@ async function chat(agent2, options = {}) {
     sendReasoning: true,
     sendSources: true,
     originalMessages: uiMessages,
-    generateMessageId: () => assistantMsgId,
+    generateMessageId: () => initialAssistantMsgId,
     messageMetadata: options.messageMetadata ?? defaultChatMessageMetadata
   });
   return createUIMessageStream2({
     originalMessages: uiMessages,
-    generateId: () => assistantMsgId,
+    generateId: () => initialAssistantMsgId,
     onStepFinish: async ({ responseMessage }) => {
-      const normalizedMessage = {
-        ...responseMessage,
-        id: assistantMsgId
-      };
-      context.set(assistant(normalizedMessage));
-      await context.save({ branch: false });
+      await context.writeAssistantSegment(responseMessage);
     },
     onFinish: async ({ responseMessage, isAborted }) => {
-      const normalizedMessage = {
-        ...responseMessage,
-        id: assistantMsgId
-      };
+      let message2 = responseMessage;
       if (isAborted) {
-        normalizedMessage.parts = sanitizeAbortedParts(normalizedMessage.parts);
+        message2 = { ...message2, parts: sanitizeAbortedParts(message2.parts) };
       }
-      const drained = sandbox.drainFileEvents();
-      const fileEvents = isAborted ? [] : drained;
-      const finalMetadata = await options.finalAssistantMetadata?.(normalizedMessage);
+      const finalMetadata = await options.finalAssistantMetadata?.(message2);
       const mergedMetadata = {
-        ...normalizedMessage.metadata ?? {},
-        ...fileEvents.length > 0 ? { fileEvents } : {},
+        ...message2.metadata ?? {},
         ...finalMetadata ?? {}
       };
-      const hasMetadata = Object.keys(mergedMetadata).length > 0;
-      const finalMessage = hasMetadata ? { ...normalizedMessage, metadata: mergedMetadata } : normalizedMessage;
-      context.set(assistant(finalMessage));
-      await context.save({ branch: false });
-      const totalUsage = await result.totalUsage;
-      await context.trackUsage(totalUsage);
+      if (Object.keys(mergedMetadata).length > 0) {
+        message2 = { ...message2, metadata: mergedMetadata };
+      }
+      await context.writeAssistantSegment(message2);
+      await context.trackUsage(await result.totalUsage);
     },
     execute: async ({ writer }) => {
       writer.merge(uiStream);
@@ -5345,6 +5487,23 @@ function lastAssistantLength(spec) {
   };
 }
 
+// packages/context/src/lib/fragments/reminders/once.ts
+function once(id) {
+  if (id.trim().length === 0) {
+    throw new Error("once(id) requires a non-empty id");
+  }
+  return (ctx) => {
+    if (ctx.firedOnceIds === void 0) {
+      throw new Error(
+        `once('${id}') is only supported on target:'steer' reminders`
+      );
+    }
+    if (ctx.firedOnceIds.has(id)) return false;
+    ctx.onceCollector?.add(id);
+    return true;
+  };
+}
+
 // packages/context/src/lib/fragments/reminders/temporal/elapsed.ts
 function elapsedExceeds(ms) {
   return (ctx) => (ctx.elapsed ?? 0) >= ms;
@@ -5502,15 +5661,15 @@ function dateReminder(options) {
       const now = /* @__PURE__ */ new Date();
       const currentDate = formatDateKey(now, tz);
       const currentDay = formatDayOfWeek(now, tz);
-      let diff2 = "";
+      let diff = "";
       if (ctx.lastMessageAt !== void 0) {
         const prev = new Date(ctx.lastMessageAt);
-        diff2 = formatDiff([
+        diff = formatDiff([
           diffLine("date", formatDateKey(prev, tz), currentDate),
           diffLine("day of week", formatDayOfWeek(prev, tz), currentDay)
         ]);
       }
-      return `${diff2}Date: ${currentDate}
+      return `${diff}Date: ${currentDate}
 Day of Week: ${currentDay}`;
     },
     { when: dayChanged(options), asPart: false }
@@ -5522,14 +5681,14 @@ function timeReminder(options) {
       const tz = resolveTz(options, ctx);
       const now = /* @__PURE__ */ new Date();
       const currentTime = formatTime(now, tz);
-      let diff2 = "";
+      let diff = "";
       if (ctx.lastMessageAt !== void 0) {
         const prev = new Date(ctx.lastMessageAt);
-        diff2 = formatDiff([
+        diff = formatDiff([
           diffLine("hour", formatHour(prev, tz), formatHour(now, tz))
         ]);
       }
-      return `${diff2}Time: ${currentTime}`;
+      return `${diff}Time: ${currentTime}`;
     },
     { when: hourChanged(options), asPart: false }
   );
@@ -5540,14 +5699,14 @@ function monthReminder(options) {
       const tz = resolveTz(options, ctx);
       const now = /* @__PURE__ */ new Date();
       const currentMonth = formatMonthName(now, tz);
-      let diff2 = "";
+      let diff = "";
       if (ctx.lastMessageAt !== void 0) {
         const prev = new Date(ctx.lastMessageAt);
-        diff2 = formatDiff([
+        diff = formatDiff([
           diffLine("month", formatMonthName(prev, tz), currentMonth)
         ]);
       }
-      return `${diff2}Month: ${currentMonth}`;
+      return `${diff}Month: ${currentMonth}`;
     },
     { when: monthChanged(options), asPart: false }
   );
@@ -5558,14 +5717,14 @@ function yearReminder(options) {
       const tz = resolveTz(options, ctx);
       const now = /* @__PURE__ */ new Date();
       const currentYear = formatYear(now, tz);
-      let diff2 = "";
+      let diff = "";
       if (ctx.lastMessageAt !== void 0) {
         const prev = new Date(ctx.lastMessageAt);
-        diff2 = formatDiff([
+        diff = formatDiff([
           diffLine("year", formatYear(prev, tz), currentYear)
         ]);
       }
-      return `${diff2}Year: ${currentYear}`;
+      return `${diff}Year: ${currentYear}`;
     },
     { when: yearChanged(options), asPart: false }
   );
@@ -5576,14 +5735,14 @@ function seasonReminder(options) {
       const tz = resolveTz(options, ctx);
       const now = /* @__PURE__ */ new Date();
       const currentSeason = getSeason(getMonthIndex(now, tz));
-      let diff2 = "";
+      let diff = "";
       if (ctx.lastMessageAt !== void 0) {
         const prev = new Date(ctx.lastMessageAt);
-        diff2 = formatDiff([
+        diff = formatDiff([
           diffLine("season", getSeason(getMonthIndex(prev, tz)), currentSeason)
         ]);
       }
-      return `${diff2}Season: ${currentSeason}`;
+      return `${diff}Season: ${currentSeason}`;
     },
     { when: seasonChanged(options), asPart: false }
   );
@@ -5601,11 +5760,11 @@ function localeReminder() {
       const current = getLocaleFromMessage(ctx.currentMessage);
       if (!current) return "";
       const last = getLocaleFromMessage(ctx.lastMessage);
-      const diff2 = last ? formatDiff([
+      const diff = last ? formatDiff([
         diffLine("language", last.language, current.language),
         diffLine("timezone", last.timeZone, current.timeZone)
       ]) : "";
-      return `${diff2}Language: ${current.language}
+      return `${diff}Language: ${current.language}
 Timezone: ${current.timeZone}`;
     },
     { when: whenFn, asPart: false }
@@ -5692,7 +5851,7 @@ function toolCallCount(name, spec) {
 function everyNTurns(n) {
   return ({ turn }) => turn % n === 0;
 }
-function once() {
+function first() {
   return ({ turn }) => turn === 1;
 }
 function firstN(n) {
@@ -6114,158 +6273,878 @@ import {
 } from "bash-tool";
 import z3 from "zod";
 
-// packages/context/src/lib/sandbox/file-events.ts
-var SnapshotFailedError = class extends Error {
-  stderr;
-  constructor(message2, stderr) {
+// packages/context/src/lib/sandbox/file-changes.ts
+import { randomUUID } from "node:crypto";
+import { posix as posix2 } from "node:path";
+
+// packages/context/src/lib/sandbox/installers/installer.ts
+import "bash-tool";
+import spawn from "nano-spawn";
+
+// packages/context/src/lib/sandbox/docker-sandbox-errors.ts
+var DockerSandboxError = class extends Error {
+  containerId;
+  constructor(message2, containerId) {
     super(message2);
-    this.name = "SnapshotFailedError";
-    this.stderr = stderr;
+    this.name = "DockerSandboxError";
+    this.containerId = containerId;
   }
 };
-function shellQuote(value) {
-  return `'${value.replace(/'/g, `'\\''`)}'`;
-}
-async function snapshot(execute, destination) {
-  const probe = await execute(`[ -d ${shellQuote(destination)} ]`);
-  if (probe.exitCode !== 0) return /* @__PURE__ */ new Map();
-  const list = await execute(
-    `find ${shellQuote(destination)} -type f -exec sha256sum {} +`
-  );
-  if (list.exitCode !== 0) {
-    throw new SnapshotFailedError(
-      `snapshot failed for ${destination}`,
-      list.stderr
-    );
-  }
-  const snap = /* @__PURE__ */ new Map();
-  if (!list.stdout) return snap;
-  for (const line of list.stdout.split("\n")) {
-    if (line.length < 66) continue;
-    snap.set(line.slice(66), line.slice(0, 64));
-  }
-  return snap;
-}
-function lazyReadable(innerPromise) {
-  let reader = null;
-  return new ReadableStream({
-    async pull(controller) {
-      if (!reader) {
-        const inner = await innerPromise;
-        reader = inner.getReader();
-      }
-      const { done, value } = await reader.read();
-      if (done) controller.close();
-      else controller.enqueue(value);
-    },
-    async cancel(reason) {
-      if (reader) {
-        await reader.cancel(reason);
-      } else {
-        const inner = await innerPromise;
-        await inner.cancel(reason);
-      }
-    }
-  });
-}
-function diff(before, after) {
-  const events = [];
-  const ts = Date.now();
-  for (const [path5, hash] of after) {
-    const prior = before.get(path5);
-    if (prior === void 0) {
-      events.push({ path: path5, op: "write", timestamp: ts });
-    } else if (prior !== hash) {
-      events.push({ path: path5, op: "modify", timestamp: ts });
-    }
+var DockerNotAvailableError = class extends DockerSandboxError {
+  constructor() {
+    super("Docker is not available. Ensure Docker daemon is running.");
+    this.name = "DockerNotAvailableError";
   }
-  for (const path5 of before.keys()) {
-    if (!after.has(path5)) {
-      events.push({ path: path5, op: "delete", timestamp: ts });
-    }
+};
+var ContainerCreationError = class extends DockerSandboxError {
+  image;
+  cause;
+  constructor(message2, image, cause) {
+    super(`Failed to create container from image "${image}": ${message2}`);
+    this.name = "ContainerCreationError";
+    this.image = image;
+    this.cause = cause;
   }
-  return events;
-}
-function observeSandboxFileEvents(sandbox, options) {
-  const { destination } = options;
-  if (!destination) {
-    throw new Error("observeSandboxFileEvents: destination is required");
+};
+var PackageInstallError = class extends DockerSandboxError {
+  packages;
+  image;
+  packageManager;
+  stderr;
+  constructor(packages, image, packageManager, stderr, containerId) {
+    super(
+      `Package installation failed for [${packages.join(", ")}] using ${packageManager} on ${image}: ${stderr}`,
+      containerId
+    );
+    this.name = "PackageInstallError";
+    this.packages = packages;
+    this.image = image;
+    this.packageManager = packageManager;
+    this.stderr = stderr;
   }
-  const innerExecute = sandbox.executeCommand.bind(sandbox);
-  const innerReadFile = sandbox.readFile.bind(sandbox);
-  const innerWriteFiles = sandbox.writeFiles.bind(sandbox);
-  const buffer = [];
-  const observe = async (fn) => {
-    const before = await snapshot(innerExecute, destination);
-    const takeAfter = async () => {
-      const after = await snapshot(innerExecute, destination);
-      buffer.push(...diff(before, after));
-    };
+};
+var InstallError = class extends DockerSandboxError {
+  target;
+  source;
+  reason;
+  url;
+  constructor(opts) {
+    const where = opts.url ? `${opts.source} (${opts.url})` : opts.source;
+    super(
+      `Failed to install "${opts.target}" via ${where}: ${opts.reason}`,
+      opts.containerId
+    );
+    this.name = "InstallError";
+    this.target = opts.target;
+    this.source = opts.source;
+    this.reason = opts.reason;
+    this.url = opts.url;
+  }
+};
+var MissingRuntimeError = class extends DockerSandboxError {
+  runtime;
+  required;
+  constructor(runtime, required, details, containerId) {
+    const base = `Required runtime "${runtime}" is not installed (needs: ${required.join(", ")}).`;
+    super(details ? `${base} ${details}` : base, containerId);
+    this.name = "MissingRuntimeError";
+    this.runtime = runtime;
+    this.required = required;
+  }
+};
+var VolumePathError = class extends DockerSandboxError {
+  source;
+  containerPath;
+  reason;
+  constructor(source, containerPath, reason) {
+    super(
+      `Invalid Docker volume path "${source}" -> "${containerPath}": ${reason}`
+    );
+    this.name = "VolumePathError";
+    this.source = source;
+    this.containerPath = containerPath;
+    this.reason = reason;
+  }
+};
+var VolumeInspectError = class extends DockerSandboxError {
+  volume;
+  reason;
+  constructor(volume, reason) {
+    super(`Failed to inspect Docker volume "${volume}": ${reason}`);
+    this.name = "VolumeInspectError";
+    this.volume = volume;
+    this.reason = reason;
+  }
+};
+var VolumeCreateError = class extends DockerSandboxError {
+  volume;
+  reason;
+  constructor(volume, reason) {
+    super(`Failed to create Docker volume "${volume}": ${reason}`);
+    this.name = "VolumeCreateError";
+    this.volume = volume;
+    this.reason = reason;
+  }
+};
+var VolumeRemoveError = class extends DockerSandboxError {
+  volume;
+  reason;
+  constructor(volume, reason) {
+    super(`Failed to remove Docker volume "${volume}": ${reason}`);
+    this.name = "VolumeRemoveError";
+    this.volume = volume;
+    this.reason = reason;
+  }
+};
+var DockerfileBuildError = class extends DockerSandboxError {
+  stderr;
+  constructor(stderr) {
+    super(`Dockerfile build failed: ${stderr}`);
+    this.name = "DockerfileBuildError";
+    this.stderr = stderr;
+  }
+};
+var ComposeStartError = class extends DockerSandboxError {
+  composeFile;
+  stderr;
+  constructor(composeFile, stderr) {
+    super(`Docker Compose failed to start: ${stderr}`);
+    this.name = "ComposeStartError";
+    this.composeFile = composeFile;
+    this.stderr = stderr;
+  }
+};
+
+// packages/context/src/lib/sandbox/installers/installer.ts
+var Installer = class {
+};
+function isDebianBased(image) {
+  const lower = image.toLowerCase();
+  if (lower.includes("alpine")) return false;
+  const debianPatterns = ["debian", "ubuntu", "node", "python"];
+  return debianPatterns.some((pattern) => lower.includes(pattern));
+}
+function shellQuote(s) {
+  return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+function createInstallerContext(containerId, image) {
+  const packageManager = isDebianBased(image) ? "apt-get" : "apk";
+  let archPromise = null;
+  const ensuredTools = /* @__PURE__ */ new Set();
+  let aptUpdated = false;
+  const exec = async (command) => {
+    try {
+      const result = await spawn("docker", [
+        "exec",
+        containerId,
+        "sh",
+        "-c",
+        command
+      ]);
+      return { stdout: result.stdout, stderr: result.stderr, exitCode: 0 };
+    } catch (error) {
+      const err = error;
+      return {
+        stdout: err.stdout ?? "",
+        stderr: err.stderr ?? err.message ?? "",
+        exitCode: err.exitCode ?? 1
+      };
+    }
+  };
+  const arch = async () => {
+    if (!archPromise) {
+      const attempt = (async () => {
+        const result = await exec("uname -m");
+        if (result.exitCode !== 0) {
+          throw new DockerSandboxError(
+            `Failed to detect container architecture: ${result.stderr}`,
+            containerId
+          );
+        }
+        return result.stdout.trim();
+      })();
+      archPromise = attempt.catch((err) => {
+        archPromise = null;
+        throw err;
+      });
+    }
+    return archPromise;
+  };
+  const installPackages = async (packages) => {
+    if (packages.length === 0) return;
+    const quoted = packages.map(shellQuote).join(" ");
+    let cmd;
+    if (packageManager === "apt-get") {
+      cmd = aptUpdated ? `apt-get install -y ${quoted}` : `apt-get update && apt-get install -y ${quoted}`;
+    } else {
+      cmd = `apk add --no-cache ${quoted}`;
+    }
+    const result = await exec(cmd);
+    if (result.exitCode !== 0) {
+      throw new PackageInstallError(
+        packages,
+        image,
+        packageManager,
+        result.stderr,
+        containerId
+      );
+    }
+    if (packageManager === "apt-get") aptUpdated = true;
+  };
+  const ensureTool = async (checkName, installName) => {
+    const cacheKey = installName ?? checkName;
+    if (ensuredTools.has(cacheKey)) return;
+    const check = await exec(`which ${shellQuote(checkName)}`);
+    if (check.exitCode === 0) {
+      ensuredTools.add(cacheKey);
+      return;
+    }
+    await installPackages([installName ?? checkName]);
+    ensuredTools.add(cacheKey);
+  };
+  return {
+    containerId,
+    image,
+    packageManager,
+    arch,
+    exec,
+    installPackages,
+    ensureTool
+  };
+}
+
+// packages/context/src/lib/sandbox/installers/package-manager.ts
+var PackageInstaller = class extends Installer {
+  kind;
+  packages;
+  constructor(packages) {
+    super();
+    this.packages = packages;
+    this.kind = packages.length === 0 ? "pkg:<empty>" : `pkg:${packages.join(",")}`;
+  }
+  async install(ctx) {
+    if (this.packages.length === 0) return;
+    await ctx.installPackages([...this.packages]);
+  }
+};
+function pkg(packages) {
+  return new PackageInstaller(packages);
+}
+
+// packages/context/src/lib/sandbox/installers/url-binary.ts
+var UrlBinaryInstaller = class extends Installer {
+  kind;
+  options;
+  constructor(options) {
+    super();
+    this.options = options;
+    this.kind = `url-binary:${options.name}`;
+  }
+  async install(ctx) {
+    const url = await resolveUrl(ctx, this.options);
+    await downloadAndInstall(
+      ctx,
+      this.options.name,
+      url,
+      this.options.binaryPath
+    );
+  }
+};
+function urlBinary(options) {
+  return new UrlBinaryInstaller(options);
+}
+async function resolveUrl(ctx, options) {
+  if (typeof options.url === "string") return options.url;
+  const arch = await ctx.arch();
+  const archUrl = options.url[arch];
+  if (!archUrl) {
+    throw new InstallError({
+      target: options.name,
+      source: "url",
+      reason: `No URL provided for architecture "${arch}". Available: ${Object.keys(options.url).join(", ")}`,
+      containerId: ctx.containerId
+    });
+  }
+  return archUrl;
+}
+async function downloadAndInstall(ctx, name, url, binaryPath, source = "url") {
+  await ctx.ensureTool("curl");
+  const isTarGz = url.endsWith(".tar.gz") || url.endsWith(".tgz");
+  const installCmd = isTarGz ? buildTarGzInstallCmd(name, url, binaryPath ?? name) : buildRawInstallCmd(name, url);
+  const result = await ctx.exec(installCmd);
+  if (result.exitCode !== 0) {
+    throw new InstallError({
+      target: name,
+      source,
+      url,
+      reason: result.stderr,
+      containerId: ctx.containerId
+    });
+  }
+}
+function buildTarGzInstallCmd(name, url, binaryPathInArchive) {
+  return `
+    set -e
+    NAME=${shellQuote(name)}
+    URL=${shellQuote(url)}
+    BIN_IN_ARCHIVE=${shellQuote(binaryPathInArchive)}
+    TMPDIR=$(mktemp -d)
+    cd "$TMPDIR"
+    curl -fsSL "$URL" -o archive.tar.gz
+    tar -xzf archive.tar.gz
+    BINARY_FILE=$(find . -name "$BIN_IN_ARCHIVE" -o -name "$NAME" | head -1)
+    if [ -z "$BINARY_FILE" ]; then
+      echo "Binary not found in archive. Contents:" >&2
+      find . -type f >&2
+      exit 1
+    fi
+    chmod +x "$BINARY_FILE"
+    mv "$BINARY_FILE" "/usr/local/bin/$NAME"
+    cd /
+    rm -rf "$TMPDIR"
+  `;
+}
+function buildRawInstallCmd(name, url) {
+  return `
+    NAME=${shellQuote(name)}
+    URL=${shellQuote(url)}
+    curl -fsSL "$URL" -o "/usr/local/bin/$NAME"
+    chmod +x "/usr/local/bin/$NAME"
+  `;
+}
+
+// packages/context/src/lib/sandbox/installers/npm.ts
+var NODE_BINARIES = ["node", "npm"];
+var ENSURE_RUNTIME_HINT = "Pass `{ ensureRuntime: true }` to auto-install, or add it via `pkg([...])`.";
+var NpmInstaller = class extends Installer {
+  kind;
+  packageName;
+  options;
+  constructor(packageName, options = {}) {
+    super();
+    this.packageName = packageName;
+    this.options = options;
+    this.kind = `npm:${packageName}`;
+  }
+  async install(ctx) {
+    await ensureNodeRuntime(ctx, this.options.ensureRuntime ?? false);
+    const spec = this.options.version ? `${this.packageName}@${this.options.version}` : this.packageName;
+    const result = await ctx.exec(`npm install -g ${spec}`);
+    if (result.exitCode !== 0) {
+      throw new InstallError({
+        target: this.packageName,
+        source: "npm",
+        reason: result.stderr,
+        containerId: ctx.containerId
+      });
+    }
+  }
+};
+function npm(packageName, options) {
+  return new NpmInstaller(packageName, options);
+}
+async function ensureNodeRuntime(ctx, ensure) {
+  if (ensure) {
+    await ctx.ensureTool("node", "nodejs");
+    await ctx.ensureTool("npm");
+    return;
+  }
+  const check = await ctx.exec("which node && which npm");
+  if (check.exitCode !== 0) {
+    throw new MissingRuntimeError(
+      "npm",
+      NODE_BINARIES,
+      ENSURE_RUNTIME_HINT,
+      ctx.containerId
+    );
+  }
+}
+
+// packages/context/src/lib/sandbox/installers/bin.ts
+import { basename, posix } from "node:path";
+var NOT_FOUND_EXIT = 11;
+var CHMOD_FAILED_EXIT = 12;
+var BinInstaller = class extends Installer {
+  kind;
+  binary;
+  options;
+  #name;
+  #target;
+  constructor(binary, options = {}) {
+    super();
+    this.binary = binary;
+    this.options = options;
+    this.#name = resolveName(binary, options);
+    this.#target = options.target ?? posix.join("/usr/local/bin", this.#name);
+    this.kind = `bin:${this.#name}`;
+  }
+  async install(ctx) {
+    const b = shellQuote(this.binary);
+    const t = shellQuote(this.#target);
+    const dir = shellQuote(posix.dirname(this.#target));
+    const result = await ctx.exec(
+      `test -f ${b} || { echo "binary not found at ${this.binary}" >&2; exit ${NOT_FOUND_EXIT}; }; if ! test -x ${b}; then chmod +x ${b} || exit ${CHMOD_FAILED_EXIT}; fi; mkdir -p ${dir} && ln -sf ${b} ${t}`
+    );
+    if (result.exitCode === 0) return;
+    throw new InstallError({
+      target: this.#name,
+      source: "bin",
+      reason: explainFailure(result.exitCode, result.stderr, this.binary),
+      containerId: ctx.containerId
+    });
+  }
+};
+function bin(binary, options) {
+  return new BinInstaller(binary, options);
+}
+function explainFailure(exitCode, stderr, binary) {
+  if (exitCode === NOT_FOUND_EXIT) {
+    return `binary not found at ${binary}`;
+  }
+  if (exitCode === CHMOD_FAILED_EXIT && /read-only file system/i.test(stderr)) {
+    return `${binary} is not executable and the bind mount is read-only \u2014 run \`chmod +x\` on the host, or mount with \`readOnly: false\`. (${stderr.trim()})`;
+  }
+  return stderr || `bin installer failed with exit code ${exitCode}`;
+}
+function resolveName(binary, options) {
+  if (options.name) return options.name;
+  const base = basename(binary);
+  const dot = base.lastIndexOf(".");
+  return dot > 0 ? base.slice(0, dot) : base;
+}
+
+// packages/context/src/lib/sandbox/installers/pip.ts
+var PYTHON_BINARIES = ["python3", "pip3"];
+var PipInstaller = class extends Installer {
+  kind;
+  packageName;
+  options;
+  constructor(packageName, options = {}) {
+    super();
+    this.packageName = packageName;
+    this.options = options;
+    this.kind = `pip:${packageName}`;
+  }
+  async install(ctx) {
+    await ensurePythonRuntime(ctx, this.options.ensureRuntime ?? false);
+    const spec = this.options.version ? `${this.packageName}${formatVersion(this.options.version)}` : this.packageName;
+    const flags = this.options.breakSystemPackages ?? true ? "--break-system-packages" : "";
+    const result = await ctx.exec(`pip3 install ${flags} ${spec}`.trim());
+    if (result.exitCode !== 0) {
+      throw new InstallError({
+        target: this.packageName,
+        source: "pypi",
+        reason: result.stderr,
+        containerId: ctx.containerId
+      });
+    }
+  }
+};
+function pip(packageName, options) {
+  return new PipInstaller(packageName, options);
+}
+async function ensurePythonRuntime(ctx, ensure) {
+  if (ensure) {
+    const pipPackage = ctx.packageManager === "apk" ? "py3-pip" : "python3-pip";
+    await ctx.ensureTool("python3");
+    await ctx.ensureTool("pip3", pipPackage);
+    return;
+  }
+  const check = await ctx.exec("which python3 && which pip3");
+  if (check.exitCode !== 0) {
+    throw new MissingRuntimeError(
+      "pip",
+      PYTHON_BINARIES,
+      "Pass `{ ensureRuntime: true }` to auto-install, or add via `pkg([...])` (Alpine: `python3 py3-pip`; Debian: `python3 python3-pip`).",
+      ctx.containerId
+    );
+  }
+}
+function formatVersion(version) {
+  return /^[<>=!~]/.test(version) ? version : `==${version}`;
+}
+
+// packages/context/src/lib/sandbox/installers/github-release.ts
+var GithubReleaseInstaller = class extends Installer {
+  kind;
+  options;
+  constructor(options) {
+    super();
+    this.options = options;
+    this.kind = `github-release:${options.owner}/${options.repo}@${options.version}`;
+  }
+  async install(ctx) {
+    const arch = await ctx.arch();
+    const assetName = this.options.asset(arch);
+    const url = `https://github.com/${this.options.owner}/${this.options.repo}/releases/download/${this.options.version}/${assetName}`;
+    await downloadAndInstall(
+      ctx,
+      this.options.name,
+      url,
+      this.options.binaryPath,
+      "github-release"
+    );
+  }
+};
+function githubRelease(options) {
+  return new GithubReleaseInstaller(options);
+}
+
+// packages/context/src/lib/sandbox/file-changes.ts
+var REASON_HINT = {
+  "ptrace-blocked": "ptrace is denied by the sandbox runtime. Modern Docker permits it by default; on a hardened host, relax the runtime seccomp/ptrace policy (allow the ptrace syscall, or add the SYS_PTRACE capability).",
+  "strace-missing": "strace is not installed in the sandbox image. Bake `strace` into the image.",
+  "trace-unparseable": "strace ran but its output is unusable \u2014 the sandbox is likely running under emulation (e.g. amd64 via Rosetta). Use a native-architecture sandbox."
+};
+var StraceUnavailableError = class extends Error {
+  reason;
+  diagnostics;
+  constructor(reason, diagnostics) {
+    super(
+      `strace file-change tracking unavailable (${reason}): ${REASON_HINT[reason]}`
+    );
+    this.name = "StraceUnavailableError";
+    this.reason = reason;
+    this.diagnostics = diagnostics;
+  }
+};
+var DEFAULT_TRACE_DIR = "/tmp/dat-trace";
+var STRACE_FLAGS = "-f -y -qq -e trace=%file,write,pwrite64,writev";
+function buildStraceCommand(command, traceFile, traceDir) {
+  return `mkdir -p ${shellQuote(traceDir)} 2>/dev/null; strace ${STRACE_FLAGS} -o ${shellQuote(traceFile)} -- sh -c ${shellQuote(command)}`;
+}
+function stripStraceDiagnostics(stderr) {
+  if (!stderr.includes("strace: ")) return stderr;
+  return stderr.split("\n").filter((line) => !line.startsWith("strace: ")).join("\n");
+}
+var CREATE_OR_TRUNC_FLAGS = /O_(CREAT|TRUNC)/;
+var RENAME_SYSCALLS = /* @__PURE__ */ new Set(["rename", "renameat", "renameat2"]);
+var DELETE_SYSCALLS = /* @__PURE__ */ new Set(["unlink", "unlinkat", "rmdir"]);
+var MKDIR_SYSCALLS = /* @__PURE__ */ new Set(["mkdir", "mkdirat"]);
+var LINK_SYSCALLS = /* @__PURE__ */ new Set(["link", "linkat", "symlink", "symlinkat"]);
+var OPEN_SYSCALLS = /* @__PURE__ */ new Set(["open", "openat", "openat2", "creat"]);
+var WRITE_SYSCALLS = /* @__PURE__ */ new Set([
+  "write",
+  "pwrite64",
+  "pwrite",
+  "writev",
+  "pwritev2"
+]);
+var TRUNCATE_SYSCALLS = /* @__PURE__ */ new Set(["truncate", "ftruncate"]);
+function stitchLines(raw) {
+  const pending = /* @__PURE__ */ new Map();
+  const out = [];
+  for (const original of raw.split("\n")) {
+    const line = original.trimEnd();
+    if (!line) continue;
+    const pid = line.match(/^\s*(\d+)\s+/)?.[1] ?? "0";
+    if (/<unfinished \.\.\.>\s*$/.test(line)) {
+      pending.set(pid, line.replace(/<unfinished \.\.\.>\s*$/, ""));
+      continue;
+    }
+    const resumed = line.match(/<\.\.\.\s+\S+\s+resumed>(.*)$/);
+    if (resumed) {
+      const head = pending.get(pid);
+      pending.delete(pid);
+      if (head !== void 0) out.push(head + resumed[1]);
+      continue;
+    }
+    out.push(line);
+  }
+  return out;
+}
+function parseCall(line) {
+  const m = line.match(
+    /^\s*(?:\d+\s+)?([a-z_][a-z0-9_]*)\((.*)\)\s*=\s*(.+?)\s*$/
+  );
+  if (!m) return null;
+  const [, syscall, args, rest] = m;
+  const errnoMatch = rest.match(/^(-?\d+)\s+([A-Z][A-Z0-9_]*)/);
+  if (errnoMatch) {
+    return { syscall, args, retval: errnoMatch[1], errno: errnoMatch[2] };
+  }
+  return { syscall, args, retval: rest.split(/\s+/)[0] };
+}
+var STRACE_ESCAPE = {
+  n: 10,
+  t: 9,
+  r: 13,
+  v: 11,
+  f: 12,
+  '"': 34,
+  "\\": 92
+};
+function decodeStraceString(s) {
+  const bytes = [];
+  for (let i = 0; i < s.length; ) {
+    if (s[i] === "\\" && i + 1 < s.length) {
+      const octal = s.slice(i + 1, i + 4).match(/^[0-7]{1,3}/)?.[0];
+      if (octal) {
+        bytes.push(parseInt(octal, 8) & 255);
+        i += 1 + octal.length;
+        continue;
+      }
+      const mapped = STRACE_ESCAPE[s[i + 1]];
+      bytes.push(mapped ?? s.charCodeAt(i + 1));
+      i += 2;
+      continue;
+    }
+    const code = s.charCodeAt(i);
+    if (code < 128) bytes.push(code);
+    else for (const b of Buffer.from(s[i], "utf8")) bytes.push(b);
+    i += 1;
+  }
+  return Buffer.from(bytes).toString("utf8");
+}
+function quotedStrings(args) {
+  const out = [];
+  const re = /"((?:[^"\\]|\\.)*)"/g;
+  let m;
+  while ((m = re.exec(args)) !== null) {
+    out.push(decodeStraceString(m[1]));
+  }
+  return out;
+}
+function dirfdPath(args) {
+  return args.match(/^\s*(?:AT_FDCWD|-?\d+)<([^>]*)>/)?.[1] ?? "/";
+}
+function fdPath(args) {
+  return args.match(/^\s*-?\d+<([^>]*)>/)?.[1] ?? null;
+}
+function openFlags(args) {
+  return args.match(/\bO_[A-Z_]+(?:\|O_[A-Z_]+)*/)?.[0] ?? "";
+}
+function parseStraceTrace(raw, options) {
+  const dest = posix2.normalize(options.destination);
+  const traceDir = options.traceDir;
+  const traceFile = options.traceFile;
+  const now = Date.now();
+  const state = /* @__PURE__ */ new Map();
+  const renames = [];
+  const resolve4 = (dir, p) => posix2.normalize(p.startsWith("/") ? p : posix2.join(dir, p));
+  const write = (path5) => {
+    state.set(path5, "write");
+  };
+  const remove = (path5) => {
+    if (state.get(path5) === "write") state.delete(path5);
+    else state.set(path5, "delete");
+  };
+  for (const line of stitchLines(raw)) {
+    const call = parseCall(line);
+    if (!call || call.errno || call.retval === "-1") continue;
+    const { syscall, args } = call;
+    const dir = dirfdPath(args);
+    if (RENAME_SYSCALLS.has(syscall)) {
+      const strings = quotedStrings(args);
+      if (strings.length < 2) continue;
+      const from = resolve4(dir, strings[0]);
+      const to = resolve4(dir, strings[strings.length - 1]);
+      state.delete(from);
+      renames.push({ from, to });
+      continue;
+    }
+    if (DELETE_SYSCALLS.has(syscall)) {
+      const strings = quotedStrings(args);
+      if (strings.length) remove(resolve4(dir, strings[0]));
+      continue;
+    }
+    if (MKDIR_SYSCALLS.has(syscall)) {
+      const strings = quotedStrings(args);
+      if (strings.length) write(resolve4(dir, strings[0]));
+      continue;
+    }
+    if (LINK_SYSCALLS.has(syscall)) {
+      const strings = quotedStrings(args);
+      if (strings.length) write(resolve4(dir, strings[strings.length - 1]));
+      continue;
+    }
+    if (OPEN_SYSCALLS.has(syscall)) {
+      if (!CREATE_OR_TRUNC_FLAGS.test(openFlags(args))) continue;
+      const strings = quotedStrings(args);
+      if (strings.length) write(resolve4(dir, strings[0]));
+      continue;
+    }
+    if (WRITE_SYSCALLS.has(syscall)) {
+      const p = fdPath(args);
+      if (p && Number(call.retval) > 0) write(posix2.normalize(p));
+      continue;
+    }
+    if (TRUNCATE_SYSCALLS.has(syscall)) {
+      const p = fdPath(args) ?? quotedStrings(args)[0];
+      if (p) write(resolve4(dir, p));
+    }
+  }
+  const keep = (path5) => {
+    if (traceFile && path5 === traceFile) return false;
+    if (traceDir && (path5 === traceDir || path5.startsWith(`${traceDir}/`))) {
+      return false;
+    }
+    if (/^\/(proc|sys|dev)(\/|$)/.test(path5)) return false;
+    return dest === "/" ? true : path5 === dest || path5.startsWith(`${dest}/`);
+  };
+  const changes = [];
+  const emittedRenameTargets = /* @__PURE__ */ new Set();
+  for (const { from, to } of renames) {
+    if (!keep(to)) continue;
+    if (state.get(to) === "delete") continue;
+    changes.push({ op: "rename", path: to, from, timestamp: now });
+    emittedRenameTargets.add(to);
+  }
+  const tail = [];
+  for (const [path5, op] of state) {
+    if (emittedRenameTargets.has(path5)) continue;
+    if (keep(path5)) tail.push({ op, path: path5, timestamp: now });
+  }
+  tail.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+  changes.push(...tail);
+  return changes;
+}
+var warnOnFileChangesError = (error) => {
+  console.warn(
+    "[traceFileChanges] onFileChanges threw on spawn; isolated",
+    error
+  );
+};
+function traceFileChanges(sandbox, options) {
+  const { destination, onFileChanges } = options;
+  const onError = options.onError ?? warnOnFileChangesError;
+  const traceDir = options.traceDir ?? DEFAULT_TRACE_DIR;
+  const innerExecute = sandbox.executeCommand.bind(sandbox);
+  const innerReadFile = sandbox.readFile.bind(sandbox);
+  const innerWriteFiles = sandbox.writeFiles.bind(sandbox);
+  const dest = posix2.normalize(destination);
+  const underDestination = (path5) => dest === "/" || path5 === dest || path5.startsWith(`${dest}/`);
+  const removeTrace = (traceFile) => void innerExecute(`rm -f ${shellQuote(traceFile)}`).catch(() => {
+  });
+  const readChanges = async (traceFile) => {
     try {
-      const result = await fn();
-      await takeAfter();
-      return result;
-    } catch (err) {
-      await takeAfter().catch(() => {
+      return parseStraceTrace(await innerReadFile(traceFile), {
+        destination,
+        traceFile,
+        traceDir
       });
-      throw err;
+    } catch {
+      return [];
+    } finally {
+      removeTrace(traceFile);
+    }
+  };
+  const collectCommand = async (traceFile) => {
+    const changes = await readChanges(traceFile);
+    if (!changes.length) return;
+    useBashMeta()?.setHidden({ fileChanges: changes });
+    await onFileChanges?.(changes);
+  };
+  const collectSpawn = async (traceFile) => {
+    const changes = await readChanges(traceFile);
+    if (!changes.length || !onFileChanges) return;
+    try {
+      await onFileChanges(changes);
+    } catch (error) {
+      onError(error);
     }
   };
   const decorated = {
-    async executeCommand(command, options2) {
-      return observe(() => innerExecute(command, options2));
-    },
-    async readFile(path5) {
-      const content = await innerReadFile(path5);
-      buffer.push({ path: path5, op: "read", timestamp: Date.now() });
-      return content;
+    async executeCommand(command, execOptions) {
+      const traceFile = `${traceDir}/${randomUUID()}.strace`;
+      const wrapped = buildStraceCommand(command, traceFile, traceDir);
+      let result;
+      try {
+        const raw = await innerExecute(wrapped, execOptions);
+        result = { ...raw, stderr: stripStraceDiagnostics(raw.stderr) };
+      } catch (error) {
+        removeTrace(traceFile);
+        throw error;
+      }
+      if (execOptions?.signal?.aborted) {
+        removeTrace(traceFile);
+        return result;
+      }
+      await collectCommand(traceFile);
+      return result;
     },
-    async writeFiles(files) {
-      await observe(() => innerWriteFiles(files));
+    readFile: innerReadFile,
+    // The writeFile tool mutates the filesystem outside strace's view, so
+    // observe it directly: synthesize a `write` change per file (under the
+    // observation root) and run it through onFileChanges. A throw propagates to
+    // the writeFile tool's execute (which rejects), the same gate as the bash
+    // path — except there's no CommandResult here, so throw a plain Error to
+    // reject; BashException.format() is meaningful only for bash commands.
+    writeFiles: async (files) => {
+      await innerWriteFiles(files);
+      const now = Date.now();
+      const changes = files.map(
+        (f) => posix2.normalize(
+          f.path.startsWith("/") ? f.path : posix2.join(dest, f.path)
+        )
+      ).filter(underDestination).map((path5) => ({ op: "write", path: path5, timestamp: now }));
+      if (changes.length) await onFileChanges?.(changes);
     },
-    dispose: sandbox.dispose.bind(sandbox)
+    dispose: async () => {
+      await innerExecute(`rm -rf ${shellQuote(traceDir)}`).catch(() => {
+      });
+      await sandbox.dispose();
+    }
   };
   if (sandbox.spawn) {
     const innerSpawn = sandbox.spawn.bind(sandbox);
-    decorated.spawn = (command, options2) => {
-      const started = (async () => {
-        const before = await snapshot(innerExecute, destination).catch(
-          () => /* @__PURE__ */ new Map()
-        );
-        const child = innerSpawn(command, options2);
-        return { before, child };
-      })();
+    decorated.spawn = (command, spawnOptions) => {
+      const traceFile = `${traceDir}/${randomUUID()}.strace`;
+      const child = innerSpawn(
+        buildStraceCommand(command, traceFile, traceDir),
+        spawnOptions
+      );
       const exit = (async () => {
-        const { before, child } = await started;
         try {
           return await child.exit;
         } finally {
-          try {
-            const after = await snapshot(innerExecute, destination);
-            buffer.push(...diff(before, after));
-          } catch {
-          }
-        }
-      })();
-      const stdoutPromise = started.then((s) => s.child.stdout);
-      const stderrPromise = started.then((s) => s.child.stderr);
-      stdoutPromise.catch(() => {
-      });
-      stderrPromise.catch(() => {
-      });
-      return {
-        stdout: lazyReadable(stdoutPromise),
-        stderr: lazyReadable(stderrPromise),
-        exit
-      };
+          await collectSpawn(traceFile).catch(() => {
+          });
+        }
+      })();
+      return { stdout: child.stdout, stderr: child.stderr, exit };
     };
   }
-  return {
-    sandbox: decorated,
-    drain() {
-      return buffer.splice(0, buffer.length);
+  return decorated;
+}
+var PTRACE_DENIED = /strace:[^\n]*(?:PTRACE_TRACEME|ptrace|Operation not permitted|EPERM)/i;
+var STRACE_MISSING = /strace:?\s+(?:command\s+)?not found/i;
+async function selfTestStrace(sandbox) {
+  const probeDir = `/tmp/dat-strace-${randomUUID()}`;
+  const traceFile = `/tmp/dat-strace-${randomUUID()}.trace`;
+  const q = shellQuote;
+  const sequence = `mkdir -p ${q(probeDir)} && echo hi > ${q(`${probeDir}/a.txt`)} && mv ${q(`${probeDir}/a.txt`)} ${q(`${probeDir}/b.txt`)} && echo more > ${q(`${probeDir}/c.txt`)}`;
+  const wrapped = buildStraceCommand(sequence, traceFile, "/tmp");
+  let result;
+  let raw = "";
+  try {
+    result = await sandbox.executeCommand(wrapped);
+    raw = await sandbox.readFile(traceFile).catch(() => "");
+    const diagnostics = `exit=${result.exitCode}
+stderr=${result.stderr}
+trace[0:600]=${raw.slice(0, 600)}`;
+    if (PTRACE_DENIED.test(result.stderr)) {
+      throw new StraceUnavailableError("ptrace-blocked", diagnostics);
+    }
+    if (!raw || result.exitCode === 127 || STRACE_MISSING.test(result.stderr)) {
+      throw new StraceUnavailableError("strace-missing", diagnostics);
+    }
+    const changes = parseStraceTrace(raw, { destination: probeDir, traceFile });
+    const hasRealFdPath = raw.includes(`<${probeDir}/`);
+    const hasRename = changes.some(
+      (c) => c.op === "rename" && c.from === `${probeDir}/a.txt` && c.path === `${probeDir}/b.txt`
+    );
+    const hasWrite = changes.some((c) => c.op === "write");
+    const allUnderDir = changes.every(
+      (c) => c.path === probeDir || c.path.startsWith(`${probeDir}/`)
+    );
+    if (!hasRealFdPath || !hasRename || !hasWrite || !allUnderDir) {
+      throw new StraceUnavailableError("trace-unparseable", diagnostics);
     }
-  };
+  } finally {
+    void sandbox.executeCommand(`rm -rf ${q(probeDir)} ${q(traceFile)}`).catch(() => {
+    });
+  }
 }
 
 // packages/context/src/lib/sandbox/upload-skills.ts
@@ -6432,12 +7311,18 @@ async function createBashTool(options) {
     extraInstructions,
     sandbox: backend,
     destination,
+    onFileChanges,
+    onError,
     ...rest
   } = options;
-  const observer = observeSandboxFileEvents(backend, {
-    destination: destination ?? "/workspace"
+  const observationRoot = destination ?? "/workspace";
+  await selfTestStrace(backend);
+  const tracked = traceFileChanges(backend, {
+    destination: observationRoot,
+    onFileChanges,
+    onError
   });
-  const sandbox = withAbortSignal(withBashExceptionCatch(observer.sandbox));
+  const sandbox = withAbortSignal(withBashExceptionCatch(tracked));
   const combinedInstructions = [extraInstructions, REASONING_INSTRUCTION].filter(Boolean).join("\n\n");
   const toolkit = await externalCreateBashTool({
     ...rest,
@@ -6485,21 +7370,37 @@ async function createBashTool(options) {
       return { type: "json", value: visible };
     }
   });
-  const skills2 = await uploadSkills(sandbox, skillInputs);
+  const upstreamWriteFile = toolkit.tools.writeFile;
+  const originalWriteExecute = upstreamWriteFile.execute;
+  const writeFileBuilder = tool2;
+  const writeFile = writeFileBuilder({
+    ...upstreamWriteFile,
+    execute: async (input, options2) => {
+      if (!originalWriteExecute) {
+        throw new Error("writeFile tool execution is not available");
+      }
+      try {
+        return await originalWriteExecute(input, options2);
+      } catch (err) {
+        if (err instanceof BashException) return err.format();
+        throw err;
+      }
+    }
+  });
+  const skills2 = await uploadSkills(backend, skillInputs);
   return {
     ...toolkit,
     sandbox,
     bash,
-    tools: { ...toolkit.tools, bash },
-    skills: skills2,
-    drainFileEvents: () => observer.drain()
+    tools: { ...toolkit.tools, bash, writeFile },
+    skills: skills2
   };
 }
 
 // packages/context/src/lib/sandbox/binary-bridges.ts
 import { existsSync as existsSync2 } from "fs";
 import { defineCommand } from "just-bash";
-import spawn from "nano-spawn";
+import spawn2 from "nano-spawn";
 import * as path4 from "path";
 function createBinaryBridges(...binaries) {
   return binaries.map((input) => {
@@ -6537,7 +7438,7 @@ function createBinaryBridges(...binaries) {
           PATH: process.env.PATH
           // Always use host PATH for binary bridges
         };
-        const result = await spawn(binaryPath, resolvedArgs, {
+        const result = await spawn2(binaryPath, resolvedArgs, {
           cwd: realCwd,
           env: mergedEnv
         });
@@ -6594,7 +7495,7 @@ function resolveRealCwd(ctx) {
 
 // packages/context/src/lib/sandbox/daytona-sandbox.ts
 import "bash-tool";
-import { randomUUID } from "node:crypto";
+import { randomUUID as randomUUID2 } from "node:crypto";
 var DAYTONA_DEFAULT_DESTINATION = "/home/daytona";
 var DAYTONA_EXIT_POLL_INTERVAL_MS = 250;
 var DAYTONA_EXIT_POLL_TIMEOUT_MS = 3e4;
@@ -7027,7 +7928,7 @@ function validateEnvKey(key) {
   }
 }
 function createSessionId(kind) {
-  return `deepagents-${kind}-${randomUUID()}`;
+  return `deepagents-${kind}-${randomUUID2()}`;
 }
 function abortedCommandResult() {
   return {
@@ -7075,243 +7976,7 @@ import spawn3 from "nano-spawn";
 import { spawn as childSpawn } from "node:child_process";
 import { createHash } from "node:crypto";
 import { existsSync as existsSync3, readFileSync as readFileSync2 } from "node:fs";
-import { Readable as Readable2 } from "node:stream";
-
-// packages/context/src/lib/sandbox/docker-sandbox-errors.ts
-var DockerSandboxError = class extends Error {
-  containerId;
-  constructor(message2, containerId) {
-    super(message2);
-    this.name = "DockerSandboxError";
-    this.containerId = containerId;
-  }
-};
-var DockerNotAvailableError = class extends DockerSandboxError {
-  constructor() {
-    super("Docker is not available. Ensure Docker daemon is running.");
-    this.name = "DockerNotAvailableError";
-  }
-};
-var ContainerCreationError = class extends DockerSandboxError {
-  image;
-  cause;
-  constructor(message2, image, cause) {
-    super(`Failed to create container from image "${image}": ${message2}`);
-    this.name = "ContainerCreationError";
-    this.image = image;
-    this.cause = cause;
-  }
-};
-var PackageInstallError = class extends DockerSandboxError {
-  packages;
-  image;
-  packageManager;
-  stderr;
-  constructor(packages, image, packageManager, stderr, containerId) {
-    super(
-      `Package installation failed for [${packages.join(", ")}] using ${packageManager} on ${image}: ${stderr}`,
-      containerId
-    );
-    this.name = "PackageInstallError";
-    this.packages = packages;
-    this.image = image;
-    this.packageManager = packageManager;
-    this.stderr = stderr;
-  }
-};
-var InstallError = class extends DockerSandboxError {
-  target;
-  source;
-  reason;
-  url;
-  constructor(opts) {
-    const where = opts.url ? `${opts.source} (${opts.url})` : opts.source;
-    super(
-      `Failed to install "${opts.target}" via ${where}: ${opts.reason}`,
-      opts.containerId
-    );
-    this.name = "InstallError";
-    this.target = opts.target;
-    this.source = opts.source;
-    this.reason = opts.reason;
-    this.url = opts.url;
-  }
-};
-var MissingRuntimeError = class extends DockerSandboxError {
-  runtime;
-  required;
-  constructor(runtime, required, details, containerId) {
-    const base = `Required runtime "${runtime}" is not installed (needs: ${required.join(", ")}).`;
-    super(details ? `${base} ${details}` : base, containerId);
-    this.name = "MissingRuntimeError";
-    this.runtime = runtime;
-    this.required = required;
-  }
-};
-var VolumePathError = class extends DockerSandboxError {
-  source;
-  containerPath;
-  reason;
-  constructor(source, containerPath, reason) {
-    super(
-      `Invalid Docker volume path "${source}" -> "${containerPath}": ${reason}`
-    );
-    this.name = "VolumePathError";
-    this.source = source;
-    this.containerPath = containerPath;
-    this.reason = reason;
-  }
-};
-var VolumeInspectError = class extends DockerSandboxError {
-  volume;
-  reason;
-  constructor(volume, reason) {
-    super(`Failed to inspect Docker volume "${volume}": ${reason}`);
-    this.name = "VolumeInspectError";
-    this.volume = volume;
-    this.reason = reason;
-  }
-};
-var VolumeCreateError = class extends DockerSandboxError {
-  volume;
-  reason;
-  constructor(volume, reason) {
-    super(`Failed to create Docker volume "${volume}": ${reason}`);
-    this.name = "VolumeCreateError";
-    this.volume = volume;
-    this.reason = reason;
-  }
-};
-var VolumeRemoveError = class extends DockerSandboxError {
-  volume;
-  reason;
-  constructor(volume, reason) {
-    super(`Failed to remove Docker volume "${volume}": ${reason}`);
-    this.name = "VolumeRemoveError";
-    this.volume = volume;
-    this.reason = reason;
-  }
-};
-var DockerfileBuildError = class extends DockerSandboxError {
-  stderr;
-  constructor(stderr) {
-    super(`Dockerfile build failed: ${stderr}`);
-    this.name = "DockerfileBuildError";
-    this.stderr = stderr;
-  }
-};
-var ComposeStartError = class extends DockerSandboxError {
-  composeFile;
-  stderr;
-  constructor(composeFile, stderr) {
-    super(`Docker Compose failed to start: ${stderr}`);
-    this.name = "ComposeStartError";
-    this.composeFile = composeFile;
-    this.stderr = stderr;
-  }
-};
-
-// packages/context/src/lib/sandbox/installers/installer.ts
-import "bash-tool";
-import spawn2 from "nano-spawn";
-var Installer = class {
-};
-function isDebianBased(image) {
-  const lower = image.toLowerCase();
-  if (lower.includes("alpine")) return false;
-  const debianPatterns = ["debian", "ubuntu", "node", "python"];
-  return debianPatterns.some((pattern) => lower.includes(pattern));
-}
-function shellQuote3(s) {
-  return `'${s.replace(/'/g, `'\\''`)}'`;
-}
-function createInstallerContext(containerId, image) {
-  const packageManager = isDebianBased(image) ? "apt-get" : "apk";
-  let archPromise = null;
-  const ensuredTools = /* @__PURE__ */ new Set();
-  let aptUpdated = false;
-  const exec = async (command) => {
-    try {
-      const result = await spawn2("docker", [
-        "exec",
-        containerId,
-        "sh",
-        "-c",
-        command
-      ]);
-      return { stdout: result.stdout, stderr: result.stderr, exitCode: 0 };
-    } catch (error) {
-      const err = error;
-      return {
-        stdout: err.stdout ?? "",
-        stderr: err.stderr ?? err.message ?? "",
-        exitCode: err.exitCode ?? 1
-      };
-    }
-  };
-  const arch = async () => {
-    if (!archPromise) {
-      const attempt = (async () => {
-        const result = await exec("uname -m");
-        if (result.exitCode !== 0) {
-          throw new DockerSandboxError(
-            `Failed to detect container architecture: ${result.stderr}`,
-            containerId
-          );
-        }
-        return result.stdout.trim();
-      })();
-      archPromise = attempt.catch((err) => {
-        archPromise = null;
-        throw err;
-      });
-    }
-    return archPromise;
-  };
-  const installPackages = async (packages) => {
-    if (packages.length === 0) return;
-    const quoted = packages.map(shellQuote3).join(" ");
-    let cmd;
-    if (packageManager === "apt-get") {
-      cmd = aptUpdated ? `apt-get install -y ${quoted}` : `apt-get update && apt-get install -y ${quoted}`;
-    } else {
-      cmd = `apk add --no-cache ${quoted}`;
-    }
-    const result = await exec(cmd);
-    if (result.exitCode !== 0) {
-      throw new PackageInstallError(
-        packages,
-        image,
-        packageManager,
-        result.stderr,
-        containerId
-      );
-    }
-    if (packageManager === "apt-get") aptUpdated = true;
-  };
-  const ensureTool = async (checkName, installName) => {
-    const cacheKey = installName ?? checkName;
-    if (ensuredTools.has(cacheKey)) return;
-    const check = await exec(`which ${shellQuote3(checkName)}`);
-    if (check.exitCode === 0) {
-      ensuredTools.add(cacheKey);
-      return;
-    }
-    await installPackages([installName ?? checkName]);
-    ensuredTools.add(cacheKey);
-  };
-  return {
-    containerId,
-    image,
-    packageManager,
-    arch,
-    exec,
-    installPackages,
-    ensureTool
-  };
-}
-
-// packages/context/src/lib/sandbox/docker-sandbox.ts
+import { Readable as Readable2 } from "node:stream";
 function isDockerfileOptions(opts) {
   return "dockerfile" in opts;
 }
@@ -7752,560 +8417,314 @@ function buildDockerExecFlags(options) {
     flags.push("-w", options.cwd);
   }
   if (options?.env) {
-    for (const [key, value] of Object.entries(options.env)) {
-      validateEnvKey2(key);
-      flags.push("-e", `${key}=${value}`);
-    }
-  }
-  return flags;
-}
-function toSandboxProcess(child, abortSignal) {
-  if (!child.stdout || !child.stderr) {
-    child.kill("SIGKILL");
-    throw new DockerSandboxError("docker exec child missing stdio streams");
-  }
-  const onAbort = abortSignal ? () => child.kill("SIGKILL") : void 0;
-  if (abortSignal && onAbort) {
-    if (abortSignal.aborted) onAbort();
-    else abortSignal.addEventListener("abort", onAbort, { once: true });
-  }
-  return {
-    stdout: Readable2.toWeb(child.stdout),
-    stderr: Readable2.toWeb(child.stderr),
-    exit: new Promise((resolve4, reject) => {
-      const settle = () => {
-        child.removeListener("exit", onExitEvent);
-        child.removeListener("error", onError);
-        if (abortSignal && onAbort) {
-          abortSignal.removeEventListener("abort", onAbort);
-        }
-      };
-      const onError = (err) => {
-        settle();
-        reject(err);
-      };
-      const onExitEvent = (code, exitSignal) => {
-        settle();
-        resolve4({ code, signal: exitSignal, success: code === 0 });
-      };
-      child.on("exit", onExitEvent);
-      child.on("error", onError);
-    })
-  };
-}
-var RuntimeStrategy = class extends DockerSandboxStrategy {
-  image;
-  installers;
-  constructor(args = {}) {
-    super({
-      volumes: args.volumes,
-      resources: args.resources,
-      env: args.env,
-      name: args.name,
-      command: args.command
-    });
-    this.image = args.image ?? "alpine:latest";
-    this.installers = args.installers ?? [];
-  }
-  async getImage() {
-    return this.image;
-  }
-  async configure() {
-    const ctx = createInstallerContext(this.context.containerId, this.image);
-    for (const installer of this.installers) {
-      await installer.install(ctx);
-    }
-  }
-};
-var DockerfileStrategy = class extends DockerSandboxStrategy {
-  imageTag;
-  dockerfile;
-  dockerContext;
-  constructor(args) {
-    super({
-      volumes: args.volumes,
-      resources: args.resources,
-      env: args.env,
-      name: args.name,
-      command: args.command
-    });
-    this.dockerfile = args.dockerfile;
-    this.dockerContext = args.context ?? ".";
-    this.imageTag = this.computeImageTag();
-  }
-  computeImageTag() {
-    const content = this.isInlineDockerfile() ? this.dockerfile : readFileSync2(this.dockerfile, "utf-8");
-    const hash = createHash("sha256").update(content).digest("hex").slice(0, 12);
-    return `sandbox-${hash}`;
-  }
-  isInlineDockerfile() {
-    return this.dockerfile.includes("\n");
-  }
-  async getImage() {
-    const exists = await this.imageExists();
-    if (!exists) {
-      await this.buildImage();
-    }
-    return this.imageTag;
-  }
-  async configure() {
-  }
-  async imageExists() {
-    try {
-      await spawn3("docker", ["image", "inspect", this.imageTag]);
-      return true;
-    } catch {
-      return false;
-    }
-  }
-  async buildImage() {
-    try {
-      if (this.isInlineDockerfile()) {
-        const buildCmd = `echo '${this.dockerfile.replace(/'/g, "'\\''")}' | docker build -t ${this.imageTag} -f - ${this.dockerContext}`;
-        await spawn3("sh", ["-c", buildCmd]);
-      } else {
-        await spawn3("docker", [
-          "build",
-          "-t",
-          this.imageTag,
-          "-f",
-          this.dockerfile,
-          this.dockerContext
-        ]);
-      }
-    } catch (error) {
-      const err = error;
-      throw new DockerfileBuildError(err.stderr || err.message);
-    }
-  }
-};
-var ComposeStrategy = class extends DockerSandboxStrategy {
-  projectName;
-  composeFile;
-  service;
-  constructor(args) {
-    super({ resources: args.resources });
-    this.composeFile = args.compose;
-    this.service = args.service;
-    this.projectName = this.computeProjectName();
-  }
-  computeProjectName() {
-    const content = readFileSync2(this.composeFile, "utf-8");
-    const hash = createHash("sha256").update(content).digest("hex").slice(0, 8);
-    return `sandbox-${hash}`;
-  }
-  async getImage() {
-    return "";
-  }
-  async startContainer(_image, _containerId) {
-    try {
-      await spawn3("docker", [
-        "compose",
-        "-f",
-        this.composeFile,
-        "-p",
-        this.projectName,
-        "up",
-        "-d"
-      ]);
-    } catch (error) {
-      const err = error;
-      if (err.stderr?.includes("Cannot connect")) {
-        throw new DockerNotAvailableError();
-      }
-      throw new ComposeStartError(this.composeFile, err.stderr || err.message);
-    }
-  }
-  defaultContainerId() {
-    return this.projectName;
-  }
-  async configure() {
-  }
-  async exec(command, options) {
-    try {
-      const result = await spawn3(
-        "docker",
-        [
-          "compose",
-          "-f",
-          this.composeFile,
-          "-p",
-          this.projectName,
-          "exec",
-          "-T",
-          this.service,
-          "sh",
-          "-c",
-          command
-        ],
-        { signal: options?.signal }
-      );
-      return { stdout: result.stdout, stderr: result.stderr, exitCode: 0 };
-    } catch (error) {
-      const err = error;
-      return {
-        stdout: err.stdout || "",
-        stderr: err.stderr || err.message || "",
-        exitCode: err.exitCode ?? 1
-      };
-    }
-  }
-  spawnProcess(command, options) {
-    const child = childSpawn("docker", [
-      "compose",
-      "-f",
-      this.composeFile,
-      "-p",
-      this.projectName,
-      "exec",
-      "-T",
-      ...buildDockerExecFlags(options),
-      this.service,
-      "sh",
-      "-c",
-      command
-    ]);
-    return toSandboxProcess(child, options?.signal);
-  }
-  async stopContainer(_containerId) {
-    try {
-      await spawn3("docker", [
-        "compose",
-        "-f",
-        this.composeFile,
-        "-p",
-        this.projectName,
-        "down"
-      ]);
-    } catch {
-    }
-  }
-};
-async function createDockerSandbox(options = {}) {
-  let strategy;
-  if (isComposeOptions(options)) {
-    strategy = new ComposeStrategy({
-      compose: options.compose,
-      service: options.service,
-      resources: options.resources
-    });
-  } else if (isDockerfileOptions(options)) {
-    strategy = new DockerfileStrategy({
-      dockerfile: options.dockerfile,
-      context: options.context,
-      volumes: options.volumes,
-      resources: options.resources,
-      env: options.env,
-      name: options.name,
-      command: options.command
-    });
-  } else {
-    strategy = new RuntimeStrategy({
-      image: options.image,
-      installers: options.installers,
-      volumes: options.volumes,
-      resources: options.resources,
-      env: options.env,
-      name: options.name,
-      command: options.command
-    });
+    for (const [key, value] of Object.entries(options.env)) {
+      validateEnvKey2(key);
+      flags.push("-e", `${key}=${value}`);
+    }
   }
-  return strategy.create();
+  return flags;
 }
-async function useSandbox(options, fn) {
-  const sandbox = await createDockerSandbox(options);
-  try {
-    return await fn(sandbox);
-  } finally {
-    await sandbox.dispose();
+function toSandboxProcess(child, abortSignal) {
+  if (!child.stdout || !child.stderr) {
+    child.kill("SIGKILL");
+    throw new DockerSandboxError("docker exec child missing stdio streams");
+  }
+  const onAbort = abortSignal ? () => child.kill("SIGKILL") : void 0;
+  if (abortSignal && onAbort) {
+    if (abortSignal.aborted) onAbort();
+    else abortSignal.addEventListener("abort", onAbort, { once: true });
   }
-}
-
-// packages/context/src/lib/sandbox/gcs.ts
-function gcs(options) {
   return {
-    type: "bind",
-    hostPath: options.hostPath,
-    containerPath: options.mountPath,
-    readOnly: options.readOnly ?? false
+    stdout: Readable2.toWeb(child.stdout),
+    stderr: Readable2.toWeb(child.stderr),
+    exit: new Promise((resolve4, reject) => {
+      const settle = () => {
+        child.removeListener("exit", onExitEvent);
+        child.removeListener("error", onError);
+        if (abortSignal && onAbort) {
+          abortSignal.removeEventListener("abort", onAbort);
+        }
+      };
+      const onError = (err) => {
+        settle();
+        reject(err);
+      };
+      const onExitEvent = (code, exitSignal) => {
+        settle();
+        resolve4({ code, signal: exitSignal, success: code === 0 });
+      };
+      child.on("exit", onExitEvent);
+      child.on("error", onError);
+    })
   };
 }
-
-// packages/context/src/lib/sandbox/installers/package-manager.ts
-var PackageInstaller = class extends Installer {
-  kind;
-  packages;
-  constructor(packages) {
-    super();
-    this.packages = packages;
-    this.kind = packages.length === 0 ? "pkg:<empty>" : `pkg:${packages.join(",")}`;
-  }
-  async install(ctx) {
-    if (this.packages.length === 0) return;
-    await ctx.installPackages([...this.packages]);
+var RuntimeStrategy = class extends DockerSandboxStrategy {
+  image;
+  installers;
+  constructor(args = {}) {
+    super({
+      volumes: args.volumes,
+      resources: args.resources,
+      env: args.env,
+      name: args.name,
+      command: args.command
+    });
+    this.image = args.image ?? "alpine:latest";
+    this.installers = args.installers ?? [];
   }
-};
-function pkg(packages) {
-  return new PackageInstaller(packages);
-}
-
-// packages/context/src/lib/sandbox/installers/url-binary.ts
-var UrlBinaryInstaller = class extends Installer {
-  kind;
-  options;
-  constructor(options) {
-    super();
-    this.options = options;
-    this.kind = `url-binary:${options.name}`;
+  async getImage() {
+    return this.image;
   }
-  async install(ctx) {
-    const url = await resolveUrl(ctx, this.options);
-    await downloadAndInstall(
-      ctx,
-      this.options.name,
-      url,
-      this.options.binaryPath
-    );
+  async configure() {
+    const ctx = createInstallerContext(this.context.containerId, this.image);
+    for (const installer of this.installers) {
+      await installer.install(ctx);
+    }
   }
 };
-function urlBinary(options) {
-  return new UrlBinaryInstaller(options);
-}
-async function resolveUrl(ctx, options) {
-  if (typeof options.url === "string") return options.url;
-  const arch = await ctx.arch();
-  const archUrl = options.url[arch];
-  if (!archUrl) {
-    throw new InstallError({
-      target: options.name,
-      source: "url",
-      reason: `No URL provided for architecture "${arch}". Available: ${Object.keys(options.url).join(", ")}`,
-      containerId: ctx.containerId
+var DockerfileStrategy = class extends DockerSandboxStrategy {
+  imageTag;
+  dockerfile;
+  dockerContext;
+  showBuildLogs;
+  constructor(args) {
+    super({
+      volumes: args.volumes,
+      resources: args.resources,
+      env: args.env,
+      name: args.name,
+      command: args.command
     });
+    this.dockerfile = args.dockerfile;
+    this.dockerContext = args.context ?? ".";
+    this.showBuildLogs = args.showBuildLogs ?? false;
+    this.imageTag = this.computeImageTag();
   }
-  return archUrl;
-}
-async function downloadAndInstall(ctx, name, url, binaryPath, source = "url") {
-  await ctx.ensureTool("curl");
-  const isTarGz = url.endsWith(".tar.gz") || url.endsWith(".tgz");
-  const installCmd = isTarGz ? buildTarGzInstallCmd(name, url, binaryPath ?? name) : buildRawInstallCmd(name, url);
-  const result = await ctx.exec(installCmd);
-  if (result.exitCode !== 0) {
-    throw new InstallError({
-      target: name,
-      source,
-      url,
-      reason: result.stderr,
-      containerId: ctx.containerId
-    });
+  computeImageTag() {
+    const content = this.isInlineDockerfile() ? this.dockerfile : readFileSync2(this.dockerfile, "utf-8");
+    const hash = createHash("sha256").update(content).digest("hex").slice(0, 12);
+    return `sandbox-${hash}`;
   }
-}
-function buildTarGzInstallCmd(name, url, binaryPathInArchive) {
-  return `
-    set -e
-    NAME=${shellQuote3(name)}
-    URL=${shellQuote3(url)}
-    BIN_IN_ARCHIVE=${shellQuote3(binaryPathInArchive)}
-    TMPDIR=$(mktemp -d)
-    cd "$TMPDIR"
-    curl -fsSL "$URL" -o archive.tar.gz
-    tar -xzf archive.tar.gz
-    BINARY_FILE=$(find . -name "$BIN_IN_ARCHIVE" -o -name "$NAME" | head -1)
-    if [ -z "$BINARY_FILE" ]; then
-      echo "Binary not found in archive. Contents:" >&2
-      find . -type f >&2
-      exit 1
-    fi
-    chmod +x "$BINARY_FILE"
-    mv "$BINARY_FILE" "/usr/local/bin/$NAME"
-    cd /
-    rm -rf "$TMPDIR"
-  `;
-}
-function buildRawInstallCmd(name, url) {
-  return `
-    NAME=${shellQuote3(name)}
-    URL=${shellQuote3(url)}
-    curl -fsSL "$URL" -o "/usr/local/bin/$NAME"
-    chmod +x "/usr/local/bin/$NAME"
-  `;
-}
-
-// packages/context/src/lib/sandbox/installers/npm.ts
-var NODE_BINARIES = ["node", "npm"];
-var ENSURE_RUNTIME_HINT = "Pass `{ ensureRuntime: true }` to auto-install, or add it via `pkg([...])`.";
-var NpmInstaller = class extends Installer {
-  kind;
-  packageName;
-  options;
-  constructor(packageName, options = {}) {
-    super();
-    this.packageName = packageName;
-    this.options = options;
-    this.kind = `npm:${packageName}`;
+  isInlineDockerfile() {
+    return this.dockerfile.includes("\n");
   }
-  async install(ctx) {
-    await ensureNodeRuntime(ctx, this.options.ensureRuntime ?? false);
-    const spec = this.options.version ? `${this.packageName}@${this.options.version}` : this.packageName;
-    const result = await ctx.exec(`npm install -g ${spec}`);
-    if (result.exitCode !== 0) {
-      throw new InstallError({
-        target: this.packageName,
-        source: "npm",
-        reason: result.stderr,
-        containerId: ctx.containerId
-      });
+  async getImage() {
+    const exists = await this.imageExists();
+    if (!exists) {
+      await this.buildImage();
     }
+    return this.imageTag;
   }
-};
-function npm(packageName, options) {
-  return new NpmInstaller(packageName, options);
-}
-async function ensureNodeRuntime(ctx, ensure) {
-  if (ensure) {
-    await ctx.ensureTool("node", "nodejs");
-    await ctx.ensureTool("npm");
-    return;
+  async configure() {
   }
-  const check = await ctx.exec("which node && which npm");
-  if (check.exitCode !== 0) {
-    throw new MissingRuntimeError(
-      "npm",
-      NODE_BINARIES,
-      ENSURE_RUNTIME_HINT,
-      ctx.containerId
-    );
+  async imageExists() {
+    try {
+      await spawn3("docker", ["image", "inspect", this.imageTag]);
+      return true;
+    } catch {
+      return false;
+    }
   }
-}
-
-// packages/context/src/lib/sandbox/installers/bin.ts
-import { basename, posix } from "node:path";
-var NOT_FOUND_EXIT = 11;
-var CHMOD_FAILED_EXIT = 12;
-var BinInstaller = class extends Installer {
-  kind;
-  binary;
-  options;
-  #name;
-  #target;
-  constructor(binary, options = {}) {
-    super();
-    this.binary = binary;
-    this.options = options;
-    this.#name = resolveName(binary, options);
-    this.#target = options.target ?? posix.join("/usr/local/bin", this.#name);
-    this.kind = `bin:${this.#name}`;
+  async buildImage() {
+    try {
+      if (this.isInlineDockerfile()) {
+        const buildCmd = `echo '${this.dockerfile.replace(/'/g, "'\\''")}' | docker build -t ${this.imageTag} -f - ${this.dockerContext}`;
+        if (this.showBuildLogs) {
+          await this.runStreamed("sh", ["-c", buildCmd]);
+        } else {
+          await spawn3("sh", ["-c", buildCmd]);
+        }
+      } else {
+        const args = [
+          "build",
+          "-t",
+          this.imageTag,
+          "-f",
+          this.dockerfile,
+          this.dockerContext
+        ];
+        if (this.showBuildLogs) {
+          await this.runStreamed("docker", args);
+        } else {
+          await spawn3("docker", args);
+        }
+      }
+    } catch (error) {
+      const err = error;
+      throw new DockerfileBuildError(err.stderr || err.message);
+    }
   }
-  async install(ctx) {
-    const b = shellQuote3(this.binary);
-    const t = shellQuote3(this.#target);
-    const dir = shellQuote3(posix.dirname(this.#target));
-    const result = await ctx.exec(
-      `test -f ${b} || { echo "binary not found at ${this.binary}" >&2; exit ${NOT_FOUND_EXIT}; }; if ! test -x ${b}; then chmod +x ${b} || exit ${CHMOD_FAILED_EXIT}; fi; mkdir -p ${dir} && ln -sf ${b} ${t}`
-    );
-    if (result.exitCode === 0) return;
-    throw new InstallError({
-      target: this.#name,
-      source: "bin",
-      reason: explainFailure(result.exitCode, result.stderr, this.binary),
-      containerId: ctx.containerId
+  /**
+   * Run a build command with stdio inherited so its output streams live to the
+   * parent terminal. On failure the build error is already on screen; the
+   * rejection just carries the exit code.
+   */
+  runStreamed(command, args) {
+    return new Promise((resolve4, reject) => {
+      const child = childSpawn(command, args, { stdio: "inherit" });
+      child.once("error", reject);
+      child.once(
+        "exit",
+        (code) => code === 0 ? resolve4() : reject(
+          new Error(
+            `docker build exited with code ${code} (see build output above)`
+          )
+        )
+      );
     });
   }
 };
-function bin(binary, options) {
-  return new BinInstaller(binary, options);
-}
-function explainFailure(exitCode, stderr, binary) {
-  if (exitCode === NOT_FOUND_EXIT) {
-    return `binary not found at ${binary}`;
+var ComposeStrategy = class extends DockerSandboxStrategy {
+  projectName;
+  composeFile;
+  service;
+  constructor(args) {
+    super({ resources: args.resources });
+    this.composeFile = args.compose;
+    this.service = args.service;
+    this.projectName = this.computeProjectName();
   }
-  if (exitCode === CHMOD_FAILED_EXIT && /read-only file system/i.test(stderr)) {
-    return `${binary} is not executable and the bind mount is read-only \u2014 run \`chmod +x\` on the host, or mount with \`readOnly: false\`. (${stderr.trim()})`;
+  computeProjectName() {
+    const content = readFileSync2(this.composeFile, "utf-8");
+    const hash = createHash("sha256").update(content).digest("hex").slice(0, 8);
+    return `sandbox-${hash}`;
   }
-  return stderr || `bin installer failed with exit code ${exitCode}`;
-}
-function resolveName(binary, options) {
-  if (options.name) return options.name;
-  const base = basename(binary);
-  const dot = base.lastIndexOf(".");
-  return dot > 0 ? base.slice(0, dot) : base;
-}
-
-// packages/context/src/lib/sandbox/installers/pip.ts
-var PYTHON_BINARIES = ["python3", "pip3"];
-var PipInstaller = class extends Installer {
-  kind;
-  packageName;
-  options;
-  constructor(packageName, options = {}) {
-    super();
-    this.packageName = packageName;
-    this.options = options;
-    this.kind = `pip:${packageName}`;
+  async getImage() {
+    return "";
   }
-  async install(ctx) {
-    await ensurePythonRuntime(ctx, this.options.ensureRuntime ?? false);
-    const spec = this.options.version ? `${this.packageName}${formatVersion(this.options.version)}` : this.packageName;
-    const flags = this.options.breakSystemPackages ?? true ? "--break-system-packages" : "";
-    const result = await ctx.exec(`pip3 install ${flags} ${spec}`.trim());
-    if (result.exitCode !== 0) {
-      throw new InstallError({
-        target: this.packageName,
-        source: "pypi",
-        reason: result.stderr,
-        containerId: ctx.containerId
-      });
+  async startContainer(_image, _containerId) {
+    try {
+      await spawn3("docker", [
+        "compose",
+        "-f",
+        this.composeFile,
+        "-p",
+        this.projectName,
+        "up",
+        "-d"
+      ]);
+    } catch (error) {
+      const err = error;
+      if (err.stderr?.includes("Cannot connect")) {
+        throw new DockerNotAvailableError();
+      }
+      throw new ComposeStartError(this.composeFile, err.stderr || err.message);
     }
   }
-};
-function pip(packageName, options) {
-  return new PipInstaller(packageName, options);
-}
-async function ensurePythonRuntime(ctx, ensure) {
-  if (ensure) {
-    const pipPackage = ctx.packageManager === "apk" ? "py3-pip" : "python3-pip";
-    await ctx.ensureTool("python3");
-    await ctx.ensureTool("pip3", pipPackage);
-    return;
+  defaultContainerId() {
+    return this.projectName;
   }
-  const check = await ctx.exec("which python3 && which pip3");
-  if (check.exitCode !== 0) {
-    throw new MissingRuntimeError(
-      "pip",
-      PYTHON_BINARIES,
-      "Pass `{ ensureRuntime: true }` to auto-install, or add via `pkg([...])` (Alpine: `python3 py3-pip`; Debian: `python3 python3-pip`).",
-      ctx.containerId
-    );
+  async configure() {
   }
-}
-function formatVersion(version) {
-  return /^[<>=!~]/.test(version) ? version : `==${version}`;
-}
-
-// packages/context/src/lib/sandbox/installers/github-release.ts
-var GithubReleaseInstaller = class extends Installer {
-  kind;
-  options;
-  constructor(options) {
-    super();
-    this.options = options;
-    this.kind = `github-release:${options.owner}/${options.repo}@${options.version}`;
+  async exec(command, options) {
+    try {
+      const result = await spawn3(
+        "docker",
+        [
+          "compose",
+          "-f",
+          this.composeFile,
+          "-p",
+          this.projectName,
+          "exec",
+          "-T",
+          this.service,
+          "sh",
+          "-c",
+          command
+        ],
+        { signal: options?.signal }
+      );
+      return { stdout: result.stdout, stderr: result.stderr, exitCode: 0 };
+    } catch (error) {
+      const err = error;
+      return {
+        stdout: err.stdout || "",
+        stderr: err.stderr || err.message || "",
+        exitCode: err.exitCode ?? 1
+      };
+    }
   }
-  async install(ctx) {
-    const arch = await ctx.arch();
-    const assetName = this.options.asset(arch);
-    const url = `https://github.com/${this.options.owner}/${this.options.repo}/releases/download/${this.options.version}/${assetName}`;
-    await downloadAndInstall(
-      ctx,
-      this.options.name,
-      url,
-      this.options.binaryPath,
-      "github-release"
-    );
+  spawnProcess(command, options) {
+    const child = childSpawn("docker", [
+      "compose",
+      "-f",
+      this.composeFile,
+      "-p",
+      this.projectName,
+      "exec",
+      "-T",
+      ...buildDockerExecFlags(options),
+      this.service,
+      "sh",
+      "-c",
+      command
+    ]);
+    return toSandboxProcess(child, options?.signal);
+  }
+  async stopContainer(_containerId) {
+    try {
+      await spawn3("docker", [
+        "compose",
+        "-f",
+        this.composeFile,
+        "-p",
+        this.projectName,
+        "down"
+      ]);
+    } catch {
+    }
   }
 };
-function githubRelease(options) {
-  return new GithubReleaseInstaller(options);
+async function createDockerSandbox(options = {}) {
+  let strategy;
+  if (isComposeOptions(options)) {
+    strategy = new ComposeStrategy({
+      compose: options.compose,
+      service: options.service,
+      resources: options.resources
+    });
+  } else if (isDockerfileOptions(options)) {
+    strategy = new DockerfileStrategy({
+      dockerfile: options.dockerfile,
+      context: options.context,
+      showBuildLogs: options.showBuildLogs,
+      volumes: options.volumes,
+      resources: options.resources,
+      env: options.env,
+      name: options.name,
+      command: options.command
+    });
+  } else {
+    strategy = new RuntimeStrategy({
+      image: options.image,
+      installers: options.installers,
+      volumes: options.volumes,
+      resources: options.resources,
+      env: options.env,
+      name: options.name,
+      command: options.command
+    });
+  }
+  return strategy.create();
+}
+async function useSandbox(options, fn) {
+  const sandbox = await createDockerSandbox(options);
+  try {
+    return await fn(sandbox);
+  } finally {
+    await sandbox.dispose();
+  }
+}
+
+// packages/context/src/lib/sandbox/gcs.ts
+function gcs(options) {
+  return {
+    type: "bind",
+    hostPath: options.hostPath,
+    containerPath: options.mountPath,
+    readOnly: options.readOnly ?? false
+  };
 }
 
 // packages/context/src/lib/sandbox/subcommand.ts
@@ -11654,10 +12073,10 @@ export {
   PostgresStreamStore,
   PromiseResolver,
   RuntimeStrategy,
-  SnapshotFailedError,
   SqlServerContextStore,
   SqliteContextStore,
   SqliteStreamStore,
+  StraceUnavailableError,
   StreamManager,
   StreamStore,
   TitleGenerator,
@@ -11682,7 +12101,7 @@ export {
   applyInlineReminder,
   applyPartReminder,
   applyReminderToMessage,
-  applyToolOutputRemindersToMessage,
+  applyRemindersToToolOutput,
   asStaticWordPartText,
   asStaticWordText,
   assertCountSpec,
@@ -11726,7 +12145,7 @@ export {
   executorContext,
   explain,
   fail,
-  findSingleOutputAvailableToolPart,
+  first,
   firstN,
   fragment,
   fromFragment,
@@ -11750,6 +12169,7 @@ export {
   isFragmentObject,
   isMessageFragment,
   isRecord,
+  isSyntheticSteerMessage,
   lastAssistantLength,
   loadSkillMetadata,
   localeReminder,
@@ -11765,10 +12185,10 @@ export {
   not,
   npm,
   nullUsage,
-  observeSandboxFileEvents,
   once,
   or,
   parseFrontmatter,
+  parseStraceTrace,
   pass,
   persistedWriter,
   persona,
@@ -11795,7 +12215,8 @@ export {
   seasonChanged,
   seasonReminder,
   selfCritique,
-  shellQuote3 as shellQuote,
+  selfTestStrace,
+  shellQuote,
   skills,
   skillsReminder,
   socraticPrompting,
@@ -11806,6 +12227,7 @@ export {
   stripTextByRanges,
   structuredOutput,
   styleGuide,
+  synthesizeSteerUserMessage,
   temporalReminder,
   term,
   timeReminder,
@@ -11815,6 +12237,7 @@ export {
   toolCallCount,
   toolCalled,
   toolFailed,
+  traceFileChanges,
   uploadSkills,
   urlBinary,
   usageExceeds,