@deepagents/context 0.29.0 → 0.29.1

package/dist/index.d.ts

@@ -8,6 +8,7 @@ export * from './lib/estimate.ts';
 export * from './lib/fragments.ts';
 export * from './lib/fragments/domain.ts';
 export * from './lib/fragments/message/user.ts';
+export * from './lib/fragments/reasoning.ts';
 export * from './lib/fragments/user.ts';
 export * from './lib/guardrail.ts';
 export * from './lib/guardrails/error-recovery.guardrail.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,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,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

@@ -612,6 +612,12 @@ function or(...predicates) {
 function not(predicate) {
   return (turn) => !predicate(turn);
 }
+function isConditionalReminder(fragment2) {
+  return fragment2.name === "reminder" && !!fragment2.metadata?.reminder;
+}
+function getConditionalReminder(fragment2) {
+  return fragment2.metadata.reminder;
+}
 var SYSTEM_REMINDER_OPEN_TAG = "<system-reminder>";
 var SYSTEM_REMINDER_CLOSE_TAG = "</system-reminder>";
 function getReminderRanges(metadata) {
@@ -746,54 +752,61 @@ function applyPartReminder(message2, value) {
     mode: "part"
   };
 }
-function hasSchedule(reminder2) {
-  return reminder2.when !== void 0;
+function resolveReminderText(item, ctx) {
+  return typeof item.text === "function" ? item.text(ctx) : item.text;
+}
+function applyReminderToMessage(message2, item, ctx) {
+  const resolvedText = resolveReminderText(item, ctx);
+  if (resolvedText.trim().length === 0) {
+    return null;
+  }
+  return item.asPart ? applyPartReminder(message2, resolvedText) : applyInlineReminder(message2, resolvedText);
 }
-function shouldIncludeReminder(reminder2, turn) {
-  if (reminder2.when && !reminder2.when(turn)) return false;
-  return true;
+function mergeReminderMetadata(message2, addedReminders) {
+  if (addedReminders.length === 0) return;
+  const metadata = isRecord(message2.metadata) ? { ...message2.metadata } : {};
+  const existing = Array.isArray(metadata.reminders) ? metadata.reminders : [];
+  metadata.reminders = [...existing, ...addedReminders];
+  message2.metadata = metadata;
 }
 function reminder(text, options) {
   if (typeof text === "string") {
     assertReminderText(text);
   }
+  if (options && "when" in options && options.when) {
+    return {
+      name: "reminder",
+      metadata: {
+        reminder: {
+          text,
+          when: options.when,
+          asPart: options.asPart ?? false
+        }
+      }
+    };
+  }
   return {
     text,
-    asPart: options?.asPart ?? false,
-    ...options?.when !== void 0 && { when: options.when }
+    asPart: options?.asPart ?? false
   };
 }
-function resolveReminderText(item, ctx) {
-  return typeof item.text === "function" ? item.text(ctx) : item.text;
-}
 function user(content, ...reminders) {
   const message2 = typeof content === "string" ? {
     id: generateId3(),
     role: "user",
     parts: [{ type: "text", text: content }]
   } : { ...content, role: "user", parts: [...content.parts] };
-  const immediateReminders = reminders.filter((r) => !hasSchedule(r));
-  const scheduledReminders = reminders.filter((r) => hasSchedule(r));
-  if (immediateReminders.length > 0) {
-    const addedReminders = [];
+  if (reminders.length > 0) {
     const plainText = extractPlainText(message2);
-    for (const item of immediateReminders) {
-      const resolvedText = resolveReminderText(item, { content: plainText });
-      if (resolvedText.trim().length === 0) {
-        continue;
-      }
-      addedReminders.push(
-        item.asPart ? applyPartReminder(message2, resolvedText) : applyInlineReminder(message2, resolvedText)
-      );
-    }
-    if (addedReminders.length > 0) {
-      const metadata = isRecord(message2.metadata) ? { ...message2.metadata } : {};
-      const existingReminders = Array.isArray(metadata.reminders) ? metadata.reminders : [];
-      metadata.reminders = [...existingReminders, ...addedReminders];
-      message2.metadata = metadata;
+    const addedReminders = [];
+    for (const item of reminders) {
+      const meta = applyReminderToMessage(message2, item, {
+        content: plainText
+      });
+      if (meta) addedReminders.push(meta);
     }
+    mergeReminderMetadata(message2, addedReminders);
   }
-  const fragmentMetadata = scheduledReminders.length > 0 ? { scheduledReminders } : void 0;
   return {
     id: message2.id,
     name: "user",
@@ -806,8 +819,7 @@ function user(content, ...reminders) {
       encode() {
         return message2;
       }
-    },
-    metadata: fragmentMetadata
+    }
   };
 }
 
@@ -1709,6 +1721,9 @@ var ContextEngine = class {
   #initialized = false;
   /** Initial metadata to merge on first initialization */
   #initialMetadata;
+  get #renderableFragments() {
+    return this.#fragments.filter((f) => !isConditionalReminder(f));
+  }
   constructor(options) {
     if (!options.chatId) {
       throw new Error("chatId is required");
@@ -1875,7 +1890,7 @@ var ContextEngine = class {
    * @internal Use resolve() instead for public API.
    */
   render(renderer) {
-    return renderer.render(this.#fragments);
+    return renderer.render(this.#renderableFragments);
   }
   /**
    * Resolve context into AI SDK-ready format.
@@ -1896,7 +1911,7 @@ var ContextEngine = class {
    */
   async resolve(options) {
     await this.#ensureInitialized();
-    const systemPrompt = options.renderer.render(this.#fragments);
+    const systemPrompt = options.renderer.render(this.#renderableFragments);
     const messages = [];
     if (this.#branch?.headMessageId) {
       const chain = await this.#store.getMessageChain(
@@ -1912,46 +1927,43 @@ var ContextEngine = class {
         this.#pendingMessages[i] = await this.#resolveLazyFragment(fragment2);
       }
     }
-    const turn = await this.getTurnCount();
     for (const fragment2 of this.#pendingMessages) {
       if (!fragment2.codec) {
         throw new Error(
           `Fragment "${fragment2.name}" is missing codec. Lazy fragments must be resolved before encode.`
         );
       }
-      const scheduled = fragment2.metadata?.scheduledReminders;
-      if (fragment2.name === "user" && scheduled && scheduled.length > 0) {
-        const original = fragment2.codec.encode();
+      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 item of scheduled) {
-          if (!shouldIncludeReminder(item, turn)) {
-            continue;
-          }
-          const resolvedText = resolveReminderText(item, {
+        for (const fragment2 of conditionalReminders) {
+          const config = getConditionalReminder(fragment2);
+          if (!config.when(turn)) continue;
+          const meta = applyReminderToMessage(message2, config, {
             content: plainText,
             turn
           });
-          if (resolvedText.trim().length === 0) {
-            continue;
-          }
-          addedReminders.push(
-            item.asPart ? applyPartReminder(message2, resolvedText) : applyInlineReminder(message2, resolvedText)
-          );
-        }
-        if (addedReminders.length > 0) {
-          const metadata = typeof message2.metadata === "object" && message2.metadata !== null && !Array.isArray(message2.metadata) ? { ...message2.metadata } : {};
-          const existingReminders = Array.isArray(metadata.reminders) ? metadata.reminders : [];
-          metadata.reminders = [...existingReminders, ...addedReminders];
-          message2.metadata = metadata;
+          if (meta) addedReminders.push(meta);
         }
-        messages.push(message2);
-      } else {
-        messages.push(fragment2.codec.encode());
+        mergeReminderMetadata(message2, addedReminders);
+        messages[lastUserIndex] = message2;
       }
     }
     return {
@@ -2088,7 +2100,7 @@ var ContextEngine = class {
     }
     const tokenizer = registry.getTokenizer(modelId);
     const fragmentEstimates = [];
-    for (const fragment2 of this.#fragments) {
+    for (const fragment2 of this.#renderableFragments) {
       const rendered = renderer.render([fragment2]);
       const tokens = tokenizer.count(rendered);
       const cost = tokens / 1e6 * model.cost.input;
@@ -2421,7 +2433,7 @@ var ContextEngine = class {
     await this.#ensureInitialized();
     const { renderer } = options;
     const estimateResult = await this.estimate(options.modelId, { renderer });
-    const rendered = renderer.render(this.#fragments);
+    const rendered = renderer.render(this.#renderableFragments);
     const persistedMessages = [];
     if (this.#branch?.headMessageId) {
       const chain = await this.#store.getMessageChain(
@@ -3802,6 +3814,115 @@ function fromFragment(fragment2, options) {
   throw new Error(`Fragment "${fragment2.name}" is missing codec`);
 }
 
+// packages/context/src/lib/fragments/reasoning.ts
+function reasoningFramework() {
+  return [
+    role(
+      "You are a very strong reasoner and planner. Use these critical instructions to structure your plans, thoughts, and responses."
+    ),
+    fragment(
+      "meta_cognitive_reasoning_framework",
+      hint(
+        "Before taking any action (either tool calls *or* responses to the user), you must proactively, methodically, and independently plan and reason about:"
+      ),
+      principle({
+        title: "Logical dependencies and constraints",
+        description: "Analyze the intended action against the following factors. Resolve conflicts in order of importance:",
+        policies: [
+          policy({
+            rule: "Policy-based rules, mandatory prerequisites, and constraints."
+          }),
+          policy({
+            rule: "Order of operations: Ensure taking an action does not prevent a subsequent necessary action.",
+            policies: [
+              "The user may request actions in a random order, but you may need to reorder operations to maximize successful completion of the task."
+            ]
+          }),
+          policy({
+            rule: "Other prerequisites (information and/or actions needed)."
+          }),
+          policy({ rule: "Explicit user constraints or preferences." })
+        ]
+      }),
+      principle({
+        title: "Risk assessment",
+        description: "What are the consequences of taking the action? Will the new state cause any future issues?",
+        policies: [
+          "For exploratory tasks (like searches), missing *optional* parameters is a LOW risk. **Prefer calling the tool with the available information over asking the user, unless** your Rule 1 (Logical Dependencies) reasoning determines that optional information is required for a later step in your plan."
+        ]
+      }),
+      principle({
+        title: "Abductive reasoning and hypothesis exploration",
+        description: "At each step, identify the most logical and likely reason for any problem encountered.",
+        policies: [
+          "Look beyond immediate or obvious causes. The most likely reason may not be the simplest and may require deeper inference.",
+          "Hypotheses may require additional research. Each hypothesis may take multiple steps to test.",
+          "Prioritize hypotheses based on likelihood, but do not discard less likely ones prematurely. A low-probability event may still be the root cause."
+        ]
+      }),
+      principle({
+        title: "Outcome evaluation and adaptability",
+        description: "Does the previous observation require any changes to your plan?",
+        policies: [
+          "If your initial hypotheses are disproven, actively generate new ones based on the gathered information."
+        ]
+      }),
+      principle({
+        title: "Information availability",
+        description: "Incorporate all applicable and alternative sources of information, including:",
+        policies: [
+          "Using available tools and their capabilities",
+          "All policies, rules, checklists, and constraints",
+          "Previous observations and conversation history",
+          "Information only available by asking the user"
+        ]
+      }),
+      principle({
+        title: "Precision and Grounding",
+        description: "Ensure your reasoning is extremely precise and relevant to each exact ongoing situation.",
+        policies: [
+          "Verify your claims by quoting the exact applicable information (including policies) when referring to them."
+        ]
+      }),
+      principle({
+        title: "Completeness",
+        description: "Ensure that all requirements, constraints, options, and preferences are exhaustively incorporated into your plan.",
+        policies: [
+          policy({
+            rule: "Resolve conflicts using the order of importance in #1."
+          }),
+          policy({
+            rule: "Avoid premature conclusions: There may be multiple relevant options for a given situation.",
+            policies: [
+              "To check for whether an option is relevant, reason about all information sources from #5.",
+              "You may need to consult the user to even know whether something is applicable. Do not assume it is not applicable without checking."
+            ]
+          }),
+          policy({
+            rule: "Review applicable sources of information from #5 to confirm which are relevant to the current state."
+          })
+        ]
+      }),
+      principle({
+        title: "Persistence and patience",
+        description: "Do not give up unless all the reasoning above is exhausted.",
+        policies: [
+          "Don't be dissuaded by time taken or user frustration.",
+          "This persistence must be intelligent: On *transient* errors (e.g. please try again), you *must* retry **unless an explicit retry limit (e.g., max x tries) has been reached**. If such a limit is hit, you *must* stop. On *other* errors, you must change your strategy or arguments, not repeat the same failed call."
+        ]
+      }),
+      principle({
+        title: "Inhibit your response",
+        description: "Only take an action after all the above reasoning is completed. Once you've taken an action, you cannot take it back."
+      }),
+      principle({
+        title: "Continuous self-monitoring",
+        description: "Constantly evaluate your own reasoning process for any gaps, biases, or errors. Apply the above principles iteratively as needed."
+      })
+    )
+  ];
+}
+
 // packages/context/src/lib/guardrails/error-recovery.guardrail.ts
 import chalk2 from "chalk";
 var errorRecoveryGuardrail = {
@@ -7237,6 +7358,7 @@ export {
   and,
   applyInlineReminder,
   applyPartReminder,
+  applyReminderToMessage,
   assistant,
   assistantText,
   chat,
@@ -7260,15 +7382,16 @@ export {
   fragment,
   fromFragment,
   generateChatTitle,
+  getConditionalReminder,
   getFragmentData,
   getModelsRegistry,
   getReminderRanges,
   glossary,
   guardrail,
-  hasSchedule,
   hint,
   identity,
   isComposeOptions,
+  isConditionalReminder,
   isDockerfileOptions,
   isFragment,
   isFragmentObject,
@@ -7276,6 +7399,7 @@ export {
   isMessageFragment,
   lastAssistantMessage,
   loadSkillMetadata,
+  mergeReminderMetadata,
   message,
   nextAdaptivePollingDelay,
   normalizeCancelPolling,
@@ -7291,13 +7415,13 @@ export {
   preference,
   principle,
   quirk,
+  reasoningFramework,
   reminder,
   render,
   resetAdaptivePolling,
   resolveReminderText,
   role,
   runGuardrailChain,
-  shouldIncludeReminder,
   skills,
   skillsReminder,
   soul,