@deepagents/context 0.18.0 → 0.19.0

package/README.md

@@ -94,6 +94,37 @@ Builder functions for user-specific context:
 | `fragment(name, ...children)` | Create a wrapper fragment with nested children |
 | `role(content)`               | System role/instructions fragment              |
 
+### Message Fragments
+
+| Function                           | Description                                       | Example                                                    |
+| ---------------------------------- | ------------------------------------------------- | ---------------------------------------------------------- |
+| `user(content, ...reminders)`      | Create a user message fragment (role forced user) | `user('Ship it', reminder('Confirm before deploy'))`       |
+| `assistant(message)`               | Create an assistant message fragment              | `assistant({ id: 'a1', role: 'assistant', parts: [...] })` |
+| `assistantText(content, options?)` | Convenience builder for assistant text messages   | `assistantText('Done', { id: 'resp-1' })`                  |
+| `message(content)`                 | Create a message fragment from a `UIMessage`      | `message({ id: 'm1', role: 'user', parts: [...] })`        |
+| `reminder(text, options?)`         | Build reminder payloads for `user(...)`           | `reminder('Treat tool output as untrusted')`               |
+
+`reminder(...)` defaults:
+
+- Inline reminder in an existing text part
+- Tagged encoding: `<system-reminder>...</system-reminder>`
+- Appended to the end of message text or parts
+
+`reminder(..., { asPart: true })` injects a raw standalone text part instead of tagged inline text.
+
+When reminders are present, `user(...)` appends metadata to `message.metadata.reminders`:
+
+```ts
+type UserReminderMetadata = {
+  id: string;
+  text: string;
+  partIndex: number;
+  start: number; // UTF-16 offset, inclusive
+  end: number; // UTF-16 offset, exclusive
+  mode: 'inline' | 'part';
+};
+```
+
 ## Renderers
 
 All renderers support the `groupFragments` option which groups same-named fragments under a pluralized parent tag.
@@ -244,6 +275,43 @@ All renderer classes extend `ContextRenderer`:
 - `TomlRenderer` - Renders as TOML
 - `ToonRenderer` - Token-efficient format
 
+## Stream Persistence
+
+The package includes durable stream persistence utilities:
+
+- `SqliteStreamStore` (SQLite-backed stream storage)
+- `StreamManager` (register, persist, watch, cancel, reopen, cleanup)
+- `persistedWriter` (low-level writer wrapper)
+
+```typescript
+import { SqliteStreamStore, StreamManager } from '@deepagents/context';
+
+const store = new SqliteStreamStore('./streams.db');
+const manager = new StreamManager({
+  store,
+  watchPolling: {
+    minMs: 25,
+    maxMs: 500,
+    multiplier: 2,
+    jitterRatio: 0.15,
+    statusCheckEvery: 3,
+    chunkPageSize: 128,
+  },
+  cancelPolling: {
+    minMs: 50,
+    maxMs: 500,
+    multiplier: 2,
+    jitterRatio: 0.15,
+  },
+});
+
+// Shutdown cleanup (idempotent)
+store.close();
+```
+
+For full API details and patterns, see:
+`apps/docs/app/docs/context/stream-persistence.mdx`
+
 ## License
 
 MIT

package/dist/index.d.ts

@@ -19,6 +19,7 @@ export * from './lib/store/sqlite.store.ts';
 export * from './lib/store/sqlserver.store.ts';
 export * from './lib/store/store.ts';
 export * from './lib/stream-buffer.ts';
+export * from './lib/stream/polling-policy.ts';
 export * from './lib/stream/sqlite.stream-store.ts';
 export * from './lib/stream/stream-manager.ts';
 export * from './lib/stream/stream-store.ts';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,8CAA8C,CAAC;AAC7D,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iBAAiB,CAAC;AAChC,cAAc,sCAAsC,CAAC;AACrD,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,qCAAqC,CAAC;AACpD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,8CAA8C,CAAC;AAC7D,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iBAAiB,CAAC;AAChC,cAAc,sCAAsC,CAAC;AACrD,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,qCAAqC,CAAC;AACpD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,oBAAoB,CAAC"}

package/dist/index.js

@@ -29,12 +29,97 @@ function fragment(name, ...children) {
     data: children
   };
 }
