@deepagents/context 0.26.0 → 0.27.0

package/dist/index.js

@@ -15,7 +15,7 @@ import { createRepairToolCall } from "@deepagents/agent";
 // packages/context/src/lib/fragments.ts
 import { generateId } from "ai";
 function isFragment(data) {
-  return typeof data === "object" && data !== null && "name" in data && "data" in data && typeof data.name === "string";
+  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);
@@ -23,6 +23,15 @@ function isFragmentObject(data) {
 function isMessageFragment(fragment2) {
   return fragment2.type === "message";
 }
+function getFragmentData(fragment2) {
+  if (fragment2.codec) {
+    return fragment2.codec.decode();
+  }
+  if ("data" in fragment2) {
+    return fragment2.data;
+  }
+  throw new Error(`Fragment "${fragment2.name}" is missing data and codec`);
+}
 function fragment(name, ...children) {
   return {
     name,
@@ -33,7 +42,6 @@ function assistant(message2) {
   return {
     id: message2.id,
     name: "assistant",
-    data: "content",
     type: "message",
     persist: true,
     codec: {
@@ -55,7 +63,6 @@ function message(content) {
   return {
     id: message2.id,
     name: message2.role,
-    data: "content",
     type: "message",
     persist: true,
     codec: {
@@ -420,7 +427,7 @@ function toMessageFragment(item) {
 }
 function chatMessageToUIMessage(item) {
   if (isFragment(item) && isMessageFragment(item)) {
-    return item.codec.decode();
+    return item.codec.encode();
   }
   return item;
 }
@@ -447,73 +454,746 @@ async function chat(agent2, messages, options) {
     await context.save();
     assistantMsgId = options?.generateMessageId?.() ?? generateId3();
   }
-  const uiMessages = messages.map(chatMessageToUIMessage);
-  const streamContextVariables = options?.contextVariables === void 0 ? {} : options.contextVariables;
-  const result = await agent2.stream(streamContextVariables, {
-    transform: options?.transform
-  });
-  const uiStream = result.toUIMessageStream({
-    onError: options?.onError ?? formatChatError,
-    sendStart: true,
-    sendFinish: true,
-    sendReasoning: true,
-    sendSources: true,
-    originalMessages: uiMessages,
-    generateMessageId: () => assistantMsgId,
-    messageMetadata: options?.messageMetadata
-  });
-  return createUIMessageStream2({
-    originalMessages: uiMessages,
-    generateId: () => assistantMsgId,
-    onStepFinish: async ({ responseMessage }) => {
-      const normalizedMessage = {
-        ...responseMessage,
-        id: assistantMsgId
-      };
-      context.set(assistant(normalizedMessage));
-      await context.save({ branch: false });
-    },
-    onFinish: async ({ responseMessage }) => {
-      const normalizedMessage = {
-        ...responseMessage,
-        id: assistantMsgId
-      };
-      const finalMetadata = await options?.finalAssistantMetadata?.(normalizedMessage);
-      const finalMessage = finalMetadata === void 0 ? normalizedMessage : {
-        ...normalizedMessage,
-        metadata: {
-          ...normalizedMessage.metadata ?? {},
-          ...finalMetadata
-        }
-      };
-      context.set(assistant(finalMessage));
-      await context.save({ branch: false });
-      const totalUsage = await result.totalUsage;
-      await context.trackUsage(totalUsage);
-    },
-    execute: async ({ writer }) => {
-      writer.merge(uiStream);
+  const uiMessages = messages.map(chatMessageToUIMessage);
+  const streamContextVariables = options?.contextVariables === void 0 ? {} : options.contextVariables;
+  const result = await agent2.stream(streamContextVariables, {
+    transform: options?.transform
+  });
+  const uiStream = result.toUIMessageStream({
+    onError: options?.onError ?? formatChatError,
+    sendStart: true,
+    sendFinish: true,
+    sendReasoning: true,
+    sendSources: true,
+    originalMessages: uiMessages,
+    generateMessageId: () => assistantMsgId,
+    messageMetadata: options?.messageMetadata
+  });
+  return createUIMessageStream2({
+    originalMessages: uiMessages,
+    generateId: () => assistantMsgId,
+    onStepFinish: async ({ responseMessage }) => {
+      const normalizedMessage = {
+        ...responseMessage,
+        id: assistantMsgId
+      };
+      context.set(assistant(normalizedMessage));
+      await context.save({ branch: false });
+    },
+    onFinish: async ({ responseMessage }) => {
+      const normalizedMessage = {
+        ...responseMessage,
+        id: assistantMsgId
+      };
+      const finalMetadata = await options?.finalAssistantMetadata?.(normalizedMessage);
+      const finalMessage = finalMetadata === void 0 ? normalizedMessage : {
+        ...normalizedMessage,
+        metadata: {
+          ...normalizedMessage.metadata ?? {},
+          ...finalMetadata
+        }
+      };
+      context.set(assistant(finalMessage));
+      await context.save({ branch: false });
+      const totalUsage = await result.totalUsage;
+      await context.trackUsage(totalUsage);
+    },
+    execute: async ({ writer }) => {
+      writer.merge(uiStream);
+    }
+  });
+}
+function formatChatError(error) {
+  if (NoSuchToolError.isInstance(error)) {
+    return "The model tried to call an unknown tool.";
+  }
+  if (InvalidToolInputError.isInstance(error)) {
+    return "The model called a tool with invalid arguments.";
+  }
+  if (ToolCallRepairError.isInstance(error)) {
+    return "The model tried to call a tool with invalid arguments, but it was repaired.";
+  }
+  if (APICallError.isInstance(error)) {
+    console.error("Upstream API call failed:", error);
+    return `Upstream API call failed with status ${error.statusCode}: ${error.message}`;
+  }
+  return JSON.stringify(error);
+}
+
+// packages/context/src/lib/codec/serialized-codec.ts
+function encodeSerializedValue(value) {
+  if (isFragment(value)) {
+    if (isMessageFragment(value)) {
+      throw new Error(
+        "Message fragments are not supported by serialized fragment conversion"
+      );
+    }
+    if (!value.codec) {
+      throw new Error(`Fragment "${value.name}" is missing codec`);
+    }
+    return value.codec.encode();
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => encodeSerializedValue(item));
+  }
+  if (isFragmentObject(value)) {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, entry]) => [
+        key,
+        encodeSerializedValue(entry)
+      ])
+    );
+  }
+  return value;
+}
+
+// packages/context/src/lib/fragments/domain.ts
+function term(name, definition) {
+  return {
+    name: "term",
+    data: { name, definition },
+    codec: {
+      encode() {
+        return { type: "term", name, definition };
+      },
+      decode() {
+        return { name, definition };
+      }
+    }
+  };
+}
+function hint(text) {
+  return {
+    name: "hint",
+    data: text,
+    codec: {
+      encode() {
+        return { type: "hint", text };
+      },
+      decode() {
+        return text;
+      }
+    }
+  };
+}
+function guardrail(input) {
+  return {
+    name: "guardrail",
+    data: {
+      rule: input.rule,
+      ...input.reason && { reason: input.reason },
+      ...input.action && { action: input.action }
+    },
+    codec: {
+      encode() {
+        return {
+          type: "guardrail",
+          rule: input.rule,
+          ...input.reason && { reason: input.reason },
+          ...input.action && { action: input.action }
+        };
+      },
+      decode() {
+        return {
+          rule: input.rule,
+          ...input.reason && { reason: input.reason },
+          ...input.action && { action: input.action }
+        };
+      }
+    }
+  };
+}
+function explain(input) {
+  return {
+    name: "explain",
+    data: {
+      concept: input.concept,
+      explanation: input.explanation,
+      ...input.therefore && { therefore: input.therefore }
+    },
+    codec: {
+      encode() {
+        return {
+          type: "explain",
+          concept: input.concept,
+          explanation: input.explanation,
+          ...input.therefore && { therefore: input.therefore }
+        };
+      },
+      decode() {
+        return {
+          concept: input.concept,
+          explanation: input.explanation,
+          ...input.therefore && { therefore: input.therefore }
+        };
+      }
+    }
+  };
+}
+function example(input) {
+  return {
+    name: "example",
+    data: {
+      question: input.question,
+      answer: input.answer,
+      ...input.note && { note: input.note }
+    },
+    codec: {
+      encode() {
+        return {
+          type: "example",
+          question: input.question,
+          answer: input.answer,
+          ...input.note && { note: input.note }
+        };
+      },
+      decode() {
+        return {
+          question: input.question,
+          answer: input.answer,
+          ...input.note && { note: input.note }
+        };
+      }
+    }
+  };
+}
+function clarification(input) {
+  return {
+    name: "clarification",
+    data: {
+      when: input.when,
+      ask: input.ask,
+      reason: input.reason
+    },
+    codec: {
+      encode() {
+        return {
+          type: "clarification",
+          when: input.when,
+          ask: input.ask,
+          reason: input.reason
+        };
+      },
+      decode() {
+        return {
+          when: input.when,
+          ask: input.ask,
+          reason: input.reason
+        };
+      }
+    }
+  };
+}
+function workflow(input) {
+  return {
+    name: "workflow",
+    data: {
+      task: input.task,
+      steps: input.steps,
+      ...input.triggers?.length && { triggers: input.triggers },
+      ...input.notes && { notes: input.notes }
+    },
+    codec: {
+      encode() {
+        return {
+          type: "workflow",
+          task: input.task,
+          steps: input.steps,
+          ...input.triggers?.length && { triggers: input.triggers },
+          ...input.notes && { notes: input.notes }
+        };
+      },
+      decode() {
+        return {
+          task: input.task,
+          steps: input.steps,
+          ...input.triggers?.length && { triggers: input.triggers },
+          ...input.notes && { notes: input.notes }
+        };
+      }
+    }
+  };
+}
+function quirk(input) {
+  return {
+    name: "quirk",
+    data: {
+      issue: input.issue,
+      workaround: input.workaround
+    },
+    codec: {
+      encode() {
+        return {
+          type: "quirk",
+          issue: input.issue,
+          workaround: input.workaround
+        };
+      },
+      decode() {
+        return {
+          issue: input.issue,
+          workaround: input.workaround
+        };
+      }
+    }
+  };
+}
+function styleGuide(input) {
+  return {
+    name: "styleGuide",
+    data: {
+      prefer: input.prefer,
+      ...input.never && { never: input.never },
+      ...input.always && { always: input.always }
+    },
+    codec: {
+      encode() {
+        return {
+          type: "styleGuide",
+          prefer: input.prefer,
+          ...input.never && { never: input.never },
+          ...input.always && { always: input.always }
+        };
+      },
+      decode() {
+        return {
+          prefer: input.prefer,
+          ...input.never && { never: input.never },
+          ...input.always && { always: input.always }
+        };
+      }
+    }
+  };
+}
+function analogy(input) {
+  return {
+    name: "analogy",
+    data: {
+      concepts: input.concepts,
+      relationship: input.relationship,
+      ...input.insight && { insight: input.insight },
+      ...input.therefore && { therefore: input.therefore },
+      ...input.pitfall && { pitfall: input.pitfall }
+    },
+    codec: {
+      encode() {
+        return {
+          type: "analogy",
+          concepts: input.concepts,
+          relationship: input.relationship,
+          ...input.insight && { insight: input.insight },
+          ...input.therefore && { therefore: input.therefore },
+          ...input.pitfall && { pitfall: input.pitfall }
+        };
+      },
+      decode() {
+        return {
+          concepts: input.concepts,
+          relationship: input.relationship,
+          ...input.insight && { insight: input.insight },
+          ...input.therefore && { therefore: input.therefore },
+          ...input.pitfall && { pitfall: input.pitfall }
+        };
+      }
+    }
+  };
+}
+function glossary(entries) {
+  return {
+    name: "glossary",
+    data: Object.entries(entries).map(([term2, expression]) => ({
+      term: term2,
+      expression
+    })),
+    codec: {
+      encode() {
+        return { type: "glossary", entries };
+      },
+      decode() {
+        return Object.entries(entries).map(([term2, expression]) => ({
+          term: term2,
+          expression
+        }));
+      }
+    }
+  };
+}
+function role(content) {
+  return {
+    name: "role",
+    data: content,
+    codec: {
+      encode() {
+        return { type: "role", content };
+      },
+      decode() {
+        return content;
+      }
+    }
+  };
+}
+function principle(input) {
+  return {
+    name: "principle",
+    data: {
+      title: input.title,
+      description: input.description,
+      ...input.policies?.length && { policies: input.policies }
+    },
+    codec: {
+      encode() {
+        return {
+          type: "principle",
+          title: input.title,
+          description: input.description,
+          ...input.policies?.length && {
+            policies: input.policies.map((item) => encodeSerializedValue(item))
+          }
+        };
+      },
+      decode() {
+        return {
+          title: input.title,
+          description: input.description,
+          ...input.policies?.length && { policies: input.policies }
+        };
+      }
+    }
+  };
+}
+function policy(input) {
+  return {
+    name: "policy",
+    data: {
+      rule: input.rule,
+      ...input.before && { before: input.before },
+      ...input.reason && { reason: input.reason },
+      ...input.policies?.length && { policies: input.policies }
+    },
+    codec: {
+      encode() {
+        return {
+          type: "policy",
+          rule: input.rule,
+          ...input.before && { before: input.before },
+          ...input.reason && { reason: input.reason },
+          ...input.policies?.length && {
+            policies: input.policies.map((item) => encodeSerializedValue(item))
+          }
+        };
+      },
+      decode() {
+        return {
+          rule: input.rule,
+          ...input.before && { before: input.before },
+          ...input.reason && { reason: input.reason },
+          ...input.policies?.length && { policies: input.policies }
+        };
+      }
+    }
+  };
+}
+
+// packages/context/src/lib/fragments/user.ts
+function identity(input) {
+  return {
+    name: "identity",
+    data: {
+      ...input.name && { name: input.name },
+      ...input.role && { role: input.role }
+    },
+    codec: {
+      encode() {
+        return {
+          type: "identity",
+          ...input.name && { name: input.name },
+          ...input.role && { role: input.role }
+        };
+      },
+      decode() {
+        return {
+          ...input.name && { name: input.name },
+          ...input.role && { role: input.role }
+        };
+      }
+    }
+  };
+}
+function persona(input) {
+  return {
+    name: "persona",
+    data: {
+      name: input.name,
+      ...input.role && { role: input.role },
+      ...input.objective && { objective: input.objective },
+      ...input.tone && { tone: input.tone }
+    },
+    codec: {
+      encode() {
+        return {
+          type: "persona",
+          name: input.name,
+          ...input.role && { role: input.role },
+          ...input.objective && { objective: input.objective },
+          ...input.tone && { tone: input.tone }
+        };
+      },
+      decode() {
+        return {
+          name: input.name,
+          ...input.role && { role: input.role },
+          ...input.objective && { objective: input.objective },
+          ...input.tone && { tone: input.tone }
+        };
+      }
+    }
+  };
+}
+function alias(term2, meaning) {
+  return {
+    name: "alias",
+    data: { term: term2, meaning },
+    codec: {
+      encode() {
+        return { type: "alias", term: term2, meaning };
+      },
+      decode() {
+        return { term: term2, meaning };
+      }
+    }
+  };
+}
+function preference(aspect, value) {
+  return {
+    name: "preference",
+    data: { aspect, value },
+    codec: {
+      encode() {
+        return { type: "preference", aspect, value };
+      },
+      decode() {
+        return { aspect, value };
+      }
+    }
+  };
+}
+function correction(subject, clarification2) {
+  return {
+    name: "correction",
+    data: { subject, clarification: clarification2 },
+    codec: {
+      encode() {
+        return { type: "correction", subject, clarification: clarification2 };
+      },
+      decode() {
+        return { subject, clarification: clarification2 };
+      }
+    }
+  };
+}
+
+// packages/context/src/lib/codec/serialized-fragments.ts
+function isSerializedFragmentLike(value) {
+  return typeof value === "object" && value !== null && "type" in value && typeof value.type === "string";
+}
+function toFragmentData(value, options) {
+  if (isSerializedFragmentLike(value)) {
+    return toFragment(value, options);
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => toFragmentData(item, options));
+  }
+  if (isFragmentObject(value)) {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, entry]) => [
+        key,
+        toFragmentData(entry, options)
+      ])
+    );
+  }
+  return value;
+}
+var builtInSerializedRegistry = {
+  term: {
+    toFragment: (input) => term(input.name, input.definition),
+    fromFragment: () => void 0
+  },
+  hint: {
+    toFragment: (input) => hint(input.text),
+    fromFragment: () => void 0
+  },
+  guardrail: {
+    toFragment: (input) => guardrail({
+      rule: input.rule,
+      reason: input.reason,
+      action: input.action
+    }),
+    fromFragment: () => void 0
+  },
+  explain: {
+    toFragment: (input) => explain({
+      concept: input.concept,
+      explanation: input.explanation,
+      therefore: input.therefore
+    }),
+    fromFragment: () => void 0
+  },
+  example: {
+    toFragment: (input) => example({
+      question: input.question,
+      answer: input.answer,
+      note: input.note
+    }),
+    fromFragment: () => void 0
+  },
+  clarification: {
+    toFragment: (input) => clarification({
+      when: input.when,
+      ask: input.ask,
+      reason: input.reason
+    }),
+    fromFragment: () => void 0
+  },
+  workflow: {
+    toFragment: (input) => workflow({
+      task: input.task,
+      steps: input.steps,
+      triggers: input.triggers,
+      notes: input.notes
+    }),
+    fromFragment: () => void 0
+  },
+  quirk: {
+    toFragment: (input) => quirk({
+      issue: input.issue,
+      workaround: input.workaround
+    }),
+    fromFragment: () => void 0
+  },
+  styleGuide: {
+    toFragment: (input) => styleGuide({
+      prefer: input.prefer,
+      never: input.never,
+      always: input.always
+    }),
+    fromFragment: () => void 0
+  },
+  analogy: {
+    toFragment: (input) => analogy({
+      concepts: input.concepts,
+      relationship: input.relationship,
+      insight: input.insight,
+      therefore: input.therefore,
+      pitfall: input.pitfall
+    }),
+    fromFragment: () => void 0
+  },
+  glossary: {
+    toFragment: (input) => glossary(input.entries),
+    fromFragment: () => void 0
+  },
+  role: {
+    toFragment: (input) => role(input.content),
+    fromFragment: () => void 0
+  },
+  principle: {
+    toFragment: (input, options) => principle({
+      title: input.title,
+      description: input.description,
+      policies: input.policies?.map((item) => toFragmentData(item, options))
+    }),
+    fromFragment: () => void 0
+  },
+  policy: {
+    toFragment: (input, options) => policy({
+      rule: input.rule,
+      before: input.before,
+      reason: input.reason,
+      policies: input.policies?.map((item) => toFragmentData(item, options))
+    }),
+    fromFragment: () => void 0
+  },
+  identity: {
+    toFragment: (input) => identity({
+      name: input.name,
+      role: input.role
+    }),
+    fromFragment: () => void 0
+  },
+  persona: {
+    toFragment: (input) => persona({
+      name: input.name,
+      role: input.role,
+      objective: input.objective,
+      tone: input.tone
+    }),
+    fromFragment: () => void 0
+  },
+  alias: {
+    toFragment: (input) => alias(input.term, input.meaning),
+    fromFragment: () => void 0
+  },
+  preference: {
+    toFragment: (input) => preference(input.aspect, input.value),
+    fromFragment: () => void 0
+  },
+  correction: {
+    toFragment: (input) => correction(input.subject, input.clarification),
+    fromFragment: () => void 0
+  }
+};
+var messageLikeTypes = /* @__PURE__ */ new Set(["user", "assistant", "message"]);
+function findCustomSerializedFragment(fragment2, options) {
+  if (!options?.registry) {
+    return void 0;
+  }
+  for (const entry of Object.values(options.registry)) {
+    const serialized = entry.fromFragment(fragment2, options);
+    if (serialized !== void 0) {
+      return serialized;
     }
-  });
+  }
+  return void 0;
 }
