@deepagents/context 0.29.1 → 0.31.0

package/dist/index.d.ts

@@ -7,6 +7,7 @@ export * from './lib/engine.ts';
 export * from './lib/estimate.ts';
 export * from './lib/fragments.ts';
 export * from './lib/fragments/domain.ts';
+export * from './lib/fragments/message/environment-reminder.ts';
 export * from './lib/fragments/message/user.ts';
 export * from './lib/fragments/reasoning.ts';
 export * from './lib/fragments/user.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,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,iCAAiC,CAAC;AAChD,cAAc,qCAAqC,CAAC;AACpD,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iCAAiC,CAAC;AAChD,cAAc,8BAA8B,CAAC;AAC7C,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,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,iCAAiC,CAAC;AAChD,cAAc,qCAAqC,CAAC;AACpD,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iDAAiD,CAAC;AAChE,cAAc,iCAAiC,CAAC;AAChD,cAAc,8BAA8B,CAAC;AAC7C,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,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC"}

package/dist/index.js

@@ -426,7 +426,7 @@ import {
 import { z } from "zod";
 
 // packages/context/src/lib/engine.ts
-import { isTextUIPart as isTextUIPart2, validateUIMessages } from "ai";
+import { validateUIMessages } from "ai";
 import { mergeWith } from "lodash-es";
 
 // packages/context/src/lib/estimate.ts
@@ -753,14 +753,45 @@ function applyPartReminder(message2, value) {
   };
 }
 function resolveReminderText(item, ctx) {
-  return typeof item.text === "function" ? item.text(ctx) : item.text;
+  return resolveReminder(item, ctx)?.text ?? "";
+}
+function normalizeReminderResolution(value) {
+  if (typeof value === "string") {
+    return value.trim().length === 0 ? null : { text: value };
+  }
+  if (value.text.trim().length === 0) {
+    return null;
+  }
+  return value;
+}
+function resolveReminder(item, ctx) {
+  const resolvedText = typeof item.text === "function" ? item.text(ctx) : item.text;
+  const resolved = normalizeReminderResolution(resolvedText);
+  if (!resolved) {
+    return null;
+  }
+  const metadata = item.metadata || resolved.metadata ? {
+    ...item.metadata ?? {},
+    ...resolved.metadata ?? {}
+  } : void 0;
+  return metadata ? { ...resolved, metadata } : resolved;
+}
+function mergeMessageMetadata(message2, addedMetadata) {
+  if (Object.keys(addedMetadata).length === 0) {
+    return;
+  }
+  const metadata = isRecord(message2.metadata) ? { ...message2.metadata } : {};
+  message2.metadata = { ...metadata, ...addedMetadata };
 }
 function applyReminderToMessage(message2, item, ctx) {
-  const resolvedText = resolveReminderText(item, ctx);
-  if (resolvedText.trim().length === 0) {
+  const resolved = resolveReminder(item, ctx);
+  if (!resolved) {
     return null;
   }
-  return item.asPart ? applyPartReminder(message2, resolvedText) : applyInlineReminder(message2, resolvedText);
+  if (resolved.metadata) {
+    mergeMessageMetadata(message2, resolved.metadata);
+  }
+  return item.asPart ? applyPartReminder(message2, resolved.text) : applyInlineReminder(message2, resolved.text);
 }
 function mergeReminderMetadata(message2, addedReminders) {
   if (addedReminders.length === 0) return;
@@ -798,14 +829,14 @@ function user(content, ...reminders) {
   } : { ...content, role: "user", parts: [...content.parts] };
   if (reminders.length > 0) {
     const plainText = extractPlainText(message2);
-    const addedReminders = [];
+    const added = [];
     for (const item of reminders) {
       const meta = applyReminderToMessage(message2, item, {
         content: plainText
       });
-      if (meta) addedReminders.push(meta);
+      if (meta) added.push(meta);
     }
-    mergeReminderMetadata(message2, addedReminders);
+    mergeReminderMetadata(message2, added);
   }
   return {
     id: message2.id,
@@ -1721,6 +1752,14 @@ var ContextEngine = class {
   #initialized = false;
   /** Initial metadata to merge on first initialization */
   #initialMetadata;
+  get #activeBranch() {
+    if (!this.#branch) {
+      throw new Error(
+        "Branch not initialized. Call #ensureInitialized() first."
+      );
+    }
+    return this.#branch;
+  }
   get #renderableFragments() {
     return this.#fragments.filter((f) => !isConditionalReminder(f));
   }
@@ -1757,7 +1796,13 @@ var ContextEngine = class {
       });
       this.#initialMetadata = void 0;
     }