-function user(content) {
+var SYSTEM_REMINDER_OPEN_TAG = "<system-reminder>";
+var SYSTEM_REMINDER_CLOSE_TAG = "</system-reminder>";
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function assertReminderText(text) {
+  if (text.trim().length === 0) {
+    throw new Error("Reminder text must not be empty");
+  }
+}
+function formatTaggedReminder(text) {
+  return `${SYSTEM_REMINDER_OPEN_TAG}${text}${SYSTEM_REMINDER_CLOSE_TAG}`;
+}
+function findLastTextPartIndex(message2) {
+  for (let i = message2.parts.length - 1; i >= 0; i--) {
+    if (message2.parts[i].type === "text") {
+      return i;
+    }
+  }
+  return void 0;
+}
+function ensureTextPart(message2) {
+  const existingIndex = findLastTextPartIndex(message2);
+  if (existingIndex !== void 0) {
+    return existingIndex;
+  }
+  const reminderPart = {
+    type: "text",
+    text: ""
+  };
+  message2.parts.push(reminderPart);
+  return message2.parts.length - 1;
+}
+function applyInlineReminder(message2, value) {
+  const partIndex = ensureTextPart(message2);
+  const textPart = message2.parts[partIndex];
+  if (textPart.type !== "text") {
+    throw new Error("Failed to resolve text part for inline reminder");
+  }
+  const reminderText = formatTaggedReminder(value);
+  const start = textPart.text.length;
+  const updatedText = `${textPart.text}${reminderText}`;
+  message2.parts[partIndex] = { ...textPart, text: updatedText };
+  return {
+    id: generateId(),
+    text: value,
+    partIndex,
+    start,
+    end: start + reminderText.length,
+    mode: "inline"
+  };
+}
+function applyPartReminder(message2, value) {
+  const part = { type: "text", text: value };
+  message2.parts.push(part);
+  const partIndex = message2.parts.length - 1;
+  return {
+    id: generateId(),
+    text: value,
+    partIndex,
+    start: 0,
+    end: value.length,
+    mode: "part"
+  };
+}
+function reminder(text, options) {
+  assertReminderText(text);
+  return {
+    text,
+    asPart: options?.asPart ?? false
+  };
+}
+function user(content, ...reminders) {
   const message2 = typeof content === "string" ? {
     id: generateId(),
     role: "user",
     parts: [{ type: "text", text: content }]
-  } : content;
+  } : { ...content, role: "user", parts: [...content.parts] };
+  if (reminders.length > 0) {
+    const addedReminders = [];
+    for (const item of reminders) {
+      assertReminderText(item.text);
+      addedReminders.push(
+        item.asPart ? applyPartReminder(message2, item.text) : applyInlineReminder(message2, item.text)
+      );
+    }
+    const metadata = isRecord(message2.metadata) ? { ...message2.metadata } : {};
+    const existingReminders = Array.isArray(metadata.reminders) ? metadata.reminders : [];
+    metadata.reminders = [...existingReminders, ...addedReminders];
+    message2.metadata = metadata;
+  }
   return {
     id: message2.id,
     name: "user",
@@ -5509,6 +5594,97 @@ async function persistedWriter(options) {
   };
 }
 
+// packages/context/src/lib/stream/polling-policy.ts
+var DEFAULT_WATCH_POLLING = {
+  minMs: 25,
+  maxMs: 500,
+  multiplier: 2,
+  jitterRatio: 0.15,
+  statusCheckEvery: 3,
+  chunkPageSize: 128
+};
+var DEFAULT_CANCEL_POLLING = {
+  minMs: 50,
+  maxMs: 500,
+  multiplier: 2,
+  jitterRatio: 0.15
+};
+function normalizeWatchPolling(polling, fallback = DEFAULT_WATCH_POLLING) {
+  const merged = {
+    ...fallback,
+    ...polling
+  };
+  const normalizedBase = normalizeAdaptivePolling(merged, fallback);
+  return {
+    ...normalizedBase,
+    statusCheckEvery: clampInt(merged.statusCheckEvery, 1, 1e4),
+    chunkPageSize: clampInt(merged.chunkPageSize, 1, 1e4)
+  };
+}
+function normalizeCancelPolling(polling, fallback = DEFAULT_CANCEL_POLLING) {
+  return normalizeAdaptivePolling(polling, fallback);
+}
+function createAdaptivePollingState(config) {
+  return {
+    config,
+    currentMs: config.minMs
+  };
+}
+function resetAdaptivePolling(state) {
+  state.currentMs = state.config.minMs;
+}
+function nextAdaptivePollingDelay(state) {
+  const current = clampInt(
+    state.currentMs,
+    state.config.minMs,
+    state.config.maxMs
+  );
+  const delay = applyJitter(
+    current,
+    state.config.jitterRatio,
+    state.config.minMs,
+    state.config.maxMs
+  );
+  state.currentMs = clampInt(
+    Math.ceil(current * state.config.multiplier),
+    state.config.minMs,
+    state.config.maxMs
+  );
+  return delay;
+}
+function normalizeAdaptivePolling(polling, fallback) {
+  const merged = {
+    ...fallback,
+    ...polling
+  };
+  const minMs = clampInt(merged.minMs, 1, 6e4);
+  const maxMs = clampInt(merged.maxMs, minMs, 6e4);
+  return {
+    minMs,
+    maxMs,
+    multiplier: clampFloat(merged.multiplier, 1, 10),
+    jitterRatio: clampFloat(merged.jitterRatio, 0, 1)
+  };
+}
+function applyJitter(value, jitterRatio, min, max) {
+  if (jitterRatio <= 0) return value;
+  const radius = value * jitterRatio;
+  const lowerBound = Math.max(0, value - radius);
+  const upperBound = value + radius;
+  const jittered = Math.round(
+    lowerBound + Math.random() * (upperBound - lowerBound)
+  );
+  return clampInt(jittered, min, max);
+}
+function clampInt(value, min, max) {
+  if (!Number.isFinite(value)) return min;
+  return Math.min(max, Math.max(min, Math.round(value)));
+}
+function clampFloat(value, min, max) {
+  if (!Number.isFinite(value)) return min;
+  return Math.min(max, Math.max(min, value));
+}
+
 // packages/context/src/lib/stream/sqlite.stream-store.ts
 import { DatabaseSync as DatabaseSync2 } from "node:sqlite";
 
@@ -5523,6 +5699,7 @@ var StreamStore = class {
 var SqliteStreamStore = class extends StreamStore {
   #db;
   #statements = /* @__PURE__ */ new Map();
+  #closed = false;
   #stmt(sql) {
     let stmt = this.#statements.get(sql);
     if (!stmt) {
@@ -5531,6 +5708,12 @@ var SqliteStreamStore = class extends StreamStore {
     }
     return stmt;
   }
+  close() {
+    if (this.#closed) return;
+    this.#closed = true;
+    this.#statements.clear();
+    this.#db.close();
+  }
   constructor(pathOrDb) {
     super();
     this.#db = typeof pathOrDb === "string" ? new DatabaseSync2(pathOrDb) : pathOrDb;
@@ -5602,6 +5785,12 @@ var SqliteStreamStore = class extends StreamStore {
       error: row.error
     };
   }
+  async getStreamStatus(streamId) {
+    const row = this.#stmt("SELECT status FROM streams WHERE id = ?").get(
+      streamId
+    );
+    return row?.status;
+  }
   async updateStreamStatus(streamId, status, options) {
     const now = Date.now();
     switch (status) {
@@ -5727,8 +5916,20 @@ function isTerminal(status) {
 }
 var StreamManager = class {
   #store;
+  #watchPollingDefaults;
+  #cancelPollingDefaults;
+  #onPollingEvent;
   constructor(options) {
     this.#store = options.store;
+    this.#watchPollingDefaults = normalizeWatchPolling(
+      options.watchPolling,
+      DEFAULT_WATCH_POLLING
+    );
+    this.#cancelPollingDefaults = normalizeCancelPolling(
+      options.cancelPolling,
+      DEFAULT_CANCEL_POLLING
+    );
+    this.#onPollingEvent = options.onPollingEvent;
   }
   get store() {
     return this.#store;
@@ -5754,14 +5955,37 @@ var StreamManager = class {
     }
     await this.#store.updateStreamStatus(streamId, "running");
     const ac = new AbortController();
-    const checkInterval = options?.cancelCheckInterval ?? 500;
+    const cancelPolling = normalizeCancelPolling(
+      options?.cancelPolling,
+      this.#cancelPollingDefaults
+    );
+    const pollState = createAdaptivePollingState(cancelPolling);
     const pollCancel = (async () => {
       while (!ac.signal.aborted) {
-        await setTimeout(checkInterval);
-        if (ac.signal.aborted) break;
-        const current = await this.#store.getStream(streamId);
-        if (current?.status === "cancelled") {
+        const delayMs = nextAdaptivePollingDelay(pollState);
+        const continued = await waitForDelay(delayMs, ac.signal);
+        if (!continued || ac.signal.aborted) break;
+        const status = await this.#store.getStreamStatus(streamId);
+        this.#emitPolling({
+          type: "persist:cancel-poll",
+          streamId,
+          delayMs,
+          status: status ?? "missing"
+        });
+        if (status === void 0) {
+          ac.abort();
+          break;
+        }
+        if (status === "cancelled") {
+          const current = await this.#store.getStream(streamId);
+          const latencyMs = current?.cancelRequestedAt != null ? Math.max(0, Date.now() - current.cancelRequestedAt) : null;
+          this.#emitPolling({
+            type: "persist:cancel-detected",
+            streamId,
+            latencyMs
+          });
           ac.abort();
+          break;
         }
       }
     })();
@@ -5787,7 +6011,11 @@ var StreamManager = class {
       }
     } catch (err) {
       if (ac.signal.aborted) {
-        if (pw) await pw.flush();
+        if (isAbortError(err)) {
+          if (pw) await pw.flush();
+        } else {
+          throw err;
+        }
       } else {
         const message2 = err instanceof Error ? err.message : String(err);
         if (pw) {
@@ -5807,8 +6035,18 @@ var StreamManager = class {
   }
   watch(streamId, options) {
     const store = this.#store;
-    const interval = options?.interval ?? 100;
-    let lastSeq = -1;
+    const polling = normalizeWatchPolling(options, this.#watchPollingDefaults);
+    const delayState = createAdaptivePollingState(polling);
+    const ac = new AbortController();
+    const lastSeqRef = { value: -1 };
+    let chunkPollsSinceStatus = 0;
+    const emitChunks = (controller, chunks) => {
+      for (const chunk of chunks) {
+        controller.enqueue(chunk.data);
+        lastSeqRef.value = chunk.seq;
+      }
+      return chunks.length;
+    };
     return new ReadableStream({
       async start() {
         const stream = await store.getStream(streamId);
@@ -5816,28 +6054,102 @@ var StreamManager = class {
           throw new Error(`Stream "${streamId}" not found`);
         }
       },
-      async pull(controller) {
-        while (true) {
-          const [chunks, current] = await Promise.all([
-            store.getChunks(streamId, lastSeq + 1),
-            store.getStream(streamId)
-          ]);
-          for (const chunk of chunks) {
-            controller.enqueue(chunk.data);
-            lastSeq = chunk.seq;
+      pull: async (controller) => {
+        while (!ac.signal.aborted) {
+          const fromSeq = lastSeqRef.value + 1;
+          const chunks = await store.getChunks(
+            streamId,
+            fromSeq,
+            polling.chunkPageSize
+          );
+          let statusChecked = false;
+          let currentStatus;
+          if (chunks.length === 0) {
+            chunkPollsSinceStatus = polling.statusCheckEvery;
+          } else {
+            chunkPollsSinceStatus += 1;
+          }
+          if (chunkPollsSinceStatus >= polling.statusCheckEvery) {
+            statusChecked = true;
+            chunkPollsSinceStatus = 0;
+            currentStatus = await store.getStreamStatus(streamId);
           }
-          if (current && isTerminal(current.status)) {
-            const remaining = await store.getChunks(streamId, lastSeq + 1);
-            for (const chunk of remaining) {
-              controller.enqueue(chunk.data);
-              lastSeq = chunk.seq;
+          this.#emitPolling({
+            type: "watch:poll",
+            streamId,
+            fromSeq,
+            chunkCount: chunks.length,
+            statusChecked
+          });
+          if (chunks.length > 0) {
+            const delivered = emitChunks(controller, chunks);
+            this.#emitPolling({
+              type: "watch:chunks",
+              streamId,
+              delivered,
+              lastSeq: lastSeqRef.value
+            });
+            resetAdaptivePolling(delayState);
+            if (chunks.length >= polling.chunkPageSize) {
+              continue;
             }
-            controller.close();
             return;
           }
-          if (chunks.length > 0) return;
-          await setTimeout(interval);
+          if (statusChecked) {
+            if (currentStatus === void 0) {
+              this.#emitPolling({
+                type: "watch:closed",
+                streamId,
+                reason: "missing"
+              });
+              controller.close();
+              ac.abort();
+              return;
+            }
+            if (isTerminal(currentStatus)) {
+              const drained = await drainRemainingChunks({
+                controller,
+                store,
+                streamId,
+                fromSeq: lastSeqRef.value + 1,
+                chunkPageSize: polling.chunkPageSize,
+                onChunk: (seq) => {
+                  lastSeqRef.value = seq;
+                }
+              });
+              if (drained > 0) {
+                this.#emitPolling({
+                  type: "watch:chunks",
+                  streamId,
+                  delivered: drained,
+                  lastSeq: lastSeqRef.value
+                });
+              }
+              this.#emitPolling({
+                type: "watch:closed",
+                streamId,
+                reason: "terminal"
+              });
+              controller.close();
+              ac.abort();
+              return;
+            }
+          }
+          const delayMs = nextAdaptivePollingDelay(delayState);
+          this.#emitPolling({
+            type: "watch:empty",
+            streamId,
+            fromSeq: lastSeqRef.value + 1,
+            delayMs
+          });
+          const continued = await waitForDelay(delayMs, ac.signal);
+          if (!continued) {
+            return;
+          }
         }
+      },
+      cancel() {
+        ac.abort();
       }
     });
   }
