@deepagents/context 0.18.0 → 0.20.0

package/dist/index.js

@@ -29,28 +29,6 @@ function fragment(name, ...children) {
     data: children
   };
 }
-function user(content) {
-  const message2 = typeof content === "string" ? {
-    id: generateId(),
-    role: "user",
-    parts: [{ type: "text", text: content }]
-  } : content;
-  return {
-    id: message2.id,
-    name: "user",
-    data: "content",
-    type: "message",
-    persist: true,
-    codec: {
-      decode() {
-        return message2;
-      },
-      encode() {
-        return message2;
-      }
-    }
-  };
-}
 function assistant(message2) {
   return {
     id: message2.id,
@@ -2277,6 +2255,145 @@ function policy(input) {
   };
 }
 
+// packages/context/src/lib/fragments/message/user.ts
+import { generateId as generateId3 } from "ai";
+var SYSTEM_REMINDER_OPEN_TAG = "<system-reminder>";
+var SYSTEM_REMINDER_CLOSE_TAG = "</system-reminder>";
+function getReminderRanges(metadata) {
+  return metadata?.reminders ?? [];
+}
+function stripTextByRanges(text, ranges) {
+  if (ranges.length === 0) {
+    return text;
+  }
+  const normalized = ranges.map((range) => ({
+    start: Math.max(0, Math.min(text.length, range.start)),
+    end: Math.max(0, Math.min(text.length, range.end))
+  })).filter((range) => range.end > range.start).sort((a, b) => a.start - b.start);
+  if (normalized.length === 0) {
+    return text;
+  }
+  let cursor = 0;
+  let output = "";
+  for (const range of normalized) {
+    if (range.start < cursor) {
+      if (range.end > cursor) {
+        cursor = range.end;
+      }
+      continue;
+    }
+    output += text.slice(cursor, range.start);
+    cursor = range.end;
+  }
+  output += text.slice(cursor);
+  return output.trimEnd();
+}
+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: generateId3(),
+    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: generateId3(),
+    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: generateId3(),
+    role: "user",
+    parts: [{ type: "text", text: 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",
+    data: "content",
+    type: "message",
+    persist: true,
+    codec: {
+      decode() {
+        return message2;
+      },
+      encode() {
+        return message2;
+      }
+    }
+  };
+}
+
 // packages/context/src/lib/fragments/user.ts
 function identity(input) {
   return {
@@ -5509,6 +5626,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 +5731,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 +5740,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 +5817,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 +5948,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 +5987,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 +6043,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 +6067,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 +6086,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 +6192,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 +6311,8 @@ export {
   ContextEngine,
   ContextRenderer,
   ContextStore,
+  DEFAULT_CANCEL_POLLING,
+  DEFAULT_WATCH_POLLING,
   DockerNotAvailableError,
   DockerSandboxError,
   DockerSandboxStrategy,
@@ -5957,6 +6341,7 @@ export {
   assistantText,
   clarification,
   correction,
+  createAdaptivePollingState,
   createBinaryBridges,
   createContainerTool,
   createDockerSandbox,
@@ -5969,6 +6354,7 @@ export {
   fail,
   fragment,
   getModelsRegistry,
+  getReminderRanges,
   glossary,
   guardrail,
   hint,
@@ -5982,6 +6368,9 @@ export {
   lastAssistantMessage,
   loadSkillMetadata,
   message,
+  nextAdaptivePollingDelay,
+  normalizeCancelPolling,
+  normalizeWatchPolling,
   parseFrontmatter,
   pass,
   persistedWriter,
@@ -5990,12 +6379,15 @@ export {
   preference,
   principle,
   quirk,
+  reminder,
   render,
+  resetAdaptivePolling,
   role,
   runGuardrailChain,
   skills,
   soul,
   stop,
+  stripTextByRanges,
   structuredOutput,
   styleGuide,
   term,