@deepagents/context 6.1.0 → 7.0.0

package/dist/index.js

@@ -313,23 +313,23 @@ import {
 } from "ai";
 import chalk from "chalk";
 function createRepairToolCall(model, abortSignal) {
-  return async ({ toolCall: toolCall2, tools, inputSchema, error }) => {
+  return async ({ toolCall: toolCall2, tools, inputSchema: inputSchema2, error }) => {
     if (NoSuchToolError.isInstance(error)) {
       return null;
     }
     console.log(
       `Debug: ${chalk.yellow("RepairingToolCall")}: ${toolCall2.toolName}`
     );
-    const tool3 = tools[toolCall2.toolName];
+    const tool4 = tools[toolCall2.toolName];
     const { output } = await generateText({
       abortSignal,
       model,
-      output: Output.object({ schema: tool3.inputSchema }),
+      output: Output.object({ schema: tool4.inputSchema }),
       prompt: [
         `The model tried to call the tool "${toolCall2.toolName}" with the following inputs:`,
         JSON.stringify(toolCall2.input),
         `The tool accepts the following schema:`,
-        JSON.stringify(inputSchema(toolCall2)),
+        JSON.stringify(inputSchema2(toolCall2)),
         "Please fix the inputs."
       ].join("\n")
     });
@@ -348,16 +348,15 @@ var Agent = class _Agent {
   sandbox;
   constructor(options) {
     this.#options = options;
-    this.tools = withHostOnlyToolMetadata({
-      ...options.sandbox.tools,
-      ...options.tools || {}
-    });
+    this.tools = withHostOnlyToolMetadata(
+      Object.assign({}, options.sandbox.tools, options.tools)
+    );
     this.context = options.context;
     this.model = options.model;
     this.sandbox = options.sandbox;
     this.#guardrails = options.guardrails || [];
   }
-  async generate(contextVariables, config) {
+  async generate(...[options]) {
     if (!this.#options.context) {
       throw new Error(`Agent ${this.#options.name} is missing a context.`);
     }
@@ -369,9 +368,10 @@ var Agent = class _Agent {
       sandbox: this.#options.sandbox
     });
     return generateText2({
-      abortSignal: config?.abortSignal,
+      abortSignal: options?.abortSignal,
       providerOptions: this.#options.providerOptions,
       telemetry: this.#options.telemetry,
+      runtimeContext: this.#options.runtimeContext,
       model: this.#options.model,
       instructions: systemPrompt,
       messages: await convertToModelMessages(messages, {
@@ -379,16 +379,18 @@ var Agent = class _Agent {
         tools: this.tools
       }),
       stopWhen: this.#options.stopWhen ?? DEFAULT_STOP_WHEN,
-      prepareStep: this.#options.context.createPrepareStep({
-        steer: false,
-        sandbox: this.#options.sandbox
-      }),
+      prepareStep: this.#withPrepareStep(
+        this.#options.context.createPrepareStep({
+          steer: false,
+          sandbox: this.#options.sandbox
+        })
+      ),
       tools: this.tools,
-      runtimeContext: contextVariables,
-      toolsContext: createToolsContext(this.tools, contextVariables),
+      toolsContext: options?.toolsContext,
+      experimental_toolCallers: this.#options.experimental_toolCallers,
       repairToolCall: createRepairToolCall(
         this.#options.model,
-        config?.abortSignal
+        options?.abortSignal
       ),
       toolChoice: this.#options.toolChoice
     });
@@ -401,7 +403,7 @@ var Agent = class _Agent {
    *
    * @example
    * ```typescript
-   * const stream = await agent.stream({});
+   * const stream = await agent.stream();
    *
    * // With guardrails - use toUIMessageStream for protection
    * await printer.readableStream(stream.toUIMessageStream());
@@ -410,20 +412,22 @@ var Agent = class _Agent {
    * await printer.stdout(stream);
    * ```
    */
-  async stream(contextVariables, config) {
+  async stream(...[options]) {
     if (!this.#options.context) {
       throw new Error(`Agent ${this.#options.name} is missing a context.`);
     }
     if (!this.#options.model) {
       throw new Error(`Agent ${this.#options.name} is missing a model.`);
     }
-    const prepareStep = this.#options.context.createPrepareStep({
-      additionalInput: this.#options.prepareStepInput,
-      sandbox: this.#options.sandbox
-    });
+    const prepareStep = this.#withPrepareStep(
+      this.#options.context.createPrepareStep({
+        additionalInput: this.#options.prepareStepInput,
+        sandbox: this.#options.sandbox
+      })
+    );
     const result = await this.#createRawStream(
-      contextVariables,
-      config,
+      options?.toolsContext,
+      options,
       prepareStep
     );
     if (this.#guardrails.length === 0) {
@@ -431,15 +435,27 @@ var Agent = class _Agent {
     }
     return this.#wrapWithGuardrails(
       result,
-      contextVariables,
-      config,
+      options?.toolsContext,
+      options,
       prepareStep
     );
   }
+  #withPrepareStep(prepareContext) {
+    const prepareStep = this.#options.prepareStep;
+    if (!prepareStep) return prepareContext;
+    return async (input) => {
+      const context = await prepareContext(input);
+      const overrides = await prepareStep({
+        ...input,
+        ...context
+      });
+      return { ...context, ...overrides };
+    };
+  }
   /**
    * Create a raw stream without guardrail processing.
    */
