dopus 0.2.4 → 0.2.6

package/README.md

@@ -1,6 +1,7 @@
 # dopus
 
-Drop an AI agent into your existing Next.js app. Your server functions become its tools.
+A lightweight agent for Next.js. Hand it the server functions your app already has, and it does the user's tasks with
+them, with the user's own permissions.
 
 ```bash
 pnpm add dopus
@@ -14,6 +15,21 @@ pnpm dopus init
 
 Built on the [Vercel AI SDK](https://ai-sdk.dev) 7. Supports OpenAI, Anthropic and Google models.
 
+**What it is for.** An assistant inside your app that answers questions about the user's data and makes small changes
+on request: "show my open orders", "move this task to done", "assign the deploy checklist to Carol". Each turn is a few
+quick server-function calls inside one request, usually a few seconds.
+
+**What it is not.** dopus stays small on purpose. These are out of scope:
+
+- Running long work itself. A tool should finish in seconds. Longer jobs run in your own queue, Lambda or worker; a
+  tool starts them, and the agent picks up again when your app announces they finished (see
+  [Background jobs](#background-jobs)).
+- Autonomous, scheduled or multi-agent workflows.
+- Built-in memory, RAG or a vector store. If you need search over documents, expose it as a tool.
+- Frameworks other than Next.js, and the Pages Router.
+- Running the agent somewhere other than your Next.js app. `dopus infra` only writes the deploy config that keeps the
+  agent route streaming on AWS, Cloudflare or Cloud Run.
+
 ---
 
 ## Quick start
@@ -108,6 +124,20 @@ export default defineAgent({
 
 `ctx` is `{ user, toolCallId, abortSignal }`. `user` is only set when you configure `identify` (see below).
 
+### Designing tools
+
+A lightweight agent works best with small, fast tools:
+
+- **Few.** Register the tools a user needs here, not every function you have. Past roughly 20 to 30 tools, models pick
+  the wrong one more often, and every request carries every description.
+- **Fast.** A tool should return in a second or two. Longer work belongs in a job (see
+  [Timeouts and long-running tools](#timeouts-and-long-running-tools)).
+- **Small results.** Take filters and a limit, and return only the fields the agent needs (`output` helps). A thousand
+  rows cost tokens on every later step, and the whole history counts against `limits.maxBodyBytes`.
+- **Batch, don't loop.** "Close all 200 stale tickets" should be one server function that takes a filter, not 200 calls.
+  A turn allows at most `maxSteps` (10) model ↔ tool round trips.
+- **Clear names and descriptions.** The model chooses by them. Say when _not_ to use a tool in `usage`.
+
 ### Errors
 
 Only two kinds of error message reach the model:
@@ -134,14 +164,14 @@ Any other error goes to `onError` and is replaced with a generic message, so dat
 
 **Prompt injection.** Assume the model can be talked into anything: by the user, or by text inside tool results that other people wrote (a task title, a comment, an email body). dopus does not rely on the model resisting it. The limits are structural:
 
-| Layer                  | What it guarantees                                                                                 |
-| ---------------------- | -------------------------------------------------------------------------------------------------- |
-| Permission inheritance | A tool can do only what the signed-in user can do through your server functions.                   |
-| `confirm: true`        | The user sees the exact input and must approve; signed approvals cannot be forged or edited.       |
-| Plain-text chat UI     | Replies render as text, never HTML or Markdown, so no XSS and no image-URL data leaks.             |
-| Request limits         | `limits.maxBodyBytes` (1 MB) and `limits.maxMessageChars` (8000) answer 413 before the model runs. |
-| `maxSteps`             | At most 10 model ↔ tool round trips per request.                                                   |
-| Core prompt            | Tells the model that tool results are data, not instructions. Helpful, but not a guarantee.        |
+| Layer                  | What it guarantees                                                                                                      |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| Permission inheritance | A tool can do only what the signed-in user can do through your server functions.                                        |
+| `confirm: true`        | The user sees the exact input and must approve; signed approvals cannot be forged or edited.                            |
+| Chat UI rendering      | Markdown without raw HTML, images never loaded, only http(s)/mailto/relative links: no XSS and no image-URL data leaks. |
+| Request limits         | `limits.maxBodyBytes` (1 MB) and `limits.maxMessageChars` (8000) answer 413 before the model runs.                      |
+| `maxSteps`             | At most 10 model ↔ tool round trips per request.                                                                        |
+| Core prompt            | Tells the model that tool results are data, not instructions. Helpful, but not a guarantee.                             |
 
 Your part, so an injected instruction cannot cause damage:
 
@@ -151,7 +181,7 @@ 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.
 
-**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. Infra adapters that run tools elsewhere will build on this.
+**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
 
@@ -173,9 +203,10 @@ 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) and `className`.
+Both accept `api`, `suggestions`, `labels` (every UI string, for translation), `className`, and `channel` /
+`maxJobFollowUps` for [background jobs](#background-jobs).
 
-The UI shows each tool call as it runs. 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. It also has stop and retry buttons, and it does not send on Enter while an IME (Korean, Japanese, Chinese) is still composing.
+The UI shows each tool call as it runs. 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.
 
 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.
 
@@ -190,6 +221,9 @@ defineAgent({
   identify: async (request) => ({ id: 'user-1' }), // optional
   maxSteps: 10, // model ↔ tool round trips per request
   limits: { maxBodyBytes: 1_000_000, maxMessageChars: 8_000 }, // over → 413
+  beforeRequest,
+  onToolCall,
+  onFinish, // see "Audit log, usage and rate limits"
   approvalSecret, // default: process.env.DOPUS_APPROVAL_SECRET
   callOptions: {
     temperature,
@@ -204,6 +238,44 @@ defineAgent({
 })
 ```
 
