@deepagents/context 5.0.0 → 6.1.0

package/dist/index.js

@@ -380,7 +380,8 @@ var Agent = class _Agent {
       }),
       stopWhen: this.#options.stopWhen ?? DEFAULT_STOP_WHEN,
       prepareStep: this.#options.context.createPrepareStep({
-        steer: false
+        steer: false,
+        sandbox: this.#options.sandbox
       }),
       tools: this.tools,
       runtimeContext: contextVariables,
@@ -417,7 +418,8 @@ var Agent = class _Agent {
       throw new Error(`Agent ${this.#options.name} is missing a model.`);
     }
     const prepareStep = this.#options.context.createPrepareStep({
-      additionalInput: this.#options.prepareStepInput
+      additionalInput: this.#options.prepareStepInput,
+      sandbox: this.#options.sandbox
     });
     const result = await this.#createRawStream(
       contextVariables,
@@ -462,7 +464,7 @@ var Agent = class _Agent {
       }),
       repairToolCall: createRepairToolCall(model, config?.abortSignal),
       stopWhen: this.#options.stopWhen ?? DEFAULT_STOP_WHEN,
-      prepareStep: prepareStep ?? context.createPrepareStep(),
+      prepareStep: prepareStep ?? context.createPrepareStep({ sandbox: this.#options.sandbox }),
       experimental_transform: config?.transform ?? smoothStream(),
       tools: this.tools,
       runtimeContext: contextVariables,
@@ -2302,6 +2304,16 @@ function toolCallCount(name, spec) {
     return checkCount(count, spec);
   };
 }
+function everyNToolCalls(n) {
+  if (!Number.isInteger(n) || n < 1) {
+    throw new Error("everyNToolCalls(n) requires a positive integer");
+  }
+  return (ctx) => toolPartsOf(ctx.lastAssistantMessage).filter(
+    (part) => ["output-available", "output-error", "output-denied"].includes(
+      part.state
+    )
+  ).length >= n;
+}
 function toolFailureStreak(ctx, name) {
   const parts = (ctx.lastAssistantMessages ?? []).flatMap(
     (message2) => toolPartsOf(message2).filter((part) => matchesName(name, toolNameOf(part)))
@@ -3838,6 +3850,42 @@ function estimateMessageContent(data) {
 function isLanguageModelUsage(value) {
   return typeof value === "object" && value !== null && "totalTokens" in value;
 }
+function cloneFragmentData(data, seen) {
+  if (typeof data !== "object" || data === null) return data;
+  const existing = seen.get(data);
+  if (existing !== void 0) return existing;
+  if (isFragment(data)) {
+    const clone = { ...data };
+    seen.set(data, clone);
+    if ("data" in data) {
+      clone.data = cloneFragmentData(data.data, seen);
+    }
+    return clone;
+  }
+  if (Array.isArray(data)) {
+    const clone = [];
+    seen.set(data, clone);
+    clone.push(...data.map((item) => cloneFragmentData(item, seen)));
+    return clone;
+  }
+  if (isFragmentObject(data)) {
+    const clone = {};
+    seen.set(data, clone);
+    for (const [key, value] of Object.entries(data)) {
+      clone[key] = cloneFragmentData(value, seen);
+    }
+    return clone;
+  }
+  return data;
+}
+function cloneFragment(fragment2) {
+  const clone = { ...fragment2 };
+  const seen = new WeakMap([[fragment2, clone]]);
+  if ("data" in fragment2) {
+    clone.data = cloneFragmentData(fragment2.data, seen);
+  }
+  return clone;
+}
 function addUsageValue(current, next) {
   if (current === void 0 && next === void 0) {
     return void 0;
@@ -3911,13 +3959,6 @@ function toolOutcomesFromStep(content) {
   }
   return outcomes;
 }
-function stepStartPartIndices(parts) {
-  const indices = [];
-  for (let i = 0; i < parts.length; i++) {
-    if (parts[i].type === "step-start") indices.push(i);
-  }
-  return indices;
-}
 var ContextEngine = class _ContextEngine {
   /** Non-message fragments (role, hints, etc.) - not persisted in graph */
   #fragments = [];
@@ -4072,7 +4113,7 @@ var ContextEngine = class _ContextEngine {
    * Count user turns in the conversation and return the previous saved user message context.
    * Includes persisted messages and pending messages in the turn count.
    */
-  async #getChainContext() {
+  async #getChainContext(pending = this.#pendingMessages) {
     await this.#ensureInitialized();
     const builder = new ChainSummaryBuilder();
     if (this.#branch?.headMessageId) {
@@ -4081,8 +4122,7 @@ var ContextEngine = class _ContextEngine {
       );
       for (const msg of chain) builder.ingestStored(msg);
     }
-    for (const fragment2 of this.#pendingMessages)
-      builder.ingestPending(fragment2);
+    for (const fragment2 of pending) builder.ingestPending(fragment2);
     return builder.build();
   }
   async getTurnCount() {
@@ -4229,14 +4269,14 @@ var ContextEngine = class _ContextEngine {
    * Add fragments to the context.
    *
    * - Message fragments (user/assistant) are queued for persistence
-   * - Non-message fragments (role/hint) are kept in memory for system prompt
+   * - Non-message fragments are cloned so lazy resolution stays engine-local
    */
   set(...fragments) {
     for (const fragment2 of fragments) {
       if (isMessageFragment(fragment2)) {
         this.#pendingMessages.push(fragment2);
       } else {
-        this.#fragments.push(fragment2);
+        this.#fragments.push(cloneFragment(fragment2));
       }
     }
     return this;
@@ -4299,12 +4339,16 @@ var ContextEngine = class _ContextEngine {
       return { headMessageId: this.#branch?.headMessageId ?? void 0 };
     }
     const pending = this.#pendingMessages;
-    const pipeline = new SavePipeline(this.#asSavePipelineEngine(), pending);
-    await pipeline.applyUpdateBranching(options?.branch ?? true);
-    await this.#foldUserReminders(pending);
-    const result = await pipeline.persist();
     this.#pendingMessages = [];
-    return result;
+    const pipeline = new SavePipeline(this.#asSavePipelineEngine(), pending);
+    try {
+      await pipeline.applyUpdateBranching(options?.branch ?? true);
+      await this.#foldUserReminders(pending);
+      return await pipeline.persist();
+    } catch (error) {
+      this.#pendingMessages.unshift(...pending);
+      throw error;
+    }
   }
   #currentReminderSession;
   /**
@@ -4318,27 +4362,19 @@ var ContextEngine = class _ContextEngine {
    * latch is desired. AI SDK v7 carries prepared message overrides forward to
    * subsequent steps.
    *
-   * writeAssistantSegment persists the matching
-   * `[assistant, reminder, assistant]` split so later requests reproduce the
-   * exact prompt prefix the model saw.
+   * Each injected input is persisted with a following assistant placeholder
+   * before prepareStep returns. writeAssistantSegment fills that placeholder,
+   * so process loss cannot make a delivered reminder eligible again and later
+   * requests reproduce the exact prompt prefix the model saw.
    */
   createPrepareStep(options = {}) {
     const enableSteer = options.steer ?? true;
     const session = {
       firedOnceIds: /* @__PURE__ */ new Set(),
-      fired: [],
-      currentSegStart: 0,
-      materialized: 0
+      currentSegStart: 0
     };
     this.#currentReminderSession = session;
-    let stepOffset = 0;
-    let previousStepNumber;
     return async ({ steps, stepNumber, messages }) => {
-      if (previousStepNumber !== void 0 && stepNumber <= previousStepNumber) {
-        stepOffset += previousStepNumber + 1;
-      }
-      previousStepNumber = stepNumber;
-      const cumulativeStepNumber = stepOffset + stepNumber;
       const priorStep = stepNumber >= 1 ? steps[stepNumber - 1] : void 0;
       const hasSafeBoundary = (priorStep?.content?.length ?? 0) > 0;
       const canFire = enableSteer && hasSafeBoundary;
@@ -4346,13 +4382,18 @@ var ContextEngine = class _ContextEngine {
       const outcomes = toolOutcomesFromStep(steps.at(-1)?.content ?? []);
       const needsChain = steerConfigs.length > 0 || outcomes.length > 0 && this.#remindersFor("tool-output").length > 0;
       const chain = needsChain ? await this.#getChainContext() : void 0;
-      const toolReminders = chain ? await this.#evaluateToolOutputReminders(outcomes, session, chain) : { texts: [], onceIds: [] };
+      const toolReminders = chain ? await this.#evaluateToolOutputReminders(
+        outcomes,
+        session,
+        chain,
+        options.sandbox
+      ) : { texts: [], onceIds: [] };
       const additionalInput = await options.additionalInput?.();
       let reminderInput;
       if (canFire && chain) {
         const configs = steerConfigs;
         if (configs.length > 0) {
-          const whenCtx = this.#steerWhenCtx(chain, session);
+          const whenCtx = this.#steerWhenCtx(chain, session, options.sandbox);
           const matched = await evaluateFiredReminders(configs, whenCtx);
           if (matched.length > 0) {
             const onceIds = [
@@ -4388,10 +4429,35 @@ var ContextEngine = class _ContextEngine {
         const inputModel = await convertToModelMessages2(inputs, {
           ignoreIncompleteToolCalls: true
         });
-        session.fired.push({
-          afterStep: cumulativeStepNumber - 1,
-          messages: inputs
-        });
+        const head = await this.headMessage();
+        if (head?.name !== "assistant") {
+          throw new Error(
+            "createPrepareStep: expected an assistant message at chain head."
+          );
+        }
+        const currentSegmentId = session.currentSegId ?? 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(
+          currentSegment.data,
+          `Stored assistant message "${currentSegment.id}"`
+        );
+        const nextSegmentId = generateId5();
+        for (const input of inputs) this.set(user(input));
+        this.set(
+          assistant({
+            id: nextSegmentId,
+            role: "assistant",
+            parts: []
+          })
+        );
+        await this.save({ branch: false });
+        session.currentSegId = nextSegmentId;
+        session.currentSegStart += currentMessage.parts.length;
         return {
           messages: [...messages, ...inputModel]
         };
@@ -4400,16 +4466,15 @@ var ContextEngine = class _ContextEngine {
     };
   }
   /**
-   * Persist the streamed assistant message, carving it at reminder boundaries.
+   * Persist the streamed assistant message into its reserved segment.
    *
    * Called from chat()'s onStepEnd/onEnd (and the guardrail path) with the
-   * cumulative response message. Segment boundaries come from the `step-start`
-   * markers in the message itself — no cross-track store read — so the carve is
-   * race-free. Idempotent: finalized segments keep stable ids; the open segment
-   * is updated in place. With no fired reminder it degrades to a plain in-place
-   * write of the whole message to the reserved head.
+   * cumulative response message. prepareStep has already persisted reminder
+   * boundaries and reserved the open segment id, so this only updates that
+   * segment in place with the cumulative prefix removed. With no fired reminder
+   * it writes the whole message to the original reserved head.
    */
-  async writeAssistantSegment(message2, options = {}) {
+  async writeAssistantSegment(message2) {
     const head = await this.headMessage();
     if (head?.name !== "assistant") {
       throw new Error(
@@ -4417,37 +4482,11 @@ var ContextEngine = class _ContextEngine {
       );
     }
     const session = this.#currentReminderSession;
-    if (!session || session.fired.length === 0) {
-      this.set(assistant({ ...message2, id: head.id }));
-      await this.save({ branch: false });
-      return;
-    }
-    if (session.currentSegId === void 0) {
-      session.currentSegId = head.id;
-      session.currentSegStart = 0;
-    }
-    const stepStarts = stepStartPartIndices(message2.parts);
-    while (session.materialized < session.fired.length) {
-      const fire = session.fired[session.materialized];
-      const boundary = stepStarts[fire.afterStep + 1] ?? (options.final ? message2.parts.length : void 0);
-      if (boundary === void 0) break;
-      this.set(
-        assistant({
-          id: session.currentSegId,
-          role: "assistant",
-          parts: message2.parts.slice(session.currentSegStart, boundary)
-        })
-      );
-      for (const input of fire.messages) this.set(user(input));
-      session.currentSegId = generateId5();
-      session.currentSegStart = boundary;
-      session.materialized++;
-    }
     this.set(
       assistant({
         ...message2,
-        id: session.currentSegId,
-        parts: message2.parts.slice(session.currentSegStart)
+        id: session?.currentSegId ?? head.id,
+        parts: message2.parts.slice(session?.currentSegStart ?? 0)
       })
     );
     await this.save({ branch: false });
@@ -4503,7 +4542,7 @@ var ContextEngine = class _ContextEngine {
       fragment2.codec.encode(),
       `Pending user fragment "${fragment2.name}"`
     );
-    const chain = await this.#getChainContext();
+    const chain = await this.#getChainContext(pending);
     const matched = await evaluateFiredReminders(configs, {
       ...this.#buildWhenCtx(chain, message2),
       firedOnceIds: chain.firedOnceIds
@@ -4544,7 +4583,7 @@ var ContextEngine = class _ContextEngine {
    * elapsedExceeds keeps firing every step once crossed — by design; compose
    * once() for control.
    */
-  #steerWhenCtx(chain, session) {
+  #steerWhenCtx(chain, session, sandbox) {
     const currentMessage = chain.lastMessage;
     if (!currentMessage) {
       throw new Error(
@@ -4553,10 +4592,11 @@ var ContextEngine = class _ContextEngine {
     }
     return {
       ...this.#buildWhenCtx(chain, currentMessage),
+      sandbox,
       firedOnceIds: /* @__PURE__ */ new Set([...chain.firedOnceIds, ...session.firedOnceIds])
     };
   }
-  async #evaluateToolOutputReminders(outcomes, session, chain) {
+  async #evaluateToolOutputReminders(outcomes, session, chain, sandbox) {
     const configs = this.#remindersFor("tool-output");
     if (configs.length === 0 || outcomes.length === 0) {
       return { texts: [], onceIds: [] };
@@ -4567,6 +4607,7 @@ var ContextEngine = class _ContextEngine {
     const onceIds = /* @__PURE__ */ new Set();
     for (const outcome of outcomes) {
       const whenCtx = this.#buildWhenCtx(chain, currentMessage);
+      whenCtx.sandbox = sandbox;
       whenCtx.toolOutcome = outcome;
       whenCtx.firedOnceIds = /* @__PURE__ */ new Set([
         ...chain.firedOnceIds,
@@ -5540,7 +5581,7 @@ async function chat(agent2, options = {}) {
       if (Object.keys(mergedMetadata).length > 0) {
         message2 = { ...message2, metadata: mergedMetadata };
       }
-      await context.writeAssistantSegment(message2, { final: true });
+      await context.writeAssistantSegment(message2);
       const usage = await result.usage;
       if (usage !== void 0) {
         await context.trackUsage(usage);
@@ -5888,6 +5929,300 @@ function fromFragment(fragment2, options) {
   throw new Error(`Fragment "${fragment2.name}" is missing codec`);
 }
 
+// packages/context/src/lib/fragments/plan.ts
+import dedent from "dedent";
+import z3 from "zod";
+var PLAN_FILE_PATH = "/workspace/.deepagents/plan.json";
+var PLAN_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:
+  1. The user's request and later corrections.
+  2. Higher-priority system, developer, and workspace instructions.
+  3. Workspace guidance such as AGENTS.md.
+  4. Existing source, public contracts, tests, documentation, issues, and generated artifacts.
+  5. The current branch, working-tree changes, and pre-existing work.
+  6. Runtime observations, reproduction results, errors, logs, and tool output.
+  7. Sandbox, permission, and available-tool constraints.
+  8. Existing plan state when resuming.
+  9. Dependencies and risks discovered during execution.
+
+  Describe the objective as the outcome the user is trying to achieve, not merely the activity requested. Derive observable success criteria from that outcome and the workspace's real validation mechanisms.
+
+  Preserve the basis of every important plan statement:
+  - Explicit requirement: stated by the user or a higher-priority instruction.
+  - Discovered constraint: demonstrated by source, a public contract, a test, or runtime evidence.
+  - Inference: supported by available evidence but not directly stated.
+  - Assumption: unresolved and potentially requiring confirmation.
+
+  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.
+
+  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",
+  "discovered_constraint",
+  "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 uniqueIds(items, label) {
+  const byId = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    if (byId.has(item.id)) {
+      throw new Error(`duplicate ${label} id "${item.id}"`);
+    }
+    byId.set(item.id, item);
+  }
+  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) {
+    const blockers = /* @__PURE__ */ new Set();
+    for (const blocker of item.blockedBy) {
+      if (blocker === item.id) {
+        throw new Error(`task "${item.id}" cannot block itself`);
+      }
+      if (!tasks.has(blocker)) {
+        throw new Error(
+          `task "${item.id}" references missing blocker "${blocker}"`
+        );
+      }
+      if (blockers.has(blocker)) {
+        throw new Error(`task "${item.id}" repeats blocker "${blocker}"`);
+      }
+      blockers.add(blocker);
+      blocks.get(blocker)?.push(item.id);
+    }
+  }
+  const visited = /* @__PURE__ */ new Set();
+  const visiting = /* @__PURE__ */ new Set();
+  const stack = [];
+  const visit = (id) => {
+    if (visited.has(id)) return;
+    if (visiting.has(id)) {
+      const cycleStart = stack.indexOf(id);
+      throw new Error(
+        `dependency cycle: ${[...stack.slice(cycleStart), id].join(" -> ")}`
+      );
+    }
+    visiting.add(id);
+    stack.push(id);
+    for (const blocker of tasks.get(id)?.blockedBy ?? []) visit(blocker);
+    stack.pop();
+    visiting.delete(id);
+    visited.add(id);
+  };
+  for (const { id } of state.tasks) visit(id);
+  for (const item of state.tasks) {
+    const incompleteBlockers = item.blockedBy.filter(
+      (id) => tasks.get(id)?.status !== "completed"
+    );
+    if (item.status !== "pending" && incompleteBlockers.length > 0) {
+      throw new Error(
+        `task "${item.id}" is ${item.status} while blocked by ${incompleteBlockers.join(", ")}`
+      );
+    }
+    if (item.status === "completed" && item.evidence.length === 0) {
+      throw new Error(`completed task "${item.id}" has no evidence`);
+    }
+  }
+  if (state.lastReview && state.lastReview.revision > state.revision) {
+    throw new Error(
+      `last review references future revision ${state.lastReview.revision}`
+    );
+  }
+  if (state.lastReview?.decision === "complete" && state.successCriteria.some(({ evidence: evidence2 }) => evidence2.length === 0)) {
+    throw new Error(
+      "a complete review requires evidence for every success criterion"
+    );
+  }
+  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 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) {
+  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(
+    ({ status, blockedBy }) => status === "pending" && blockedBy.every((id) => tasks.get(id)?.status === "completed")
+  );
+  const waiting = state.tasks.filter(
+    ({ status, blockedBy }) => status === "pending" && blockedBy.some((id) => tasks.get(id)?.status !== "completed")
+  );
+  const completed = state.tasks.filter(({ status }) => status === "completed");
+  return [
+    `Current plan (revision ${state.revision})`,
+    `Objective: ${state.objective.text} [${state.objective.basis}; ${state.objective.source}]`,
+    "",
+    "Success criteria:",
+    ...lineItems(
+      state.successCriteria.map(
+        (criterion) => `${criterion.evidence.length > 0 ? "[supported]" : "[unsupported]"} ${criterion.id}: ${criterion.text}${latestEvidence(criterion.evidence)}`
+      )
+    ),
+    "",
+    "Constraints:",
+    ...lineItems(
+      state.constraints.map(
+        (item) => `${item.text} [${item.basis}; ${item.source}]`
+      )
+    ),
+    "",
+    "Assumptions:",
+    ...lineItems(
+      state.assumptions.map(
+        (item) => `${item.text} [${item.basis}; ${item.source}]`
+      )
+    ),
+    "",
+    "Active tasks:",
+    ...lineItems(active.map((item) => formatTask(item, blocks))),
+    "",
+    "Ready tasks:",
+    ...lineItems(ready.map((item) => formatTask(item, blocks))),
+    "",
+    "Waiting tasks:",
+    ...lineItems(
+      waiting.map(
+        (item) => `${formatTask(item, blocks)}; waiting for ${item.blockedBy.filter((id) => tasks.get(id)?.status !== "completed").join(", ")}`
+      )
+    ),
+    "",
+    "Completed tasks:",
+    ...lineItems(completed.map((item) => formatTask(item, blocks))),
+    ...state.lastReview ? [
+      "",
+      `Last review: ${state.lastReview.decision} at revision ${state.lastReview.revision} \u2014 ${state.lastReview.summary}`
+    ] : [],
+    "",
+    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);
+}
+function review(options) {
+  return reminder(({ sandbox }) => resolvePlanReview(sandbox), {
+    when: options.when,
+    target: "steer"
+  });
+}
+var plan = { path: PLAN_FILE_PATH, instructions, review };
+
 // packages/context/src/lib/fragments/reasoning.ts
 function reasoningFramework() {
   return [
@@ -7520,7 +7855,7 @@ import fg from "fast-glob";
 import { BashTransformPipeline, TeePlugin } from "just-bash";
 import { readFile } from "node:fs/promises";
 import * as path from "node:path";
-import z3 from "zod";
+import z4 from "zod";
 import { withHostOnlyToolMetadata as withHostOnlyToolMetadata2 } from "@deepagents/agent";
 var DEFAULT_DESTINATION = "/workspace";
 var DEFAULT_MAX_FILES = 1e3;
@@ -7543,6 +7878,7 @@ var KNOWN_TOOLS = /* @__PURE__ */ new Set([
   "head",
   "html-to-markdown",
   "iconv",
+  "js-exec",
   "join",
   "jq",
   "node",
@@ -7687,6 +8023,7 @@ async function createToolPrompt(sandbox, filenames, customPrompt) {
   const available = new Set(
     result.stdout.split("\n").filter((entry) => KNOWN_TOOLS.has(entry))
   );
+  if (available.has("js-exec")) available.delete("node");
   if (available.size === 0) return "";
   const lines = [
     `Available tools: ${[...available].sort().join(", ")}, and more`
@@ -7764,9 +8101,9 @@ async function createBashTool(options) {
       extraInstructions,
       experimentalTeeTransform
     }),
-    inputSchema: z3.object({
-      command: z3.string().describe("The bash command to execute"),
-      reasoning: z3.string().trim().min(1).describe("Brief reason for executing this command")
+    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")
     }),
     execute: async ({ command: originalCommand }, executionOptions) => {
       let command = originalCommand;
@@ -7808,8 +8145,8 @@ async function createBashTool(options) {
   });
   const readFile2 = tool2({
     description: "Read the contents of a file from the sandbox.",
-    inputSchema: z3.object({
-      path: z3.string().describe("The path to the file to read")
+    inputSchema: z4.object({
+      path: z4.string().describe("The path to the file to read")
     }),
     execute: async ({ path: filePath }) => ({
       content: await sandbox.readFile(
@@ -7819,9 +8156,9 @@ async function createBashTool(options) {
   });
   const writeFile2 = tool2({
     description: "Write content to a file in the sandbox. Creates parent directories if needed.",
-    inputSchema: z3.object({
-      path: z3.string().describe("The path where the file should be written"),
-      content: z3.string().describe("The content to write to the file")
+    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")
     }),
     execute: async ({ path: filePath, content }) => {
       try {
@@ -9902,12 +10239,15 @@ function buildSubcommandRepair(name, subcommands) {
 }
 
 // packages/context/src/lib/sandbox/virtual-sandbox.ts
-import { Bash } from "just-bash";
+import {
+  Bash
+} from "just-bash";
 async function createVirtualSandbox(options) {
   const bash = new Bash({
     fs: options.fs,
     cwd: options.cwd,
     env: options.env,
+    javascript: options.javascript,
     customCommands: options.customCommands
   });
   const sandbox = {
@@ -9952,7 +10292,7 @@ async function createVirtualSandbox(options) {
 }
 
 // packages/context/src/lib/skills/fragments.ts
-import dedent from "dedent";
+import dedent2 from "dedent";
 function skills(availableSkills) {
   const skillSnapshot = availableSkills.map(({ name, description, path: path3 }) => ({
     name,
@@ -9983,7 +10323,7 @@ function skills(availableSkills) {
     metadata: { skills: skillSnapshot }
   };
 }
-var SKILLS_INSTRUCTIONS = dedent`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 = 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.
 
 ### 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.
@@ -13152,29 +13492,55 @@ var StreamManager = class {
     const detect = async () => {
       if (detected) return;
       detected = true;
-      await this.#notifyCancellation(streamId, options);
       ac.abort();
+      await this.#notifyCancellation(streamId, options);
     };
+    const retryState = createAdaptivePollingState(DEFAULT_CANCEL_POLLING);
     const listeners = this.#localCancellationListeners.get(streamId) ?? /* @__PURE__ */ new Set();
     listeners.add(detect);
     this.#localCancellationListeners.set(streamId, listeners);
     try {
-      for await (const change of this.#changeSource.subscribe(
-        streamId,
-        ac.signal
-      )) {
-        if (change.kind === "chunks") continue;
-        const status = await this.#store.getStreamStatus(streamId);
-        if (status === void 0) {
-          ac.abort();
-          return;
+      while (!ac.signal.aborted && !detected) {
+        try {
+          const initialStatus = await this.#store.getStreamStatus(streamId);
+          if (initialStatus === void 0) {
+            ac.abort();
+            return;
+          }
+          if (initialStatus === "cancelled") {
+            await detect();
+            return;
+          }
+          if (isTerminal3(initialStatus)) return;
+          const subscribedAt = Date.now();
+          let subscriptionStabilized = false;
+          for await (const change of this.#changeSource.subscribe(
+            streamId,
+            ac.signal
+          )) {
+            if (!subscriptionStabilized && Date.now() - subscribedAt >= DEFAULT_CANCEL_POLLING.maxMs) {
+              resetAdaptivePolling(retryState);
+              subscriptionStabilized = true;
+            }
+            if (change.kind === "chunks") continue;
+            const status = await this.#store.getStreamStatus(streamId);
+            if (status === void 0) {
+              ac.abort();
+              return;
+            }
+            if (status === "cancelled") {
+              await detect();
+              return;
+            }
+            if (isTerminal3(status)) return;
+          }
+        } catch {
+          if (ac.signal.aborted || detected) return;
         }
-        if (status === "cancelled") {
-          await detect();
+        if (!await waitForDelay2(nextAdaptivePollingDelay(retryState), ac.signal)) {
           return;
         }
       }
-    } catch {
     } finally {
       listeners.delete(detect);
       if (listeners.size === 0) {
@@ -13188,7 +13554,11 @@ var StreamManager = class {
     await Promise.all([...listeners].map((listener) => listener()));
   }
   async #notifyCancellation(streamId, options) {
-    const current = await this.#store.getStream(streamId);
+    let current;
+    try {
+      current = await this.#store.getStream(streamId);
+    } catch {
+    }
     const latencyMs = current?.cancelRequestedAt != null ? Math.max(0, Date.now() - current.cancelRequestedAt) : null;
     this.#emit({ type: "persist:cancel-detected", streamId, latencyMs });
     if (!options?.onCancelDetected) return;
@@ -13303,6 +13673,20 @@ var StreamManager = class {
     }
   }
 };
+function waitForDelay2(ms, signal) {
+  if (signal.aborted) return Promise.resolve(false);
+  return new Promise((resolve3) => {
+    const timeout = globalThis.setTimeout(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve3(true);
+    }, ms);
+    const onAbort = () => {
+      globalThis.clearTimeout(timeout);
+      resolve3(false);
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
 async function drainAvailable(controller, store, streamId, lastSeqRef, pageSize, onPage) {
   let total = 0;
   while (true) {
@@ -13530,6 +13914,7 @@ export {
   errorRecoveryGuardrail,
   estimate,
   evaluateFiredReminders,
+  everyNToolCalls,
   everyNTurns,
   everyOfLastN,
   example,
@@ -13585,6 +13970,7 @@ export {
   persona,
   pip,
   pkg,
+  plan,
   policy,
   preference,
   principle,