@deepagents/context 0.39.0 → 1.0.0

package/README.md

@@ -1,10 +1,10 @@
 # @deepagents/context
 
-A domain-agnostic context system for LLM applications, including fragment rendering, persistence, chat orchestration, and portable sandbox tooling.
+A domain-agnostic context system for LLM applications, including fragment rendering, persistence, chat orchestration, and sandbox tooling.
 
 ## Overview
 
-This package provides a flexible way to compose and render context in multiple formats (XML, Markdown, TOML, TOON), persist conversations, orchestrate chat flows, and expose portable host-side command surfaces. Context fragments are structured units that can be transformed into different prompt representations for different LLM styles.
+This package provides a flexible way to compose and render context in multiple formats (XML, Markdown, TOML, TOON), persist conversations, orchestrate chat flows, and run real sandbox commands. Context fragments are structured units that can be transformed into different prompt representations for different LLM styles.
 
 ## Installation
 
@@ -26,19 +26,16 @@ like store implementations, sandbox tooling, and filesystem-based skill loading.
 ## Sandbox Tooling
 
 The server-side package also ships the sandbox primitives used by
-`@deepagents/text2sql` and other tool-driven agents. Use
-`createRoutingSandbox({ backend, hostExtensions })` to run the same host
-commands across virtual, Docker, or Agent OS backends.
-
-If an upstream service already has an OpenAPI description,
-`createOpenAPIExtension({ name, openapi, ... })` turns it into a portable
-`SandboxExtension` with validated subcommands and a built-in `schema`
-introspection command.
+`@deepagents/text2sql` and other tool-driven agents. Use `createBashTool()`
+with `createVirtualSandbox()`, `createContainerTool()`, `createDockerSandbox()`,
+or `createAgentOsSandbox()` depending on whether commands should run in memory,
+Docker, or Agent OS.
 
 See the docs for the full API surface:
 
