@deepagents/context 3.0.1 → 4.0.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,83 @@ 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
+
+`withStraceFileChanges()` decorates a real sandbox backend so each command,
+spawn, or file write reports the mutations it caused as a `FileChange[]`
+(`{ op: 'write' | 'delete' | 'rename'; path; from?; timestamp }`).
+Consume changes via the `onFileChanges` callback (fires per command, spawn, or
+`writeFiles` call). Bash tool calls also receive
+`tool-result.output.meta.fileChanges` as hidden host-only metadata.
+
+Scope which paths are reported with `include` glob patterns (required — a path
+must match at least one); drop noise such as uploaded skills with optional
+`exclude` patterns. Both match absolute paths via Node's `path.matchesGlob`.
+
+```ts
+const backend = await createDockerSandbox({ image: 'my-image-with-strace' });
+const tracked = await withStraceFileChanges(backend, {
+  include: ['/workspace/**', '/workspace'],
+  onFileChanges: (changes) => {
+    for (const c of changes) console.log(`${c.op} ${c.path}`);
+  },
+});
+const sandbox = await createBashTool({
+  sandbox: tracked,
+  destination: '/workspace',
+});
+```
+
+Tracking uses `strace` (per `executeCommand` and per `spawn`) when you compose
+the `withStraceFileChanges()` decorator. The decorator itself does **no**
+self-test — it trusts that strace tracing works in the sandbox, because "strace
+works here" is an invariant of the (image + host kernel + seccomp/caps) that is
+constant for the container's lifetime. Re-proving it per composition would re-pay
+several host→container round-trips on every tool call for no new information.
+
+Verifying the invariant is the consumer's **once-per-container** responsibility.
+Run the probe once at startup (e.g. a daemon boot gate) via the lean leaf entry:
+
+```ts
+import { selfTestStrace } from '@deepagents/context/sandbox/strace';
+
+// Throws StraceUnavailableError (reason: 'strace-missing' | 'ptrace-blocked' |
+// 'trace-unparseable') with no silent fallback. A DisposableSandbox satisfies
+// the StraceHost shape structurally, so pass a real backend unchanged; an
+// in-process caller implements just { executeCommand, readFile }.
+await selfTestStrace(backend);
+```
+
+The `@deepagents/context/sandbox/strace` subpath is a node-builtins-only bundle
+(probe + parser + `StraceUnavailableError`) with no agent/context-framework
+imports, so a minimal daemon can import it without pulling the whole framework.
+Import `StraceUnavailableError` from this same subpath when catching the probe's
+error (each entry point is bundled independently, so `instanceof` requires the
+class from the same entry).
+
+The backend must 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 `withStraceFileChanges()` — `selfTestStrace` hard-fails
+against it. 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 +272,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 +301,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 +310,7 @@ import {
   everyOfLastN,
   not,
   reminder,
+  streamStepsExceed,
   toolCalled,
   usageExceeds,
   user,
@@ -239,9 +320,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 +340,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

@@ -1815,6 +1815,11 @@ function getReminderRanges(metadata) {
     end: record.end
   }));
 }
+function getReminderOnceIds(message2) {
+  const meta = message2.metadata;
+  if (!isRecord(meta) || !Array.isArray(meta.onceIds)) return [];
+  return meta.onceIds.filter((id) => typeof id === "string");
+}
 function getReminderMetadataRecords(metadata) {
   const reminders = metadata?.reminders;
   if (!Array.isArray(reminders)) return [];
@@ -1822,35 +1827,12 @@ 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) {
-  return options !== void 0 && "when" in options;
-}
-function isPromiseLike(value) {
-  return (typeof value === "object" || typeof value === "function") && value !== null && "then" in value && typeof value.then === "function";
-}
-function normalizeImmediateReminderText(textOrFragment) {
-  if (isFragment(textOrFragment)) {
-    return new XmlRenderer().render([textOrFragment]);
-  }
-  if (typeof textOrFragment === "string") {
-    return textOrFragment;
-  }
-  return (ctx) => {
-    const resolved = textOrFragment(ctx);
-    if (isPromiseLike(resolved)) {
-      throw new Error("Async reminder text requires a when predicate");
-    }
-    return resolved;
-  };
-}
 function normalizeConditionalReminderText(textOrFragment) {
   return isFragment(textOrFragment) ? new XmlRenderer().render([textOrFragment]) : textOrFragment;
 }
