dopus 0.2.8 → 0.2.10

package/README.md

@@ -224,13 +224,76 @@ Anthropic gets an explicit cache breakpoint after layer 3. OpenAI and Gemini cac
 - `<AgentChat />`: the panel;
 - `<AgentWidget />`: a floating launcher that opens the panel.
 
-Both accept `api`, `suggestions`, `labels` (every UI string, for translation), `className`, and `channel` /
-`maxJobFollowUps` for [background jobs](#background-jobs).
+Both accept `api`, `suggestions`, `labels` (every UI string, for translation), `className`, `channel` /
+`maxJobFollowUps` for [background jobs](#background-jobs), and `history` to [keep the chat](#chat-history).
 
 The UI shows each tool call as it runs. When a reply finishes while the widget is closed (for example the agent
 continuing after a [background job](#background-jobs)), the launcher shows a dot until it is opened (`labels.unread`
 for screen readers; `onReply` if you want your own signal). It renders an approve/decline card for confirmed tools and continues automatically once the user answers. When a tool has run, it calls `router.refresh()` so server components show the changed data. Closing the widget keeps the conversation, and a "New chat" button clears it. Assistant replies render as Markdown (tables, lists, code) through `react-markdown` with `remark-gfm`, which `init` installs. Raw HTML is never rendered, images show only their alt text, and links keep only http(s), mailto and relative URLs. If a request is over the size limit (413), the UI says so and offers a new chat instead of a useless retry. It also has stop and retry buttons, and it does not send on Enter while an IME (Korean, Japanese, Chinese) is still composing.
 
+### Chat history
+
+By default the conversation lives in memory: a reload starts a new chat. To keep it, pass `history` with `load`
+(called once on mount) and `save` (called when the chat settles, and with `[]` on "New chat"). Where it goes is up to
+you. Both hold functions, so set them up in a client component.
+
+In this tab only (sessionStorage), keyed by user so that after a sign-out the next user in the tab does not see it:
+
+```tsx
+// components/agent/agent.tsx
+'use client'
+import { useMemo } from 'react'
+import { type AgentChatHistory, type AgentChatProps, AgentWidget } from './agent-chat'
+
+const sessionHistory = (key: string): AgentChatHistory => ({
+  load: () => JSON.parse(sessionStorage.getItem(key) ?? '[]'),
+  save: (messages) => sessionStorage.setItem(key, JSON.stringify(messages)),
+})
+
+export function Agent({ userId, ...props }: AgentChatProps & { userId: string }) {
+  const history = useMemo(() => sessionHistory(`dopus-chat:${userId}`), [userId])
+  return <AgentWidget {...props} history={history} />
+}
+```
+
+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 (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 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
+  per user, and clear it on sign-out if the device may be shared.
+- **It is still one conversation.** The browser sends the whole history with each message, so a long chat reaches the
+  size limit (413) and the UI offers a new chat. There is no list of past chats.
+- **Background jobs across a reload.** A job that finishes while the page is reloading is not announced again, so its
+  "working in the background" line stays. The user can ask, and the agent reads the result with your status tool.
+
 Styling is one plain CSS file (`agent-chat.css`) whose classes all start with `dopus-`, themed through `--dopus-*` variables, with dark mode included. It is deliberately not a CSS Module: create-next-app's Tailwind setup routes every `*.css` file, modules included, through its own Turbopack loader, which left module classes unstyled. It needs no Tailwind and no component library. The file is yours, so restyle it or swap in your own components.
 
 ## Configuration
@@ -285,6 +348,7 @@ defineAgent({
   },
 
   // Once per request, when the reply is done: tokens summed over all steps.
+  // 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 })
   },
@@ -521,6 +585,7 @@ Planned next, within the lightweight scope above:
 pnpm install
 pnpm build && pnpm lint && pnpm typecheck && pnpm test
 pnpm example:build && pnpm example:e2e   # next start + scripted model
+pnpm example:ui                          # the chat UI in Chromium (Playwright): approvals, jobs, limits
 pnpm example:live                        # real model from examples/next-app/.env.local (costs cents)
 pnpm smoke                               # packed tarball → fresh app → init (older release) → update → next build
 pnpm templates:history                   # after changing a template: record its hash for `dopus update`

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { n as PROVIDERS, t as VERSION } from "./version-Bs8LB7Ph.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

@@ -111,7 +111,10 @@ interface AgentConfig<TOOLS extends DopusToolSet = DopusToolSet> {
   }) => Response | undefined | Promise<Response | undefined>;
   /** 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. For usage tracking. */
+  /**
+   * 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. */
   maxSteps?: number;
@@ -169,6 +172,22 @@ interface FinishEvent {
   steps: number;
   finishReason: string;
   durationMs: number;
+  /**
+   * 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[];
 }
 /** Identity function that gives `agent.config.ts` type checking. */
 export declare function defineAgent<TOOLS extends DopusToolSet>(config: AgentConfig<TOOLS>): AgentConfig<TOOLS>;
@@ -216,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.8";
+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-Bs8LB7Ph.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
 /**
@@ -378,6 +378,14 @@ function createAgentHandler(config, options = {}) {
 			})
 		};
 		const approvalSecret = config.approvalSecret ?? process.env.DOPUS_APPROVAL_SECRET;
+		const finish = { async emit() {
+			if (this.done || !this.usage || !this.conversation) return;
+			this.done = true;
+			await runHook(config.onFinish, {
+				...this.usage,
+				...this.conversation
+			}, report);
+		} };
 		const result = streamText({
 			...config.callOptions,
 			model: config.model,
@@ -410,7 +418,7 @@ function createAgentHandler(config, options = {}) {
 			onError: ({ error }) => report(error),
 			onEnd: async (event) => {
 				await config.callOptions?.onEnd?.(event);
-				await runHook(config.onFinish, {
+				finish.usage = {
 					user,
 					model: {
 						provider: event.model.provider,
@@ -425,13 +433,24 @@ function createAgentHandler(config, options = {}) {
 					steps: event.stepNumber + 1,
 					finishReason: event.finishReason,
 					durationMs: Date.now() - started
-				}, report);
+				};
+				await finish.emit();
 			}
 		});
 		const response = createUIMessageStreamResponse({ stream: toUIMessageStream({
 			stream: result.stream,
 			tools,
 			originalMessages: messages,
+			onEnd: async ({ messages: final, responseMessage, isAborted }) => {
+				if (isAborted) return;
+				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) => {
 				if (error instanceof ToolError) return error.message;
 				report(error);

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dopus",
-  "version": "0.2.8",
+  "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",

package/templates/history.json

@@ -5,7 +5,8 @@
     "af6a34c9f15d4bef": "0.2.5",
     "e0ff5f54b6823dba": "0.2.6",
     "a3542945427a3dfa": "0.2.7",
-    "46c4c3eca89693fe": "0.2.8"
+    "46c4c3eca89693fe": "0.2.8",
+    "291cb0b17e9d8613": "0.2.9"
   },
   "ui/agent-chat.module.css": {
     "8ecfa2904dee75e9": "0.1.0"

package/templates/ui/agent-chat.tsx

@@ -5,6 +5,7 @@
  * Talks to POST /api/agent with the AI SDK `useChat` protocol.
  * Styles: ./agent-chat.css — plain global CSS with `dopus-` class names (works with or without Tailwind).
  * Background jobs: pass a `channel` and the agent continues by itself when a job it started finishes.
+ * Chat history: pass `history` to keep the conversation across reloads (sessionStorage, your API...).
  */
 import { useChat } from '@ai-sdk/react'
 import {
@@ -76,6 +77,16 @@ export interface AgentChatProps {
   maxJobFollowUps?: number
   /** Called when the agent finishes a reply. `AgentWidget` uses it to mark the closed launcher as unread. */
   onReply?: () => void
+  /** Keep the conversation across reloads. Off by default (the chat lives in memory). */
+  history?: AgentChatHistory
+}
+
+/** Where the conversation is kept. Both are optional; neither may throw away the user's data silently. */
+export interface AgentChatHistory {
+  /** Called once when the chat mounts; return the conversation to restore. */
+  load?: () => UIMessage[] | null | undefined | Promise<UIMessage[] | null | undefined>
+  /** Called when the chat settles after a change, and with `[]` on "New chat". */
+  save?: (messages: UIMessage[]) => void | Promise<void>
 }
 
 export interface AgentChannel {
@@ -298,6 +309,7 @@ export function AgentChat({
   channel,
   maxJobFollowUps = 3,
   onReply,
+  history,
 }: AgentChatProps) {
   const labels = { ...DEFAULT_LABELS, ...labelOverrides }
   const router = useRouter()
@@ -340,6 +352,39 @@ export function AgentChat({
   const listRef = useRef<HTMLDivElement>(null)
   const busy = status === 'submitted' || status === 'streaming'
 
+  // Chat history: restore once on mount (after hydration), then save whenever the chat settles.
+  const historyRef = useRef(history)
+  useEffect(() => {
+    historyRef.current = history
+  })
+  const [restored, setRestored] = useState(!history?.load)
+  useEffect(() => {
+    const load = historyRef.current?.load
+    if (!load) return
+    let cancelled = false
+    Promise.resolve()
+      .then(load)
+      .then((saved) => {
+        // Keep anything the user already typed while it was loading.
+        if (!cancelled && saved?.length)
+          setMessages((current) => (current.length ? current : saved))
+      })
+      .catch((error) => console.error('[dopus] history.load failed', error))
+      .finally(() => {
+        if (!cancelled) setRestored(true)
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [setMessages])
+  useEffect(() => {
+    // Empty is saved only by "New chat", so a slow or failed load never overwrites what was stored.
+    if (!restored || status !== 'ready' || messages.length === 0) return
+    Promise.resolve(historyRef.current?.save?.(messages)).catch((error) =>
+      console.error('[dopus] history.save failed', error),
+    )
+  }, [restored, status, messages])
+
   // Jobs the channel reported finished. Kept even before this chat shows the job (a job can finish before
   // its tool output has streamed in); only IDs this chat started are acted on.
   const [finishedJobs, setFinishedJobs] = useState<Set<string>>(() => new Set())
@@ -428,6 +473,9 @@ export function AgentChat({
     clearError()
     setMessages([])
     setInput('')
+    Promise.resolve(historyRef.current?.save?.([])).catch((error) =>
+      console.error('[dopus] history.save failed', error),
+    )
   }
 
   // The route answers 413 when the history is over its size limit; retrying cannot help then.