-- [Routing Sandbox](https://januarylabs.github.io/deepagents/docs/context/routing-sandbox)
 - [Sandbox](https://januarylabs.github.io/deepagents/docs/context/sandbox)
+- [Container Tool](https://januarylabs.github.io/deepagents/docs/context/container-tool)
+- [Subcommand Builders](https://januarylabs.github.io/deepagents/docs/context/subcommand)
 
 ## Basic Usage
 
@@ -218,6 +215,42 @@ const messageWithoutReminders = stripReminders(message);
 ```
 
 - `getReminderRanges(metadata)` returns `metadata.reminders` as offset ranges (or `[]` when missing).
+
+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:
+
+```ts
+import {
+  anyToolCalled,
+  everyOfLastN,
+  not,
+  reminder,
+  toolCalled,
+  usageExceeds,
+  user,
+} from '@deepagents/context';
+
+engine.set(
+  reminder('Ask for confirmation before repeating destructive tool calls', {
+    when: toolCalled('bash'),
+  }),
+  reminder('Pause and summarize if the thread is getting expensive', {
+    when: usageExceeds(20_000),
+  }),
+  reminder('If no tools were needed for three turns, keep the answer brief', {
+    when: everyOfLastN(3, not(anyToolCalled())),
+  }),
+  user('continue'),
+);
+```
+
+Other exported helpers include `toolCallCount(...)`,
+`lastAssistantLength(...)`, `withinLastN(...)`, `everyOfLastN(...)`, and
+`elapsedExceeds(...)`. See the
+[Predicates](https://januarylabs.github.io/deepagents/docs/context/predicates)
+page for the full catalog.
+
 - `stripTextByRanges(text, ranges)` removes offset spans from text and returns the remaining visible content.
 - `stripReminders(message)` strips inline/part reminders from a `UIMessage` and removes `metadata.reminders`.
 - Reminder ranges are local to a message part, so filter by `partIndex` before stripping a specific part's text.

package/dist/browser.js

@@ -4,7 +4,12 @@ function isFragment(data) {
   return typeof data === "object" && data !== null && "name" in data && ("data" in data || "codec" in data) && typeof data.name === "string";
 }
 function isFragmentObject(data) {
-  return typeof data === "object" && data !== null && !Array.isArray(data) && !isFragment(data);
+  if (typeof data !== "object" || data === null) return false;
+  if (Array.isArray(data)) return false;
+  if (data instanceof Promise) return false;
+  if (Symbol.asyncIterator in data || Symbol.iterator in data) return false;
+  if (isFragment(data)) return false;
+  return true;
 }
 function isMessageFragment(fragment2) {
   return fragment2.type === "message";
@@ -890,7 +895,10 @@ async function estimate(modelId, renderer, ...fragments) {
 }
 
 // packages/context/src/lib/fragments/message/user.ts
-import { generateId as generateId2 } from "ai";
+import {
+  generateId as generateId2,
+  isStaticToolUIPart
+} from "ai";
 
 // packages/context/src/lib/renderers/abstract.renderer.ts
 import pluralize from "pluralize";
@@ -1784,7 +1792,56 @@ function isConditionalReminder(fragment2) {
 var SYSTEM_REMINDER_OPEN_TAG = "<system-reminder>";
 var SYSTEM_REMINDER_CLOSE_TAG = "</system-reminder>";
 function getReminderRanges(metadata) {
-  return metadata?.reminders ?? [];
+  return getReminderMetadataRecords(metadata).map((record) => ({
+    partIndex: record.partIndex,
+    start: record.start,
+    end: record.end
+  }));
+}
+function getReminderMetadataRecords(metadata) {
+  const reminders = metadata?.reminders;
+  if (!Array.isArray(reminders)) return [];
+  return reminders.filter(
+    (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";
+  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;
+}
+function isOutputAvailableToolPart(part) {
+  return isStaticToolUIPart(part) && part.state === "output-available";
+}
+function isToolOutputReminderEnvelope(value) {
+  return isRecord(value) && typeof value.systemReminder === "string";
 }
 function stripTextByRanges(text, ranges) {
   if (ranges.length === 0) {
@@ -1813,17 +1870,44 @@ function stripTextByRanges(text, ranges) {
   return output.trimEnd();
 }
 function stripReminders(message2) {
-  const reminderRanges = getReminderRanges(
+  const reminderRecords = getReminderMetadataRecords(
     isRecord(message2.metadata) ? message2.metadata : void 0
   );
   const rangesByPartIndex = /* @__PURE__ */ new Map();
-  for (const range of reminderRanges) {
+  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 }];
+      }
+    }
     const ranges = rangesByPartIndex.get(partIndex);
     if (clonedPart.type !== "text" || ranges === void 0) {
       return [clonedPart];
@@ -1893,6 +1977,7 @@ function applyInlineReminder(message2, value) {
   return {
     id: generateId2(),
     text: value,
+    target: "user",
     partIndex,
     start,
     end: start + reminderText.length,
@@ -1906,6 +1991,7 @@ function applyPartReminder(message2, value) {
   return {
     id: generateId2(),
     text: value,
+    target: "user",
     partIndex,
     start: 0,
     end: value.length,
@@ -1960,6 +2046,65 @@ 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")
+    }
+  };
+  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;
   const metadata = isRecord(message2.metadata) ? { ...message2.metadata } : {};
@@ -1968,28 +2113,37 @@ function mergeReminderMetadata(message2, addedReminders) {
   message2.metadata = metadata;
 }
 function reminder(textOrFragment, options) {
-  const fromFragment2 = isFragment(textOrFragment);
-  const text = fromFragment2 ? new XmlRenderer().render([textOrFragment]) : textOrFragment;
-  if (typeof text === "string") {
-    assertReminderText(text);
-  }
-  const asPart = options?.asPart ?? false;
-  if (options && "when" in options && options.when) {
+  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,
+          text: text2,
           when: options.when,
-          asPart
+          asPart,
+          target
         }
       }
     };
   }
+  if (target !== "user") {
+    throw new Error('Reminder target "tool-output" requires a when predicate');
+  }
+  const text = normalizeImmediateReminderText(textOrFragment);
+  if (typeof text === "string") {
+    assertReminderText(text);
+  }
   return {
     text,
-    asPart
+    asPart,
+    target
   };
 }
 function user(content, ...reminders) {
@@ -2215,6 +2369,7 @@ export {
   applyInlineReminder,
   applyPartReminder,
   applyReminderToMessage,
+  applyToolOutputRemindersToMessage,
   assistant,
   assistantText,
   clarification,
@@ -2224,6 +2379,7 @@ export {
   example,
   explain,
   fail,
+  findSingleOutputAvailableToolPart,
   fragment,
   fromFragment,
   getFragmentData,