-function formatChatError(error) {
-  if (NoSuchToolError.isInstance(error)) {
-    return "The model tried to call an unknown tool.";
+function toFragment(input, options) {
+  if (messageLikeTypes.has(input.type)) {
+    throw new Error(
+      "Message fragments are not supported by serialized fragment conversion"
+    );
   }
-  if (InvalidToolInputError.isInstance(error)) {
-    return "The model called a tool with invalid arguments.";
+  const entry = options?.registry?.[input.type] ?? builtInSerializedRegistry[input.type];
+  if (!entry) {
+    throw new Error(`Unsupported serialized fragment type: ${input.type}`);
   }
-  if (ToolCallRepairError.isInstance(error)) {
-    return "The model tried to call a tool with invalid arguments, but it was repaired.";
+  return entry.toFragment(input, options);
+}
+function fromFragment(fragment2, options) {
+  if (isMessageFragment(fragment2)) {
+    throw new Error(
+      "Message fragments are not supported by serialized fragment conversion"
+    );
   }
-  if (APICallError.isInstance(error)) {
-    console.error("Upstream API call failed:", error);
-    return `Upstream API call failed with status ${error.statusCode}: ${error.message}`;
+  const customSerialized = findCustomSerializedFragment(fragment2, options);
+  if (customSerialized !== void 0) {
+    return customSerialized;
   }
-  return JSON.stringify(error);
+  if (fragment2.codec) {
+    const encoded = fragment2.codec.encode();
+    if (!isSerializedFragmentLike(encoded)) {
+      throw new Error(
+        `Fragment "${fragment2.name}" codec must encode to a serialized fragment object`
+      );
+    }
+    return encoded;
+  }
+  if (!builtInSerializedRegistry[fragment2.name]) {
+    throw new Error(`Unsupported fragment name: ${fragment2.name}`);
+  }
+  throw new Error(`Fragment "${fragment2.name}" is missing codec`);
 }
 
 // packages/context/src/lib/engine.ts
+import { validateUIMessages } from "ai";
 import { mergeWith } from "lodash-es";
 
 // packages/context/src/lib/estimate.ts
@@ -718,7 +1398,7 @@ var ContextRenderer = class {
     return sanitized;
   }
   sanitizeFragment(fragment2, seen) {
-    const data = this.sanitizeData(fragment2.data, seen);
+    const data = this.sanitizeData(getFragmentData(fragment2), seen);
     if (data == null) {
       return null;
     }
@@ -795,12 +1475,13 @@ var XmlRenderer = class extends ContextRenderer {
     return sanitized.map((f) => this.#renderTopLevel(f)).filter(Boolean).join("\n");
   }
   #renderTopLevel(fragment2) {
-    if (this.isPrimitive(fragment2.data)) {
-      return this.#leafRoot(fragment2.name, String(fragment2.data));
+    const data = getFragmentData(fragment2);
+    if (this.isPrimitive(data)) {
+      return this.#leafRoot(fragment2.name, String(data));
     }
-    if (Array.isArray(fragment2.data)) {
-      if (fragment2.data.length === 1) {
-        const single = fragment2.data[0];
+    if (Array.isArray(data)) {
+      if (data.length === 1) {
+        const single = data[0];
         if (this.isPrimitive(single)) {
           return this.#leafRoot(fragment2.name, String(single));
         }
@@ -818,19 +1499,15 @@ var XmlRenderer = class extends ContextRenderer {
           );
         }
       }
-      return this.#renderArray(fragment2.name, fragment2.data, 0);
+      return this.#renderArray(fragment2.name, data, 0);
     }
-    if (isFragment(fragment2.data)) {
-      return this.#renderFragmentContentsUnderParent(
-        fragment2.name,
-        fragment2.data,
-        0
-      );
+    if (isFragment(data)) {
+      return this.#renderFragmentContentsUnderParent(fragment2.name, data, 0);
     }
-    if (isFragmentObject(fragment2.data)) {
+    if (isFragmentObject(data)) {
       return this.#wrap(
         fragment2.name,
-        this.renderEntries(fragment2.data, { depth: 1, path: [] })
+        this.renderEntries(data, { depth: 1, path: [] })
       );
     }
     return "";
@@ -962,23 +1639,23 @@ ${this.#indent(safe, 2)}
     return `<${tag}>${safe}</${tag}>`;
   }
   renderFragment(fragment2, ctx) {
-    const { name, data } = fragment2;
+    const data = getFragmentData(fragment2);
     if (this.isPrimitive(data)) {
-      return this.#leaf(name, String(data), ctx.depth);
+      return this.#leaf(fragment2.name, String(data), ctx.depth);
     }
     if (isFragment(data)) {
       const child = this.renderFragment(data, { ...ctx, depth: ctx.depth + 1 });
-      return this.#wrapIndented(name, [child], ctx.depth);
+      return this.#wrapIndented(fragment2.name, [child], ctx.depth);
     }
     if (Array.isArray(data)) {
-      return this.#renderArrayIndented(name, data, ctx.depth);
+      return this.#renderArrayIndented(fragment2.name, data, ctx.depth);
     }
     if (isFragmentObject(data)) {
       const children = this.renderEntries(data, {
         ...ctx,
         depth: ctx.depth + 1
       });
-      return this.#wrapIndented(name, children, ctx.depth);
+      return this.#wrapIndented(fragment2.name, children, ctx.depth);
     }
     return "";
   }
@@ -1095,21 +1772,22 @@ var MarkdownRenderer = class extends ContextRenderer {
   render(fragments) {
     return this.sanitizeFragments(fragments).map((f) => {
       const title = `## ${titlecase(f.name)}`;
-      if (this.isPrimitive(f.data)) {
+      const data = getFragmentData(f);
+      if (this.isPrimitive(data)) {
         return `${title}
-${String(f.data)}`;
+${String(data)}`;
       }
-      if (Array.isArray(f.data)) {
+      if (Array.isArray(data)) {
         return `${title}
-${this.#renderArray(f.data, 0)}`;
+${this.#renderArray(data, 0)}`;
       }
-      if (isFragment(f.data)) {
+      if (isFragment(data)) {
         return `${title}
-${this.renderFragment(f.data, { depth: 0, path: [] })}`;
+${this.renderFragment(data, { depth: 0, path: [] })}`;
       }
-      if (isFragmentObject(f.data)) {
+      if (isFragmentObject(data)) {
         return `${title}
-${this.renderEntries(f.data, { depth: 0, path: [] }).join("\n")}`;
+${this.renderEntries(data, { depth: 0, path: [] }).join("\n")}`;
       }
       return `${title}
 `;
@@ -1159,10 +1837,10 @@ ${this.renderEntries(f.data, { depth: 0, path: [] }).join("\n")}`;
     return `${this.#pad(depth)}- ${String(item)}`;
   }
   renderFragment(fragment2, ctx) {
-    const { name, data } = fragment2;
-    const header = `${this.#pad(ctx.depth)}- **${name}**:`;
+    const data = getFragmentData(fragment2);
+    const header = `${this.#pad(ctx.depth)}- **${fragment2.name}**:`;
     if (this.isPrimitive(data)) {
-      return `${this.#pad(ctx.depth)}- **${name}**: ${String(data)}`;
+      return `${this.#pad(ctx.depth)}- **${fragment2.name}**: ${String(data)}`;
     }
     if (isFragment(data)) {
       const child = this.renderFragment(data, { ...ctx, depth: ctx.depth + 1 });
@@ -1201,21 +1879,22 @@ ${this.renderEntries(f.data, { depth: 0, path: [] }).join("\n")}`;
 var TomlRenderer = class extends ContextRenderer {
   render(fragments) {
     const rendered = [];
-    for (const f of this.sanitizeFragments(fragments)) {
-      if (this.isPrimitive(f.data)) {
-        rendered.push(`${f.name} = ${this.#formatValue(f.data)}`);
-      } else if (Array.isArray(f.data)) {
-        rendered.push(this.#renderTopLevelArray(f.name, f.data));
-      } else if (isFragment(f.data)) {
+    for (const it of this.sanitizeFragments(fragments)) {
+      const data = getFragmentData(it);
+      if (this.isPrimitive(data)) {
+        rendered.push(`${it.name} = ${this.#formatValue(data)}`);
+      } else if (Array.isArray(data)) {
+        rendered.push(this.#renderTopLevelArray(it.name, data));
+      } else if (isFragment(data)) {
         rendered.push(
           [
-            `[${f.name}]`,
-            this.renderFragment(f.data, { depth: 0, path: [f.name] })
+            `[${it.name}]`,
+            this.renderFragment(data, { depth: 0, path: [it.name] })
           ].join("\n")
         );
-      } else if (isFragmentObject(f.data)) {
-        const entries = this.#renderObjectEntries(f.data, [f.name]);
-        rendered.push([`[${f.name}]`, ...entries].join("\n"));
+      } else if (isFragmentObject(data)) {
+        const entries = this.#renderObjectEntries(data, [it.name]);
+        rendered.push([`[${it.name}]`, ...entries].join("\n"));
       }
     }
     return rendered.join("\n\n");
@@ -1285,10 +1964,10 @@ var TomlRenderer = class extends ContextRenderer {
     }).filter(Boolean);
   }
   renderFragment(fragment2, ctx) {
-    const { name, data } = fragment2;
-    const newPath = [...ctx.path, name];
+    const data = getFragmentData(fragment2);
+    const newPath = [...ctx.path, fragment2.name];
     if (this.isPrimitive(data)) {
-      return `${name} = ${this.#formatValue(data)}`;
+      return `${fragment2.name} = ${this.#formatValue(data)}`;
     }
     if (isFragment(data)) {
       return [
@@ -1310,7 +1989,7 @@ var TomlRenderer = class extends ContextRenderer {
         return parts.join("\n");
       }
       const values = nonFragmentItems.map((item) => this.#formatValue(item));
-      return `${name} = [${values.join(", ")}]`;
+      return `${fragment2.name} = [${values.join(", ")}]`;
     }
     if (isFragmentObject(data)) {
       const entries = this.#renderObjectEntries(data, newPath);
@@ -1340,27 +2019,27 @@ var ToonRenderer = class extends ContextRenderer {
     return sanitized.map((f) => this.#renderTopLevel(f)).filter(Boolean).join("\n");
   }
   #renderTopLevel(fragment2) {
-    const { name, data } = fragment2;
+    const data = getFragmentData(fragment2);
     if (this.isPrimitive(data)) {
-      return `${name}: ${this.#formatValue(data)}`;
+      return `${fragment2.name}: ${this.#formatValue(data)}`;
     }
     if (Array.isArray(data)) {
-      return this.#renderArrayField(name, data, 0);
+      return this.#renderArrayField(fragment2.name, data, 0);
     }
     if (isFragment(data)) {
       const child = this.renderFragment(data, { depth: 1, path: [] });
-      return `${name}:
+      return `${fragment2.name}:
 ${child}`;
     }
     if (isFragmentObject(data)) {
       const entries = this.#renderObjectEntries(data, 1);
       if (!entries) {
-        return `${name}:`;
+        return `${fragment2.name}:`;
       }
-      return `${name}:
+      return `${fragment2.name}:
 ${entries}`;
     }
-    return `${name}:`;
+    return `${fragment2.name}:`;
   }
   #renderArrayField(key, items, depth) {
     const filtered = items.filter((item) => item != null);
@@ -1435,8 +2114,9 @@ ${entries}`;
         depth: depth + 1,
         path: []
       });
-      if (this.isPrimitive(item.data)) {
-        return `${this.#pad(depth)}- ${item.name}: ${this.#formatValue(item.data)}`;
+      const itemData = getFragmentData(item);
+      if (this.isPrimitive(itemData)) {
+        return `${this.#pad(depth)}- ${item.name}: ${this.#formatValue(itemData)}`;
       }
       return `${this.#pad(depth)}- ${item.name}:
 ${rendered.split("\n").slice(1).join("\n")}`;
@@ -1479,30 +2159,30 @@ ${nested}`);
     return lines.join("\n");
   }
   renderFragment(fragment2, ctx) {
-    const { name, data } = fragment2;
+    const data = getFragmentData(fragment2);
     if (this.isPrimitive(data)) {
-      return `${this.#pad(ctx.depth)}${name}: ${this.#formatValue(data)}`;
+      return `${this.#pad(ctx.depth)}${fragment2.name}: ${this.#formatValue(data)}`;
     }
     if (isFragment(data)) {
       const child = this.renderFragment(data, {
         ...ctx,
         depth: ctx.depth + 1
       });
-      return `${this.#pad(ctx.depth)}${name}:
+      return `${this.#pad(ctx.depth)}${fragment2.name}:
 ${child}`;
     }
     if (Array.isArray(data)) {
-      return this.#renderArrayField(name, data, ctx.depth);
+      return this.#renderArrayField(fragment2.name, data, ctx.depth);
     }
     if (isFragmentObject(data)) {
       const entries = this.#renderObjectEntries(data, ctx.depth + 1);
       if (!entries) {
-        return `${this.#pad(ctx.depth)}${name}:`;
+        return `${this.#pad(ctx.depth)}${fragment2.name}:`;
       }
-      return `${this.#pad(ctx.depth)}${name}:
+      return `${this.#pad(ctx.depth)}${fragment2.name}:
 ${entries}`;
     }
-    return `${this.#pad(ctx.depth)}${name}:`;
+    return `${this.#pad(ctx.depth)}${fragment2.name}:`;
   }
   renderPrimitive(key, value, ctx) {
     return `${this.#pad(ctx.depth)}${key}: ${this.#formatValue(value)}`;
@@ -1557,6 +2237,9 @@ var ContextStore = class {
 };
 
 // packages/context/src/lib/engine.ts
+function estimateMessageContent(data) {
+  return typeof data === "string" ? data : JSON.stringify(data);
+}
 var ContextEngine = class {
   /** Non-message fragments (role, hints, etc.) - not persisted in graph */
   #fragments = [];
@@ -1739,7 +2422,7 @@ var ContextEngine = class {
         this.#branch.headMessageId
       );
       for (const msg of chain) {
-        messages.push(message(msg.data).codec?.decode());
+        messages.push(msg.data);
       }
     }
     for (let i = 0; i < this.#pendingMessages.length; i++) {
@@ -1751,13 +2434,15 @@ var ContextEngine = class {
     for (const fragment2 of this.#pendingMessages) {
       if (!fragment2.codec) {
         throw new Error(
-          `Fragment "${fragment2.name}" is missing codec. Lazy fragments must be resolved before decode.`
+          `Fragment "${fragment2.name}" is missing codec. Lazy fragments must be resolved before encode.`
         );
       }
-      const decoded = fragment2.codec.decode();
-      messages.push(decoded);
+      messages.push(fragment2.codec.encode());
     }
-    return { systemPrompt, messages };
+    return {
+      systemPrompt,
+      messages: messages.length === 0 ? [] : await validateUIMessages({ messages })
+    };
   }
   /**
    * Save pending messages to the graph.
@@ -1904,7 +2589,7 @@ var ContextEngine = class {
         this.#branch.headMessageId
       );
       for (const msg of chain) {
-        const content = String(msg.data);
+        const content = estimateMessageContent(msg.data);
         const tokens = tokenizer.count(content);
         const cost = tokens / 1e6 * model.cost.input;
         fragmentEstimates.push({
@@ -1916,7 +2601,9 @@ var ContextEngine = class {
       }
     }
     for (const fragment2 of this.#pendingMessages) {
-      const content = String(fragment2.data);
+      const content = estimateMessageContent(
+        fragment2.codec ? fragment2.codec.encode() : getFragmentData(fragment2)
+      );
       const tokens = tokenizer.count(content);
       const cost = tokens / 1e6 * model.cost.input;
       fragmentEstimates.push({
@@ -2246,138 +2933,6 @@ var ContextEngine = class {
   }
 };
 
-// packages/context/src/lib/fragments/domain.ts
-function term(name, definition) {
-  return {
-    name: "term",
-    data: { name, definition }
-  };
-}
-function hint(text) {
-  return {
-    name: "hint",
-    data: text
-  };
-}
-function guardrail(input) {
-  return {
-    name: "guardrail",
-    data: {
-      rule: input.rule,
-      ...input.reason && { reason: input.reason },
-      ...input.action && { action: input.action }
-    }
-  };
-}
-function explain(input) {
-  return {
-    name: "explain",
-    data: {
-      concept: input.concept,
-      explanation: input.explanation,
-      ...input.therefore && { therefore: input.therefore }
-    }
-  };
-}
-function example(input) {
-  return {
-    name: "example",
-    data: {
-      question: input.question,
-      answer: input.answer,
-      ...input.note && { note: input.note }
-    }
-  };
-}
-function clarification(input) {
-  return {
-    name: "clarification",
-    data: {
-      when: input.when,
-      ask: input.ask,
-      reason: input.reason
-    }
-  };
-}
-function workflow(input) {
-  return {
-    name: "workflow",
-    data: {
-      task: input.task,
-      steps: input.steps,
-      ...input.triggers?.length && { triggers: input.triggers },
-      ...input.notes && { notes: input.notes }
-    }
-  };
-}
-function quirk(input) {
-  return {
-    name: "quirk",
-    data: {
-      issue: input.issue,
-      workaround: input.workaround
-    }
-  };
-}
-function styleGuide(input) {
-  return {
-    name: "styleGuide",
-    data: {
-      prefer: input.prefer,
-      ...input.never && { never: input.never },
-      ...input.always && { always: input.always }
-    }
-  };
-}
-function analogy(input) {
-  return {
-    name: "analogy",
-    data: {
-      concepts: input.concepts,
-      relationship: input.relationship,
-      ...input.insight && { insight: input.insight },
-      ...input.therefore && { therefore: input.therefore },
-      ...input.pitfall && { pitfall: input.pitfall }
-    }
-  };
-}
-function glossary(entries) {
-  return {
-    name: "glossary",
-    data: Object.entries(entries).map(([term2, expression]) => ({
-      term: term2,
-      expression
-    }))
-  };
-}
-function role(content) {
-  return {
-    name: "role",
-    data: content
-  };
-}
-function principle(input) {
-  return {
-    name: "principle",
-    data: {
-      title: input.title,
-      description: input.description,
-      ...input.policies?.length && { policies: input.policies }
-    }
-  };
-}
-function policy(input) {
-  return {
-    name: "policy",
-    data: {
-      rule: input.rule,
-      ...input.before && { before: input.before },
-      ...input.reason && { reason: input.reason },
-      ...input.policies?.length && { policies: input.policies }
-    }
-  };
-}
-
 // packages/context/src/lib/fragments/message/user.ts
 import { generateId as generateId4, isTextUIPart } from "ai";
 var SYSTEM_REMINDER_OPEN_TAG = "<system-reminder>";
@@ -2551,7 +3106,6 @@ function user(content, ...reminders) {
   return {
     id: message2.id,
     name: "user",
-    data: "content",
     type: "message",
     persist: true,
     codec: {
@@ -2565,52 +3119,6 @@ function user(content, ...reminders) {
   };
 }
 
-// packages/context/src/lib/fragments/user.ts
-function identity(input) {
-  return {
-    name: "identity",
-    data: {
-      ...input.name && { name: input.name },
-      ...input.role && { role: input.role }
-    }
-  };
-}
-function persona(input) {
-  return {
-    name: "persona",
-    data: {
-      name: input.name,
-      ...input.role && { role: input.role },
-      ...input.objective && { objective: input.objective },
-      ...input.tone && { tone: input.tone }
-    }
-  };
-}
-function alias(term2, meaning) {
-  return {
-    name: "alias",
-    data: { term: term2, meaning }
-  };
-}
-function preference(aspect, value) {
-  return {
-    name: "preference",
-    data: { aspect, value }
-  };
-}
-function userContext(description) {
-  return {
-    name: "userContext",
-    data: description
-  };
-}
-function correction(subject, clarification2) {
-  return {
-    name: "correction",
-    data: { subject, clarification: clarification2 }
-  };
-}
-
 // packages/context/src/lib/guardrails/error-recovery.guardrail.ts
 import chalk2 from "chalk";
 var errorRecoveryGuardrail = {
@@ -6590,6 +7098,8 @@ export {
   explain,
   fail,
   fragment,
+  fromFragment,
+  getFragmentData,
   getModelsRegistry,
   getReminderRanges,
   glossary,
@@ -6630,10 +7140,10 @@ export {
   structuredOutput,
   styleGuide,
   term,
+  toFragment,
   toMessageFragment,
   useSandbox,
   user,
-  userContext,
   visualizeGraph,
   workflow
 };