@deepagents/context 3.1.0 → 4.0.0

package/README.md

@@ -49,26 +49,59 @@ deletes the underlying Daytona sandbox.
 
 ### File-change tracking
 
-`createBashTool` reports what each tool call mutated as a `FileChange[]`
+`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 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).
+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 sandbox = await createBashTool({
-  sandbox: await createDockerSandbox({ image: 'my-image-with-strace' }),
+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 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, …):
+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
@@ -78,8 +111,8 @@ satisfy, on any non-virtual backend (Docker, Daytona, e2b, …):
    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.
+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

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 [];
@@ -1828,27 +1833,6 @@ function normalizeReminderTarget(target) {
   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;
 }
@@ -2057,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 (target !== "user") {
+  if (options?.when === void 0 && target !== "user") {
     throw new Error(`Reminder target "${target}" 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",
@@ -2120,6 +2082,16 @@ 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);
@@ -2388,6 +2360,7 @@ export {
   applyPartReminder,
   applyReminderToMessage,
   applyRemindersToToolOutput,
+  applyUserRemindersToMessage,
   assistant,
   assistantText,
   clarification,
@@ -2402,6 +2375,7 @@ export {
   fromFragment,
   getFragmentData,
   getModelsRegistry,
+  getReminderOnceIds,
   getReminderRanges,
   glossary,
   guardrail,