-  async #createRawStream(contextVariables, config, prepareStep) {
+  async #createRawStream(toolsContext, config, prepareStep) {
     const context = this.#options.context;
     if (!context) {
       throw new Error(`Agent ${this.#options.name} is missing a context.`);
@@ -454,8 +470,13 @@ var Agent = class _Agent {
     });
     return streamText({
       abortSignal: config?.abortSignal,
+      onStart: config?.onStart,
+      onStepStart: config?.onStepStart,
+      onStepEnd: config?.onStepEnd,
+      include: config?.include,
       providerOptions: this.#options.providerOptions,
       telemetry: this.#options.telemetry,
+      runtimeContext: this.#options.runtimeContext,
       model,
       instructions: systemPrompt,
       messages: await convertToModelMessages(messages, {
@@ -464,11 +485,15 @@ var Agent = class _Agent {
       }),
       repairToolCall: createRepairToolCall(model, config?.abortSignal),
       stopWhen: this.#options.stopWhen ?? DEFAULT_STOP_WHEN,
-      prepareStep: prepareStep ?? context.createPrepareStep({ sandbox: this.#options.sandbox }),
+      // Streaming erases the tool-set type; the callback still receives this.tools.
+      prepareStep: prepareStep ?? context.createPrepareStep({
+        sandbox: this.#options.sandbox
+      }),
       experimental_transform: config?.transform ?? smoothStream(),
       tools: this.tools,
-      runtimeContext: contextVariables,
-      toolsContext: createToolsContext(this.tools, contextVariables),
+      // Generic wrappers cannot reduce AI SDK's conditional context or caller maps.
+      toolsContext,
+      experimental_toolCallers: this.#options.experimental_toolCallers,
       toolChoice: this.#options.toolChoice
     });
   }
@@ -480,7 +505,7 @@ var Agent = class _Agent {
    * 2. A finish-step is emitted, triggering onStepEnd to persist the self-correction
    * 3. A new stream is started and the model continues from the correction
    */
-  #wrapWithGuardrails(result, contextVariables, config, prepareStep) {
+  #wrapWithGuardrails(result, toolsContext, config, prepareStep) {
     const maxRetries = config?.maxRetries ?? this.#options.maxGuardrailRetries ?? 3;
     const context = this.#options.context;
     if (!context) {
@@ -570,7 +595,7 @@ var Agent = class _Agent {
             writer.write({ type: "finish-step" });
             await stepSaved.promise;
             currentResult = await this.#createRawStream(
-              contextVariables,
+              toolsContext,
               config,
               prepareStep
             );
@@ -614,21 +639,10 @@ var Agent = class _Agent {
 ${output}
 </OutputInstructions>` : input;
           ctx.set(user(prompt));
-          const sub = agent({
-            name: this.#options.name,
-            sandbox: this.#options.sandbox,
-            model: this.model,
-            context: ctx,
-            tools: this.#options.tools,
-            providerOptions: this.#options.providerOptions,
-            telemetry: this.#options.telemetry
+          const result = await this.clone({ context: ctx }).generate({
+            toolsContext: options.context,
+            abortSignal: options.abortSignal
           });
-          const result = await sub.generate(
-            {},
-            {
-              abortSignal: options.abortSignal
-            }
-          );
           if (props?.outputExtractor) {
             return await props.outputExtractor(result);
           }
@@ -721,9 +735,9 @@ function agent(options) {
   return new Agent(options);
 }
 function structuredOutput(options) {
-  const tools = options.tools ? withHostOnlyToolMetadata(options.tools) : void 0;
+  const tools = withHostOnlyToolMetadata({ ...options.tools });
   return {
-    async generate(contextVariables, config) {
+    async generate(...[callOptions]) {
       if (!options.context) {
         throw new Error(`structuredOutput is missing a context.`);
       }
@@ -735,7 +749,7 @@ function structuredOutput(options) {
         sandbox: options.sandbox
       });
       const result = await generateText2({
-        abortSignal: config?.abortSignal,
+        abortSignal: callOptions?.abortSignal,
         providerOptions: options.providerOptions,
         telemetry: options.telemetry,
         model: options.model,
@@ -747,16 +761,15 @@ function structuredOutput(options) {
         stopWhen: DEFAULT_STOP_WHEN,
         repairToolCall: createRepairToolCall(
           options.model,
-          config?.abortSignal
+          callOptions?.abortSignal
         ),
-        runtimeContext: contextVariables,
-        toolsContext: createToolsContext(tools ?? {}, contextVariables),
+        toolsContext: callOptions?.toolsContext,
         output: Output2.object({ schema: options.schema }),
         tools
       });
       return result.output;
     },
-    async stream(contextVariables, config) {
+    async stream(...[callOptions]) {
       if (!options.context) {
         throw new Error(`structuredOutput is missing a context.`);
       }
@@ -768,34 +781,28 @@ function structuredOutput(options) {
         sandbox: options.sandbox
       });
       return streamText({
-        abortSignal: config?.abortSignal,
+        abortSignal: callOptions?.abortSignal,
         providerOptions: options.providerOptions,
         telemetry: options.telemetry,
         model: options.model,
         instructions: systemPrompt,
         repairToolCall: createRepairToolCall(
           options.model,
-          config?.abortSignal
+          callOptions?.abortSignal
         ),
         messages: await convertToModelMessages(messages, {
           ignoreIncompleteToolCalls: true,
           tools
         }),
         stopWhen: DEFAULT_STOP_WHEN,
-        experimental_transform: config?.transform ?? smoothStream(),
-        runtimeContext: contextVariables,
-        toolsContext: createToolsContext(tools ?? {}, contextVariables),
+        experimental_transform: callOptions?.transform ?? smoothStream(),
+        toolsContext: callOptions?.toolsContext,
         output: Output2.object({ schema: options.schema }),
         tools
       });
     }
   };
 }
-function createToolsContext(tools, context) {
-  return Object.fromEntries(
-    Object.keys(tools).map((toolName) => [toolName, context])
-  );
-}
 function chunkId(chunk) {
   if (typeof chunk !== "object" || chunk === null || !("id" in chunk)) {
     return void 0;
@@ -840,6 +847,7 @@ import { getErrorMessage } from "@ai-sdk/provider";
 import {
   convertToModelMessages as convertToModelMessages2,
   generateId as generateId5,
+  isStaticToolUIPart as isStaticToolUIPart2,
   validateUIMessages
 } from "ai";
 
@@ -1436,13 +1444,13 @@ var TomlRenderer = class extends ContextRenderer {
     const entries = this.#renderObjectEntries(obj, newPath);
     return ["", `[${newPath.join(".")}]`, ...entries].join("\n");
   }
-  #renderObjectEntries(obj, path3) {
+  #renderObjectEntries(obj, path6) {
     return Object.entries(obj).map(([key, value]) => {
       if (value == null) {
         return "";
       }
       if (isFragmentObject(value)) {
-        const newPath = [...path3, key];
+        const newPath = [...path6, key];
         const entries = this.#renderObjectEntries(value, newPath);
         return ["", `[${newPath.join(".")}]`, ...entries].join("\n");
       }
@@ -3025,30 +3033,30 @@ var FragmentLoaderResolver = class {
       fragments.map((f) => this.#walkFragment(f, ctx, 0, /* @__PURE__ */ new Set(), f.name))
     );
   }
-  async #walkFragment(fragment2, ctx, depth, ancestors, path3) {
+  async #walkFragment(fragment2, ctx, depth, ancestors, path6) {
     if (!("data" in fragment2)) return;
     fragment2.data = await this.#walkData(
       fragment2.data,
       ctx,
       depth,
       ancestors,
-      path3
+      path6
     );
   }
-  async #walkData(value, ctx, depth, ancestors, path3) {
+  async #walkData(value, ctx, depth, ancestors, path6) {
     if (ctx.signal?.aborted) {
       throw ctx.signal.reason ?? new Error("Resolver aborted");
     }
     if (depth > this.#maxDepth) {
       throw new Error(
-        `Resolver recursion exceeded maxDepth=${this.#maxDepth} at fragment '${path3}'`
+        `Resolver recursion exceeded maxDepth=${this.#maxDepth} at fragment '${path6}'`
       );
     }
     const handler = this.#resolvers.find((r) => r.canResolve(value));
     if (handler) {
       if (handler.requiresSandbox && !ctx.sandbox) {
         throw new Error(
-          `Fragment '${path3}' is dispatched to ${handler.name}, which requires a sandbox; none was provided`
+          `Fragment '${path6}' is dispatched to ${handler.name}, which requires a sandbox; none was provided`
         );
       }
       let resolved;
@@ -3059,11 +3067,11 @@ var FragmentLoaderResolver = class {
         );
       } catch (cause) {
         throw new Error(
-          `Async fragment '${path3}' failed in ${handler.name}: ${cause instanceof Error ? cause.message : String(cause)}`,
+          `Async fragment '${path6}' failed in ${handler.name}: ${cause instanceof Error ? cause.message : String(cause)}`,
           { cause }
         );
       }
-      return this.#walkData(resolved, ctx, depth + 1, ancestors, path3);
+      return this.#walkData(resolved, ctx, depth + 1, ancestors, path6);
     }
     if (value === null || value === void 0) {
       return value;
@@ -3072,7 +3080,7 @@ var FragmentLoaderResolver = class {
       if (ancestors.has(value)) return void 0;
       const childAncestors = new Set(ancestors);
       childAncestors.add(value);
-      const childPath = `${path3}.${value.name}`;
+      const childPath = `${path6}.${value.name}`;
       await this.#walkFragment(
         value,
         ctx,
@@ -3088,7 +3096,7 @@ var FragmentLoaderResolver = class {
       childAncestors.add(value);
       return Promise.all(
         value.map(
-          (item) => this.#walkData(item, ctx, depth, childAncestors, path3)
+          (item) => this.#walkData(item, ctx, depth, childAncestors, path6)
         )
       );
     }
@@ -3100,7 +3108,7 @@ var FragmentLoaderResolver = class {
       const entries = Object.entries(value);
       const resolvedValues = await Promise.all(
         entries.map(
-          ([, v]) => this.#walkData(v, ctx, depth, childAncestors, path3)
+          ([, v]) => this.#walkData(v, ctx, depth, childAncestors, path6)
         )
       );
       for (let i = 0; i < entries.length; i += 1) {
@@ -3959,6 +3967,58 @@ function toolOutcomesFromStep(content) {
   }
   return outcomes;
 }
+function terminalToolPartsFromStep(content) {
+  return content.flatMap((part) => {
+    if (part.type === "tool-result" && part.dynamic !== true) {
+      return [
+        {
+          type: `tool-${part.toolName}`,
+          toolCallId: part.toolCallId,
+          state: "output-available",
+          input: part.input,
+          output: part.output === void 0 ? null : part.output
+        }
+      ];
+    }
+    if (part.type === "tool-error" && part.dynamic !== true) {
+      return [
+        {
+          type: `tool-${part.toolName}`,
+          toolCallId: part.toolCallId,
+          state: "output-error",
+          input: part.input,
+          errorText: getErrorMessage(part.error)
+        }
+      ];
+    }
+    if (part.type === "tool-approval-response" && part.approved === false && part.toolCall.dynamic !== true) {
+      return [
+        {
+          type: `tool-${part.toolCall.toolName}`,
+          toolCallId: part.toolCall.toolCallId,
+          state: "output-denied",
+          input: part.toolCall.input,
+          approval: {
+            id: part.approvalId,
+            approved: false,
+            ...part.reason === void 0 ? {} : { reason: part.reason }
+          }
+        }
+      ];
+    }
+    return [];
+  });
+}
+function mergeTerminalToolParts(message2, liveParts) {
+  const remaining = new Map(liveParts);
+  const parts = message2.parts.map((part) => {
+    if (!isStaticToolUIPart2(part)) return part;
+    remaining.delete(part.toolCallId);
+    return part;
+  });
+  parts.push(...remaining.values());
+  return { ...message2, parts };
+}
 var ContextEngine = class _ContextEngine {
   /** Non-message fragments (role, hints, etc.) - not persisted in graph */
   #fragments = [];
@@ -4037,6 +4097,7 @@ var ContextEngine = class _ContextEngine {
       );
     }
     this.#branch = branch;
+    this.#branchName = branch.name;
     this.#initialized = true;
   }
   /**
@@ -4371,12 +4432,24 @@ var ContextEngine = class _ContextEngine {
     const enableSteer = options.steer ?? true;
     const session = {
       firedOnceIds: /* @__PURE__ */ new Set(),
-      currentSegStart: 0
+      terminalToolParts: /* @__PURE__ */ new Map(),
+      segments: [],
+      initialStepStarts: null,
+      stepOffset: 0,
+      lastStepNumber: null
     };
     this.#currentReminderSession = session;
     return async ({ steps, stepNumber, messages }) => {
+      if (stepNumber === 0 && session.lastStepNumber !== null) {
+        session.stepOffset += session.lastStepNumber + 1;
+      }
+      session.lastStepNumber = stepNumber;
+      const completedSteps = session.stepOffset + stepNumber;
       const priorStep = stepNumber >= 1 ? steps[stepNumber - 1] : void 0;
       const hasSafeBoundary = (priorStep?.content?.length ?? 0) > 0;
+      for (const part of terminalToolPartsFromStep(priorStep?.content ?? [])) {
+        session.terminalToolParts.set(part.toolCallId, part);
+      }
       const canFire = enableSteer && hasSafeBoundary;
       const steerConfigs = canFire ? this.#remindersFor("steer") : [];
       const outcomes = toolOutcomesFromStep(steps.at(-1)?.content ?? []);
@@ -4435,18 +4508,24 @@ var ContextEngine = class _ContextEngine {
             "createPrepareStep: expected an assistant message at chain head."
           );
         }
-        const currentSegmentId = session.currentSegId ?? head.id;
+        const currentSegmentId = head.id;
         const currentSegment = await this.#store.getMessage(currentSegmentId);
         if (!currentSegment || currentSegment.name !== "assistant") {
           throw new Error(
             "createPrepareStep: expected the open assistant segment to be persisted."
           );
         }
-        const currentMessage = requireUIMessage(
+        requireUIMessage(
           currentSegment.data,
           `Stored assistant message "${currentSegment.id}"`
         );
         const nextSegmentId = generateId5();
+        if (session.segments.length === 0) {
+          session.segments.push({
+            id: currentSegmentId,
+            startStep: 0
+          });
+        }
         for (const input of inputs) this.set(user(input));
         this.set(
           assistant({
@@ -4456,8 +4535,11 @@ var ContextEngine = class _ContextEngine {
           })
         );
         await this.save({ branch: false });
-        session.currentSegId = nextSegmentId;
-        session.currentSegStart += currentMessage.parts.length;
+        session.segments.push({
+          id: nextSegmentId,
+          startStep: completedSteps
+        });
+        session.terminalToolParts.clear();
         return {
           messages: [...messages, ...inputModel]
         };
@@ -4482,14 +4564,81 @@ var ContextEngine = class _ContextEngine {
       );
     }
     const session = this.#currentReminderSession;
-    this.set(
-      assistant({
-        ...message2,
-        id: session?.currentSegId ?? head.id,
-        parts: message2.parts.slice(session?.currentSegStart ?? 0)
-      })
-    );
-    await this.save({ branch: false });
+    let id = head.id;
+    let parts = message2.parts;
+    if (session) {
+      if (session.initialStepStarts === null) {
+        const initialId = session.segments[0]?.id ?? head.id;
+        const initial = await this.#store.getMessage(initialId);
+        if (!initial || initial.name !== "assistant") {
+          throw new Error(
+            `writeAssistantSegment: initial segment "${initialId}" was not found`
+          );
+        }
+        session.initialStepStarts = requireUIMessage(
+          initial.data,
+          `Stored assistant message "${initial.id}"`
+        ).parts.filter((part) => part.type === "step-start").length;
+      }
+      const streamStepStarts = message2.parts.flatMap(
+        (part, index) => part.type === "step-start" ? [index] : []
+      );
+      const completedSteps = streamStepStarts.length - session.initialStepStarts;
+      if (completedSteps < 0) {
+        throw new Error(
+          "writeAssistantSegment: response lost an existing step boundary"
+        );
+      }
+      const segmentIndex = session.segments.findLastIndex(
+        (candidate) => candidate.startStep < completedSteps
+      );
+      if (segmentIndex >= 0) {
+        const segment = session.segments[segmentIndex];
+        id = segment.id;
+        if (segmentIndex > 0) {
+          const start = streamStepStarts[session.initialStepStarts + segment.startStep];
+          if (start === void 0) {
+            throw new Error(
+              `writeAssistantSegment: response is missing step ${segment.startStep + 1}`
+            );
+          }
+          parts = message2.parts.slice(start);
+        }
+      } else {
+        const lastSegment = session.segments.at(-1);
+        if (lastSegment) {
+          id = lastSegment.id;
+          parts = [];
+        }
+      }
+    }
+    const fragment2 = assistant({
+      ...message2,
+      id,
+      parts
+    });
+    if (!session) {
+      this.set(fragment2);
+      await this.save({ branch: false });
+      return;
+    }
+    const stored = await this.#store.getMessage(id);
+    if (!stored) {
+      throw new Error(
+        `writeAssistantSegment: reserved segment "${id}" was not found`
+      );
+    }
+    if (!fragment2.codec) {
+      throw new Error("writeAssistantSegment: assistant codec is missing");
+    }
+    await this.#store.addMessages([
+      {
+        ...stored,
+        name: fragment2.name,
+        type: fragment2.type,
+        data: fragment2.codec.encode()
+      }
+    ]);
   }
   #remindersFor(target) {
     return this.#fragments.filter(isConditionalReminder).map((fragment2) => fragment2.metadata.reminder).filter((config) => config.target === target);
@@ -4590,8 +4739,16 @@ var ContextEngine = class _ContextEngine {
         "steer reminders require a user message earlier in the turn"
       );
     }
+    const lastAssistantMessage = chain.lastAssistantMessage;
+    if (!lastAssistantMessage) {
+      throw new Error("steer reminders require a completed assistant step");
+    }
     return {
       ...this.#buildWhenCtx(chain, currentMessage),
+      lastAssistantMessage: mergeTerminalToolParts(
+        lastAssistantMessage,
+        session.terminalToolParts
+      ),
       sandbox,
       firedOnceIds: /* @__PURE__ */ new Set([...chain.firedOnceIds, ...session.firedOnceIds])
     };
@@ -4998,10 +5155,10 @@ var ContextEngine = class _ContextEngine {
     for (const fragment2 of this.#fragments) {
       const skills2 = fragment2.metadata?.skills;
       if (fragment2.name === "available_skills" && Array.isArray(skills2) && skills2.every(isAvailableSkill)) {
-        return skills2.map(({ name, description, path: path3 }) => ({
+        return skills2.map(({ name, description, path: path6 }) => ({
           name,
           description,
-          path: path3
+          path: path6
         }));
       }
     }
@@ -5489,7 +5646,7 @@ var TitleGenerator = class {
       context,
       model: options.model,
       schema: titleSchema
-    }).generate({}, { abortSignal: options.abortSignal });
+    }).generate({ abortSignal: options.abortSignal });
     if (!title) {
       throw new Error("Title generation returned an empty string.");
     }
@@ -5524,7 +5681,8 @@ var defaultChatMessageMetadata = ({
   }
   return void 0;
 };
-async function chat(agent2, options = {}) {
+async function chat(agent2, ...args) {
+  const [options] = args;
   const context = agent2.context;
   if (!context) {
     throw new Error(
@@ -5539,32 +5697,11 @@ async function chat(agent2, options = {}) {
   }
   const initialAssistantMsgId = head.id;
   const uiMessages = await context.getMessages();
-  const streamContextVariables = options.contextVariables === void 0 ? {} : options.contextVariables;
-  const [title, result] = await Promise.all([
-    makeTitle({
-      context,
-      model: agent2.model,
-      generateTitle: options.generateTitle,
-      abortSignal: options.abortSignal
-    }),
-    agent2.stream(streamContextVariables, {
-      transform: options.transform,
-      abortSignal: options.abortSignal
-    })
-  ]);
-  const uiStream = result.toUIMessageStream({
-    onError: options.onError ?? formatChatError,
-    sendStart: true,
-    sendFinish: true,
-    sendReasoning: true,
-    sendSources: true,
-    originalMessages: uiMessages,
-    generateMessageId: () => initialAssistantMsgId,
-    messageMetadata: options.messageMetadata ?? defaultChatMessageMetadata
-  });
+  let result;
   return createUIMessageStream2({
     originalMessages: uiMessages,
     generateId: () => initialAssistantMsgId,
+    onError: options?.onError ?? formatChatError,
     onStepEnd: async ({ responseMessage }) => {
       await context.writeAssistantSegment(responseMessage);
     },
@@ -5573,7 +5710,7 @@ async function chat(agent2, options = {}) {
       if (isAborted) {
         message2 = { ...message2, parts: sanitizeAbortedParts(message2.parts) };
       }
-      const finalMetadata = await options.finalAssistantMetadata?.(message2);
+      const finalMetadata = await options?.finalAssistantMetadata?.(message2);
       const mergedMetadata = {
         ...message2.metadata ?? {},
         ...finalMetadata ?? {}
@@ -5582,13 +5719,35 @@ async function chat(agent2, options = {}) {
         message2 = { ...message2, metadata: mergedMetadata };
       }
       await context.writeAssistantSegment(message2);
-      const usage = await result.usage;
+      const usage = await result?.usage;
       if (usage !== void 0) {
         await context.trackUsage(usage);
       }
     },
     execute: async ({ writer }) => {
-      writer.merge(uiStream);
+      writer.write({ type: "start", messageId: initialAssistantMsgId });
+      options?.onStream?.(writer);
+      const [title, streamed] = await Promise.all([
+        makeTitle({
+          context,
+          model: agent2.model,
+          generateTitle: options?.generateTitle,
+          abortSignal: options?.abortSignal
+        }),
+        agent2.stream(...args)
+      ]);
+      result = streamed;
+      writer.merge(
+        result.toUIMessageStream({
+          onError: options?.onError ?? formatChatError,
+          sendStart: false,
+          sendReasoning: true,
+          sendSources: true,
+          originalMessages: uiMessages,
+          generateMessageId: () => initialAssistantMsgId,
+          messageMetadata: options?.messageMetadata ?? defaultChatMessageMetadata
+        })
+      );
       if (title) {
         writer.write({ type: "data-chat-title", data: title, transient: true });
       }
@@ -5634,7 +5793,7 @@ function formatChatError(error) {
     console.error("Upstream API call failed:", error);
     return `Upstream API call failed with status ${error.statusCode}: ${error.message}`;
   }
-  return JSON.stringify(error);
+  return error instanceof Error ? "An error occurred." : JSON.stringify(error);
 }
 async function makeTitle(options) {
   const titler = new TitleGenerator({ context: options.context });
@@ -5930,10 +6089,14 @@ function fromFragment(fragment2, options) {
 }
 
 // packages/context/src/lib/fragments/plan.ts
+import dedent2 from "dedent";
+import z4 from "zod";
+
+// packages/context/src/lib/fragments/plan-shared.ts
 import dedent from "dedent";
 import z3 from "zod";
 var PLAN_FILE_PATH = "/workspace/.deepagents/plan.json";
-var PLAN_INSTRUCTIONS = dedent`
+var PLAN_FOUNDATION_INSTRUCTIONS = dedent`
   You own the plan. The user is not required to provide a structured objective, success criteria, constraints, or task breakdown.
 
   Build and maintain the plan from the best available evidence, in this order:
@@ -5957,28 +6120,11 @@ var PLAN_INSTRUCTIONS = dedent`
 
   Never silently promote an assumption into a requirement or constraint. Ask the user only when an unresolved choice materially changes the outcome, cannot be answered from the workspace or runtime, or requires authority beyond the request. Do not ask merely because the user did not provide structured plan fields.
 
-  Maintain the authoritative plan as JSON at ${PLAN_FILE_PATH}. Read the latest file before changing it and write the complete document in one operation. The plan has this shape:
-  - revision: a positive integer, incremented whenever the objective, criteria, constraints, assumptions, tasks, or dependencies change; recording lastReview alone does not increment it;
-  - objective: { text, basis, source };
-  - successCriteria: [{ id, text, basis, source, evidence: [{ summary, source }] }];
-  - constraints and assumptions: [{ text, basis, source }];
-  - tasks: [{ id, title, status, blockedBy, evidence }], where status is pending, in_progress, or completed;
-  - lastReview, when present: { revision, decision, summary }.
-
-  Use basis values explicit_requirement, discovered_constraint, inference, or assumption. Store only blockedBy dependency edges. Never store blocks, readiness, or a blocked task status; those are derived when the plan is read. A task may be in_progress only when every blocker is completed, and a completed task must include concrete evidence.
-
+  Maintain the authoritative plan as JSON at ${PLAN_FILE_PATH}. Read the latest file before changing it and write the complete document in one operation.
+`;
+var PLAN_REVIEW_INSTRUCTIONS = dedent`
   Whenever plan review fires, record lastReview before continuing. Its revision is the plan revision that was evaluated. If the decision is revise or replace, increment the plan revision when applying the resulting changes while preserving the evaluated revision in lastReview.
-
-  Revise the plan when new evidence invalidates its objective, criteria, constraints, assumptions, sequencing, or dependencies. Before recording a complete decision or claiming completion, map every success criterion to concrete evidence. Completed task statuses alone do not prove completion.
 `;
-var REVIEW_REMINDER = [
-  "Re-read the current plan and consider the evidence gathered since the previous review.",
-  "",
-  "Is the current plan still valid given the latest evidence?",
-  "",
-  "If yes, continue. If not, revise it before taking another action.",
-  "Before claiming completion, verify the success criteria against evidence."
-].join("\n");
 var nonEmptyString = z3.string().trim().min(1);
 var statementBasis = z3.enum([
   "explicit_requirement",
@@ -5986,40 +6132,24 @@ var statementBasis = z3.enum([
   "inference",
   "assumption"
 ]);
-var statement = z3.strictObject({
-  text: nonEmptyString,
-  basis: statementBasis,
-  source: nonEmptyString
-});
 var evidence = z3.strictObject({
   summary: nonEmptyString,
   source: nonEmptyString
 });
-var successCriterion = statement.extend({
-  id: nonEmptyString,
-  evidence: z3.array(evidence)
-});
-var task = z3.strictObject({
-  id: nonEmptyString,
-  title: nonEmptyString,
-  status: z3.enum(["pending", "in_progress", "completed"]),
-  blockedBy: z3.array(nonEmptyString),
-  evidence: z3.array(evidence)
-});
 var lastReview = z3.strictObject({
   revision: z3.number().int().positive(),
   decision: z3.enum(["continue", "revise", "replace", "complete", "blocked"]),
   summary: nonEmptyString
 });
-var planState = z3.strictObject({
-  revision: z3.number().int().positive(),
-  objective: statement,
-  successCriteria: z3.array(successCriterion).min(1),
-  constraints: z3.array(statement),
-  assumptions: z3.array(statement),
-  tasks: z3.array(task),
-  lastReview: lastReview.optional()
-});
+function parsePlanSchema(schema, value) {
+  const result = schema.safeParse(value);
+  if (result.success) return result.data;
+  const issues = result.error.issues.slice(0, 5).map(({ path: path6, message: message2 }) => `${path6.join(".") || "plan"}: ${message2}`);
+  const remaining = result.error.issues.length - issues.length;
+  throw new Error(
+    `schema errors: ${issues.join("; ")}${remaining > 0 ? `; ${remaining} more` : ""}`
+  );
+}
 function uniqueIds(items, label) {
   const byId = /* @__PURE__ */ new Map();
   for (const item of items) {
@@ -6030,23 +6160,22 @@ function uniqueIds(items, label) {
   }
   return byId;
 }
-function validatePlan(state) {
-  uniqueIds(state.successCriteria, "success criterion");
-  const tasks = uniqueIds(state.tasks, "task");
-  const blocks = new Map(state.tasks.map(({ id }) => [id, []]));
-  for (const item of state.tasks) {
+function validateDependencies(items, label) {
+  const byId = uniqueIds(items, label);
+  const blocks = new Map(items.map(({ id }) => [id, []]));
+  for (const item of items) {
     const blockers = /* @__PURE__ */ new Set();
     for (const blocker of item.blockedBy) {
       if (blocker === item.id) {
-        throw new Error(`task "${item.id}" cannot block itself`);
+        throw new Error(`${label} "${item.id}" cannot block itself`);
       }
-      if (!tasks.has(blocker)) {
+      if (!byId.has(blocker)) {
         throw new Error(
-          `task "${item.id}" references missing blocker "${blocker}"`
+          `${label} "${item.id}" references missing blocker "${blocker}"`
         );
       }
       if (blockers.has(blocker)) {
-        throw new Error(`task "${item.id}" repeats blocker "${blocker}"`);
+        throw new Error(`${label} "${item.id}" repeats blocker "${blocker}"`);
       }
       blockers.add(blocker);
       blocks.get(blocker)?.push(item.id);
@@ -6065,12 +6194,112 @@ function validatePlan(state) {
     }
     visiting.add(id);
     stack.push(id);
-    for (const blocker of tasks.get(id)?.blockedBy ?? []) visit(blocker);
+    for (const blocker of byId.get(id)?.blockedBy ?? []) visit(blocker);
     stack.pop();
     visiting.delete(id);
     visited.add(id);
   };
-  for (const { id } of state.tasks) visit(id);
+  for (const { id } of items) visit(id);
+  return { byId, blocks };
+}
+function lineItems(items) {
+  return items.length > 0 ? items.map((item) => `- ${item}`) : ["- none"];
+}
+function latestEvidence(items) {
+  const latest = items.at(-1);
+  return latest ? ` Evidence: ${latest.summary} (${latest.source})` : "";
+}
+function errorMessage(error) {
+  const message2 = error instanceof Error ? error.message : String(error);
+  return message2.length > 500 ? `${message2.slice(0, 497)}...` : message2;
+}
+function parsePlanJson(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    const message2 = error instanceof Error ? error.message : String(error);
+    throw new Error(`invalid JSON: ${message2}`, { cause: error });
+  }
+}
+function createPlanReview(options, formatPlanReview, reviewReminder) {
+  return reminder(
+    async ({ sandbox }) => {
+      let raw;
+      try {
+        raw = await sandbox.sandbox.readFile(PLAN_FILE_PATH);
+      } catch (error) {
+        return [
+          `The plan file at ${PLAN_FILE_PATH} could not be read: ${errorMessage(error)}`,
+          "Create or repair it before taking another action.",
+          "",
+          reviewReminder
+        ].join("\n");
+      }
+      try {
+        return formatPlanReview(parsePlanJson(raw));
+      } catch (error) {
+        return [
+          `The plan file at ${PLAN_FILE_PATH} is invalid: ${errorMessage(error)}`,
+          "Repair the plan before taking another action.",
+          "",
+          reviewReminder
+        ].join("\n");
+      }
+    },
+    { when: options.when, target: "steer" }
+  );
+}
+
+// packages/context/src/lib/fragments/plan.ts
+var EXECUTION_PLAN_INSTRUCTIONS = dedent2`
+  Use an execution plan with this shape:
+  - revision: a positive integer, incremented whenever the objective, criteria, constraints, assumptions, tasks, or dependencies change; recording lastReview alone does not increment it;
+  - objective: { text, basis, source };
+  - successCriteria: [{ id, text, basis, source, evidence: [{ summary, source }] }];
+  - constraints and assumptions: [{ text, basis, source }];
+  - tasks: [{ id, title, status, blockedBy, evidence }], where status is pending, in_progress, or completed;
+  - lastReview, when present: { revision, decision, summary }.
+
+  Use basis values explicit_requirement, discovered_constraint, inference, or assumption. Store only blockedBy dependency edges. Never store blocks, readiness, or a blocked task status; those are derived when the plan is read. A task may be in_progress only when every blocker is completed, and a completed task must include concrete evidence.
+
+  Revise the plan when new evidence invalidates its objective, criteria, constraints, assumptions, sequencing, or dependencies. Before recording a complete decision or claiming completion, map every success criterion to concrete evidence. Completed task statuses alone do not prove completion.
+`;
+var EXECUTION_REVIEW_REMINDER = [
+  "Re-read the current plan and consider the evidence gathered since the previous review.",
+  "",
+  "Is the current plan still valid given the latest evidence?",
+  "",
+  "If yes, continue. If not, revise it before taking another action.",
+  "Before claiming completion, verify the success criteria against evidence."
+].join("\n");
+var statement = z4.strictObject({
+  text: nonEmptyString,
+  basis: statementBasis,
+  source: nonEmptyString
+});
+var successCriterion = statement.extend({
+  id: nonEmptyString,
+  evidence: z4.array(evidence)
+});
+var task = z4.strictObject({
+  id: nonEmptyString,
+  title: nonEmptyString,
+  status: z4.enum(["pending", "in_progress", "completed"]),
+  blockedBy: z4.array(nonEmptyString),
+  evidence: z4.array(evidence)
+});
+var executionPlanState = z4.strictObject({
+  revision: z4.number().int().positive(),
+  objective: statement,
+  successCriteria: z4.array(successCriterion).min(1),
+  constraints: z4.array(statement),
+  assumptions: z4.array(statement),
+  tasks: z4.array(task),
+  lastReview: lastReview.optional()
+});
+function validateExecutionPlan(state) {
+  uniqueIds(state.successCriteria, "success criterion");
+  const { byId: tasks, blocks } = validateDependencies(state.tasks, "task");
   for (const item of state.tasks) {
     const incompleteBlockers = item.blockedBy.filter(
       (id) => tasks.get(id)?.status !== "completed"
@@ -6096,37 +6325,19 @@ function validatePlan(state) {
   }
   return blocks;
 }
-function parsePlan(raw) {
-  let parsed;
-  try {
-    parsed = JSON.parse(raw);
-  } catch (error) {
-    const message2 = error instanceof Error ? error.message : String(error);
-    throw new Error(`invalid JSON: ${message2}`, { cause: error });
-  }
-  const result = planState.safeParse(parsed);
-  if (!result.success) {
-    const issues = result.error.issues.slice(0, 5).map(({ path: path3, message: message2 }) => `${path3.join(".") || "plan"}: ${message2}`);
-    const remaining = result.error.issues.length - issues.length;
-    throw new Error(
-      `schema errors: ${issues.join("; ")}${remaining > 0 ? `; ${remaining} more` : ""}`
-    );
-  }
-  return { state: result.data, blocks: validatePlan(result.data) };
-}
-function lineItems(items) {
-  return items.length > 0 ? items.map((item) => `- ${item}`) : ["- none"];
-}
-function latestEvidence(items) {
-  const latest = items.at(-1);
-  return latest ? ` Evidence: ${latest.summary} (${latest.source})` : "";
+function parseExecutionPlan(value) {
+  const state = parsePlanSchema(executionPlanState, value);
+  return { state, blocks: validateExecutionPlan(state) };
 }
 function formatTask(item, blocks) {
   const blocked = blocks.get(item.id) ?? [];
   const suffix = blocked.length > 0 ? `; blocks ${blocked.join(", ")}` : "";
   return `${item.id}: ${item.title}${suffix}${latestEvidence(item.evidence)}`;
 }
-function formatPlanReview(state, blocks) {
+function formatExecutionPlanReview({
+  state,
+  blocks
+}) {
   const tasks = new Map(state.tasks.map((item) => [item.id, item]));
   const active = state.tasks.filter(({ status }) => status === "in_progress");
   const ready = state.tasks.filter(
@@ -6181,45 +6392,23 @@ function formatPlanReview(state, blocks) {
       `Last review: ${state.lastReview.decision} at revision ${state.lastReview.revision} \u2014 ${state.lastReview.summary}`
     ] : [],
     "",
-    REVIEW_REMINDER
+    EXECUTION_REVIEW_REMINDER
   ].join("\n");
 }
-function errorMessage(error) {
-  const message2 = error instanceof Error ? error.message : String(error);
-  return message2.length > 500 ? `${message2.slice(0, 497)}...` : message2;
-}
-async function resolvePlanReview(sandbox) {
-  let raw;
-  try {
-    raw = await sandbox.sandbox.readFile(PLAN_FILE_PATH);
-  } catch (error) {
-    return [
-      `The plan file at ${PLAN_FILE_PATH} could not be read: ${errorMessage(error)}`,
-      "Create or repair it before taking another action.",
-      "",
-      REVIEW_REMINDER
-    ].join("\n");
-  }
-  try {
-    const { state, blocks } = parsePlan(raw);
-    return formatPlanReview(state, blocks);
-  } catch (error) {
-    return [
-      `The plan file at ${PLAN_FILE_PATH} is invalid: ${errorMessage(error)}`,
-      "Repair the plan before taking another action.",
-      "",
-      REVIEW_REMINDER
-    ].join("\n");
-  }
-}
 function instructions() {
-  return fragment("plan_instructions", PLAN_INSTRUCTIONS);
+  return fragment(
+    "plan_instructions",
+    PLAN_FOUNDATION_INSTRUCTIONS,
+    EXECUTION_PLAN_INSTRUCTIONS,
+    PLAN_REVIEW_INSTRUCTIONS
+  );
 }
 function review(options) {
-  return reminder(({ sandbox }) => resolvePlanReview(sandbox), {
-    when: options.when,
-    target: "steer"
-  });
+  return createPlanReview(
+    options,
+    (value) => formatExecutionPlanReview(parseExecutionPlan(value)),
+    EXECUTION_REVIEW_REMINDER
+  );
 }
 var plan = { path: PLAN_FILE_PATH, instructions, review };
 
@@ -6347,67 +6536,304 @@ function selfCritique(checks = DEFAULT_SELF_CRITIQUE_CHECKS) {
   });
 }
 
+// packages/context/src/lib/fragments/socratic-inquiry.ts
+var SOCRATIC_ROLE = "You are a deep, methodical thinker. For substantive work, build understanding through explicit questions and evidence before executing. Scale the inquiry to the task instead of manufacturing ceremony.";
+function socraticInquiry() {
+  return fragment(
+    "socratic_inquiry",
+    hint(
+      "Use Socratic inquiry when uncertainty, tradeoffs, or quality judgment matter. Skip Socratic inquiry for mechanical tasks with one obvious path, or when the user explicitly says to proceed directly, unless another active contract explicitly requires it."
+    ),
+    principle({
+      title: "Interrogate the domain",
+      description: "Surface the principles that separate excellent work from merely plausible output before choosing an approach.",
+      policies: [
+        "Ask what the user or audience actually needs from the result.",
+        "Ask which frameworks, mental models, and quality criteria govern this domain.",
+        "Ask which common failure modes would produce convincing but wrong results.",
+        "Explore the logical, practical, user-specific, and risk dimensions that materially affect the outcome."
+      ]
+    }),
+    principle({
+      title: "Apply to the specific case",
+      description: "Translate the domain principles into questions about the actual request, source, runtime, and constraints.",
+      policies: [
+        "Ask which evidence in this case changes which general principles matter most.",
+        "Ask which assumptions remain unresolved and what observation could answer them.",
+        "Ask what an expert would inspect, test, or rule out before committing to an answer."
+      ]
+    }),
+    principle({
+      title: "Bridge and execute",
+      description: "Synthesize the answers into the concrete action before producing the result.",
+      policies: [
+        'State "Applying to this task:" and connect the inquiry answers to the chosen action.',
+        "Execute from that synthesis rather than reverting to a generic answer or checklist.",
+        "Verify the result against the criteria discovered during inquiry."
+      ]
+    }),
+    principle({
+      title: "Adaptive and evolving inquiry",
+      description: "Match inquiry depth to task complexity and let evidence determine follow-up questions.",
+      policies: [
+        "Use about 2 focused questions for light work, 3-4 for medium work, and 5-7 for heavy work.",
+        "Do not precompute every follow-up question; answers should create, revise, or eliminate later questions.",
+        "Retain questions and answers that explain consequential decisions."
+      ]
+    }),
+    workflow({
+      task: "Socratic reasoning process",
+      steps: [
+        "Interrogate the domain and answer the foundational questions.",
+        "Apply those answers to the specific request and available evidence.",
+        "Add or revise follow-up questions based on what the answers changed.",
+        'Bridge the answers into the concrete action with "Applying to this task:".',
+        "Execute and verify the result against the discovered criteria."
+      ]
+    })
+  );
+}
+
 // packages/context/src/lib/fragments/socratic.ts
 function socraticPrompting() {
-  return [
-    role(
-      "You are a deep, methodical thinker. Before producing any output, you reason through the problem by asking and answering foundational questions. You never treat a request as a simple task to complete \u2014 you first build understanding through inquiry, then apply that understanding to produce high-quality output."
-    ),
-    fragment(
-      "socratic_prompting",
-      hint(
-        "When given a task, do not jump straight to producing output. Instead, decompose the task into foundational questions that, once answered, will make the output significantly better. Answer those questions first, then synthesize your answers into the final output."
-      ),
-      principle({
-        title: "Question-first decomposition",
-        description: 'Every task hides assumptions about what "good" looks like. Surface those assumptions by asking what makes the output effective before attempting to produce it.',
-        policies: [
-          'Ask "What makes X effective/compelling/useful?" before producing X.',
-          "Identify the criteria, frameworks, or principles that govern quality for this type of output.",
-          "Do not skip this step even when the task seems straightforward \u2014 obvious tasks often have non-obvious quality dimensions."
-        ]
-      }),
-      principle({
-        title: "Multi-dimensional inquiry",
-        description: "Explore the problem from multiple angles \u2014 emotional, logical, practical, audience-specific \u2014 through targeted questions.",
-        policies: [
-          "Ask about the audience: Who is this for? What do they care about?",
-          "Ask about constraints: What must this include or avoid?",
-          "Ask about effectiveness: What separates great output from mediocre output in this domain?",
-          "Ask about structure: How should this be organized for maximum impact?"
-        ]
-      }),
-      principle({
-        title: "Framework discovery before application",
-        description: "Build or recall a relevant framework by reasoning through questions, then explicitly apply that framework to the specific task.",
-        policies: [
-          "First derive the framework: What principles govern this type of work?",
-          'Then apply it: "Now, using these principles, produce the specific output."',
-          "The framework should emerge from your reasoning, not from a template."
-        ]
-      }),
-      workflow({
-        task: "Socratic reasoning process",
-        steps: [
-          "Identify the core task and desired output type.",
-          "Formulate 2-5 foundational questions about what makes this output effective.",
-          "Answer each question, drawing on relevant knowledge and frameworks.",
-          "Synthesize answers into a coherent set of principles or criteria.",
-          "Apply the discovered framework to produce the specific output.",
-          "Verify the output satisfies the criteria you identified."
-        ]
-      }),
-      example({
-        question: "How should I prompt for a value proposition for my AI analytics tool?",
-        answer: "What makes a value proposition compelling to B2B buyers? What emotional and logical triggers should it hit? Now apply that framework to an AI analytics tool that helps teams make faster data-driven decisions."
-      }),
-      example({
-        question: "How should I prompt for a 30-day LinkedIn content calendar for B2B SaaS?",
-        answer: "What types of LinkedIn content generate the most engagement in B2B SaaS? What posting frequency avoids audience fatigue? How should topics build on each other? Now design a 30-day calendar using these principles."
-      })
-    )
-  ];
+  return [role(SOCRATIC_ROLE), socraticInquiry()];
+}
+
+// packages/context/src/lib/fragments/socratic-plan.ts
+import dedent3 from "dedent";
+import z5 from "zod";
+var SOCRATIC_PLAN_INSTRUCTIONS = dedent3`
+  Use a Socratic plan as an evolving question-and-answer inquiry, not an execution task list whose titles merely end in question marks. It has this shape:
+  The only top-level keys are revision, objective, successCriteria, constraints, assumptions, inquiries, and lastReview.
+  - revision: a positive integer, incremented whenever a question, answer, dependency, or review-driven conclusion changes; recording lastReview alone does not increment it;
+  - objective: one question entry;
+  - successCriteria: question entries with an id;
+  - constraints: question entries;
+  - assumptions: question entries;
+  - inquiries: question entries with id, phase, status, and blockedBy;
+  - lastReview: null before the first review, then { revision, decision, summary, nextQuestionId }.
+
+  A question entry is { question, basis, source, answer }. Its answer is null until answered, then { text, basis, source, evidence: [{ summary, source }] }. Use basis values explicit_requirement, discovered_constraint, inference, or assumption for every basis field. Every question must end with a question mark and include an answer field. Never store an answer as a bare string. Use phase values domain, case, or bridge. Use inquiry status values open, answering, or answered. Store only blockedBy dependencies; readiness and reverse edges are derived. An inquiry may be answering only after every blocker is answered. An answered inquiry must have an evidence-backed answer. An open inquiry must have answer: null. nextQuestionId records the inquiry selected by that review; use null when the review selects none.
+
+  After reading any required skill or workspace instructions, write the initial inquiry before substantive investigation. Begin with the governing objective question and verification questions. Create an initial inquiry proportional to complexity: about 2 questions for light work, 3-4 for medium work, and 5-7 for heavy work. Do not precompute every follow-up question. After each answer, ask what it changed, then add, revise, or remove later questions. Preserve consequential questions and answers as the decision log.
+
+  Domain questions discover governing principles, relevant frameworks, and common failure modes. Case questions apply them to the actual source, runtime, constraints, and evidence. A bridge answer must begin with "Applying to this task:" and state the concrete action implied by the earlier answers. Execute from that bridge, then answer the success questions with verification evidence.
+
+  Before recording a complete decision, every objective, success, constraint, assumption, and inquiry question must have an evidence-backed answer. Completion means the answers collectively establish the requested outcome; the presence of answered questions alone does not prove completion. Do not return a final answer until lastReview records a complete decision at the current revision with nextQuestionId: null.
+`;
+var SOCRATIC_REVIEW_REMINDER = [
+  "Re-read the current Socratic plan and the evidence gathered since the previous review.",
+  "",
+  "What did the latest evidence answer?",
+  "Does that answer invalidate another answer, assumption, dependency, or question?",
+  "Which unanswered question would reduce the most consequential uncertainty next?",
+  "",
+  "Record the review and its nextQuestionId, then revise the inquiry before continuing when needed.",
+  "Before claiming completion, verify that every required question has an evidence-backed answer and that the answers establish the requested outcome."
+].join("\n");
+var questionText = nonEmptyString.refine((text) => text.endsWith("?"), {
+  message: "must end with a question mark"
+});
+var answer = z5.strictObject({
+  text: nonEmptyString,
+  basis: statementBasis,
+  source: nonEmptyString,
+  evidence: z5.array(evidence).min(1)
+});
+var question = z5.strictObject({
+  question: questionText,
+  basis: statementBasis,
+  source: nonEmptyString,
+  answer: answer.nullable()
+});
+var successQuestion = question.extend({ id: nonEmptyString });
+var inquiry = question.extend({
+  id: nonEmptyString,
+  phase: z5.enum(["domain", "case", "bridge"]),
+  status: z5.enum(["open", "answering", "answered"]),
+  blockedBy: z5.array(nonEmptyString)
+});
+var socraticLastReview = lastReview.extend({
+  nextQuestionId: nonEmptyString.nullable()
+});
+var socraticPlanState = z5.strictObject({
+  revision: z5.number().int().positive(),
+  objective: question,
+  successCriteria: z5.array(successQuestion).min(1),
+  constraints: z5.array(question),
+  assumptions: z5.array(question),
+  inquiries: z5.array(inquiry).min(1),
+  lastReview: socraticLastReview.nullable().optional()
+});
+function validateSocraticPlan(state) {
+  uniqueIds(state.successCriteria, "success question");
+  const { byId: inquiries, blocks } = validateDependencies(
+    state.inquiries,
+    "inquiry"
+  );
+  for (const item of state.inquiries) {
+    const incompleteBlockers = item.blockedBy.filter(
+      (id) => inquiries.get(id)?.status !== "answered"
+    );
+    if (item.status !== "open" && incompleteBlockers.length > 0) {
+      throw new Error(
+        `inquiry "${item.id}" is ${item.status} while blocked by ${incompleteBlockers.join(", ")}`
+      );
+    }
+    if (item.status === "open" && item.answer) {
+      throw new Error(`open inquiry "${item.id}" already has an answer`);
+    }
+    if (item.status === "answered" && !item.answer) {
+      throw new Error(`inquiry "${item.id}" is answered without an answer`);
+    }
+    if (item.phase === "bridge" && item.answer && !item.answer.text.startsWith("Applying to this task:")) {
+      throw new Error(
+        `bridge inquiry "${item.id}" answer must start with "Applying to this task:"`
+      );
+    }
+  }
+  if (state.lastReview && state.lastReview.revision > state.revision) {
+    throw new Error(
+      `last review references future revision ${state.lastReview.revision}`
+    );
+  }
+  const nextQuestionId = state.lastReview?.nextQuestionId;
+  if (nextQuestionId) {
+    const next = inquiries.get(nextQuestionId);
+    if (!next) {
+      throw new Error(
+        `last review references missing next question "${nextQuestionId}"`
+      );
+    }
+    if (state.lastReview?.revision === state.revision) {
+      if (next.status === "answered") {
+        throw new Error(
+          `last review next question "${nextQuestionId}" is already answered`
+        );
+      }
+      const incompleteBlockers = next.blockedBy.filter(
+        (id) => inquiries.get(id)?.status !== "answered"
+      );
+      if (incompleteBlockers.length > 0) {
+        throw new Error(
+          `last review next question "${nextQuestionId}" is blocked by ${incompleteBlockers.join(", ")}`
+        );
+      }
+    }
+  }
+  if (state.lastReview?.decision === "complete") {
+    if (state.lastReview.revision !== state.revision) {
+      throw new Error(
+        "a complete Socratic review must reference the current revision"
+      );
+    }
+    const unansweredStatements = [
+      state.objective,
+      ...state.successCriteria,
+      ...state.constraints,
+      ...state.assumptions
+    ].some(({ answer: answer2 }) => answer2 === null);
+    if (unansweredStatements || state.inquiries.some(({ status }) => status !== "answered")) {
+      throw new Error(
+        "a complete Socratic review requires an answer for every required question"
+      );
+    }
+    if (state.lastReview.nextQuestionId !== null) {
+      throw new Error("a complete Socratic review cannot name a next question");
+    }
+  }
+  return blocks;
+}
+function parseSocraticPlan(value) {
+  const state = parsePlanSchema(socraticPlanState, value);
+  return { state, blocks: validateSocraticPlan(state) };
+}
+function formatAnswer(answer2) {
+  return answer2 ? `Answer: ${answer2.text} [${answer2.basis}; ${answer2.source}]${latestEvidence(answer2.evidence)}` : "Answer: unanswered";
+}
+function formatQuestion(item) {
+  return `${item.question} [${item.basis}; ${item.source}]
+  ${formatAnswer(item.answer)}`;
+}
+function formatInquiry(item, blocks) {
+  const blocked = blocks.get(item.id) ?? [];
+  const suffix = blocked.length > 0 ? `; blocks ${blocked.join(", ")}` : "";
+  return `${item.id} [${item.phase}]: ${item.question} [${item.basis}; ${item.source}]${suffix}
+  ${formatAnswer(item.answer)}`;
+}
+function formatSocraticPlanReview({
+  state,
+  blocks
+}) {
+  const inquiries = new Map(state.inquiries.map((item) => [item.id, item]));
+  const active = state.inquiries.filter(({ status }) => status === "answering");
+  const ready = state.inquiries.filter(
+    ({ status, blockedBy }) => status === "open" && blockedBy.every((id) => inquiries.get(id)?.status === "answered")
+  );
+  const waiting = state.inquiries.filter(
+    ({ status, blockedBy }) => status === "open" && blockedBy.some((id) => inquiries.get(id)?.status !== "answered")
+  );
+  const answered = state.inquiries.filter(
+    ({ status }) => status === "answered"
+  );
+  return [
+    `Current Socratic plan (revision ${state.revision})`,
+    `Governing question: ${formatQuestion(state.objective)}`,
+    "",
+    "Success questions:",
+    ...lineItems(
+      state.successCriteria.map(
+        (item) => `${item.id}: ${formatQuestion(item)}`
+      )
+    ),
+    "",
+    "Constraint questions:",
+    ...lineItems(state.constraints.map(formatQuestion)),
+    "",
+    "Assumption questions:",
+    ...lineItems(state.assumptions.map(formatQuestion)),
+    "",
+    "Active inquiries:",
+    ...lineItems(active.map((item) => formatInquiry(item, blocks))),
+    "",
+    "Ready inquiries:",
+    ...lineItems(ready.map((item) => formatInquiry(item, blocks))),
+    "",
+    "Waiting inquiries:",
+    ...lineItems(
+      waiting.map(
+        (item) => `${formatInquiry(item, blocks)}; waiting for ${item.blockedBy.filter((id) => inquiries.get(id)?.status !== "answered").join(", ")}`
+      )
+    ),
+    "",
+    "Answered inquiries:",
+    ...lineItems(answered.map((item) => formatInquiry(item, blocks))),
+    ...state.lastReview ? [
+      "",
+      `Last review: ${state.lastReview.decision} at revision ${state.lastReview.revision} \u2014 ${state.lastReview.summary}`,
+      `Next question: ${state.lastReview.nextQuestionId ?? "none"}`
+    ] : [],
+    "",
+    SOCRATIC_REVIEW_REMINDER
+  ].join("\n");
+}
+function instructions2() {
+  return fragment(
+    "plan_instructions",
+    PLAN_FOUNDATION_INSTRUCTIONS,
+    socraticInquiry(),
+    SOCRATIC_PLAN_INSTRUCTIONS,
+    PLAN_REVIEW_INSTRUCTIONS
+  );
 }
+function review2(options) {
+  return createPlanReview(
+    options,
+    (value) => formatSocraticPlanReview(parseSocraticPlan(value)),
+    SOCRATIC_REVIEW_REMINDER
+  );
+}
+var socraticPlan = { path: PLAN_FILE_PATH, instructions: instructions2, review: review2 };
 
 // packages/context/src/lib/guardrails/error-recovery.guardrail.ts
 import chalk3 from "chalk";
@@ -6519,7 +6945,15 @@ function render(tag, ...fragments) {
 
 // packages/context/src/lib/sandbox/agent-os-sandbox.ts
 import { PassThrough, Readable } from "node:stream";
+
+// packages/context/src/lib/sandbox/read-file.ts
 var decoder = new TextDecoder();
+function readFileContent(bytes, options) {
+  const content = options?.encoding === "binary" ? bytes : decoder.decode(bytes);
+  return content;
+}
+
+// packages/context/src/lib/sandbox/agent-os-sandbox.ts
 var AgentOsSandboxError = class extends Error {
   constructor(message2) {
     super(message2);
@@ -6557,7 +6991,7 @@ function startKernelProcess(os, command, options) {
   const stderr = new PassThrough();
   const onStdout = (chunk) => stdout.write(chunk);
   const onStderr = (chunk) => stderr.write(chunk);
-  const { pid } = os.spawn("sh", ["-c", command], {
+  const { pid } = os.spawn("bash", ["-lc", command], {
     ...options,
     onStdout,
     onStderr
@@ -6610,6 +7044,25 @@ async function createAgentOsSandbox(options = {}) {
     const err = error instanceof Error ? error : new Error(String(error));
     throw new AgentOsCreationError(err.message, err);
   }
+  try {
+    const probe = startKernelProcess(os, ":", {});
+    const [, stderr, exitCode] = await Promise.all([
+      readAll(probe.stdout),
+      readAll(probe.stderr),
+      probe.exit
+    ]);
+    if (exitCode !== 0) {
+      throw new Error(stderr.trim() || `exit code ${exitCode}`);
+    }
+  } catch (error) {
+    await os.dispose().catch(() => {
+    });
+    const err = error instanceof Error ? error : new Error(String(error));
+    throw new AgentOsCreationError(
+      `Bash is required to execute sandbox commands but could not be started: ${err.message}`,
+      err
+    );
+  }
   const sandbox = {
     async executeCommand(command, { signal } = {}) {
       if (signal?.aborted) {
@@ -6657,16 +7110,19 @@ async function createAgentOsSandbox(options = {}) {
         exit
       };
     },
-    async readFile(path3) {
+    async readFile(path6, options2) {
       try {
-        const bytes = await os.readFile(path3);
-        return decoder.decode(bytes);
+        const bytes = await os.readFile(path6);
+        return readFileContent(bytes, options2);
       } catch (error) {
         throw new Error(
-          `Failed to read file "${path3}": ${error instanceof Error ? error.message : String(error)}`
+          `Failed to read file "${path6}": ${error instanceof Error ? error.message : String(error)}`
         );
       }
     },
+    async exists(path6) {
+      return os.exists(path6);
+    },
     async writeFiles(files) {
       const results = await os.writeFiles(
         files.map((f) => ({
@@ -6853,9 +7309,9 @@ function toSandboxProcess(child, abortSignal) {
   };
 }
 var BASE64_WRITE_CHUNK = 32768;
-function base64WriteCommands(path3, content) {
+function base64WriteCommands(path6, content) {
   const base64 = Buffer.from(content).toString("base64");
-  const quotedPath = shellQuote(path3);
+  const quotedPath = shellQuote(path6);
   const commands = [];
   for (let offset = 0; offset < base64.length; offset += BASE64_WRITE_CHUNK) {
     const chunk = base64.slice(offset, offset + BASE64_WRITE_CHUNK);
@@ -6869,8 +7325,11 @@ function base64WriteCommands(path3, content) {
   }
   return commands;
 }
-function base64ReadCommand(path3) {
-  return `base64 ${shellQuote(path3)}`;
+function base64ReadCommand(path6) {
+  return `base64 ${shellQuote(path6)}`;
+}
+function existsCommand(path6) {
+  return `test -e ${shellQuote(path6)} && printf true || printf false`;
 }
 
 // packages/context/src/lib/sandbox/installers/installer.ts
@@ -7143,6 +7602,7 @@ var ContainerSandboxStrategy = class {
         await this.engine.ensureWorkdir(this.context.containerId, this.workdir);
         await this.configure();
       }
+      await this.assertBashAvailable();
     } catch (error) {
       if (acquired && !acquired.attached) {
         await this.stopContainer(acquired.containerId);
@@ -7375,7 +7835,7 @@ var ContainerSandboxStrategy = class {
     const volumes = [...this.createdVolumes].reverse();
     for (const volume of volumes) {
       try {
-        await spawn2(this.engine.cli, ["volume", "rm", volume]);
+        await this.engine.removeVolume(volume);
         this.createdVolumes.delete(volume);
       } catch (error) {
         const reason = this.engineErrorMessage(error);
@@ -7441,6 +7901,15 @@ var ContainerSandboxStrategy = class {
       };
     }
   }
+  async assertBashAvailable() {
+    const result = await this.exec(":");
+    if (result.exitCode === 0) return;
+    const detail = result.stderr.trim() || result.stdout.trim();
+    throw this.engine.errors.generic(
+      `Bash is required to execute sandbox commands but could not be started${detail ? `: ${detail}` : "."}`,
+      this.context.containerId
+    );
+  }
   spawnProcess(command, options) {
     const child = childSpawn(
       this.engine.cli,
@@ -7453,12 +7922,18 @@ var ContainerSandboxStrategy = class {
     const sandbox = {
       executeCommand: async (command, options) => this.exec(command, options),
       spawn: (command, options) => this.spawnProcess(command, options),
-      readFile: async (path3) => {
-        const result = await sandbox.executeCommand(base64ReadCommand(path3));
+      readFile: async (path6, options) => {
+        const result = await sandbox.executeCommand(base64ReadCommand(path6));
         if (result.exitCode !== 0) {
-          throw new Error(`Failed to read file "${path3}": ${result.stderr}`);
+          throw new Error(`Failed to read file "${path6}": ${result.stderr}`);
         }
-        return Buffer.from(result.stdout, "base64").toString("utf-8");
+        return readFileContent(Buffer.from(result.stdout, "base64"), options);
+      },
+      exists: async (path6) => {
+        const result = await sandbox.executeCommand(existsCommand(path6));
+        if (result.stdout === "true") return true;
+        if (result.stdout === "false") return false;
+        throw new Error(`Failed to check "${path6}": ${result.stderr}`);
       },
       writeFiles: async (files) => {
         for (const file of files) {
@@ -7632,7 +8107,7 @@ var appleEngine = {
         flags.push("--env", `${key}=${value}`);
       }
     }
-    return ["exec", ...flags, containerId, "sh", "-c", command];
+    return ["exec", ...flags, containerId, "bash", "-lc", command];
   },
   inspectArgs(containerId) {
     return ["inspect", containerId];
@@ -7645,6 +8120,9 @@ var appleEngine = {
   volumeCreateArgs(volume) {
     return ["volume", "create", volume.name];
   },
+  async removeVolume(name) {
+    await spawn3(CLI, ["volume", "rm", name]);
+  },
   errorMessage: getCliErrorMessage,
   isServiceDown(message2) {
     return /apiserver|not running|connection refused|could not connect|xpc/i.test(
@@ -7661,9 +8139,15 @@ var appleEngine = {
     return /already exists/i.test(message2);
   },
   async ensureWorkdir(containerId, workdir) {
-    await spawn3(CLI, ["exec", containerId, "sh", "-c", `mkdir -p ${workdir}`]);
+    await spawn3(CLI, [
+      "exec",
+      containerId,
+      "bash",
+      "-lc",
+      `mkdir -p ${shellQuote(workdir)}`
+    ]);
   },
-  defaultImage: "docker.io/library/alpine:latest",
+  defaultImage: "docker.io/library/bash:5.3-alpine3.24",
   createInstallerContext: createAppleInstallerContext,
   async imageExists(tag) {
     try {
@@ -7850,13 +8334,200 @@ var BashException = class extends Error {
 };
 
 // packages/context/src/lib/sandbox/bash-tool.ts
-import { tool as tool2 } from "ai";
+import { tool as tool3 } from "ai";
 import fg from "fast-glob";
 import { BashTransformPipeline, TeePlugin } from "just-bash";
 import { readFile } from "node:fs/promises";
-import * as path from "node:path";
-import z4 from "zod";
+import * as path4 from "node:path";
+import z7 from "zod";
 import { withHostOnlyToolMetadata as withHostOnlyToolMetadata2 } from "@deepagents/agent";
+
+// packages/context/src/lib/sandbox/read-file-tool/index.ts
+import { tool as tool2 } from "ai";
+import path3 from "node:path";
+import z6 from "zod";
+
+// packages/context/src/lib/sandbox/read-file-tool/binary.ts
+import { detectMediaType } from "@ai-sdk/provider-utils";
+import path from "node:path";
+var SNIFF_BYTES = 8 * 1024;
+var NUL = 0;
+var mediaKinds = /* @__PURE__ */ new Set(["image", "video", "audio"]);
+var binaryFileFormat = {
+  read({ bytes, path: filePath, options }) {
+    options.abortSignal?.throwIfAborted();
+    const mediaType = detectMediaType({ data: bytes });
+    const kind = mediaType?.split("/")[0];
+    const binary = kind !== void 0 && mediaKinds.has(kind) || bytes.subarray(0, SNIFF_BYTES).includes(NUL);
+    if (!binary) return void 0;
+    return {
+      type: "error-text",
+      value: `${path.posix.basename(filePath)} is a binary ${mediaType ?? "file"} that readFile cannot display. Convert it in the sandbox first and read the result: HEIC stills with \`heif-dec in.heic out.jpg\`, video frames with \`ffmpeg -i in.mov -frames:v 1 frame.jpg\`, audio through a transcript or metadata tool. UTF-16 text counts as binary too; re-encode it as UTF-8.`
+    };
+  }
+};
+
+// packages/context/src/lib/sandbox/read-file-tool/format.ts
+import path2 from "node:path";
+function formatBytes(bytes) {
+  return `${(bytes / 1024 / 1024).toFixed(2)} MB`;
+}
+function attachment(input, {
+  label,
+  maxBytes,
+  mediaType
+}) {
+  input.options.abortSignal?.throwIfAborted();
+  if (input.bytes.byteLength > maxBytes) {
+    return {
+      type: "error-text",
+      value: `${label} exceeds ${formatBytes(maxBytes)} limit (got ${formatBytes(input.bytes.byteLength)})`
+    };
+  }
+  return {
+    type: "content",
+    value: [
+      {
+        type: "file",
+        data: {
+          type: "data",
+          data: Buffer.from(input.bytes).toString("base64")
+        },
+        mediaType,
+        filename: path2.posix.basename(input.path)
+      }
+    ]
+  };
+}
+
+// packages/context/src/lib/sandbox/read-file-tool/image.ts
+import { detectMediaType as detectMediaType2 } from "@ai-sdk/provider-utils";
+var IMAGE_MAX_BYTES = 5 * 1024 * 1024;
+var supportedImageMediaTypes = /* @__PURE__ */ new Set([
+  "image/png",
+  "image/jpeg",
+  "image/gif",
+  "image/webp"
+]);
+var imageFileFormat = {
+  read(input) {
+    const mediaType = detectMediaType2({
+      data: input.bytes,
+      topLevelType: "image"
+    });
+    return mediaType && supportedImageMediaTypes.has(mediaType) ? attachment(input, {
+      label: "Image",
+      maxBytes: IMAGE_MAX_BYTES,
+      mediaType
+    }) : void 0;
+  }
+};
+
+// packages/context/src/lib/sandbox/read-file-tool/ooxml.ts
+import { extname } from "node:path";
+var OFFICE_MAX_BYTES = 50 * 1024 * 1024;
+var mediaTypeByExtension = {
+  ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+  ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+};
+function hasZipSignature(bytes) {
+  return bytes[0] === 80 && bytes[1] === 75 && bytes[2] === 3 && bytes[3] === 4;
+}
+var ooxmlFileFormat = {
+  read(input) {
+    if (!hasZipSignature(input.bytes)) return void 0;
+    const mediaType = mediaTypeByExtension[extname(input.path).toLowerCase()];
+    return mediaType ? attachment(input, {
+      label: "Office file",
+      maxBytes: OFFICE_MAX_BYTES,
+      mediaType
+    }) : void 0;
+  }
+};
+
+// packages/context/src/lib/sandbox/read-file-tool/pdf.ts
+import { detectMediaType as detectMediaType3 } from "@ai-sdk/provider-utils";
+var PDF_MAX_BYTES = 32 * 1024 * 1024;
+var pdfFileFormat = {
+  read(input) {
+    return detectMediaType3({
+      data: input.bytes,
+      topLevelType: "application"
+    }) === "application/pdf" ? attachment(input, {
+      label: "PDF",
+      maxBytes: PDF_MAX_BYTES,
+      mediaType: "application/pdf"
+    }) : void 0;
+  }
+};
+
+// packages/context/src/lib/sandbox/read-file-tool/text.ts
+var TEXT_MAX_BYTES = 10 * 1024 * 1024;
+var textFileFormat = {
+  read({ bytes, limit, offset, options }) {
+    options.abortSignal?.throwIfAborted();
+    if (offset === void 0 && limit === void 0 && bytes.byteLength > TEXT_MAX_BYTES) {
+      return {
+        type: "error-text",
+        value: `Text file exceeds ${formatBytes(TEXT_MAX_BYTES)} limit (got ${formatBytes(bytes.byteLength)}). Use offset/limit to slice.`
+      };
+    }
+    const content = readFileContent(bytes, { encoding: "utf-8" });
+    if (offset === void 0 && limit === void 0) {
+      return { type: "text", value: content };
+    }
+    const start = (offset ?? 1) - 1;
+    const end = limit === void 0 ? void 0 : start + limit;
+    return {
+      type: "text",
+      value: content.split(/\r\n|\n|\r/u).slice(start, end).join("\n")
+    };
+  }
+};
+
+// packages/context/src/lib/sandbox/read-file-tool/index.ts
+var formats = [
+  imageFileFormat,
+  pdfFileFormat,
+  ooxmlFileFormat,
+  binaryFileFormat,
+  textFileFormat
+];
+var inputSchema = z6.strictObject({
+  path: z6.string().min(1).describe("The path to the file to read"),
+  offset: z6.number().int().min(1).optional().describe("1-based line number to start at for text files"),
+  limit: z6.number().int().min(1).optional().describe("Number of text lines to return from offset")
+});
+function createReadFileTool({
+  sandbox,
+  destination
+}) {
+  return tool2({
+    description: "Read a sandbox file. Supports text, PNG, JPEG, GIF, WebP, PDF, XLSX, DOCX, and PPTX; other binary files such as HEIC, video, and audio are refused with conversion guidance. Use offset/limit with large text files.",
+    inputExamples: [
+      { input: { path: "README.md" } },
+      { input: { path: "logs/trace.jsonl", offset: 1, limit: 200 } }
+    ],
+    inputSchema,
+    execute: async (input, options) => {
+      options.abortSignal?.throwIfAborted();
+      const bytes = await sandbox.readFile(
+        path3.posix.resolve(destination, input.path),
+        { encoding: "binary" }
+      );
+      options.abortSignal?.throwIfAborted();
+      for (const format of formats) {
+        const result = format.read({ ...input, bytes, options });
+        if (result !== void 0) return result;
+      }
+      throw new Error(`No file format accepted ${input.path}`);
+    },
+    toModelOutput: ({ output }) => output
+  });
+}
+
+// packages/context/src/lib/sandbox/bash-tool.ts
 var DEFAULT_DESTINATION = "/workspace";
 var DEFAULT_MAX_FILES = 1e3;
 var DEFAULT_MAX_OUTPUT_LENGTH = 3e4;
@@ -7948,8 +8619,9 @@ function withBashExceptionCatch(sandbox) {
         throw error;
       }
     },
-    readFile: (filePath) => sandbox.readFile(filePath),
+    readFile: (filePath, options) => sandbox.readFile(filePath, options),
     writeFiles: (files) => sandbox.writeFiles(files),
+    exists: (filePath) => sandbox.exists(filePath),
     dispose: () => sandbox.dispose(),
     [Symbol.asyncDispose]() {
       return decorated.dispose();
@@ -7979,7 +8651,7 @@ async function listInitialFiles(options) {
   const files = /* @__PURE__ */ new Map();
   if (options.uploadDirectory) {
     const { source, include = "**/*" } = options.uploadDirectory;
-    const absoluteSource = path.resolve(source);
+    const absoluteSource = path4.resolve(source);
     const uploaded = await fg(include, {
       cwd: absoluteSource,
       dot: true,
@@ -7989,7 +8661,7 @@ async function listInitialFiles(options) {
     for (const relativePath of uploaded) {
       files.set(relativePath, {
         path: relativePath,
-        sourcePath: path.join(absoluteSource, relativePath)
+        sourcePath: path4.join(absoluteSource, relativePath)
       });
     }
   }
@@ -8008,7 +8680,7 @@ async function uploadInitialFiles(sandbox, destination, files) {
   for (let index = 0; index < files.length; index += WRITE_BATCH_SIZE) {
     const batch = await Promise.all(
       files.slice(index, index + WRITE_BATCH_SIZE).map(async (file) => ({
-        path: path.posix.join(destination, file.path),
+        path: path4.posix.join(destination, file.path),
         content: "content" in file ? file.content : await readFile(file.sourcePath)
       }))
     );
@@ -8028,12 +8700,12 @@ async function createToolPrompt(sandbox, filenames, customPrompt) {
   const lines = [
     `Available tools: ${[...available].sort().join(", ")}, and more`
   ];
-  const formats = new Set(
+  const formats2 = new Set(
     filenames.map(
-      (filename) => EXTENSION_FORMATS[path.extname(filename).toLowerCase()]
+      (filename) => EXTENSION_FORMATS[path4.extname(filename).toLowerCase()]
     ).filter((format) => format !== void 0)
   );
-  for (const format of formats) {
+  for (const format of formats2) {
     const tools = FORMAT_TOOLS[format].filter((name) => available.has(name));
     if (tools.length > 0) {
       lines.push(`For ${FORMAT_LABELS[format]}: ${tools.join(", ")}`);
@@ -8093,7 +8765,7 @@ async function createBashTool(options) {
   );
   const extraInstructions = [options.extraInstructions, REASONING_INSTRUCTION].filter(Boolean).join("\n\n");
   const experimentalTeeTransform = options.experimentalTeeTransform ?? false;
-  const bash = tool2({
+  const bash = tool3({
     description: createBashDescription({
       destination,
       filenames: initialFiles.map((file) => file.path),
@@ -8101,9 +8773,9 @@ async function createBashTool(options) {
       extraInstructions,
       experimentalTeeTransform
     }),
-    inputSchema: z4.object({
-      command: z4.string().describe("The bash command to execute"),
-      reasoning: z4.string().trim().min(1).describe("Brief reason for executing this command")
+    inputSchema: z7.object({
+      command: z7.string().describe("The bash command to execute"),
+      reasoning: z7.string().trim().min(1).describe("Brief reason for executing this command")
     }),
     execute: async ({ command: originalCommand }, executionOptions) => {
       let command = originalCommand;
@@ -8143,28 +8815,18 @@ async function createBashTool(options) {
       return Object.keys(meta).length > 0 ? { ...result, meta } : result;
     }
   });
-  const readFile2 = tool2({
-    description: "Read the contents of a file from the sandbox.",
-    inputSchema: z4.object({
-      path: z4.string().describe("The path to the file to read")
-    }),
-    execute: async ({ path: filePath }) => ({
-      content: await sandbox.readFile(
-        path.posix.resolve(destination, filePath)
-      )
-    })
-  });
-  const writeFile2 = tool2({
+  const readFile2 = createReadFileTool({ sandbox, destination });
+  const writeFile2 = tool3({
     description: "Write content to a file in the sandbox. Creates parent directories if needed.",
-    inputSchema: z4.object({
-      path: z4.string().describe("The path where the file should be written"),
-      content: z4.string().describe("The content to write to the file")
+    inputSchema: z7.object({
+      path: z7.string().describe("The path where the file should be written"),
+      content: z7.string().describe("The content to write to the file")
     }),
     execute: async ({ path: filePath, content }) => {
       try {
         await sandbox.writeFiles([
           {
-            path: path.posix.resolve(destination, filePath),
+            path: path4.posix.resolve(destination, filePath),
             content
           }
         ]);
@@ -8183,7 +8845,7 @@ async function createBashTool(options) {
 import { existsSync as existsSync2 } from "fs";
 import { defineCommand } from "just-bash";
 import spawn4 from "nano-spawn";
-import * as path2 from "path";
+import * as path5 from "path";
 function createBinaryBridges(...binaries) {
   return binaries.map((input) => {
     const config = typeof input === "string" ? { name: input } : input;
@@ -8205,11 +8867,11 @@ function createBinaryBridges(...binaries) {
           if (arg.startsWith("-")) {
             return arg;
           }
-          const hasExtension = path2.extname(arg) !== "";
-          const hasPathSep = arg.includes(path2.sep) || arg.includes("/");
+          const hasExtension = path5.extname(arg) !== "";
+          const hasPathSep = arg.includes(path5.sep) || arg.includes("/");
           const isRelative = arg.startsWith(".");
           if (hasExtension || hasPathSep || isRelative) {
-            return path2.resolve(realCwd, arg);
+            return path5.resolve(realCwd, arg);
           }
           return arg;
         });
@@ -8262,7 +8924,7 @@ function resolveRealCwd(ctx) {
   const fs = ctx.fs;
   let realCwd;
   if (fs.root) {
-    realCwd = path2.join(fs.root, ctx.cwd);
+    realCwd = path5.join(fs.root, ctx.cwd);
   } else if (typeof fs.getMountPoint === "function" && typeof fs.toRealPath === "function") {
     const real = fs.toRealPath(ctx.cwd);
     realCwd = real ?? process.cwd();
@@ -8313,7 +8975,9 @@ async function createDaytonaSandbox(client, options = {}) {
   } catch (error) {
     throw normalizeDaytonaError(error, sdk);
   }
+  await assertDaytonaBash(sandbox, options.commandTimeout);
   const backend = createDaytonaSandboxMethods({
+    sdk,
     sandbox,
     commandTimeout: options.commandTimeout
   });
@@ -8328,6 +8992,24 @@ async function createDaytonaSandbox(client, options = {}) {
   }
   return backend;
 }
+async function assertDaytonaBash(sandbox, commandTimeout) {
+  try {
+    const result = await sandbox.process.executeCommand(
+      "bash -lc ':'",
+      void 0,
+      void 0,
+      commandTimeout
+    );
+    if (result.exitCode === void 0 || result.exitCode === 0) return;
+    throw new Error(result.result || `exit code ${result.exitCode}`);
+  } catch (error) {
+    const err = toError(error);
+    throw new DaytonaCreationError(
+      `Bash is required to execute sandbox commands but could not be started: ${err.message}`,
+      err
+    );
+  }
+}
 var UNRECOVERABLE_SANDBOX_STATES = /* @__PURE__ */ new Set([
   "error",
   "build_failed",
@@ -8449,7 +9131,7 @@ function validateDaytonaOptions(options) {
   }
 }
 function createDaytonaSandboxMethods(args) {
-  const { sandbox, commandTimeout } = args;
+  const { sdk, sandbox, commandTimeout } = args;
   const executeCommand = async (command, options) => {
     if (options?.signal?.aborted) {
       return abortedCommandResult();
@@ -8464,7 +9146,7 @@ function createDaytonaSandboxMethods(args) {
         return abortedCommandResult();
       }
       const response = await sandbox.process.executeCommand(
-        command,
+        `bash -lc ${shellQuote(command)}`,
         void 0,
         void 0,
         commandTimeout
@@ -8495,13 +9177,25 @@ function createDaytonaSandboxMethods(args) {
         commandTimeout
       });
     },
-    async readFile(path3) {
+    async readFile(path6, options) {
       try {
-        const bytes = await sandbox.fs.downloadFile(path3);
-        return Buffer.from(bytes).toString("utf-8");
+        const bytes = await sandbox.fs.downloadFile(path6);
+        return readFileContent(bytes, options);
+      } catch (error) {
+        throw new DaytonaCommandError(
+          `Failed to read file "${path6}": ${toError(error).message}`,
+          toError(error)
+        );
+      }
+    },
+    async exists(path6) {
+      try {
+        await sandbox.fs.getFileDetails(path6);
+        return true;
       } catch (error) {
+        if (error instanceof sdk.DaytonaNotFoundError) return false;
         throw new DaytonaCommandError(
-          `Failed to read file "${path3}": ${toError(error).message}`,
+          `Failed to check "${path6}": ${toError(error).message}`,
           toError(error)
         );
       }
@@ -8706,13 +9400,13 @@ function buildSessionCommand(command, options) {
   const env = options.env ?? {};
   const entries = Object.entries(env);
   if (entries.length === 0) {
-    return `sh -lc ${shellQuote(`${cwdPrefix}${command}`)}`;
+    return `bash -lc ${shellQuote(`${cwdPrefix}${command}`)}`;
   }
   for (const [key] of entries) {
     validateEnvKey(key);
   }
   const exports = entries.map(([key, value]) => `export ${key}=${shellQuote(value)}`).join("; ");
-  return `sh -lc ${shellQuote(`${exports}; ${cwdPrefix}${command}`)}`;
+  return `bash -lc ${shellQuote(`${exports}; ${cwdPrefix}${command}`)}`;
 }
 function validateEnvKey(key) {
   if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
@@ -8740,10 +9434,10 @@ function abortedExitInfo() {
 }
 function uniqueParentDirectories(paths) {
   const dirs = /* @__PURE__ */ new Set();
-  for (const path3 of paths) {
-    const index = path3.lastIndexOf("/");
+  for (const path6 of paths) {
+    const index = path6.lastIndexOf("/");
     if (index > 0) {
-      dirs.add(path3.slice(0, index));
+      dirs.add(path6.slice(0, index));
     }
   }
   return [...dirs];
@@ -8764,8 +9458,9 @@ function toError(error) {
 // packages/context/src/lib/sandbox/docker-sandbox.ts
 import spawn5 from "nano-spawn";
 import { spawn as childSpawn3 } from "node:child_process";
-import { createHash as createHash2 } from "node:crypto";
+import { createHash as createHash2, randomUUID as randomUUID2 } from "node:crypto";
 import { readFileSync as readFileSync2 } from "node:fs";
+import { setTimeout as delay2 } from "node:timers/promises";
 function isDockerfileOptions(opts) {
   return "dockerfile" in opts;
 }
@@ -8952,7 +9647,7 @@ var dockerEngine = {
         flags.push("-e", `${key}=${value}`);
       }
     }
-    return ["exec", ...flags, containerId, "sh", "-c", command];
+    return ["exec", ...flags, containerId, "bash", "-lc", command];
   },
   inspectArgs(containerId) {
     return [
@@ -8981,6 +9676,20 @@ var dockerEngine = {
     const err = error;
     return err.stderr || err.stdout || err.message || String(error);
   },
+  async removeVolume(name) {
+    const deadline = performance.now() + 3e4;
+    while (true) {
+      try {
+        await spawn5("docker", ["volume", "rm", name]);
+        return;
+      } catch (error) {
+        if (!this.errorMessage(error).includes("volume is in use") || performance.now() >= deadline) {
+          throw error;
+        }
+        await delay2(25);
+      }
+    }
+  },
   isServiceDown(message2) {
     return message2.includes("Cannot connect") || message2.includes("docker daemon");
   },
@@ -8995,7 +9704,7 @@ var dockerEngine = {
   },
   async ensureWorkdir() {
   },
-  defaultImage: "alpine:latest",
+  defaultImage: "bash:5.3-alpine3.24",
   createInstallerContext,
   async imageExists(tag) {
     try {
@@ -9050,14 +9759,190 @@ function buildDockerExecFlags(options) {
   }
   return flags;
 }
+function managedDockerCommand(command, controlPath) {
+  return [
+    "set -m",
+    `control=${shellQuote(controlPath)}`,
+    ': > "$control" || exit 1',
+    `trap 'rm -f "$control"' EXIT`,
+    `bash -lc ${shellQuote(command)} &`,
+    "pid=$!",
+    `printf '%s\\n' "$pid" > "$control"`,
+    'wait "$pid"',
+    'exit "$?"'
+  ].join("\n");
+}
+async function waitForDockerExecPid(execArgs, controlPath, localExit) {
+  const exited = localExit.then(
+    () => true,
+    () => true
+  );
+  const readPid = `if IFS= read -r pid < ${shellQuote(controlPath)}; then printf '%s' "$pid"; fi`;
+  while (true) {
+    const result = await spawn5("docker", execArgs(readPid));
+    if (result.stdout) return Number(result.stdout);
+    if (await Promise.race([exited, delay2(10).then(() => false)])) {
+      return void 0;
+    }
+  }
+}
+async function terminateDockerExec(execArgs, controlPath, localExit) {
+  const pid = await waitForDockerExecPid(execArgs, controlPath, localExit);
+  if (pid === void 0) return false;
+  const result = await spawn5(
+    "docker",
+    execArgs(
+      [
+        `pid=${pid}`,
+        `IFS= read -r control_pid < ${shellQuote(controlPath)} || exit 0`,
+        '[ "$control_pid" = "$pid" ] || exit 0',
+        'kill -KILL -- "-$pid" 2>/dev/null || exit 0',
+        "group_alive() {",
+        "  local stat rest state pgrp",
+        "  for stat_path in /proc/[0-9]*/stat; do",
+        '    IFS= read -r stat < "$stat_path" || continue',
+        "    rest=${stat##*) }",
+        '    read -r state _ pgrp _ <<< "$rest"',
+        '    if [ "$pgrp" = "$pid" ] && [ "$state" != Z ]; then return 0; fi',
+        "  done",
+        "  return 1",
+        "}",
+        "while group_alive; do sleep 0.01; done",
+        "printf terminated"
+      ].join("\n")
+    )
+  );
+  return result.stdout === "terminated";
+}
+function spawnDockerProcess(execArgs, command, options = {}, commandTimeout) {
+  if (!commandTimeout && options.signal === void 0) {
+    return toSandboxProcess(
+      childSpawn3("docker", execArgs(command, options)),
+      void 0
+    );
+  }
+  const controlPath = `/dev/shm/deepagents-exec-${randomUUID2()}.pid`;
+  const localProcess = toSandboxProcess(
+    childSpawn3(
+      "docker",
+      execArgs(managedDockerCommand(command, controlPath), options)
+    ),
+    void 0
+  );
+  let termination;
+  const terminate = (reason) => {
+    termination ??= {
+      reason,
+      confirmed: terminateDockerExec(execArgs, controlPath, localProcess.exit)
+    };
+  };
+  const onAbort = () => terminate("abort");
+  if (options.signal?.aborted) onAbort();
+  else options.signal?.addEventListener("abort", onAbort, { once: true });
+  let timeout;
+  if (commandTimeout) {
+    timeout = setTimeout(() => terminate("timeout"), commandTimeout);
+    timeout.unref();
+  }
+  return {
+    stdout: localProcess.stdout,
+    stderr: localProcess.stderr,
+    exit: localProcess.exit.then(async (info) => {
+      const activeTermination = termination;
+      if (!activeTermination || !await activeTermination.confirmed) {
+        return info;
+      }
+      return activeTermination.reason === "timeout" ? { code: 124, signal: null, success: false } : { code: null, signal: "SIGKILL", success: false };
+    }).finally(() => {
+      clearTimeout(timeout);
+      options.signal?.removeEventListener("abort", onAbort);
+    })
+  };
+}
+async function executeDockerCommand(execArgs, command, options = {}, commandTimeout) {
+  if (!commandTimeout && options.signal === void 0) {
+    try {
+      const result2 = await spawn5("docker", execArgs(command));
+      return { stdout: result2.stdout, stderr: result2.stderr, exitCode: 0 };
+    } catch (error) {
+      const err = error;
+      return {
+        stdout: err.stdout || "",
+        stderr: err.stderr || err.message || "",
+        exitCode: err.exitCode ?? 1
+      };
+    }
+  }
+  const process2 = spawnDockerProcess(
+    execArgs,
+    command,
+    { signal: options.signal },
+    commandTimeout
+  );
+  const [stdout, stderr, info] = await Promise.all([
+    new Response(process2.stdout).text(),
+    new Response(process2.stderr).text(),
+    process2.exit
+  ]);
+  const result = {
+    stdout: stdout.replace(/\r?\n$/, ""),
+    stderr: stderr.replace(/\r?\n$/, "")
+  };
+  if (info.signal === "SIGKILL") {
+    return {
+      ...result,
+      stderr: result.stderr || "Command aborted",
+      exitCode: 1
+    };
+  }
+  return { ...result, exitCode: info.code ?? 1 };
+}
+var DockerRuntimeStrategy = class extends RuntimeStrategy {
+  exec(command, options) {
+    return executeDockerCommand(
+      (value, spawnOptions) => this.engine.execArgs(this.context.containerId, value, spawnOptions),
+      command,
+      options,
+      this.opts.commandTimeout
+    );
+  }
+  spawnProcess(command, options) {
+    return spawnDockerProcess(
+      (value, spawnOptions) => this.engine.execArgs(this.context.containerId, value, spawnOptions),
+      command,
+      options,
+      this.opts.commandTimeout
+    );
+  }
+};
+var DockerContainerfileStrategy = class extends ContainerfileStrategy {
+  exec(command, options) {
+    return executeDockerCommand(
+      (value, spawnOptions) => this.engine.execArgs(this.context.containerId, value, spawnOptions),
+      command,
+      options,
+      this.opts.commandTimeout
+    );
+  }
+  spawnProcess(command, options) {
+    return spawnDockerProcess(
+      (value, spawnOptions) => this.engine.execArgs(this.context.containerId, value, spawnOptions),
+      command,
+      options,
+      this.opts.commandTimeout
+    );
+  }
+};
 var ComposeStrategy = class extends ContainerSandboxStrategy {
   projectName;
   composeFile;
   service;
+  commandTimeout;
   constructor(args) {
     super({ resources: args.resources }, dockerEngine);
     this.composeFile = args.compose;
     this.service = args.service;
+    this.commandTimeout = args.commandTimeout;
     this.projectName = this.computeProjectName();
   }
   computeProjectName() {
@@ -9093,36 +9978,23 @@ var ComposeStrategy = class extends ContainerSandboxStrategy {
   async configure() {
   }
   async exec(command, options) {
-    try {
-      const result = await spawn5(
-        "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
-      };
-    }
+    return executeDockerCommand(
+      (value, spawnOptions) => this.execArgs(value, spawnOptions),
+      command,
+      options,
+      this.commandTimeout
+    );
   }
   spawnProcess(command, options) {
-    const child = childSpawn3("docker", [
+    return spawnDockerProcess(
+      (value, spawnOptions) => this.execArgs(value, spawnOptions),
+      command,
+      options,
+      this.commandTimeout
+    );
+  }
+  execArgs(command, options) {
+    return [
       "compose",
       "-f",
       this.composeFile,
@@ -9132,11 +10004,10 @@ var ComposeStrategy = class extends ContainerSandboxStrategy {
       "-T",
       ...buildDockerExecFlags(options),
       this.service,
-      "sh",
-      "-c",
+      "bash",
+      "-lc",
       command
-    ]);
-    return toSandboxProcess(child, options?.signal);
+    ];
   }
   async stopContainer(_containerId) {
     try {
@@ -9157,18 +10028,19 @@ async function createDockerSandbox(options = {}) {
     return new ComposeStrategy({
       compose: options.compose,
       service: options.service,
-      resources: options.resources
+      resources: options.resources,
+      commandTimeout: options.commandTimeout
     }).create();
   }
   if (isDockerfileOptions(options)) {
-    return new ContainerfileStrategy(options, dockerEngine, {
+    return new DockerContainerfileStrategy(options, dockerEngine, {
       dockerfile: options.dockerfile,
       context: options.context ?? ".",
       showBuildLogs: options.showBuildLogs ?? false,
       identity: options.platform
     }).create();
   }
-  return new RuntimeStrategy(options, dockerEngine, {
+  return new DockerRuntimeStrategy(options, dockerEngine, {
     image: options.image ?? dockerEngine.defaultImage,
     installers: options.installers ?? []
   }).create();
@@ -9183,7 +10055,7 @@ async function useSandbox(options, fn) {
 }
 
 // packages/context/src/lib/sandbox/strace/file-changes.ts
-import { randomUUID as randomUUID2 } from "node:crypto";
+import { randomUUID as randomUUID3 } from "node:crypto";
 import { posix as posix3 } from "node:path";
 
 // packages/context/src/lib/sandbox/strace/index.ts
@@ -9191,10 +10063,10 @@ import spawn6 from "nano-spawn";
 import { posix as posix2 } from "node:path";
 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)}`;
+  return `mkdir -p ${shellQuote(traceDir)} 2>/dev/null; strace ${STRACE_FLAGS} -o ${shellQuote(traceFile)} -- bash -lc ${shellQuote(command)}`;
 }
 function buildTracedCommand(command, traceFile, traceDir, sentinel) {
-  return `mkdir -p ${shellQuote(traceDir)} 2>/dev/null; strace ${STRACE_FLAGS} -o ${shellQuote(traceFile)} -- sh -c ${shellQuote(command)}; __dat_rc=$?; printf '\\n%s\\n' ${shellQuote(sentinel)}; base64 ${shellQuote(traceFile)} 2>/dev/null; rm -f ${shellQuote(traceFile)} 2>/dev/null; exit $__dat_rc`;
+  return `mkdir -p ${shellQuote(traceDir)} 2>/dev/null; strace ${STRACE_FLAGS} -o ${shellQuote(traceFile)} -- bash -lc ${shellQuote(command)}; __dat_rc=$?; printf '\\n%s\\n' ${shellQuote(sentinel)}; base64 ${shellQuote(traceFile)} 2>/dev/null; rm -f ${shellQuote(traceFile)} 2>/dev/null; exit $__dat_rc`;
 }
 function splitTracedOutput(stdout, sentinel) {
   const marker = `
@@ -9305,8 +10177,8 @@ function fdPath(args) {
 function openFlags(args) {
   return args.match(/\bO_[A-Z_]+(?:\|O_[A-Z_]+)*/)?.[0] ?? "";
 }
-function matchesGlobs(path3, include, exclude) {
-  return include.some((glob) => posix2.matchesGlob(path3, glob)) && !exclude?.some((glob) => posix2.matchesGlob(path3, glob));
+function matchesGlobs(path6, include, exclude) {
+  return include.some((glob) => posix2.matchesGlob(path6, glob)) && !exclude?.some((glob) => posix2.matchesGlob(path6, glob));
 }
 function parseStraceTrace(raw, options) {
   const { include, exclude, traceDir, traceFile } = options;
@@ -9314,12 +10186,12 @@ function parseStraceTrace(raw, options) {
   const state = /* @__PURE__ */ new Map();
   const renames = [];
   const resolve3 = (dir, p) => posix2.normalize(p.startsWith("/") ? p : posix2.join(dir, p));
-  const write = (path3) => {
-    state.set(path3, "write");
+  const write = (path6) => {
+    state.set(path6, "write");
   };
-  const remove = (path3) => {
-    if (state.get(path3) === "write") state.delete(path3);
-    else state.set(path3, "delete");
+  const remove = (path6) => {
+    if (state.get(path6) === "write") state.delete(path6);
+    else state.set(path6, "delete");
   };
   for (const line of stitchLines(raw)) {
     const call = parseCall(line);
@@ -9366,13 +10238,13 @@ function parseStraceTrace(raw, options) {
       if (p) write(resolve3(dir, p));
     }
   }
-  const keep = (path3) => {
-    if (traceFile && path3 === traceFile) return false;
-    if (traceDir && (path3 === traceDir || path3.startsWith(`${traceDir}/`))) {
+  const keep = (path6) => {
+    if (traceFile && path6 === traceFile) return false;
+    if (traceDir && (path6 === traceDir || path6.startsWith(`${traceDir}/`))) {
       return false;
     }
-    if (/^\/(proc|sys|dev)(\/|$)/.test(path3)) return false;
-    return matchesGlobs(path3, include, exclude);
+    if (/^\/(proc|sys|dev)(\/|$)/.test(path6)) return false;
+    return matchesGlobs(path6, include, exclude);
   };
   const changes = [];
   const emittedRenameTargets = /* @__PURE__ */ new Set();
@@ -9383,9 +10255,9 @@ function parseStraceTrace(raw, options) {
     emittedRenameTargets.add(to);
   }
   const tail = [];
-  for (const [path3, op] of state) {
-    if (emittedRenameTargets.has(path3)) continue;
-    if (keep(path3)) tail.push({ op, path: path3, timestamp: now });
+  for (const [path6, op] of state) {
+    if (emittedRenameTargets.has(path6)) continue;
+    if (keep(path6)) tail.push({ op, path: path6, timestamp: now });
   }
   tail.sort((a, b) => {
     if (a.path < b.path) return -1;
@@ -9413,13 +10285,12 @@ async function withStraceFileChanges(sandbox, 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 removeTrace = (traceFile) => void innerExecute(`rm -f ${shellQuote(traceFile)}`).catch(() => {
   });
   const readChanges = async (traceFile) => {
     try {
-      return parseStraceTrace(await innerReadFile(traceFile), {
+      return parseStraceTrace(await sandbox.readFile(traceFile), {
         include,
         exclude,
         traceFile,
@@ -9442,8 +10313,8 @@ async function withStraceFileChanges(sandbox, options) {
   };
   const decorated = {
     async executeCommand(command, execOptions) {
-      const traceFile = `${traceDir}/${randomUUID2()}.strace`;
-      const sentinel = `__dat_trace_${randomUUID2()}__`;
+      const traceFile = `${traceDir}/${randomUUID3()}.strace`;
+      const sentinel = `__dat_trace_${randomUUID3()}__`;
       const wrapped = buildTracedCommand(
         command,
         traceFile,
@@ -9483,7 +10354,8 @@ async function withStraceFileChanges(sandbox, options) {
       }
       return result;
     },
-    readFile: innerReadFile,
+    readFile: (path6, options2) => sandbox.readFile(path6, options2),
+    exists: (path6) => sandbox.exists(path6),
     // 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
@@ -9493,7 +10365,7 @@ async function withStraceFileChanges(sandbox, options) {
     writeFiles: async (files) => {
       await innerWriteFiles(files);
       const now = Date.now();
-      const changes = files.map((f) => posix3.normalize(f.path)).filter((path3) => matchesGlobs(path3, include, exclude)).map((path3) => ({ op: "write", path: path3, timestamp: now }));
+      const changes = files.map((f) => posix3.normalize(f.path)).filter((path6) => matchesGlobs(path6, include, exclude)).map((path6) => ({ op: "write", path: path6, timestamp: now }));
       if (changes.length) await onFileChanges?.(changes);
     },
     dispose: async () => {
@@ -9508,7 +10380,7 @@ async function withStraceFileChanges(sandbox, options) {
   if (sandbox.spawn) {
     const innerSpawn = sandbox.spawn.bind(sandbox);
     decorated.spawn = (command, spawnOptions) => {
-      const traceFile = `${traceDir}/${randomUUID2()}.strace`;
+      const traceFile = `${traceDir}/${randomUUID3()}.strace`;
       const child = innerSpawn(
         buildStraceCommand(command, traceFile, traceDir),
         spawnOptions
@@ -9815,9 +10687,9 @@ function formatVersion(version) {
 }
 
 // packages/context/src/lib/sandbox/microsandbox-sandbox.ts
-import { randomUUID as randomUUID3 } from "node:crypto";
+import { randomUUID as randomUUID4 } from "node:crypto";
 var MICROSANDBOX_DEFAULT_DESTINATION = "/workspace";
-var MICROSANDBOX_DEFAULT_IMAGE = "alpine";
+var MICROSANDBOX_DEFAULT_IMAGE = "bash:5.3-alpine3.24";
 var MICROSANDBOX_MAX_NAME_BYTES = 128;
 var COMMAND_TIMEOUT_EXIT_CODE = 124;
 var MicrosandboxSandboxError = class extends Error {
@@ -9852,13 +10724,29 @@ async function createMicrosandboxSandbox(options = {}) {
   validateMicrosandboxOptions(options);
   const sdk = await importMicrosandbox();
   const ephemeral = options.name === void 0;
-  const name = options.name ?? `deepagents-msb-${randomUUID3()}`;
+  const name = options.name ?? `deepagents-msb-${randomUUID4()}`;
   const workdir = options.workdir ?? MICROSANDBOX_DEFAULT_DESTINATION;
+  const sandboxBuilder = (replace) => {
+    let builder = sdk.Sandbox.builder(name).image(MICROSANDBOX_DEFAULT_IMAGE).patch((patch) => patch.mkdir(workdir));
+    if (options.configure) builder = options.configure(builder);
+    builder = builder.workdir(workdir).ephemeral(ephemeral).shell("bash");
+    return replace ? builder.replace() : builder;
+  };
   let vm;
   try {
-    vm = await acquireSandbox(sdk, { ...options, name, ephemeral, workdir });
+    const builder = sandboxBuilder(options.replace === true);
+    vm = await (ephemeral || options.replace ? builder.create() : builder.connectOrCreate());
+  } catch (error) {
+    throw normalizeMicrosandboxError(error, sdk);
+  }
+  try {
     await vm.fs().mkdir(workdir);
+    await assertMicrosandboxBash(vm);
   } catch (error) {
+    await vm[Symbol.asyncDispose]().catch(() => {
+    });
+    if (ephemeral) await sdk.Sandbox.remove(name).catch(() => {
+    });
     throw normalizeMicrosandboxError(error, sdk);
   }
   const backend = createMicrosandboxMethods({
@@ -9866,7 +10754,8 @@ async function createMicrosandboxSandbox(options = {}) {
     vm,
     name,
     ephemeral,
-    commandTimeout: options.commandTimeout
+    commandTimeout: options.commandTimeout,
+    reconnect: ephemeral ? void 0 : () => sandboxBuilder(false).connectOrCreate()
   });
   if (options.readiness) {
     try {
@@ -9886,56 +10775,22 @@ async function importMicrosandbox() {
     throw new MicrosandboxNotAvailableError(toError2(error));
   }
 }
-async function acquireSandbox(sdk, options) {
-  if (options.ephemeral || options.replace) {
-    return buildSandbox(sdk, options);
-  }
-  let handle;
-  try {
-    handle = await sdk.Sandbox.get(options.name);
-  } catch (error) {
-    if (error instanceof sdk.SandboxNotFoundError) {
-      return createFreshSandbox(sdk, options);
-    }
-    throw error;
-  }
-  if (handle.status === "running") {
-    return handle.connect();
-  }
-  if (handle.status === "draining") {
-    await handle.waitUntilStopped();
-  }
-  try {
-    return await handle.start();
-  } catch {
-    await sdk.Sandbox.remove(options.name).catch(() => {
-    });
-    return buildSandbox(sdk, options);
-  }
-}
-async function createFreshSandbox(sdk, options) {
+async function assertMicrosandboxBash(vm) {
   try {
-    return await buildSandbox(sdk, options);
+    const result = await vm.exec("bash", ["-lc", ":"]);
+    if (result.code === 0) return;
+    throw new Error(result.stderr() || `exit code ${result.code}`);
   } catch (error) {
-    if (error instanceof sdk.SandboxAlreadyExistsError) {
-      const handle = await sdk.Sandbox.get(options.name);
-      return handle.status === "running" ? handle.connect() : handle.start();
-    }
-    throw error;
+    const err = toError2(error);
+    throw new MicrosandboxCreationError(
+      `Bash is required to execute sandbox commands but could not be started: ${err.message}`,
+      err
+    );
   }
 }
-function buildSandbox(sdk, options) {
-  let builder = sdk.Sandbox.builder(options.name).image(options.image ?? MICROSANDBOX_DEFAULT_IMAGE).patch((patch) => patch.mkdir(options.workdir)).workdir(options.workdir);
-  if (options.ephemeral) builder = builder.ephemeral(true);
-  if (options.replace) builder = builder.replace();
-  if (options.cpus !== void 0) builder = builder.cpus(options.cpus);
-  if (options.memory !== void 0) builder = builder.memory(options.memory);
-  if (options.env) builder = builder.envs(options.env);
-  if (options.configure) builder = options.configure(builder);
-  return builder.create();
-}
 function normalizeMicrosandboxError(error, sdk) {
   const err = toError2(error);
+  if (err instanceof MicrosandboxSandboxError) return err;
   if (err instanceof sdk.LibkrunfwNotFoundError) {
     return new MicrosandboxNotAvailableError(err);
   }
@@ -9957,9 +10812,25 @@ function validateMicrosandboxOptions(options) {
   }
 }
 function createMicrosandboxMethods(args) {
-  const { sdk, vm, name, ephemeral, commandTimeout } = args;
+  const { sdk, name, ephemeral, commandTimeout, reconnect } = args;
+  let vm = args.vm;
+  let reconnecting;
+  const run = async (operation) => {
+    try {
+      return await operation(vm);
+    } catch (error) {
+      if (!reconnect || !(error instanceof sdk.SandboxNotRunningError)) {
+        throw error;
+      }
+      reconnecting ??= reconnect().finally(() => {
+        reconnecting = void 0;
+      });
+      vm = await reconnecting;
+      return operation(vm);
+    }
+  };
   const spawn7 = (command, options = {}) => {
-    return spawnMicrosandboxProcess(sdk, vm, command, {
+    return spawnMicrosandboxProcess(sdk, run, command, {
       ...options,
       commandTimeout
     });
@@ -9983,25 +10854,38 @@ function createMicrosandboxMethods(args) {
       return { stdout, stderr, exitCode: info.code ?? 1 };
     },
     spawn: spawn7,
-    async readFile(path3) {
+    async readFile(path6, options) {
       try {
-        return await vm.fs().readToString(path3);
+        const bytes = await run((vm2) => vm2.fs().read(path6));
+        return readFileContent(bytes, options);
       } catch (error) {
         throw new MicrosandboxCommandError(
-          `Failed to read file "${path3}": ${toError2(error).message}`,
+          `Failed to read file "${path6}": ${toError2(error).message}`,
+          toError2(error)
+        );
+      }
+    },
+    async exists(path6) {
+      try {
+        return await run((vm2) => vm2.fs().exists(path6));
+      } catch (error) {
+        throw new MicrosandboxCommandError(
+          `Failed to check "${path6}": ${toError2(error).message}`,
           toError2(error)
         );
       }
     },
     async writeFiles(files) {
       try {
-        const fs = vm.fs();
-        for (const dir of uniqueParentDirectories2(files.map((f) => f.path))) {
-          await fs.mkdir(dir);
-        }
-        for (const file of files) {
-          await fs.write(file.path, file.content);
-        }
+        await run(async (vm2) => {
+          const fs = vm2.fs();
+          for (const dir of uniqueParentDirectories2(files.map((f) => f.path))) {
+            await fs.mkdir(dir);
+          }
+          for (const file of files) {
+            await fs.write(file.path, file.content);
+          }
+        });
       } catch (error) {
         const err = toError2(error);
         throw new MicrosandboxCommandError(
@@ -10011,10 +10895,7 @@ function createMicrosandboxMethods(args) {
       }
     },
     async dispose() {
-      try {
-        await vm.stop();
-      } catch {
-      }
+      await vm[Symbol.asyncDispose]();
       if (ephemeral) {
         await sdk.Sandbox.remove(name).catch(() => {
         });
@@ -10025,14 +10906,14 @@ function createMicrosandboxMethods(args) {
     }
   };
 }
-function spawnMicrosandboxProcess(sdk, vm, command, options) {
+function spawnMicrosandboxProcess(sdk, run, command, options) {
   const stdout = createByteReadable();
   const stderr = createByteReadable();
-  const exit = pumpExecStream({ sdk, vm, command, options, stdout, stderr });
+  const exit = pumpExecStream({ sdk, run, command, options, stdout, stderr });
   return { stdout: stdout.stream, stderr: stderr.stream, exit };
 }
 async function pumpExecStream(args) {
-  const { sdk, vm, command, options, stdout, stderr } = args;
+  const { sdk, run, command, options, stdout, stderr } = args;
   const { signal } = options;
   let handle;
   let aborted = signal?.aborted ?? false;
@@ -10050,12 +10931,14 @@ async function pumpExecStream(args) {
   }
   signal?.addEventListener("abort", abort, { once: true });
   try {
-    handle = await vm.execStreamWith("sh", (builder) => {
-      builder.args(["-lc", command]).stdinNull();
-      if (options.cwd) builder.cwd(options.cwd);
-      if (options.env) builder.envs(options.env);
-      return builder;
-    });
+    handle = await run(
+      (vm) => vm.execStreamWith("bash", (builder) => {
+        builder.args(["-lc", command]).stdinNull();
+        if (options.cwd) builder.cwd(options.cwd);
+        if (options.env) builder.envs(options.env);
+        return builder;
+      })
+    );
     if (aborted) {
       return abortedExitInfo2();
     }
@@ -10154,10 +11037,10 @@ function abortedExitInfo2() {
 }
 function uniqueParentDirectories2(paths) {
   const dirs = /* @__PURE__ */ new Set();
-  for (const path3 of paths) {
-    const index = path3.lastIndexOf("/");
+  for (const path6 of paths) {
+    const index = path6.lastIndexOf("/");
     if (index > 0) {
-      dirs.add(path3.slice(0, index));
+      dirs.add(path6.slice(0, index));
     }
   }
   return [...dirs];
@@ -10243,13 +11126,15 @@ import {
   Bash
 } from "just-bash";
 async function createVirtualSandbox(options) {
+  const { fs } = options;
   const bash = new Bash({
-    fs: options.fs,
+    fs,
     cwd: options.cwd,
     env: options.env,
     javascript: options.javascript,
     customCommands: options.customCommands
   });
+  const resolve3 = (path6) => fs.resolvePath(bash.getCwd(), path6);
   const sandbox = {
     async executeCommand(command, options2) {
       const result = await bash.exec(
@@ -10262,17 +11147,20 @@ async function createVirtualSandbox(options) {
         exitCode: result.exitCode
       };
     },
-    async readFile(path3) {
-      return bash.readFile(path3);
+    async readFile(path6, readOptions) {
+      return readFileContent(
+        await fs.readFileBuffer(resolve3(path6)),
+        readOptions
+      );
     },
     async writeFiles(files) {
       for (const file of files) {
-        await bash.writeFile(
-          file.path,
-          typeof file.content === "string" ? file.content : Buffer.from(file.content).toString("utf-8")
-        );
+        await fs.writeFile(resolve3(file.path), file.content);
       }
     },
+    async exists(path6) {
+      return fs.exists(resolve3(path6));
+    },
     async dispose() {
     },
     [Symbol.asyncDispose]() {
@@ -10292,12 +11180,12 @@ async function createVirtualSandbox(options) {
 }
 
 // packages/context/src/lib/skills/fragments.ts
-import dedent2 from "dedent";
+import dedent4 from "dedent";
 function skills(availableSkills) {
-  const skillSnapshot = availableSkills.map(({ name, description, path: path3 }) => ({
+  const skillSnapshot = availableSkills.map(({ name, description, path: path6 }) => ({
     name,
     description,
-    path: path3
+    path: path6
   }));
   if (skillSnapshot.length === 0) {
     return {
@@ -10323,7 +11211,7 @@ function skills(availableSkills) {
     metadata: { skills: skillSnapshot }
   };
 }
-var SKILLS_INSTRUCTIONS = dedent2`A skill is a set of local instructions to follow that is stored in a \`SKILL.md\` file. Below is the list of skills that can be used. Each entry includes a name, description, and file path so you can open the source for full instructions when using a specific skill.
+var SKILLS_INSTRUCTIONS = dedent4`A skill is a set of local instructions to follow that is stored in a \`SKILL.md\` file. Below is the list of skills that can be used. Each entry includes a name, description, and file path so you can open the source for full instructions when using a specific skill.
 
 ### How to use skills
 - Discovery: The list below shows the skills available in this session (name + description + file path). Skill bodies live on disk at the listed paths.
@@ -12045,6 +12933,7 @@ async function persistedWriter(options) {
   let seq = 0;
   let buffer = [];
   let failedByErrorChunk = false;
+  let abortedByChunk = false;
   async function flush() {
     if (buffer.length === 0) return;
     const batch = buffer;
@@ -12070,11 +12959,14 @@ async function persistedWriter(options) {
     }
   }
   async function persistChunk(chunk) {
+    if (chunk.data.type === "abort") {
+      abortedByChunk = true;
+    }
     if (strategy === "immediate") {
       await appendBatch([chunk]);
     } else {
       buffer.push(chunk);
-      if (buffer.length >= flushSize) {
+      if (buffer.length >= flushSize || chunk.data.type.startsWith("data-")) {
         await flush();
       }
     }
@@ -12102,7 +12994,10 @@ async function persistedWriter(options) {
     async complete() {
       await flush();
       if (failedByErrorChunk) return;
-      await store.updateStreamStatus(streamId, "completed");
+      await store.updateStreamStatus(
+        streamId,
+        abortedByChunk ? "cancelled" : "completed"
+      );
     },
     async fail(error) {
       await flush();
@@ -12116,7 +13011,7 @@ async function persistedWriter(options) {
 }
 
 // packages/context/src/lib/stream/polling-change-source.ts
-import { setTimeout as delay2 } from "node:timers/promises";
+import { setTimeout as delay3 } from "node:timers/promises";
 
 // packages/context/src/lib/stream/polling-policy.ts
 var DEFAULT_WATCH_POLLING = {
@@ -12161,7 +13056,7 @@ function nextAdaptivePollingDelay(state) {
     state.config.minMs,
     state.config.maxMs
   );
-  const delay3 = applyJitter(
+  const delay4 = applyJitter(
     current,
     state.config.jitterRatio,
     state.config.minMs,
@@ -12172,7 +13067,7 @@ function nextAdaptivePollingDelay(state) {
     state.config.minMs,
     state.config.maxMs
   );
-  return delay3;
+  return delay4;
 }
 function normalizeAdaptivePolling(polling, fallback) {
   const merged = {
@@ -12272,7 +13167,7 @@ function isTerminal(status) {
   return status !== "queued" && status !== "running";
 }
 function waitForDelay(ms, signal) {
-  return delay2(ms, true, { signal }).catch((err) => {
+  return delay3(ms, true, { signal }).catch((err) => {
     if (signal.aborted) return false;
     throw err;
   });
@@ -13975,6 +14870,7 @@ export {
   preference,
   principle,
   quirk,
+  readFileContent,
   reasoningFramework,
   reminder,
   render,
@@ -13991,6 +14887,7 @@ export {
   shellQuote,
   skills,
   skillsReminder,
+  socraticPlan,
   socraticPrompting,
   soul,
   stop,