dopus 0.2.9 → 0.2.10

package/README.md

@@ -256,27 +256,35 @@ export function Agent({ userId, ...props }: AgentChatProps & { userId: string })
 }
 ```
 
-In your database: save on the server, where you know the user, and load from the client.
+In your database: save on the server, where you know the user, and load from the client. `onFinish` gives you who
+(`user`, from `identify`), which conversation (`conversationId`) and what this request added (`newMessages`: the user's
+message and the agent's reply, with tool calls and results inside).
 
 ```ts
-// agent.config.ts
-onFinish: async ({ user, messages }) => {
-  if (user) await db.chat.upsert({ userId: user.id, messages })   // needs `identify`
+// agent.config.ts (needs `identify`, so `user` is set)
+onFinish: async ({ user, conversationId, newMessages }) => {
+  if (!user) return
+  for (const message of newMessages) {
+    // Upsert by id: after an approval the reply arrives again, continued. Key by user too, since
+    // conversationId comes from the browser.
+    await db.chatMessage.upsert({ id: message.id, userId: user.id, conversationId, message })
+  }
 },
 ```
 
 ```tsx
-// components/agent/agent.tsx: loadChat is your server action returning the saved messages
-;<AgentWidget
-  history={{
-    load: () => loadChat(),
-    save: (m) => {
-      if (m.length === 0) clearChat()
-    },
-  }}
-/>
+// components/agent/agent.tsx: loadChat is your server action returning the latest conversation's messages
+;<AgentWidget history={{ load: () => loadChat() }} />
 ```
 
+- **`conversationId`** is the id of the conversation's first message: the same after a reload (when `history.load`
+  restores it), new after "New chat". A list of past conversations is yours to build from it.
+- **`newMessages`** rather than the whole history: the browser sends the whole conversation with every request, so
+  saving only what this request added keeps earlier stored messages out of its reach. `messages` (the whole
+  conversation) is there too if one snapshot per conversation is enough.
+- **Stopped or failed turns** do not reach `onFinish`. To keep the user's message anyway, save it in `beforeRequest`
+  (it gets `user` and `messages`).
+
 Things to know:
 
 - **Tool results are stored too.** Whatever your tools returned (orders, names) is in the saved conversation. Keep it
@@ -340,7 +348,7 @@ defineAgent({
   },
 
   // Once per request, when the reply is done: tokens summed over all steps.
-  // also gets `messages`: the whole conversation after this reply (see "Chat history")
+  // also gets conversationId, newMessages and messages, to save the chat (see "Chat history")
   onFinish: async ({ user, model, usage, steps, finishReason, durationMs }) => {
     await db.usage.insert({ userId: user?.id, model: model.modelId, ...usage })
   },

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { n as PROVIDERS, t as VERSION } from "./version-NYbd20Zw.js";
+import { n as PROVIDERS, t as VERSION } from "./version-CWmiLdVn.js";
 import { execFileSync, spawn } from "node:child_process";
 import { parseArgs } from "node:util";
 import * as p from "@clack/prompts";

package/dist/index.d.ts

@@ -112,8 +112,8 @@ interface AgentConfig<TOOLS extends DopusToolSet = DopusToolSet> {
   /** Called once per tool call: ran (`success` / `error`) or declined by the user (`denied`). For audit logs. */
   onToolCall?: (event: ToolCallEvent) => void | Promise<void>;
   /**
-   * Called once per request when the reply is finished: tokens, steps, model (usage tracking), and the whole
-   * conversation including the reply (to save chat history in your database).
+   * Called once per request when the reply is finished: tokens, steps, model (usage tracking), and the conversation
+   * (to save chat history in your database: `user`, `conversationId`, `newMessages`).
    */
   onFinish?: (event: FinishEvent) => void | Promise<void>;
   /** Maximum model steps (tool round trips) per request. Default 10. */
@@ -173,8 +173,19 @@ interface FinishEvent {
   finishReason: string;
   durationMs: number;
   /**
-   * The conversation after this reply, as the chat UI holds it (`UIMessage[]`). Save it to restore the chat later
-   * (the chat UI's `history.load`). It came from the browser, so treat it as the user's own data, not as trusted.
+   * Which conversation this is: the id of its first message. The same across reloads (when the chat UI restores
+   * its `history`), new after "New chat". Sent by the browser, so store it under `user`, never on its own.
+   */
+  conversationId: string;
+  /**
+   * What this request added or changed: the user's message (when the request started with one) and the
+   * assistant's reply. After an approval the reply is the same message, continued, so upsert by `id`.
+   * Saving only these keeps earlier stored messages out of the browser's reach.
+   */
+  newMessages: UIMessage[];
+  /**
+   * The whole conversation after this reply, as the chat UI holds it. Handy to store one snapshot per
+   * conversation; it comes from the browser, so it can differ from what you stored earlier.
    */
   messages: UIMessage[];
 }
@@ -224,5 +235,5 @@ interface ProviderInfo {
 }
 /** Verified against @ai-sdk/openai@4.0.111, @ai-sdk/anthropic@4.0.99, @ai-sdk/google@4.0.114. */
 export declare const PROVIDERS: Record<ProviderId, ProviderInfo>;
-export declare const VERSION = "0.2.9";
+export declare const VERSION = "0.2.10";
 export type { AgentConfig, AgentUser, ClientContext, ConfirmOption, DopusTool, DopusToolSet, FinishEvent, HandlerOptions, PromptLayers, ProviderId, ProviderInfo, RuntimeContext, ToolCallEvent, ToolContext, ToolOptions };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { n as PROVIDERS, t as VERSION } from "./version-NYbd20Zw.js";
+import { n as PROVIDERS, t as VERSION } from "./version-CWmiLdVn.js";
 import { convertToModelMessages, createUIMessageStreamResponse, getToolName, isStepCount, isToolUIPart, safeValidateUIMessages, streamText, toUIMessageStream, tool } from "ai";
 // src/job.ts
 /**
@@ -379,11 +379,11 @@ function createAgentHandler(config, options = {}) {
 		};
 		const approvalSecret = config.approvalSecret ?? process.env.DOPUS_APPROVAL_SECRET;
 		const finish = { async emit() {
-			if (this.done || !this.usage || !this.messages) return;
+			if (this.done || !this.usage || !this.conversation) return;
 			this.done = true;
 			await runHook(config.onFinish, {
 				...this.usage,
-				messages: this.messages
+				...this.conversation
 			}, report);
 		} };
 		const result = streamText({
@@ -441,9 +441,14 @@ function createAgentHandler(config, options = {}) {
 			stream: result.stream,
 			tools,
 			originalMessages: messages,
-			onEnd: async ({ messages: final, isAborted }) => {
+			onEnd: async ({ messages: final, responseMessage, isAborted }) => {
 				if (isAborted) return;
-				finish.messages = final;
+				const last = messages.at(-1);
+				finish.conversation = {
+					conversationId: messages[0]?.id ?? responseMessage.id,
+					newMessages: last?.role === "user" ? [last, responseMessage] : [responseMessage],
+					messages: final
+				};
 				await finish.emit();
 			},
 			onError: (error) => {

package/dist/{version-NYbd20Zw.js → version-CWmiLdVn.js}

@@ -27,5 +27,5 @@ const PROVIDERS = {
 	}
 };
 // src/version.ts
-const VERSION = "0.2.9";
+const VERSION = "0.2.10";
 export { PROVIDERS as n, VERSION as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dopus",
-  "version": "0.2.9",
+  "version": "0.2.10",
   "description": "A lightweight agent for Next.js: your existing server functions become its tools, run with the signed-in user's permissions.",
   "license": "MIT",
   "author": "akodm",