@@ -1858,7 +1840,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 +1869,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 +2024,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;
@@ -2132,54 +2041,32 @@ function mergeReminderMetadata(message2, addedReminders) {
 function reminder(textOrFragment, options) {
   const target = normalizeReminderTarget(options?.target);
   const asPart = target === "user" ? options?.asPart ?? false : false;
-  if (isConditionalReminderOptions(options)) {
-    const text2 = normalizeConditionalReminderText(textOrFragment);
-    if (typeof text2 === "string") {
-      assertReminderText(text2);
-    }
-    return {
-      name: "reminder",
-      data: null,
-      metadata: {
-        reminder: {
-          text: text2,
-          when: options.when,
-          asPart,
-          target
-        }
-      }
-    };
+  if (options?.when === void 0 && target !== "user") {
+    throw new Error(`Reminder target "${target}" requires a when predicate`);
   }
-  if (target !== "user") {
-    throw new Error('Reminder target "tool-output" requires a when predicate');
-  }
-  const text = normalizeImmediateReminderText(textOrFragment);
+  const text = normalizeConditionalReminderText(textOrFragment);
   if (typeof text === "string") {
     assertReminderText(text);
   }
   return {
-    text,
-    asPart,
-    target
+    name: "reminder",
+    data: null,
+    metadata: {
+      reminder: {
+        text,
+        when: options?.when ?? (() => true),
+        asPart,
+        target
+      }
+    }
   };
 }
-function user(content, ...reminders) {
+function user(content) {
   const message2 = typeof content === "string" ? {
     id: generateId2(),
     role: "user",
     parts: [{ type: "text", text: content }]
   } : { ...content, role: "user", parts: [...content.parts] };
-  if (reminders.length > 0) {
-    const plainText = extractPlainText(message2);
-    const added = [];
-    for (const item of reminders) {
-      const meta = applyReminderToMessage(message2, item, {
-        content: plainText
-      });
-      if (meta) added.push(meta);
-    }
-    mergeReminderMetadata(message2, added);
-  }
   return {
     id: message2.id,
     name: "user",
@@ -2195,6 +2082,58 @@ function user(content, ...reminders) {
     }
   };
 }
+function applyUserRemindersToMessage(message2, reminders) {
+  if (reminders.length === 0) return;
+  const plainText = extractPlainText(message2);
+  const added = [];
+  for (const item of reminders) {
+    const meta = applyReminderToMessage(message2, item, { content: plainText });
+    if (meta) added.push(meta);
+  }
+  mergeReminderMetadata(message2, added);
+}
+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 +2359,8 @@ export {
   applyInlineReminder,
   applyPartReminder,
   applyReminderToMessage,
-  applyToolOutputRemindersToMessage,
+  applyRemindersToToolOutput,
+  applyUserRemindersToMessage,
   assistant,
   assistantText,
   clarification,
@@ -2431,11 +2371,11 @@ export {
   example,
   explain,
   fail,
-  findSingleOutputAvailableToolPart,
   fragment,
   fromFragment,
   getFragmentData,
   getModelsRegistry,
+  getReminderOnceIds,
   getReminderRanges,
   glossary,
   guardrail,
@@ -2446,6 +2386,7 @@ export {
   isFragmentObject,
   isMessageFragment,
   isRecord,
+  isSyntheticSteerMessage,
   mergeMessageMetadata,
   mergeReminderMetadata,
   message,
@@ -2468,6 +2409,7 @@ export {
   stripReminders,
   stripTextByRanges,
   styleGuide,
+  synthesizeSteerUserMessage,
   term,
   toFragment,
   toMessageFragment,