@deepagents/context 3.1.0 → 4.1.0

package/README.md

@@ -27,14 +27,15 @@ 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
-`createDaytonaSandbox(client, options)`, or `createAgentOsSandbox()` depending
-on whether commands should run in memory, Docker, managed Daytona sandboxes, or
-Agent OS.
+with `createVirtualSandbox()`, `createDockerSandbox()`,
+`createAppleContainerSandbox()`, `createDaytonaSandbox(client, options)`, or
+`createAgentOsSandbox()` depending on whether commands should run in memory,
+Docker, Apple Container lightweight VMs, managed Daytona sandboxes, or Agent OS.
 
 See the docs for the full API surface:
 
 - [Sandbox](https://januarylabs.github.io/deepagents/docs/context/sandbox)
+- [Apple Container Sandbox](https://januarylabs.github.io/deepagents/docs/context/apple-container-sandbox)
 - [Subcommand Builders](https://januarylabs.github.io/deepagents/docs/context/subcommand)
 - [GCS Cloud Storage Volumes](https://januarylabs.github.io/deepagents/docs/context/recipes/gcs-cloud-storage)
 
@@ -49,37 +50,74 @@ 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 inside the sandbox 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.
+await selfTestStrace();
+```
+
+The `@deepagents/context/sandbox/strace` subpath is a small Node-runtime leaf
+(probe + parser + `StraceUnavailableError`) with no agent/context-framework
+imports, so a minimal daemon or bundled probe can import it without pulling the
+whole framework. If the host process owns only a remote `DisposableSandbox`,
+bundle this leaf entry with a tiny driver, write it into the sandbox, and run it
+there with `node`.
+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, Apple Container,
+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
+2. `ptrace` permitted by the runtime — the default on Docker, Apple Container,
+   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.
+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;
 }
@@ -1856,7 +1840,7 @@ function isOutputAvailableToolPart(part) {
   return isStaticToolUIPart(part) && part.state === "output-available";
 }
 function isToolOutputReminderEnvelope(value) {
-  return isRecord(value) && "result" in value && typeof value.systemReminder === "string" && value.systemReminder.startsWith(SYSTEM_REMINDER_OPEN_TAG);
+  return isRecord(value) && isRecord(value.meta) && value.meta.reminder === true && "result" in value && typeof value.systemReminder === "string";
 }
 function stripTextByRanges(text, ranges) {
   if (ranges.length === 0) {
@@ -1979,7 +1963,8 @@ function applyInlineReminder(message2, value) {
   };
 }
 function applyPartReminder(message2, value) {
-  const part = { type: "text", text: value };
+  const reminderText = formatTaggedReminder(value);
+  const part = { type: "text", text: reminderText };
   message2.parts.push(part);
   const partIndex = message2.parts.length - 1;
   return {
@@ -1988,13 +1973,10 @@ function applyPartReminder(message2, value) {
     target: "user",
     partIndex,
     start: 0,
-    end: value.length,
+    end: reminderText.length,
     mode: "part"
   };
 }
-function resolveReminderText(item, ctx) {
-  return resolveReminder(item, ctx)?.text ?? "";
-}
 function normalizeReminderResolution(value) {
   if (typeof value === "string") {
     return value.trim().length === 0 ? null : { text: value };
@@ -2044,7 +2026,19 @@ function applyRemindersToToolOutput(output, texts) {
   if (texts.length === 0) return output;
   return {
     result: output === void 0 ? null : output,
-    systemReminder: formatTaggedReminder(texts.join("\n"))
+    systemReminder: formatTaggedReminder(texts.join("\n")),
+    meta: { reminder: true }
+  };
+}
+function toToolReminderModelOutput(output, projectResult) {
+  if (!isToolOutputReminderEnvelope(output)) return null;
+  const projected = projectResult(output.result);
+  return {
+    type: "json",
+    value: {
+      result: isRecord(projected) ? projected.value : projected,
+      systemReminder: output.systemReminder
+    }
   };
 }
 function mergeReminderMetadata(message2, addedReminders) {
@@ -2057,54 +2051,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 +2092,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 +2370,7 @@ export {
   applyPartReminder,
   applyReminderToMessage,
   applyRemindersToToolOutput,
+  applyUserRemindersToMessage,
   assistant,
   assistantText,
   clarification,
@@ -2402,6 +2385,7 @@ export {
   fromFragment,
   getFragmentData,
   getModelsRegistry,
+  getReminderOnceIds,
   getReminderRanges,
   glossary,
   guardrail,
@@ -2427,7 +2411,6 @@ export {
   render,
   resolveReminder,
   resolveReminderAsync,
-  resolveReminderText,
   role,
   runGuardrailChain,
   soul,
@@ -2439,6 +2422,7 @@ export {
   term,
   toFragment,
   toMessageFragment,
+  toToolReminderModelOutput,
   user,
   visualizeGraph,
   workflow