dopus 0.2.9 → 0.2.12

package/README.md

@@ -142,6 +142,7 @@ export default defineAgent({
 | `input`       | **Required.** A zod schema. The model's arguments are validated before `fn` runs.                        |
 | `confirm`     | `true`, or `(input, ctx) => boolean`, to ask the user before each call. Use it for anything that writes. |
 | `output`      | `(result) => unknown`. Trims the result before the model sees it, for example to drop internal fields.   |
+| `public`      | `true` to offer the tool to users who are not signed in too. Needs `identify` (see below).               |
 
 `ctx` is `{ user, toolCallId, abortSignal }`. `user` is only set when you configure `identify` (see below).
 
@@ -202,6 +203,33 @@ Your part, so an injected instruction cannot cause damage:
 
 We tested this with a real model in a small task-board app. A member wrote a task whose title ordered the assistant to delete other tasks, then an admin's assistant listed the tasks. Claude (claude-sonnet-5-5) did not even request the deletion and pointed out the planted text. If a model did request it, the approval card would still stop it. Other models were not tested this way.
 
+**Signed-in and anonymous users.** Define `identify` and dopus knows who is signed in. When it returns `undefined`, the
+model gets only the tools marked `public: true` (product info, opening hours, "am I signed in?"), and the prompt says
+the rest needs sign-in, so the agent tells the visitor to sign in instead of trying. Member tools are not offered at
+all, so a visitor does not see which features exist. Signed-in users get every tool. An approval for a member tool
+that arrives after the user signed out (in another tab) is not run.
+
+```ts
+defineAgent({
+  tools: {
+    getOpeningHours: defineTool(getOpeningHours, {
+      description: '...',
+      input: z.object({}),
+      public: true,
+    }),
+    listMyOrders: defineTool(() => listMyOrders(), { description: '...', input: z.object({}) }),
+  },
+  identify: async () => {
+    const session = await getSession()
+    return session ? { id: session.userId } : undefined
+  },
+})
+```
+
+This decides what the model sees, nothing more: keep the checks in your server functions. Without `identify` dopus
+cannot tell, so every tool is offered to everyone (and `defineAgent` warns if you used `public`). Anonymous users cost
+model tokens too; rate-limit them in `beforeRequest` (see [Audit log, usage and rate limits](#audit-log-usage-and-rate-limits)).
+
 **Running tools outside the request.** Background jobs and queues lose the request's cookies. For that case, define `identify(request)` to resolve a serialisable user. Tools then receive it as `ctx.user` and can pass it on explicitly. dopus itself always runs tools inside the request; this is for jobs your tools hand off.
 
 ## Prompts
@@ -256,27 +284,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 +376,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-gbic1Mgf.js";
 import { execFileSync, spawn } from "node:child_process";
 import { parseArgs } from "node:util";
 import * as p from "@clack/prompts";

package/dist/index.d.ts

@@ -66,6 +66,12 @@ interface ToolOptions<SCHEMA extends z.ZodType, RESULT> {
    * the job finishes the agent is told, reads the result with another of your tools, and continues.
    */
   job?: (result: Awaited<RESULT>) => string;
+  /**
+   * Also offered to users who are not signed in. Needs `identify` in the agent config: when it returns
+   * `undefined`, only public tools are given to the model, so features that need an account stay out of sight.
+   * This only decides which tools the model sees; keep the permission checks in your server functions.
+   */
+  public?: boolean;
 }
 type ToolFunction<INPUT, RESULT> = (input: INPUT, ctx: ToolContext) => RESULT;
 interface DopusTool<SCHEMA extends z.ZodType = z.ZodType, RESULT = unknown> {
@@ -112,8 +118,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 +179,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 +241,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.12";
 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-gbic1Mgf.js";
 import { convertToModelMessages, createUIMessageStreamResponse, getToolName, isStepCount, isToolUIPart, safeValidateUIMessages, streamText, toUIMessageStream, tool } from "ai";
 // src/job.ts
 /**
@@ -82,7 +82,8 @@ const CACHE_BREAKPOINT = { anthropic: { cacheControl: { type: "ephemeral" } } };
 const RUNTIME_LABELS = {
 	locale: "Response language",
 	role: "User role",
-	page: "Current page (reported by the browser)"
+	page: "Current page (reported by the browser)",
+	access: "Access"
 };
 /** Picks `ko-KR`, then `ko`, from the locale notes. */
 function pickLocaleNotes(notes, locale) {
@@ -194,8 +195,27 @@ function defineAgent(config) {
 		if (!isDopusTool(value)) throw new TypeError(`defineAgent: tools.${name} must be created with defineTool()`);
 		if (!/^[a-zA-Z0-9_-]{1,64}$/.test(name)) throw new TypeError(`defineAgent: tool name "${name}" must match [a-zA-Z0-9_-]{1,64}`);
 	}
+	if (!config.identify && Object.values(config.tools).some((t) => t.options.public)) console.warn("[dopus] `public` tools need `identify` in defineAgent: without it dopus cannot tell who is signed in, so every tool is offered to everyone.");
 	return config;
 }
+/**
+* The tools this request may use: all of them for a signed-in user, only `public` ones for an anonymous user.
+* Without `identify` dopus cannot tell who is signed in, so every tool is offered (the server functions decide).
+*/
+function visibleTools(config, user) {
+	if (!config.identify || user) return {
+		tools: config.tools,
+		hidden: []
+	};
+	const tools = {};
+	const hidden = [];
+	for (const [name, t] of Object.entries(config.tools)) if (t.options.public) tools[name] = t;
+	else hidden.push(name);
+	return {
+		tools,
+		hidden
+	};
+}
 /** Runs a user hook; a failing hook is reported but never breaks the chat. */
 async function runHook(hook, event, report) {
 	if (!hook) return;
@@ -277,6 +297,10 @@ function readClientContext(body, request) {
 		page: clean(raw.page, 200)
 	};
 }
+/** Reason recorded for a confirmation of a tool that needs sign-in, answered by a user who is not signed in. */
+const SIGN_IN_REASON = "Not run: this needs the user to be signed in, and they are not (anymore). Tell them to sign in first.";
+/** Runtime prompt line for anonymous users when some tools are hidden from them. */
+const SIGNED_OUT_NOTE = "Not signed in. Only features that work without an account are available; if the user asks for something else, tell them to sign in first.";
 /** Reason recorded for a confirmation the conversation moved past (the model reads it). */
 const NOT_RUN_REASON = "Not run: the user sent a new message instead of approving it. If they still want it, call the tool again so they can approve it.";
 /**
@@ -286,11 +310,11 @@ const NOT_RUN_REASON = "Not run: the user sent a new message instead of approvin
 * approved-but-unrun call makes every later request fail with a missing tool result. A stale approval is never
 * executed: the user has moved on, so it may no longer be what they want.
 */
-function settleStaleApprovals(messages) {
+function settleStaleApprovals(messages, hidden = []) {
 	const last = messages.length - 1;
 	return messages.map((message, index) => {
-		if (message.role !== "assistant" || index === last) return message;
-		const pending = (part) => isToolUIPart(part) && (part.state === "approval-requested" || part.state === "approval-responded");
+		if (message.role !== "assistant") return message;
+		const pending = (part) => isToolUIPart(part) && (part.state === "approval-requested" || part.state === "approval-responded") && (index !== last || hidden.includes(getToolName(part)));
 		if (!message.parts.some(pending)) return message;
 		return {
 			...message,
@@ -303,7 +327,7 @@ function settleStaleApprovals(messages) {
 					approval: {
 						id: part.approval.id,
 						approved: false,
-						reason: declined ? part.approval.reason : NOT_RUN_REASON
+						reason: declined ? part.approval.reason : index === last ? SIGN_IN_REASON : NOT_RUN_REASON
 					}
 				};
 			})
@@ -343,14 +367,15 @@ function createAgentHandler(config, options = {}) {
 			return errorResponse(400, "Request body must be JSON");
 		}
 		const user = await config.identify?.(request);
-		const { tools, toolApproval } = buildTools(config.tools, {
+		const visible = visibleTools(config, user);
+		const { tools, toolApproval } = buildTools(visible.tools, {
 			user,
 			report,
 			onToolCall: config.onToolCall
 		});
 		const validated = await safeValidateUIMessages({ messages: body?.messages });
 		if (!validated.success) return errorResponse(400, "Invalid messages");
-		const messages = settleStaleApprovals(validated.data);
+		const messages = settleStaleApprovals(validated.data, visible.hidden);
 		if (messages.some((message) => message.role === "user" && message.parts.some((part) => part.type === "text" && part.text.length > maxMessageChars))) return errorResponse(413, "Message is too long");
 		if (messages.some((message) => message.parts.some((part) => part.type === "data-dopus-job" && !isJobId(part.data?.id)))) return errorResponse(400, "Invalid job notice");
 		const early = await config.beforeRequest?.({
@@ -372,6 +397,7 @@ function createAgentHandler(config, options = {}) {
 		const client = readClientContext(body, request);
 		const runtime = {
 			...client,
+			...visible.hidden.length > 0 ? { access: SIGNED_OUT_NOTE } : {},
 			...await config.runtime?.(request, {
 				user,
 				client
@@ -379,11 +405,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 +467,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-gbic1Mgf.js}

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

package/package.json

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