-    this.#branch = await this.#store.getActiveBranch(this.#chatId);
+    const branch = await this.#store.getActiveBranch(this.#chatId);
+    if (!branch) {
+      throw new Error(
+        `Active branch not found for chat "${this.#chatId}" after upsertChat`
+      );
+    }
+    this.#branch = branch;
     this.#initialized = true;
   }
   /**
@@ -1841,30 +1886,35 @@ var ContextEngine = class {
     };
   }
   /**
-   * Count user+assistant message pairs (turns) in the conversation.
-   * Includes persisted messages and pending messages.
-   * A turn is one user message paired with one assistant message.
-   * An unpaired trailing user message counts as the next turn.
+   * Count user turns in the conversation and return the previous saved user message context.
+   * Includes persisted messages and pending messages in the turn count.
    */
-  async getTurnCount() {
+  async #getChainContext() {
     await this.#ensureInitialized();
-    let userCount = 0;
+    let turn = 0;
+    let lastMessageAt;
+    let lastMessage;
     if (this.#branch?.headMessageId) {
       const chain = await this.#store.getMessageChain(
         this.#branch.headMessageId
       );
       for (const msg of chain) {
-        if (msg.name === "user") {
-          userCount++;
+        if (msg.name !== "user") {
+          continue;
         }
+        turn++;
+        lastMessageAt = msg.createdAt;
+        lastMessage = msg.data;
       }
     }
     for (const fragment2 of this.#pendingMessages) {
-      if (fragment2.name === "user") {
-        userCount++;
-      }
+      if (fragment2.name === "user") turn++;
     }
-    return userCount;
+    return { turn, lastMessageAt, lastMessage };
+  }
+  async getTurnCount() {
+    const { turn } = await this.#getChainContext();
+    return turn;
   }
   /**
    * Add fragments to the context.
@@ -1935,37 +1985,6 @@ var ContextEngine = class {
       }
       messages.push(fragment2.codec.encode());
     }
-    const conditionalReminders = this.#fragments.filter(isConditionalReminder);
-    if (conditionalReminders.length > 0) {
-      const turn = await this.getTurnCount();
-      let lastUserIndex = -1;
-      for (let i = messages.length - 1; i >= 0; i--) {
-        if (messages[i].role === "user") {
-          lastUserIndex = i;
-          break;
-        }
-      }
-      if (lastUserIndex >= 0) {
-        const original = messages[lastUserIndex];
-        const message2 = {
-          ...original,
-          parts: [...original.parts]
-        };
-        const plainText = message2.parts.filter(isTextUIPart2).map((p) => p.text).join(" ");
-        const addedReminders = [];
-        for (const fragment2 of conditionalReminders) {
-          const config = getConditionalReminder(fragment2);
-          if (!config.when(turn)) continue;
-          const meta = applyReminderToMessage(message2, config, {
-            content: plainText,
-            turn
-          });
-          if (meta) addedReminders.push(meta);
-        }
-        mergeReminderMetadata(message2, addedReminders);
-        messages[lastUserIndex] = message2;
-      }
-    }
     return {
       systemPrompt,
       messages: messages.length === 0 ? [] : await validateUIMessages({ messages })
@@ -2009,7 +2028,49 @@ var ContextEngine = class {
         }
       }
     }
-    let parentId = this.#branch.headMessageId;
+    const conditionalReminders = this.#fragments.filter(isConditionalReminder);
+    if (conditionalReminders.length > 0) {
+      let lastUserIndex = -1;
+      for (let i = this.#pendingMessages.length - 1; i >= 0; i--) {
+        if (this.#pendingMessages[i].name === "user") {
+          lastUserIndex = i;
+          break;
+        }
+      }
+      if (lastUserIndex >= 0) {
+        const lastUserFragment = this.#pendingMessages[lastUserIndex];
+        if (lastUserFragment.codec) {
+          const { turn, lastMessageAt, lastMessage } = await this.#getChainContext();
+          const firedReminders = conditionalReminders.map(getConditionalReminder).filter((config) => config.when(turn));
+          if (firedReminders.length > 0) {
+            const original = lastUserFragment.codec.encode();
+            const plainText = extractPlainText(original);
+            const reminders = firedReminders.flatMap((rem) => {
+              const resolved = resolveReminder(rem, {
+                content: plainText,
+                turn,
+                lastMessageAt,
+                lastMessage
+              });
+              if (!resolved) {
+                return [];
+              }
+              return [
+                {
+                  text: resolved.text,
+                  asPart: rem.asPart,
+                  metadata: resolved.metadata
+                }
+              ];
+            });
+            const recreated = user(original, ...reminders);
+            recreated.id = lastUserFragment.id;
+            this.#pendingMessages[lastUserIndex] = recreated;
+          }
+        }
+      }
+    }
+    let parentId = this.#activeBranch.headMessageId;
     const now = Date.now();
     for (const fragment2 of this.#pendingMessages) {
       if (!fragment2.codec) {
@@ -2037,10 +2098,10 @@ var ContextEngine = class {
       await this.#store.addMessage(messageData);
       parentId = messageData.id;
     }
-    await this.#store.updateBranchHead(this.#branch.id, parentId);
-    this.#branch.headMessageId = parentId;
+    await this.#store.updateBranchHead(this.#activeBranch.id, parentId);
+    this.#activeBranch.headMessageId = parentId;
     this.#pendingMessages = [];
-    return { headMessageId: this.#branch.headMessageId ?? void 0 };
+    return { headMessageId: this.#activeBranch.headMessageId ?? void 0 };
   }
   /**
    * Resolve a lazy fragment by finding the appropriate ID.
@@ -3814,6 +3875,159 @@ function fromFragment(fragment2, options) {
   throw new Error(`Fragment "${fragment2.name}" is missing codec`);
 }
 
+// packages/context/src/lib/fragments/message/environment-reminder.ts
+var ENVIRONMENT_REMINDER_METADATA_KEY = "environment";
+function getSeason(month) {
+  if (month >= 2 && month <= 4) return "Spring";
+  if (month >= 5 && month <= 7) return "Summer";
+  if (month >= 8 && month <= 10) return "Fall";
+  return "Winter";
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function buildEnvironmentSnapshot(now, options) {
+  const { language, timeZone } = options;
+  const currentDateTime = now.toLocaleString("en-CA", {
+    timeZone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    hour12: false
+  });
+  const dayOfWeek = now.toLocaleString("default", {
+    weekday: "long",
+    timeZone
+  });
+  const month = now.toLocaleString("default", {
+    month: "long",
+    timeZone
+  });
+  const year = parseInt(
+    now.toLocaleString("en-CA", { year: "numeric", timeZone }),
+    10
+  );
+  const monthIndex = parseInt(now.toLocaleString("en-CA", { month: "numeric", timeZone }), 10) - 1;
+  return {
+    timeZone,
+    language,
+    currentDateTime,
+    dateKey: now.toLocaleDateString("en-CA", { timeZone }),
+    dayOfWeek,
+    month,
+    year,
+    season: getSeason(monthIndex),
+    timestamp: now.getTime()
+  };
+}
+function buildEnvironmentBlock(snapshot) {
+  return `TimeZone is always in ${snapshot.timeZone}.
+
+Current Date & Time: "${snapshot.currentDateTime}"
+Day of Week: ${snapshot.dayOfWeek}
+Month: ${snapshot.month}
+Year: ${snapshot.year}
+Timestamp: ${snapshot.timestamp}
+Language: ${snapshot.language}
+Season: ${snapshot.season}`;
+}
+function formatChange(previous, current) {
+  const changes = [];
+  if (previous.timeZone !== current.timeZone) {
+    changes.push(`time zone: ${previous.timeZone} -> ${current.timeZone}`);
+  }
+  if (previous.language !== current.language) {
+    changes.push(`language: ${previous.language} -> ${current.language}`);
+  }
+  if (previous.dateKey !== current.dateKey) {
+    changes.push(`date: ${previous.dateKey} -> ${current.dateKey}`);
+  }
+  if (previous.dayOfWeek !== current.dayOfWeek) {
+    changes.push(`day of week: ${previous.dayOfWeek} -> ${current.dayOfWeek}`);
+  }
+  if (previous.month !== current.month) {
+    changes.push(`month: ${previous.month} -> ${current.month}`);
+  }
+  if (previous.year !== current.year) {
+    changes.push(`year: ${previous.year} -> ${current.year}`);
+  }
+  if (previous.season !== current.season) {
+    changes.push(`season: ${previous.season} -> ${current.season}`);
+  }
+  return changes;
+}
+function buildChangeSummary(previous, current) {
+  if (!previous) {
+    return "";
+  }
+  const changes = formatChange(previous, current);
+  if (changes.length === 0) {
+    return "";
+  }
+  return `Changes since last environment snapshot:
+- ${changes.join("\n- ")}
+
+`;
+}
+function parseEnvironmentSnapshot(value) {
+  if (!isRecord2(value)) {
+    return null;
+  }
+  if (typeof value.timeZone !== "string" || typeof value.language !== "string" || typeof value.currentDateTime !== "string" || typeof value.dateKey !== "string" || typeof value.dayOfWeek !== "string" || typeof value.month !== "string" || typeof value.year !== "number" || typeof value.season !== "string" || typeof value.timestamp !== "number") {
+    return null;
+  }
+  return {
+    timeZone: value.timeZone,
+    language: value.language,
+    currentDateTime: value.currentDateTime,
+    dateKey: value.dateKey,
+    dayOfWeek: value.dayOfWeek,
+    month: value.month,
+    year: value.year,
+    season: value.season,
+    timestamp: value.timestamp
+  };
+}
+function getEnvironmentSnapshot(message2) {
+  const metadata = isRecord2(message2?.metadata) ? message2.metadata : null;
+  if (!metadata) {
+    return null;
+  }
+  const stored = metadata[ENVIRONMENT_REMINDER_METADATA_KEY];
+  if (!isRecord2(stored) || stored.version !== 1) {
+    return null;
+  }
+  return parseEnvironmentSnapshot(stored.snapshot);
+}
+function environmentReminder(options) {
+  const getNow = options?.getNow ?? (() => /* @__PURE__ */ new Date());
+  const language = options?.language ?? "English (US)";
+  const timeZone = options?.timeZone ?? "UTC";
+  return reminder(
+    (ctx) => {
+      const snapshot = buildEnvironmentSnapshot(getNow(), {
+        language,
+        timeZone
+      });
+      const previousSnapshot = getEnvironmentSnapshot(ctx.lastMessage);
+      const summary = buildChangeSummary(previousSnapshot, snapshot);
+      return {
+        text: `${summary}${buildEnvironmentBlock(snapshot)}`,
+        metadata: {
+          [ENVIRONMENT_REMINDER_METADATA_KEY]: {
+            version: 1,
+            snapshot
+          }
+        }
+      };
+    },
+    { when: everyNTurns(1) }
+  );
+}
+
 // packages/context/src/lib/fragments/reasoning.ts
 function reasoningFramework() {
   return [
@@ -3922,6 +4136,21 @@ function reasoningFramework() {
     )
   ];
 }