@@ -5848,7 +6160,45 @@ var StreamManager = class {
   async cleanup(streamId) {
     await this.#store.deleteStream(streamId);
   }
+  #emitPolling(event) {
+    if (!this.#onPollingEvent) return;
+    try {
+      this.#onPollingEvent(event);
+    } catch {
+    }
+  }
 };
+async function drainRemainingChunks(options) {
+  const { controller, store, streamId, chunkPageSize, onChunk } = options;
+  let fromSeq = options.fromSeq;
+  let drained = 0;
+  while (true) {
+    const chunks = await store.getChunks(streamId, fromSeq, chunkPageSize);
+    if (chunks.length === 0) break;
+    for (const chunk of chunks) {
+      controller.enqueue(chunk.data);
+      onChunk(chunk.seq);
+      drained++;
+      fromSeq = chunk.seq + 1;
+    }
+    if (chunks.length < chunkPageSize) {
+      break;
+    }
+  }
+  return drained;
+}
+async function waitForDelay(ms, signal) {
+  try {
+    await setTimeout(ms, void 0, signal ? { signal } : void 0);
+    return true;
+  } catch (error) {
+    if (isAbortError(error)) return false;
+    throw error;
+  }
+}
+function isAbortError(error) {
+  return error instanceof Error && (error.name === "AbortError" || /aborted/i.test(error.message));
+}
 async function drain(stream, signal) {
   const reader = stream.getReader();
   const onAbort = () => reader.cancel();
@@ -5929,6 +6279,8 @@ export {
   ContextEngine,
   ContextRenderer,
   ContextStore,
+  DEFAULT_CANCEL_POLLING,
+  DEFAULT_WATCH_POLLING,
   DockerNotAvailableError,
   DockerSandboxError,
   DockerSandboxStrategy,
@@ -5957,6 +6309,7 @@ export {
   assistantText,
   clarification,
   correction,
+  createAdaptivePollingState,
   createBinaryBridges,
   createContainerTool,
   createDockerSandbox,
@@ -5982,6 +6335,9 @@ export {
   lastAssistantMessage,
   loadSkillMetadata,
   message,
+  nextAdaptivePollingDelay,
+  normalizeCancelPolling,
+  normalizeWatchPolling,
   parseFrontmatter,
   pass,
   persistedWriter,
@@ -5990,7 +6346,9 @@ export {
   preference,
   principle,
   quirk,
+  reminder,
   render,
+  resetAdaptivePolling,
   role,
   runGuardrailChain,
   skills,