@deepagents/context 0.38.0 → 0.38.1

package/dist/index.js

@@ -199,6 +199,12 @@ function assistant(message2) {
     }
   };
 }
+function toMessageFragment(item) {
+  if (isFragment(item) && isMessageFragment(item)) {
+    return item;
+  }
+  return message(item);
+}
 function message(content) {
   const message2 = typeof content === "string" ? {
     id: generateId(),
@@ -1869,7 +1875,6 @@ import {
   NoSuchToolError as NoSuchToolError2,
   ToolCallRepairError,
   createUIMessageStream as createUIMessageStream2,
-  generateId as generateId4,
   isToolUIPart
 } from "ai";
 
@@ -1877,7 +1882,10 @@ import {
 import { z as z2 } from "zod";
 
 // packages/context/src/lib/engine.ts
-import { validateUIMessages } from "ai";
+import {
+  generateId as generateId4,
+  validateUIMessages
+} from "ai";
 import { mergeWith } from "lodash-es";
 
 // packages/context/src/lib/estimate.ts
@@ -2585,6 +2593,9 @@ function estimateMessageContent(data) {
 function isLanguageModelUsage(value) {
   return typeof value === "object" && value !== null && "totalTokens" in value;
 }
+function isEmptyAssistantPlaceholder(message2) {
+  return message2.role === "assistant" && message2.parts.length === 0;
+}
 var ContextEngine = class _ContextEngine {
   /** Non-message fragments (role, hints, etc.) - not persisted in graph */
   #fragments = [];
@@ -2766,6 +2777,120 @@ var ContextEngine = class _ContextEngine {
     const { turn } = await this.#getChainContext();
     return turn;
   }
+  async firstUserMessage() {
+    await this.#ensureInitialized();
+    if (this.#branch?.headMessageId) {
+      const chain = await this.#store.getMessageChain(
+        this.#branch.headMessageId
+      );
+      for (const msg of chain) {
+        if (msg.name === "user") return msg.data;
+      }
+    }
+    for (const fragment2 of this.#pendingMessages) {
+      if (fragment2.name !== "user") continue;
+      if (!fragment2.codec) {
+        throw new Error(`Fragment "${fragment2.name}" is missing codec.`);
+      }
+      return fragment2.codec.encode();
+    }
+    return void 0;
+  }
+  /**
+   * Return the head of the conversation — pending tail or persisted branch head.
+   *
+   * Includes empty assistant placeholders (use this for id-lookup, not for
+   * building model prompts — see `getMessages()` for prompt-ready output).
+   *
+   * @throws if the pending tail is missing an id (programming error).
+   */
+  async headMessage() {
+    await this.#ensureInitialized();
+    if (this.#pendingMessages.length > 0) {
+      const tail = this.#pendingMessages[this.#pendingMessages.length - 1];
+      if (!tail.id) {
+        throw new Error(
+          `headMessage: pending fragment "${tail.name}" is missing id`
+        );
+      }
+      return { id: tail.id, name: tail.name };
+    }
+    if (this.#branch?.headMessageId) {
+      const msg = await this.#store.getMessage(this.#branch.headMessageId);
+      if (msg) return { id: msg.id, name: msg.name };
+    }
+    return void 0;
+  }
+  /**
+   * Return the model-ready conversation: persisted chain plus pending fragments,
+   * with empty assistant placeholders filtered out.
+   *
+   * For id-lookup use `headMessage()` instead — that one keeps placeholders.
+   */
+  async getMessages() {
+    await this.#ensureInitialized();
+    const messages = [];
+    if (this.#branch?.headMessageId) {
+      const chain = await this.#store.getMessageChain(
+        this.#branch.headMessageId
+      );
+      for (const msg of chain) {
+        const data = msg.data;
+        if (isEmptyAssistantPlaceholder(data)) continue;
+        messages.push(data);
+      }
+    }
+    for (const fragment2 of this.#pendingMessages) {
+      if (!fragment2.codec) {
+        throw new Error(`Fragment "${fragment2.name}" is missing codec.`);
+      }
+      const encoded = fragment2.codec.encode();
+      if (isEmptyAssistantPlaceholder(encoded)) continue;
+      messages.push(encoded);
+    }
+    return messages.length === 0 ? [] : validateUIMessages({ messages });
+  }
+  /**
+   * Advance the conversation by one turn. Required setup before `chat()`.
+   *
+   * - User input → persists the message AND appends an empty assistant
+   *   placeholder reserving the id of the next streamed response.
+   * - Assistant input (tool-resume / continuation) → persists in-place
+   *   (`branch: false`), reusing the input's id.
+   *
+   * Always leaves the chain head as an assistant fragment, satisfying chat()'s
+   * precondition.
+   *
+   * @returns the assistant id that will receive the streamed response — useful
+   *   for telemetry, optimistic UI, or correlating logs before the stream starts.
+   * @throws if assistant input is missing an id.
+   *
+   * @example
+   * ```ts
+   * const assistantId = await context.continue(user('hi'));
+   * const stream = await chat(agent); // streams into assistantId
+   * ```
+   */
+  async continue(input) {
+    const fragment2 = toMessageFragment(input);
+    const isAssistantUpdate = fragment2.name === "assistant";
+    let assistantId;
+    if (isAssistantUpdate) {
+      if (!fragment2.id) {
+        throw new Error("continue: assistant input is missing id");
+      }
+      assistantId = fragment2.id;
+      this.set(fragment2);
+    } else {
+      assistantId = generateId4();
+      this.set(
+        fragment2,
+        assistant({ id: assistantId, role: "assistant", parts: [] })
+      );
+    }
+    await this.save({ branch: !isAssistantUpdate });
+    return assistantId;
+  }
   /**
    * Add fragments to the context.
    *
@@ -2812,25 +2937,8 @@ var ContextEngine = class _ContextEngine {
   async resolve(options) {
     await this.#ensureInitialized();
     const systemPrompt = options.renderer.render(this.#renderableFragments);
-    const messages = [];
-    if (this.#branch?.headMessageId) {
-      const chain = await this.#store.getMessageChain(
-        this.#branch.headMessageId
-      );
-      for (const msg of chain) {
-        messages.push(msg.data);
-      }
-    }
-    for (const fragment2 of this.#pendingMessages) {
-      if (!fragment2.codec) {
-        throw new Error(`Fragment "${fragment2.name}" is missing codec.`);
-      }
-      messages.push(fragment2.codec.encode());
-    }
-    return {
-      systemPrompt,
-      messages: messages.length === 0 ? [] : await validateUIMessages({ messages })
-    };
+    const messages = await this.getMessages();
+    return { systemPrompt, messages };
   }
   /**
    * Save pending messages to the graph.
@@ -3746,55 +3854,75 @@ Examples:
 - "hi" -> New Conversation
 - "debug my python code" -> Python Debugging`;
 var titleSchema = z2.object({ title: z2.string() });
-function extractText(message2) {
-  const cleaned = stripReminders(message2);
-  const textPart = cleaned.parts.find((p) => p.type === "text");
-  return textPart && "text" in textPart ? textPart.text : "";
-}
-function truncateTitle(text) {
-  if (!text) return "New Chat";
-  return text.length > 100 ? text.slice(0, 100) + "..." : text;
-}
-function staticChatTitle(message2) {
-  return truncateTitle(extractText(message2));
-}
-async function generateChatTitle(options) {
-  const text = extractText(options.message);
-  const fallback = truncateTitle(text);
-  if (!text) return fallback;
-  const store2 = new InMemoryContextStore();
-  const context = new ContextEngine({
-    store: store2,
-    chatId: crypto.randomUUID(),
-    userId: "system"
-  });
-  context.set(role(TITLE_PROMPT), user(text));
-  try {
+var TitleGenerator = class {
+  #context;
+  constructor(options) {
+    this.#context = options.context;
+  }
+  async ensure(options) {
+    const msg = await this.#firstUntitledUser();
+    if (!msg) return null;
+    try {
+      const title = await this.#generateTitle(msg, options);
+      return this.#applyTitle(title, "llm");
+    } catch (error) {
+      console.warn(
+        "TitleGenerator: LLM title generation failed, falling back to static.",
+        error
+      );
+      return this.#applyTitle(this.#staticTitle(msg), "static");
+    }
+  }
+  async ensureStatic() {
+    const msg = await this.#firstUntitledUser();
+    if (!msg) return null;
+    return this.#applyTitle(this.#staticTitle(msg), "static");
+  }
+  #staticTitle(message2) {
+    return this.#truncateTitle(this.#extractText(message2));
+  }
+  async #generateTitle(message2, options) {
+    const text = this.#extractText(message2);
+    if (!text) {
+      throw new Error(
+        "Cannot generate chat title: message has no text content."
+      );
+    }
+    const store2 = new InMemoryContextStore();
+    const context = new ContextEngine({
+      store: store2,
+      chatId: crypto.randomUUID(),
+      userId: "system"
+    });
+    context.set(role(TITLE_PROMPT), user(text));
     const { title } = await structuredOutput({
       context,
       model: options.model,
       schema: titleSchema
     }).generate({}, { abortSignal: options.abortSignal });
-    return title || fallback;
-  } catch (error) {
-    console.warn("Title generation failed, using fallback:", error);
-    return fallback;
+    if (!title) {
+      throw new Error("Title generation returned an empty string.");
+    }
+    return title;
   }
-}
-
-// packages/context/src/lib/chat.ts
-function toMessageFragment(item) {
-  if (isFragment(item) && isMessageFragment(item)) {
-    return item;
+  #extractText(message2) {
+    return extractPlainText(stripReminders(message2));
   }
-  return message(item);
-}
-function chatMessageToUIMessage(item) {
-  if (isFragment(item) && isMessageFragment(item)) {
-    return item.codec.encode();
+  #truncateTitle(text) {
+    if (!text) return "New Chat";
+    return text.length > 100 ? text.slice(0, 100) + "..." : text;
   }
-  return item;
-}
+  async #applyTitle(title, source) {
+    await this.#context.updateChat({ title });
+    return { title, source };
+  }
+  async #firstUntitledUser() {
+    if (this.#context.chat?.title) return void 0;
+    return this.#context.firstUserMessage();
+  }
+};
+
+// packages/context/src/lib/chat.ts
 var defaultChatMessageMetadata = ({
   part
 }) => {
@@ -3806,7 +3934,7 @@ var defaultChatMessageMetadata = ({
   }
   return void 0;
 };
-async function chat(agent2, messages, options) {
+async function chat(agent2, options = {}) {
   const context = agent2.context;
   const sandbox = agent2.sandbox;
   if (!context) {
@@ -3814,53 +3942,36 @@ async function chat(agent2, messages, options) {
       "Agent is missing a context. Provide context when creating the agent."
     );
   }
-  if (messages.length === 0) {
-    throw new Error("messages must not be empty");
-  }
-  const lastItem = messages[messages.length - 1];
-  const lastFragment = toMessageFragment(lastItem);
-  const lastUIMessage = chatMessageToUIMessage(lastItem);
-  let assistantMsgId;
-  if (lastUIMessage.role === "assistant") {
-    context.set(lastFragment);
-    await context.save({ branch: false });
-    assistantMsgId = lastUIMessage.id;
-  } else {
-    context.set(lastFragment);
-    await context.save();
-    assistantMsgId = generateId4();
-  }
-  const uiMessages = messages.map(chatMessageToUIMessage);
-  let title = null;
-  if (!context.chat?.title) {
-    const firstUserMsg = uiMessages.find((m) => m.role === "user");
-    if (firstUserMsg) {
-      if (options?.generateTitle && agent2.model) {
-        title = await generateChatTitle({
-          message: firstUserMsg,
-          model: agent2.model,
-          abortSignal: options?.abortSignal
-        });
-      } else {
-        title = staticChatTitle(firstUserMsg);
-      }
-      await context.updateChat({ title });
-    }
+  const head = await context.headMessage();
+  if (head?.name !== "assistant") {
+    throw new Error(
+      "chat: expected an assistant message at head. Call context.continue(input) before chat()."
+    );
   }
-  const streamContextVariables = options?.contextVariables === void 0 ? {} : options.contextVariables;
-  const result = await agent2.stream(streamContextVariables, {
-    transform: options?.transform,
-    abortSignal: options?.abortSignal
-  });
+  const assistantMsgId = head.id;
+  const uiMessages = await context.getMessages();
+  const streamContextVariables = options.contextVariables === void 0 ? {} : options.contextVariables;
+  const [title, result] = await Promise.all([
+    makeTitle({
+      context,
+      model: agent2.model,
+      generateTitle: options.generateTitle,
+      abortSignal: options.abortSignal
+    }),
+    agent2.stream(streamContextVariables, {
+      transform: options.transform,
+      abortSignal: options.abortSignal
+    })
+  ]);
   const uiStream = result.toUIMessageStream({
-    onError: options?.onError ?? formatChatError,
+    onError: options.onError ?? formatChatError,
     sendStart: true,
     sendFinish: true,
     sendReasoning: true,
     sendSources: true,
     originalMessages: uiMessages,
     generateMessageId: () => assistantMsgId,
-    messageMetadata: options?.messageMetadata ?? defaultChatMessageMetadata
+    messageMetadata: options.messageMetadata ?? defaultChatMessageMetadata
   });
   return createUIMessageStream2({
     originalMessages: uiMessages,
@@ -3883,7 +3994,7 @@ async function chat(agent2, messages, options) {
       }
       const drained = sandbox.drainFileEvents?.() ?? [];
       const fileEvents = isAborted ? [] : drained;
-      const finalMetadata = await options?.finalAssistantMetadata?.(normalizedMessage);
+      const finalMetadata = await options.finalAssistantMetadata?.(normalizedMessage);
       const mergedMetadata = {
         ...normalizedMessage.metadata ?? {},
         ...fileEvents.length > 0 ? { fileEvents } : {},
@@ -3920,9 +4031,7 @@ function sanitizeAbortedParts(parts) {
       sanitized.push(part);
       continue;
     }
-    if (part.state === "input-streaming") {
-      continue;
-    }
+    if (part.state === "input-streaming") continue;
     sanitized.push({
       ...part,
       state: "output-error",
@@ -3947,6 +4056,19 @@ function formatChatError(error) {
   }
   return JSON.stringify(error);
 }
+async function makeTitle(options) {
+  const titler = new TitleGenerator({ context: options.context });
+  if (options.generateTitle && !options.model) {
+    console.warn(
+      "chat: generateTitle=true but agent.model is unset; using static title."
+    );
+  }
+  const result = options.generateTitle && options.model ? await titler.ensure({
+    model: options.model,
+    abortSignal: options.abortSignal
+  }) : await titler.ensureStatic();
+  return result?.title ?? null;
+}
 
 // packages/context/src/lib/fragments/user.ts
 function identity(input) {
@@ -9211,6 +9333,7 @@ export {
   SqliteStreamStore,
   StreamManager,
   StreamStore,
+  TitleGenerator,
   TomlRenderer,
   ToonRenderer,
   XmlRenderer,
@@ -9234,7 +9357,6 @@ export {
   buildSubcommandRepair,
   chainHooks,
   chat,
-  chatMessageToUIMessage,
   clarification,
   classifies,
   contentIncludes,
@@ -9272,7 +9394,6 @@ export {
   formatResponse,
   fragment,
   fromFragment,
-  generateChatTitle,
   getFragmentData,
   getLocaleFromMessage,
   getModelsRegistry,
@@ -9335,7 +9456,6 @@ export {
   skillsReminder,
   socraticPrompting,
   soul,
-  staticChatTitle,
   stop,
   stripQuoteArtifacts,
   stripReminders,