+## Audit log, usage and rate limits
+
+Three optional hooks in `defineAgent`. `user` in each comes from `identify`, so define it if you need to know who asked.
+
+```ts
+defineAgent({
+  // ...
+  identify: async () => {
+    const session = await getSession()
+    return session ? { id: session.userId } : undefined
+  },
+
+  // Before the model is called. Return a Response to answer with it instead.
+  beforeRequest: async ({ user, request, messages }) => {
+    const { success } = await ratelimit.limit(user?.id ?? ip(request))
+    if (!success) return Response.json({ error: 'Too many requests' }, { status: 429 })
+  },
+
+  // Every tool call: outcome 'success' | 'error' | 'denied' (the user declined the approval).
+  onToolCall: async ({ user, tool, input, outcome, output, error, durationMs }) => {
+    await db.auditLog.insert({ userId: user?.id, tool, input, outcome, error, durationMs })
+  },
+
+  // Once per request, when the reply is done: tokens summed over all steps.
+  onFinish: async ({ user, model, usage, steps, finishReason, durationMs }) => {
+    await db.usage.insert({ userId: user?.id, model: model.modelId, ...usage })
+  },
+})
+```
+
+- `onToolCall` gets the tool's original error message. It stays on the server; the model and the browser get the safe
+  message described under [Errors](#errors).
+- A hook that throws goes to `onError` and does not break the chat. Hooks are awaited, so a slow log write delays the
+  reply; queue the write if that matters.
+- `usage.cachedInputTokens` shows prompt caching at work. In the demo task board with Claude, about 90% of input tokens
+  were cache reads.
+- The chat UI shows a generic error for a 429. Pass your own `labels.error` if you want different wording.
+
 ## Timeouts and long-running tools
 
 An agent turn can take a while: several model calls plus your tools. Two kinds of limits apply, handled differently.
@@ -247,11 +319,98 @@ The job runs in your queue or background worker, outside the request, so it does
 permissions in `startExportJob` and pass the user to the job explicitly (see `identify` and `ctx.user`). Have `getExportJob`
 check that the job belongs to the caller.
 
+With a status tool alone, the user has to ask "is it done?". To have the agent continue by itself when the job finishes,
+mark the start tool with `job` and give the chat UI a channel: see [Background jobs](#background-jobs).
+
 **If a turn is cut anyway**, tools that already ran stay done. "Retry" asks the model again and may call a tool again.
 Tools behind `confirm: true` need a new approval; make other writes idempotent.
 
+## Background jobs
+
+For work that takes longer than a request: a Lambda that calls an LLM for a minute, a report, a bulk import. The tool
+starts the job and returns at once; your worker does the work; your app announces "job X finished" on a channel it
+already has (Supabase Realtime, a WebSocket, SSE, polling). The chat UI hears it and the agent continues: it reads the
+result with another of your tools and does what the user asked next.
+
+```
+user: "build the workload report, then assign unassigned tasks to whoever is least busy"
+  → startWorkloadReport          returns { jobId } at once; the agent says it started, the turn ends
+  … your worker runs for a minute, saves the result, publishes "job-7 finished" on your channel …
+  → the chat UI hears job-7      sends a notice carrying only the ID; a new turn starts
+  → getReportResult({ jobId })   your tool reads the result and checks it belongs to the user
+  → assignTask(...)              confirmed tools still stop at the approval card
+```
+
+**Server**: mark the tool that starts the job, and add a tool that reads the result.
+
+```ts
+startReport: defineTool(() => startReportJob(), {           // invoke the Lambda / enqueue, return { jobId } at once
+  description: 'Starts the workload report. Takes about a minute.',
+  input: z.object({}),
+  job: (result) => result.jobId,                              // this tool starts a background job
+}),
+getReportResult: defineTool((input) => readReport(input.jobId), {   // check the job belongs to the caller
+  description: 'Reads a report job by its id: status and, when done, the report.',
+  usage: 'After the app says a report job has finished.',
+  input: z.object({ jobId: z.string() }),
+}),
+```
+
+`job` returns the job's ID (letters, digits, `_ . : -`, up to 128 characters). dopus tells the model the job runs in
+the background and that it will be told when it finishes, so it does not poll.
+
+**Client**: give the chat a `channel`. It holds functions, so create it in a client component, once:
+
+```tsx
+// components/agent/agent.tsx
+'use client'
+import { type AgentChannel, type AgentChatProps, AgentWidget } from './agent-chat'
+import { supabase } from '@/lib/supabase/client'
+
+const channel: AgentChannel = {
+  subscribe(finished) {
+    const ch = supabase
+      .channel('jobs', { config: { private: true } })
+      .on('broadcast', { event: 'job-done' }, ({ payload }) => finished(payload.jobId))
+      .subscribe()
+    return () => {
+      supabase.removeChannel(ch)
+    }
+  },
+}
+
+export function Agent(props: AgentChatProps) {
+  return <AgentWidget {...props} channel={channel} />
+}
+```
+
+Any source works: `new EventSource(url)`, a WebSocket, or a `setInterval` that asks your API which jobs finished. Call
+`finished(jobId)` for each one; return a function that stops listening. Then use `<Agent />` in your layout instead of
+`<AgentWidget />`.
+
+**How it is kept safe:**
+
+- **The channel is a doorbell, not a mailbox.** Only the job ID goes from the channel to the server. The text the model
+  sees ("Background job X has finished…") is written by the server, and the result comes from your tool, which checks
+  permissions. A forged or replayed event can at most make the agent look up a job the user can already read.
+- **Only this chat's jobs.** The UI reacts only to IDs that a tool in this conversation returned and that it has not
+  reported yet. Another tab, or a new chat, ignores them.
+- **Follow-ups are capped.** After `maxJobFollowUps` (default 3) automatic turns in a row, a finished job is shown in
+  the chat but the agent waits for the user's next message, so a job that starts another job cannot loop.
+- **Approvals still apply.** An automatic turn stops at the approval card like any other.
+
+**Limits:**
+
+- The follow-up runs only while the chat is open in a browser. If the user closes the tab, the result is still in your
+  app (show it there); the agent just does not act on it. Work that must continue without the user belongs in your
+  worker, not in the agent.
+- Each finished job costs one more model call.
+
 ## Deploying
 
+The `dopus infra` commands write the deploy configuration that keeps the agent route streaming within each platform's
+limits. The agent still runs inside your Next.js app; nothing is moved elsewhere.
+
 **Vercel / any Node server.** Nothing extra. The route streams. Raise `maxDuration` in `app/api/agent/route.ts` if your plan allows it; the time budget follows it.
 
 **AWS (OpenNext / SST).**
@@ -329,9 +488,10 @@ Swap in a scripted `MockLanguageModelV4` from `ai/test` behind an environment va
 
 dopus is pre-1.0, so expect breaking changes before 1.0. It is tested on Next.js 16 with the Node.js runtime.
 
-Planned next:
+Planned next, within the lightweight scope above:
 
-- `dopus prompts diff` to compare your copies with newer templates;
+- a command that updates your copies of the chat UI and route when the templates change (it also brings background
+  job support into projects created before it);
 - tool input schemas inferred from TypeScript types.
 
 ## Development

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { n as PROVIDERS, t as VERSION } from "./version-CNF5aJ7W.js";
+import { n as PROVIDERS, t as VERSION } from "./version-Dm8IBEUF.js";
 import { execFileSync, spawn } from "node:child_process";
 import { parseArgs } from "node:util";
 import * as p from "@clack/prompts";
@@ -367,7 +367,9 @@ async function runInit(options, io) {
 		["ai", "ai@^7"],
 		["zod", "zod@^4"],
 		[info.packageName, `${info.packageName}@^4`],
-		["@ai-sdk/react", "@ai-sdk/react@^4"]
+		["@ai-sdk/react", "@ai-sdk/react@^4"],
+		["react-markdown", "react-markdown@^10"],
+		["remark-gfm", "remark-gfm@^4"]
 	].filter(([name]) => !project.dependencies[name]).map(([, spec]) => spec);
 	if (missing.length > 0) {
 		if (options.install === false) io.warn(`Install these yourself: ${project.packageManager} ${installArgs(project.packageManager, missing).join(" ")}`);

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { LanguageModel, SystemModelMessage, streamText } from "ai";
+import { LanguageModel, SystemModelMessage, UIMessage, streamText } from "ai";
 import { z } from "zod";
 /**
  * Layer 1 (Core). Kept short: tool-use and safety rules that apply to every app.
@@ -60,6 +60,12 @@ interface ToolOptions<SCHEMA extends z.ZodType, RESULT> {
   confirm?: ConfirmOption<z.infer<SCHEMA>>;
   /** Map the function's return value before it is sent to the model (trim fields, hide secrets). */
   output?: (result: Awaited<RESULT>) => unknown;
+  /**
+   * Marks a tool that starts a background job and returns at once (hands work to a queue, a Lambda, ...).
+   * Return the job's ID from the function's result. The chat UI waits for that ID on its `channel`; when
+   * the job finishes the agent is told, reads the result with another of your tools, and continues.
+   */
+  job?: (result: Awaited<RESULT>) => string;
 }
 type ToolFunction<INPUT, RESULT> = (input: INPUT, ctx: ToolContext) => RESULT;
 interface DopusTool<SCHEMA extends z.ZodType = z.ZodType, RESULT = unknown> {
@@ -94,6 +100,19 @@ interface AgentConfig<TOOLS extends DopusToolSet = DopusToolSet> {
    * needed when tools run outside the request. Return `undefined` for anonymous users.
    */
   identify?: (request: Request) => AgentUser | undefined | Promise<AgentUser | undefined>;
+  /**
+   * Runs before the model is called, after the body is validated. Return a `Response` (e.g. a 429 from your rate
+   * limiter) to answer with it instead; return nothing to continue.
+   */
+  beforeRequest?: (ctx: {
+    request: Request;
+    user: AgentUser | undefined;
+    messages: UIMessage[];
+  }) => 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. */
+  onFinish?: (event: FinishEvent) => void | Promise<void>;
   /** Maximum model steps (tool round trips) per request. Default 10. */
   maxSteps?: number;
   /**
@@ -120,6 +139,37 @@ interface AgentConfig<TOOLS extends DopusToolSet = DopusToolSet> {
    */
   keepAlive?: number | false;
 }
+interface ToolCallEvent {
+  tool: string;
+  toolCallId: string;
+  input: unknown;
+  /** From `identify`; `undefined` if you did not define it. */
+  user: AgentUser | undefined;
+  outcome: 'success' | 'error' | 'denied';
+  /** The tool's return value (`success`). */
+  output?: unknown;
+  /** The original error message (`error`). Server-side only: the model and the browser see a safe message. */
+  error?: string;
+  /** Execution time (`success` / `error`). */
+  durationMs?: number;
+}
+interface FinishEvent {
+  user: AgentUser | undefined;
+  model: {
+    provider: string;
+    modelId: string;
+  };
+  /** Summed over all steps of this request. */
+  usage: {
+    inputTokens: number | undefined;
+    outputTokens: number | undefined;
+    totalTokens: number | undefined;
+    cachedInputTokens: number | undefined;
+  };
+  steps: number;
+  finishReason: string;
+  durationMs: number;
+}
 /** Identity function that gives `agent.config.ts` type checking. */
 export declare function defineAgent<TOOLS extends DopusToolSet>(config: AgentConfig<TOOLS>): AgentConfig<TOOLS>;
 /**
@@ -166,5 +216,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.4";
-export type { AgentConfig, AgentUser, ClientContext, ConfirmOption, DopusTool, DopusToolSet, HandlerOptions, PromptLayers, ProviderId, ProviderInfo, RuntimeContext, ToolContext, ToolOptions };
+export declare const VERSION = "0.2.6";
+export type { AgentConfig, AgentUser, ClientContext, ConfirmOption, DopusTool, DopusToolSet, FinishEvent, HandlerOptions, PromptLayers, ProviderId, ProviderInfo, RuntimeContext, ToolCallEvent, ToolContext, ToolOptions };

package/dist/index.js

@@ -1,5 +1,32 @@
-import { n as PROVIDERS, t as VERSION } from "./version-CNF5aJ7W.js";
-import { convertToModelMessages, createUIMessageStreamResponse, isStepCount, safeValidateUIMessages, streamText, toUIMessageStream, tool } from "ai";
+import { n as PROVIDERS, t as VERSION } from "./version-Dm8IBEUF.js";
+import { convertToModelMessages, createUIMessageStreamResponse, getToolName, isStepCount, isToolUIPart, safeValidateUIMessages, streamText, toUIMessageStream, tool } from "ai";
+// src/job.ts
+/**
+* Background jobs: a tool marked with `job` starts work elsewhere (a queue, a Lambda) and returns at once.
+* The chat UI listens on the app's channel for "job <id> finished", then sends a notice part back. The
+* notice carries only the job ID; the agent reads the result with one of the app's tools, which checks the
+* user's permissions. Nothing the channel delivers reaches the model as text.
+*/
+/** Key added to a job tool's output; the chat UI reads it to know which jobs this conversation started. */
+const JOB_OUTPUT_KEY = "dopusJob";
+const JOB_ID = /^[A-Za-z0-9_.:-]{1,128}$/;
+function isJobId(value) {
+	return typeof value === "string" && JOB_ID.test(value);
+}
+const JOB_USAGE = "This starts a background job and returns at once. The app tells you in this chat when the job finishes; do not check on it unless the user asks.";
+function withJob(output, id) {
+	return typeof output === "object" && output !== null && !Array.isArray(output) ? {
+		...output,
+		[JOB_OUTPUT_KEY]: id
+	} : {
+		result: output,
+		[JOB_OUTPUT_KEY]: id
+	};
+}
+/** Server-written text for a job notice. Only the validated ID comes from the client. */
+function jobNotice(id) {
+	return `[Background job ${id} has finished. This notice comes from the app, not from the user. Read the job's result with your tools, then continue with what the user asked, and tell the user briefly what came of it.]`;
+}
 // src/next-errors.ts
 /**
 * An error whose message is safe to show to the model (and, through it, the user).
@@ -110,7 +137,8 @@ function isDopusTool(value) {
 function toolDescription(options) {
 	const description = options.description.trim();
 	const usage = options.usage?.trim();
-	return usage ? `${description}\n\nWhen to use: ${usage}` : description;
+	const text = usage ? `${description}\n\nWhen to use: ${usage}` : description;
+	return options.job ? `${text}\n\n${JOB_USAGE}` : text;
 }
 // src/agent.ts
 const KEEP_ALIVE = new TextEncoder().encode(": keep-alive\n\n");
@@ -167,6 +195,15 @@ function defineAgent(config) {
 	}
 	return config;
 }
+/** Runs a user hook; a failing hook is reported but never breaks the chat. */
+async function runHook(hook, event, report) {
+	if (!hook) return;
+	try {
+		await hook(event);
+	} catch (error) {
+		report?.(error);
+	}
+}
 function buildTools(tools, ctx) {
 	const aiTools = {};
 	const approval = {};
@@ -176,14 +213,40 @@ function buildTools(tools, ctx) {
 			description: toolDescription(options),
 			inputSchema: options.input,
 			execute: async (input, { toolCallId, abortSignal }) => {
+				const started = Date.now();
+				const base = {
+					tool: name,
+					toolCallId,
+					input,
+					user: ctx.user
+				};
 				try {
 					const result = await fn(input, {
 						user: ctx.user,
 						toolCallId,
 						abortSignal
 					});
-					return options.output ? options.output(result) : result;
+					const mapped = options.output ? options.output(result) : result;
+					let output = mapped;
+					if (options.job) {
+						const jobId = options.job(result);
+						if (!isJobId(jobId)) throw new TypeError(`tools.${name}: job() must return an ID matching [A-Za-z0-9_.:-]{1,128}`);
+						output = withJob(mapped, jobId);
+					}
+					await runHook(ctx.onToolCall, {
+						...base,
+						outcome: "success",
+						output,
+						durationMs: Date.now() - started
+					}, ctx.report);
+					return output;
 				} catch (error) {
+					await runHook(ctx.onToolCall, {
+						...base,
+						outcome: "error",
+						error: error instanceof Error ? error.message : String(error),
+						durationMs: Date.now() - started
+					}, ctx.report);
 					const translated = translateNextError(error);
 					if (translated instanceof ToolError) throw translated;
 					ctx.report?.(error);
@@ -232,6 +295,7 @@ function createAgentHandler(config, options = {}) {
 	const maxSteps = config.maxSteps ?? 10;
 	const report = config.onError ?? ((error) => console.error("[dopus]", error));
 	return async function handleAgentRequest(request) {
+		const started = Date.now();
 		const deadline = options.maxDuration ? Date.now() + options.maxDuration * 1e3 * TIME_BUDGET_SHARE : void 0;
 		const maxBodyBytes = config.limits?.maxBodyBytes ?? 1e6;
 		const maxMessageChars = config.limits?.maxMessageChars ?? 8e3;
@@ -247,12 +311,30 @@ function createAgentHandler(config, options = {}) {
 		const user = await config.identify?.(request);
 		const { tools, toolApproval } = buildTools(config.tools, {
 			user,
-			report
+			report,
+			onToolCall: config.onToolCall
 		});
 		const validated = await safeValidateUIMessages({ messages: body?.messages });
 		if (!validated.success) return errorResponse(400, "Invalid messages");
 		const messages = validated.data;
 		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?.({
+			request,
+			user,
+			messages
+		});
+		if (early instanceof Response) return early;
+		for (const part of messages.at(-1)?.role === "assistant" ? messages.at(-1)?.parts ?? [] : []) {
+			if (!isToolUIPart(part) || part.state !== "approval-responded" || part.approval.approved) continue;
+			await runHook(config.onToolCall, {
+				tool: getToolName(part),
+				toolCallId: part.toolCallId,
+				input: part.input,
+				user,
+				outcome: "denied"
+			}, report);
+		}
 		const client = readClientContext(body, request);
 		const runtime = {
 			...client,
@@ -266,7 +348,13 @@ function createAgentHandler(config, options = {}) {
 			...config.callOptions,
 			model: config.model,
 			instructions: buildInstructions(config.prompt, runtime),
-			messages: await convertToModelMessages(messages, { tools }),
+			messages: await convertToModelMessages(messages, {
+				tools,
+				convertDataPart: (part) => part.type === "data-dopus-job" ? {
+					type: "text",
+					text: jobNotice(part.data.id)
+				} : void 0
+			}),
 			tools,
 			toolApproval,
 			stopWhen: isStepCount(maxSteps),
@@ -285,7 +373,26 @@ function createAgentHandler(config, options = {}) {
 			},
 			abortSignal: request.signal,
 			...approvalSecret ? { experimental_toolApprovalSecret: approvalSecret } : {},
-			onError: ({ error }) => report(error)
+			onError: ({ error }) => report(error),
+			onEnd: async (event) => {
+				await config.callOptions?.onEnd?.(event);
+				await runHook(config.onFinish, {
+					user,
+					model: {
+						provider: event.model.provider,
+						modelId: event.model.modelId
+					},
+					usage: {
+						inputTokens: event.totalUsage.inputTokens,
+						outputTokens: event.totalUsage.outputTokens,
+						totalTokens: event.totalUsage.totalTokens,
+						cachedInputTokens: event.totalUsage.inputTokenDetails?.cacheReadTokens
+					},
+					steps: event.stepNumber + 1,
+					finishReason: event.finishReason,
+					durationMs: Date.now() - started
+				}, report);
+			}
 		});
 		const response = createUIMessageStreamResponse({ stream: toUIMessageStream({
 			stream: result.stream,

package/dist/{version-CNF5aJ7W.js → version-Dm8IBEUF.js}

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dopus",
-  "version": "0.2.4",
-  "description": "Drop an AI agent into your existing Next.js app — your server functions become its tools.",
+  "version": "0.2.6",
+  "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",
   "homepage": "https://github.com/akodm/dopus#readme",
@@ -24,7 +24,10 @@
     "openai",
     "anthropic",
     "gemini",
-    "chatbot"
+    "chatbot",
+    "lightweight",
+    "app-router",
+    "tools"
   ],
   "type": "module",
   "engines": {
@@ -70,6 +73,8 @@
     "ai": "7.0.166",
     "next": "16.4.6",
     "react": "19.3.1",
+    "react-markdown": "10.1.0",
+    "remark-gfm": "4.0.1",
     "tsdown": "0.23.7",
     "typescript": "6.0.3",
     "vitest": "5.1.0",

package/templates/ui/agent-chat.css

@@ -44,6 +44,10 @@
 }
 
 .dopus-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
   padding: 12px 16px;
   font-weight: 600;
   border-bottom: 1px solid var(--dopus-border);
@@ -138,6 +142,12 @@
   color: var(--dopus-muted);
 }
 
+.dopus-notice {
+  align-self: center;
+  color: var(--dopus-muted);
+  font-size: 0.8125rem;
+}
+
 .dopus-error {
   color: var(--dopus-danger);
 }
@@ -257,3 +267,91 @@
   cursor: pointer;
   box-shadow: 0 6px 20px rgb(0 0 0 / 0.2);
 }
+
+/* Assistant replies (Markdown). Compact spacing for a chat bubble. */
+.dopus-markdown {
+  white-space: normal;
+}
+.dopus-markdown > :first-child {
+  margin-top: 0;
+}
+.dopus-markdown > :last-child {
+  margin-bottom: 0;
+}
+.dopus-markdown p,
+.dopus-markdown ul,
+.dopus-markdown ol,
+.dopus-markdown pre,
+.dopus-table {
+  margin: 0 0 8px;
+}
+.dopus-table {
+  overflow-x: auto;
+}
+.dopus-markdown ul,
+.dopus-markdown ol {
+  padding-left: 20px;
+}
+.dopus-markdown ul {
+  list-style: disc;
+}
+.dopus-markdown ol {
+  list-style: decimal;
+}
+.dopus-markdown h1,
+.dopus-markdown h2,
+.dopus-markdown h3,
+.dopus-markdown h4 {
+  margin: 12px 0 6px;
+  font-size: 15px;
+  font-weight: 600;
+}
+.dopus-markdown a {
+  color: inherit;
+  text-decoration: underline;
+}
+.dopus-markdown strong {
+  font-weight: 600;
+}
+.dopus-markdown code {
+  padding: 1px 4px;
+  border-radius: 4px;
+  background: var(--dopus-surface);
+  font:
+    12px / 1.4 ui-monospace,
+    SFMono-Regular,
+    Menlo,
+    monospace;
+}
+.dopus-markdown pre {
+  padding: 8px 10px;
+  border-radius: 8px;
+  background: var(--dopus-surface);
+  overflow-x: auto;
+}
+.dopus-markdown pre code {
+  padding: 0;
+  background: none;
+}
+.dopus-markdown table {
+  border-collapse: collapse;
+  font-size: 13px;
+}
+.dopus-markdown th,
+.dopus-markdown td {
+  padding: 4px 8px;
+  border: 1px solid var(--dopus-border);
+  text-align: left;
+  vertical-align: top;
+}
+.dopus-markdown th {
+  background: var(--dopus-surface);
+  font-weight: 600;
+}
+
+/* After .dopus-link, which resets font. */
+.dopus-new-chat {
+  font-weight: 400;
+  font-size: 13px;
+  color: var(--dopus-muted);
+}

package/templates/ui/agent-chat.tsx

@@ -4,6 +4,7 @@
  * Chat UI for the dopus agent. Copied by `dopus init`; this file is yours to edit.
  * 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.
  */
 import { useChat } from '@ai-sdk/react'
 import {
@@ -14,7 +15,17 @@ import {
   type UIMessage,
 } from 'ai'
 import { useRouter } from 'next/navigation'
-import { type FormEvent, type KeyboardEvent, useEffect, useRef, useState } from 'react'
+import {
+  type ComponentProps,
+  type FormEvent,
+  type KeyboardEvent,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react'
+import Markdown, { defaultUrlTransform } from 'react-markdown'
+import remarkGfm from 'remark-gfm'
 import './agent-chat.css'
 
 const DEFAULT_LABELS = {
@@ -23,6 +34,8 @@ const DEFAULT_LABELS = {
   send: 'Send',
   stop: 'Stop',
   retry: 'Retry',
+  newChat: 'New chat',
+  tooLong: 'Too long to send. Start a new chat or shorten your message.',
   error: 'Something went wrong.',
   thinking: 'Thinking…',
   running: 'Running',
@@ -33,6 +46,8 @@ const DEFAULT_LABELS = {
   declined: 'Declined',
   failed: 'Failed',
   details: 'Details',
+  jobRunning: 'Working in the background',
+  jobDone: 'Background task finished',
   open: 'Open assistant',
   close: 'Close assistant',
 }
@@ -46,6 +61,35 @@ export interface AgentChatProps {
   /** Example prompts shown before the first message. */
   suggestions?: string[]
   className?: string
+  /**
+   * Where the app announces finished background jobs (Supabase Realtime, a WebSocket, SSE, polling...).
+   * When a job started in this chat finishes, the agent is told and continues by itself. Create the
+   * channel once (module scope or `useMemo`) in a client component; it holds functions, so it cannot be
+   * passed from a server component.
+   */
+  channel?: AgentChannel
+  /** Follow-up turns the agent may take in a row on finished jobs before waiting for the user. Default 3. */
+  maxJobFollowUps?: number
+}
+
+export interface AgentChannel {
+  /** Start listening and call `finished(jobId)` for each job that finishes. Return a function that stops. */
+  subscribe: (finished: (jobId: string) => void) => () => void
+}
+
+// Must match the dopus server: a job tool's output carries `dopusJob: <id>`, and a finished job is reported
+// back as a `data-dopus-job` part. The part carries only the ID; the server writes the text the model sees.
+const JOB_KEY = 'dopusJob'
+const JOB_PART = 'data-dopus-job'
+
+function startedJob(part: UIMessage['parts'][number]): string | undefined {
+  if (!isToolUIPart(part) || part.state !== 'output-available') return undefined
+  const id = (part.output as Record<string, unknown> | null)?.[JOB_KEY]
+  return typeof id === 'string' ? id : undefined
+}
+
+function isJobNotice(message: UIMessage) {
+  return message.role === 'user' && message.parts.every((part) => part.type === JOB_PART)
 }
 
 type ToolPart = Extract<UIMessage['parts'][number], { toolCallId: string }>
@@ -67,12 +111,21 @@ function ToolCall({
   part,
   labels,
   onRespond,
+  waiting,
 }: {
   part: ToolPart
   labels: AgentChatLabels
   onRespond: (approvalId: string, approved: boolean) => void
+  waiting: boolean
 }) {
   const name = humanize(getToolName(part))
+  if (waiting) {
+    return (
+      <div className="dopus-tool" data-state="running">
+        <span className="dopus-spinner" aria-hidden /> {labels.jobRunning}: {name}
+      </div>
+    )
+  }
 
   switch (part.state) {
     case 'input-streaming':
@@ -137,28 +190,80 @@ function ToolCall({
   }
 }
 
+/**
+ * Assistant replies are Markdown (tables, lists, bold). Rendered with react-markdown, which never renders raw HTML.
+ * Images are shown as their alt text and never loaded, and links keep only http(s), mailto and relative URLs:
+ * a reply influenced by prompt injection cannot load a URL that leaks data, or run script.
+ */
+const MARKDOWN_COMPONENTS: ComponentProps<typeof Markdown>['components'] = {
+  a: ({ href, children }) => (
+    <a href={href} target="_blank" rel="noopener noreferrer nofollow">
+      {children}
+    </a>
+  ),
+  img: ({ alt }) => (alt ? <span>[{alt}]</span> : null),
+  table: ({ children }) => (
+    <div className="dopus-table">
+      <table>{children}</table>
+    </div>
+  ),
+}
+
+function AssistantText({ text }: { text: string }) {
+  return (
+    <div className="dopus-text dopus-markdown">
+      <Markdown
+        remarkPlugins={[remarkGfm]}
+        components={MARKDOWN_COMPONENTS}
+        urlTransform={(url) =>
+          /^(https?:|mailto:|\/|#)/i.test(url) ? defaultUrlTransform(url) : ''
+        }
+      >
+        {text}
+      </Markdown>
+    </div>
+  )
+}
+
 function Message({
   message,
   labels,
   onRespond,
+  waitingJobs,
 }: {
   message: UIMessage
   labels: AgentChatLabels
   onRespond: (approvalId: string, approved: boolean) => void
+  waitingJobs: Set<string>
 }) {
+  if (isJobNotice(message)) {
+    return <div className="dopus-notice">✓ {labels.jobDone}</div>
+  }
   return (
     <div className="dopus-message" data-role={message.role}>
       {message.parts.map((part, index) => {
         const key = `${message.id}-${index}`
         if (part.type === 'text') {
-          return part.text ? (
+          if (!part.text) return null
+          return message.role === 'assistant' ? (
+            <AssistantText key={key} text={part.text} />
+          ) : (
             <div key={key} className="dopus-text">
               {part.text}
             </div>
-          ) : null
+          )
         }
         if (isToolUIPart(part)) {
-          return <ToolCall key={key} part={part} labels={labels} onRespond={onRespond} />
+          const job = startedJob(part)
+          return (
+            <ToolCall
+              key={key}
+              part={part}
+              labels={labels}
+              onRespond={onRespond}
+              waiting={job !== undefined && waitingJobs.has(job)}
+            />
+          )
         }
         return null
       })}
@@ -171,6 +276,8 @@ export function AgentChat({
   labels: labelOverrides,
   suggestions = [],
   className,
+  channel,
+  maxJobFollowUps = 3,
 }: AgentChatProps) {
   const labels = { ...DEFAULT_LABELS, ...labelOverrides }
   const router = useRouter()
@@ -182,22 +289,80 @@ export function AgentChat({
         body: () => ({ context: { page: window.location.pathname, locale: navigator.language } }),
       }),
   )
-  const { messages, sendMessage, status, stop, error, regenerate, addToolApprovalResponse } =
-    useChat({
-      transport,
-      sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses,
-      // A tool ran, so data the page shows may have changed (server actions call revalidatePath):
-      // re-render the current route's server components.
-      onFinish: ({ message }) => {
-        if (message.parts.some((part) => isToolUIPart(part) && part.state === 'output-available')) {
-          router.refresh()
-        }
-      },
-    })
+  const {
+    messages,
+    setMessages,
+    sendMessage,
+    status,
+    stop,
+    error,
+    clearError,
+    regenerate,
+    addToolApprovalResponse,
+  } = useChat({
+    transport,
+    sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses,
+    // A tool ran, so data the page shows may have changed (server actions call revalidatePath):
+    // re-render the current route's server components.
+    onFinish: ({ message }) => {
+      if (message.parts.some((part) => isToolUIPart(part) && part.state === 'output-available')) {
+        router.refresh()
+      }
+    },
+  })
   const [input, setInput] = useState('')
   const listRef = useRef<HTMLDivElement>(null)
   const busy = status === 'submitted' || status === 'streaming'
 
+  // 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())
+  useEffect(() => {
+    if (!channel) return
+    return channel.subscribe((id) => setFinishedJobs((prev) => new Set(prev).add(id)))
+  }, [channel])
+
+  // Derived from the messages, so a new chat (or another tab) never reacts to jobs it did not start.
+  const { waitingJobs, readyJobs } = useMemo(() => {
+    const started = new Set<string>()
+    const reported = new Set<string>()
+    for (const message of messages) {
+      for (const part of message.parts) {
+        const id = startedJob(part)
+        if (id) started.add(id)
+        if (part.type === JOB_PART) reported.add((part.data as { id: string }).id)
+      }
+    }
+    const waiting = new Set([...started].filter((id) => !reported.has(id)))
+    return { waitingJobs: waiting, readyJobs: [...waiting].filter((id) => finishedJobs.has(id)) }
+  }, [messages, finishedJobs])
+
+  useEffect(() => {
+    if (readyJobs.length === 0 || status !== 'ready') return
+    const last = messages.at(-1)
+    // Wait while an approval card is open: the user answers that first.
+    if (last?.parts.some((part) => isToolUIPart(part) && part.state === 'approval-requested'))
+      return
+    const notice = {
+      role: 'user' as const,
+      parts: readyJobs.map(
+        (id) => ({ type: JOB_PART, data: { id } }) as UIMessage['parts'][number],
+      ),
+    }
+    // Follow-ups since the user last wrote; past the cap, the notice waits in the history for the user's next message.
+    let followUps = 0
+    for (const message of [...messages].reverse()) {
+      if (message.role !== 'user') continue
+      if (!isJobNotice(message)) break
+      followUps++
+    }
+    if (followUps >= maxJobFollowUps) {
+      setMessages([...messages, { id: `job-${readyJobs.join('-')}`, ...notice }])
+    } else {
+      sendMessage(notice)
+    }
+  }, [readyJobs, status, messages, maxJobFollowUps, sendMessage, setMessages])
+
   // biome-ignore lint/correctness/useExhaustiveDependencies: scroll whenever messages change
   useEffect(() => {
     listRef.current?.scrollTo({ top: listRef.current.scrollHeight, behavior: 'smooth' })
@@ -225,12 +390,29 @@ export function AgentChat({
 
   const respond = (id: string, approved: boolean) => addToolApprovalResponse({ id, approved })
 
+  function newChat() {
+    if (busy) stop()
+    clearError()
+    setMessages([])
+    setInput('')
+  }
+
+  // The route answers 413 when the history is over its size limit; retrying cannot help then.
+  const tooLong = (error as { statusCode?: number } | undefined)?.statusCode === 413
+
   return (
     <section
       className={['dopus-chat', className].filter(Boolean).join(' ')}
       aria-label={labels.title}
     >
-      <header className="dopus-header">{labels.title}</header>
+      <header className="dopus-header">
+        <span>{labels.title}</span>
+        {messages.length > 0 && (
+          <button type="button" className="dopus-link dopus-new-chat" onClick={newChat}>
+            {labels.newChat}
+          </button>
+        )}
+      </header>
       <div ref={listRef} className="dopus-messages" aria-live="polite">
         {messages.length === 0 && suggestions.length > 0 && (
           <div className="dopus-suggestions">
@@ -247,14 +429,24 @@ export function AgentChat({
           </div>
         )}
         {messages.map((message) => (
-          <Message key={message.id} message={message} labels={labels} onRespond={respond} />
+          <Message
+            key={message.id}
+            message={message}
+            labels={labels}
+            onRespond={respond}
+            waitingJobs={waitingJobs}
+          />
         ))}
         {status === 'submitted' && <div className="dopus-thinking">{labels.thinking}</div>}
         {error && (
           <div className="dopus-error" role="alert">
-            {labels.error}{' '}
-            <button type="button" className="dopus-link" onClick={() => regenerate()}>
-              {labels.retry}
+            {tooLong ? labels.tooLong : labels.error}{' '}
+            <button
+              type="button"
+              className="dopus-link"
+              onClick={() => (tooLong ? newChat() : regenerate())}
+            >
+              {tooLong ? labels.newChat : labels.retry}
             </button>
           </div>
         )}