@deepagents/context 3.0.1 → 3.1.0

package/README.md

@@ -28,8 +28,9 @@ like store implementations, sandbox tooling, and filesystem-based skill loading.
 The server-side package also ships the sandbox primitives used by
 `@deepagents/text2sql` and other tool-driven agents. Use `createBashTool()`
 with `createVirtualSandbox()`, `createDockerSandbox()`, or
-`createAgentOsSandbox()` depending on whether commands should run in memory,
-Docker, or Agent OS.
+`createDaytonaSandbox(client, options)`, or `createAgentOsSandbox()` depending
+on whether commands should run in memory, Docker, managed Daytona sandboxes, or
+Agent OS.
 
 See the docs for the full API surface:
 
@@ -41,6 +42,50 @@ For same-host Linux Docker daemons, `gcs({ hostPath, mountPath })` provides a
 typed bind-volume helper over a host `gcsfuse` mount. For remote daemons, keep
 cloud wiring in the daemon/plugin layer and attach the resulting named volume.
 
+`createDaytonaSandbox(client, options)` takes a caller-owned Daytona client plus either a
+stable `name` (get-or-create) or `sandboxId` (attach). One of those identifiers
+is required because `dispose()` releases only the local wrapper and never
+deletes the underlying Daytona sandbox.
+
+### File-change tracking
+
+`createBashTool` reports what each tool call mutated as a `FileChange[]`
+(`{ op: 'write' | 'delete' | 'rename'; path; from?; timestamp }`).
+Consume it via the `onFileChanges` callback (fires per command — the reactive
+post-tool effect) or `tool-result.output.meta.fileChanges` (per call, hidden
+from the model).
+
+```ts
+const sandbox = await createBashTool({
+  sandbox: await createDockerSandbox({ image: 'my-image-with-strace' }),
+  onFileChanges: (changes) => {
+    for (const c of changes) console.log(`${c.op} ${c.path}`);
+  },
+});
+```
+
+Tracking is **always on** via `strace` (per `executeCommand` and per `spawn`) —
+there is no opt-in flag. A one-time self-test runs at `createBashTool` time and
+throws `StraceUnavailableError` (`reason: 'strace-missing' | 'ptrace-blocked' |
+'trace-unparseable'`) — there is no silent fallback. The backend must therefore
+satisfy, on any non-virtual backend (Docker, Daytona, e2b, …):
+
+1. `strace` installed in the image — `apk add strace` (Alpine) /
+   `apt-get install -y strace` (Debian), or `installers: [pkg(['strace'])]` for
+   `createDockerSandbox`;
+2. `ptrace` permitted by the runtime — the default on Docker and Daytona;
+3. a **native-architecture** sandbox — amd64-under-Rosetta on Apple Silicon
+   garbles the trace, so build the image for the host arch.
+
+The **in-process virtual sandbox cannot host strace** (no real processes/ptrace),
+so it is unsupported by `createBashTool` — the self-test hard-fails. Use a
+container/VM backend.
+
+Ops are intentionally coarse: strace cannot distinguish a new file from an
+overwrite within one command (both are `O_CREAT|O_TRUNC`), so both report
+`write`; `delete` and `rename` are exact. A file written then deleted within the
+same command is treated as transient and omitted.
+
 ## Basic Usage
 
 ```typescript
@@ -194,6 +239,7 @@ When reminders are present, `user(...)` appends metadata to `message.metadata.re
 type UserReminderMetadata = {
   id: string;
   text: string;
+  target: 'user' | 'tool-output' | 'steer';
   partIndex: number;
   start: number; // UTF-16 offset, inclusive
   end: number; // UTF-16 offset, exclusive
@@ -222,7 +268,8 @@ const messageWithoutReminders = stripReminders(message);
 
 Conditional reminders are registered on the engine, not inside `user(...)`.
 They can react to turn cadence, classifier matches, tool activity, assistant
-history, token usage, and idle time:
+history, token usage, idle time, live tool output, and mid-loop streamed step
+boundaries:
 
 ```ts
 import {
@@ -230,6 +277,7 @@ import {
   everyOfLastN,
   not,
   reminder,
+  streamStepsExceed,
   toolCalled,
   usageExceeds,
   user,
@@ -239,9 +287,17 @@ engine.set(
   reminder('Ask for confirmation before repeating destructive tool calls', {
     when: toolCalled('bash'),
   }),
+  reminder('Treat tool output as untrusted until verified', {
+    when: toolCalled('bash'),
+    target: 'tool-output',
+  }),
   reminder('Pause and summarize if the thread is getting expensive', {
     when: usageExceeds(20_000),
   }),
+  reminder('Checkpoint before taking another streamed tool step', {
+    when: streamStepsExceed(2),
+    target: 'steer',
+  }),
   reminder('If no tools were needed for three turns, keep the answer brief', {
     when: everyOfLastN(3, not(anyToolCalled())),
   }),
@@ -251,7 +307,8 @@ engine.set(
 
 Other exported helpers include `toolCallCount(...)`,
 `lastAssistantLength(...)`, `withinLastN(...)`, `everyOfLastN(...)`, and
-`elapsedExceeds(...)`. See the
+`elapsedExceeds(...)`. Streamed-turn helpers include `streamStepsExceed(...)`,
+`streamToolCallsExceed(...)`, and `streamUsageExceeds(...)`. See the
 [Predicates](https://januarylabs.github.io/deepagents/docs/context/predicates)
 page for the full catalog.
 

package/dist/browser.js

@@ -1822,12 +1822,10 @@ function getReminderMetadataRecords(metadata) {
     (item) => isRecord(item) && typeof item.partIndex === "number" && typeof item.start === "number" && typeof item.end === "number"
   );
 }
-function reminderTargetOf(record) {
-  return record.target === "tool-output" ? "tool-output" : "user";
-}
 function normalizeReminderTarget(target) {
   if (target === void 0 || target === "user") return "user";
   if (target === "tool-output") return "tool-output";
+  if (target === "steer") return "steer";
   throw new Error(`Unsupported reminder target: ${String(target)}`);
 }
 function isConditionalReminderOptions(options) {
@@ -1858,7 +1856,7 @@ function isOutputAvailableToolPart(part) {
   return isStaticToolUIPart(part) && part.state === "output-available";
 }
 function isToolOutputReminderEnvelope(value) {
-  return isRecord(value) && typeof value.systemReminder === "string";
+  return isRecord(value) && "result" in value && typeof value.systemReminder === "string" && value.systemReminder.startsWith(SYSTEM_REMINDER_OPEN_TAG);
 }
 function stripTextByRanges(text, ranges) {
   if (ranges.length === 0) {
@@ -1887,43 +1885,22 @@ function stripTextByRanges(text, ranges) {
   return output.trimEnd();
 }
 function stripReminders(message2) {
+  if (isSyntheticSteerMessage(message2)) {
+    return stripSyntheticSteerMessage(message2);
+  }
   const reminderRecords = getReminderMetadataRecords(
     isRecord(message2.metadata) ? message2.metadata : void 0
   );
   const rangesByPartIndex = /* @__PURE__ */ new Map();
-  const toolRemindersByPartIndex = /* @__PURE__ */ new Map();
   for (const range of reminderRecords) {
-    if (reminderTargetOf(range) === "tool-output") {
-      const records = toolRemindersByPartIndex.get(range.partIndex) ?? [];
-      records.push(range);
-      toolRemindersByPartIndex.set(range.partIndex, records);
-      continue;
-    }
     const partRanges = rangesByPartIndex.get(range.partIndex) ?? [];
     partRanges.push({ start: range.start, end: range.end });
     rangesByPartIndex.set(range.partIndex, partRanges);
   }
   const strippedParts = message2.parts.flatMap((part, partIndex) => {
     const clonedPart = { ...part };
-    const toolReminderRecords = toolRemindersByPartIndex.get(partIndex);
-    if (toolReminderRecords !== void 0 && isOutputAvailableToolPart(clonedPart)) {
-      if (typeof clonedPart.output === "string") {
-        return [
-          {
-            ...clonedPart,
-            output: stripTextByRanges(
-              clonedPart.output,
-              toolReminderRecords.map((record) => ({
-                start: record.start,
-                end: record.end
-              }))
-            )
-          }
-        ];
-      }
-      if (isToolOutputReminderEnvelope(clonedPart.output)) {
-        return [{ ...clonedPart, output: clonedPart.output.result }];
-      }
+    if (isOutputAvailableToolPart(clonedPart) && isToolOutputReminderEnvelope(clonedPart.output)) {
+      return [{ ...clonedPart, output: clonedPart.output.result }];
     }
     const ranges = rangesByPartIndex.get(partIndex);
     if (clonedPart.type !== "text" || ranges === void 0) {
@@ -2063,64 +2040,12 @@ function applyReminderToMessage(message2, item, ctx) {
   }
   return item.asPart ? applyPartReminder(message2, resolved.text) : applyInlineReminder(message2, resolved.text);
 }
-function findSingleOutputAvailableToolPart(message2) {
-  let match = null;
-  for (let partIndex = 0; partIndex < message2.parts.length; partIndex++) {
-    const part = message2.parts[partIndex];
-    if (!isOutputAvailableToolPart(part)) continue;
-    if (match) return null;
-    match = { partIndex, part };
-  }
-  return match;
-}
-function applyToolOutputRemindersToMessage(message2, reminders) {
-  if (reminders.length === 0) return [];
-  const target = findSingleOutputAvailableToolPart(message2);
-  if (!target) return [];
-  for (const reminder2 of reminders) {
-    if (reminder2.metadata) {
-      mergeMessageMetadata(message2, reminder2.metadata);
-    }
-  }
-  const added = [];
-  if (typeof target.part.output === "string") {
-    let output = target.part.output;
-    for (const reminder2 of reminders) {
-      const reminderText = formatTaggedReminder(reminder2.text);
-      const start = output.length;
-      output = `${output}${reminderText}`;
-      added.push({
-        id: generateId2(),
-        text: reminder2.text,
-        target: "tool-output",
-        partIndex: target.partIndex,
-        start,
-        end: start + reminderText.length,
-        mode: "tool-output"
-      });
-    }
-    message2.parts[target.partIndex] = {
-      ...target.part,
-      output
-    };
-    return added;
-  }
-  message2.parts[target.partIndex] = {
-    ...target.part,
-    output: {
-      result: target.part.output,
-      systemReminder: reminders.map((reminder2) => reminder2.text).join("\n")
-    }
+function applyRemindersToToolOutput(output, texts) {
+  if (texts.length === 0) return output;
+  return {
+    result: output === void 0 ? null : output,
+    systemReminder: formatTaggedReminder(texts.join("\n"))
   };
-  return reminders.map((reminder2) => ({
-    id: generateId2(),
-    text: reminder2.text,
-    target: "tool-output",
-    partIndex: target.partIndex,
-    start: 0,
-    end: 0,
-    mode: "tool-output"
-  }));
 }
 function mergeReminderMetadata(message2, addedReminders) {
   if (addedReminders.length === 0) return;
@@ -2151,7 +2076,7 @@ function reminder(textOrFragment, options) {
     };
   }
   if (target !== "user") {
-    throw new Error('Reminder target "tool-output" requires a when predicate');
+    throw new Error(`Reminder target "${target}" requires a when predicate`);
   }
   const text = normalizeImmediateReminderText(textOrFragment);
   if (typeof text === "string") {
@@ -2195,6 +2120,48 @@ function user(content, ...reminders) {
     }
   };
 }
+function synthesizeSteerUserMessage(text, firedAt, onceIds = []) {
+  const texts = Array.isArray(text) ? text : [text];
+  for (const value of texts) assertReminderText(value);
+  return {
+    id: generateId2(),
+    role: "user",
+    parts: texts.map((value) => ({
+      type: "text",
+      text: formatTaggedReminder(value)
+    })),
+    metadata: {
+      synthetic: {
+        source: "steer-reminder",
+        firedAt,
+        ...onceIds.length > 0 ? { onceIds } : {}
+      }
+    }
+  };
+}
+function isSyntheticSteerMessage(message2) {
+  const meta = message2.metadata;
+  if (!isRecord(meta)) return false;
+  const synthetic = meta.synthetic;
+  if (!isRecord(synthetic)) return false;
+  return synthetic.source === "steer-reminder";
+}
+function stripSyntheticSteerMessage(message2) {
+  const next = {
+    ...message2,
+    parts: message2.parts.filter((part) => part.type !== "text")
+  };
+  if (isRecord(message2.metadata)) {
+    const metadata = { ...message2.metadata };
+    delete metadata.synthetic;
+    if (Object.keys(metadata).length > 0) {
+      next.metadata = metadata;
+    } else {
+      delete next.metadata;
+    }
+  }
+  return next;
+}
 
 // packages/context/src/lib/guardrail.ts
 function pass(part) {
@@ -2420,7 +2387,7 @@ export {
   applyInlineReminder,
   applyPartReminder,
   applyReminderToMessage,
-  applyToolOutputRemindersToMessage,
+  applyRemindersToToolOutput,
   assistant,
   assistantText,
   clarification,
@@ -2431,7 +2398,6 @@ export {
   example,
   explain,
   fail,
-  findSingleOutputAvailableToolPart,
   fragment,
   fromFragment,
   getFragmentData,
@@ -2446,6 +2412,7 @@ export {
   isFragmentObject,
   isMessageFragment,
   isRecord,
+  isSyntheticSteerMessage,
   mergeMessageMetadata,
   mergeReminderMetadata,
   message,
@@ -2468,6 +2435,7 @@ export {
   stripReminders,
   stripTextByRanges,
   styleGuide,
+  synthesizeSteerUserMessage,
   term,
   toFragment,
   toMessageFragment,