+var DEFAULT_SELF_CRITIQUE_CHECKS = [
+  "Did I answer the user's intent, not just their literal words?",
+  "Is every claim grounded in the provided context, schema, or data?",
+  "Did I follow the requested output format and constraints?"
+];
+function selfCritique(checks = DEFAULT_SELF_CRITIQUE_CHECKS) {
+  return workflow({
+    task: "Self-critique before returning final response",
+    steps: [
+      "Before returning your final response, review your generated output against the user's original constraints:",
+      ...checks.map((check, i) => `${i + 1}. ${check}`),
+      "If any check fails, revise your response before returning it."
+    ]
+  });
+}
 
 // packages/context/src/lib/guardrails/error-recovery.guardrail.ts
 import chalk2 from "chalk";
@@ -7335,6 +7564,7 @@ export {
   DockerSandboxStrategy,
   DockerfileBuildError,
   DockerfileStrategy,
+  ENVIRONMENT_REMINDER_METADATA_KEY,
   InMemoryContextStore,
   LAZY_ID,
   MarkdownRenderer,
@@ -7372,17 +7602,20 @@ export {
   defaultTokenizer,
   discoverSkillsInDirectory,
   encodeSerializedValue,
+  environmentReminder,
   errorRecoveryGuardrail,
   estimate,
   everyNTurns,
   example,
   explain,
+  extractPlainText,
   fail,
   firstN,
   fragment,
   fromFragment,
   generateChatTitle,
   getConditionalReminder,
+  getEnvironmentSnapshot,
   getFragmentData,
   getModelsRegistry,
   getReminderRanges,
@@ -7399,6 +7632,7 @@ export {
   isMessageFragment,
   lastAssistantMessage,
   loadSkillMetadata,
+  mergeMessageMetadata,
   mergeReminderMetadata,
   message,
   nextAdaptivePollingDelay,
@@ -7419,9 +7653,11 @@ export {
   reminder,
   render,
   resetAdaptivePolling,
+  resolveReminder,
   resolveReminderText,
   role,
   runGuardrailChain,
+  selfCritique,
   skills,
   skillsReminder,
   soul,