dopus 0.2.5 → 0.2.7

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
@@ -67,6 +83,27 @@ dopus init [--provider openai|anthropic|google] [--model <id>]
 
 `--yes` runs without prompts. It needs `--provider` and skips the API key prompt, so add the key to `.env.local` yourself afterwards.
 
+### Updating
+
+`init` copies files into your project, so a new dopus version does not change them by itself. After upgrading the
+package, bring them up to date:
+
+```bash
+pnpm add dopus@latest
+pnpm dopus update            # --dry-run to only see what would change
+```
+
+`update` handles the files `init` copied: the chat UI (`agent-chat.tsx`, `agent-chat.css`), the route and the preset
+prompt. It never touches `agent.config.ts`, `agent/prompts/app.ts` or `.env.local`.
+
+- A file you never edited (it matches a template some dopus version shipped) is replaced.
+- A file you edited is never replaced silently. You choose: see the diff, keep yours and get the new template next to
+  it as `<file>.new` to merge by hand, replace it, or skip. `--yes` always takes the `.new` route; `--force` replaces.
+- Packages the new chat UI needs are installed (`--no-install` prints the command instead).
+
+Commit first, so `git diff` shows exactly what changed. The [changelog](CHANGELOG.md) says what each version changed
+and anything to do in `agent.config.ts`.
+
 ## Tools
 
 ```ts
@@ -108,6 +145,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:
@@ -151,7 +202,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 +224,12 @@ 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, 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.
+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.
 
 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.
 
@@ -288,11 +342,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).**
@@ -370,9 +511,8 @@ 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;
 - tool input schemas inferred from TypeScript types.
 
 ## Development
@@ -382,7 +522,8 @@ pnpm install
 pnpm build && pnpm lint && pnpm typecheck && pnpm test
 pnpm example:build && pnpm example:e2e   # next start + scripted model
 pnpm example:live                        # real model from examples/next-app/.env.local (costs cents)
-pnpm smoke                               # packed tarball → fresh app → dopus init → next build
+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`
 pnpm aws:emu                             # OpenNext build → local Lambda streaming invoke
 pnpm cf:e2e                              # dopus infra cloudflare → wrangler dev (workerd) → e2e
 pnpm gcp:e2e                             # dopus infra gcp → docker build/run (Cloud Run style) → e2e

package/dist/cli.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
-import { n as PROVIDERS, t as VERSION } from "./version-DmrGrSmM.js";
+import { n as PROVIDERS, t as VERSION } from "./version-DqzDElrt.js";
 import { execFileSync, spawn } from "node:child_process";
 import { parseArgs } from "node:util";
 import * as p from "@clack/prompts";
 import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
-import { randomBytes } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 import { fileURLToPath } from "node:url";
 // src/init/detect.ts
 var InitError = class extends Error {
@@ -808,11 +808,249 @@ async function runInfraGcp(options, io) {
 	].join("\n"), "Cloud Run notes");
 	return result;
 }
+// src/update/diff.ts
+/** Line diff (LCS) in unified style with 3 lines of context. Small and dependency-free; templates are short. */
+function unifiedDiff(before, after, context = 3) {
+	const a = before.replace(/\r\n/g, "\n").split("\n");
+	const b = after.replace(/\r\n/g, "\n").split("\n");
+	const n = a.length;
+	const m = b.length;
+	if (n * m > 4e6) return "(files too large to diff here)";
+	const table = new Uint32Array((n + 1) * (m + 1));
+	const lcs = (i, j) => table[i * (m + 1) + j] ?? 0;
+	for (let i = n - 1; i >= 0; i--) for (let j = m - 1; j >= 0; j--) table[i * (m + 1) + j] = a[i] === b[j] ? lcs(i + 1, j + 1) + 1 : Math.max(lcs(i + 1, j), lcs(i, j + 1));
+	const lines = [];
+	let i = 0;
+	let j = 0;
+	while (i < n || j < m) if (i < n && j < m && a[i] === b[j]) {
+		lines.push({
+			op: " ",
+			text: a[i] ?? ""
+		});
+		i++;
+		j++;
+	} else if (i < n && (j >= m || lcs(i + 1, j) >= lcs(i, j + 1))) {
+		lines.push({
+			op: "-",
+			text: a[i] ?? ""
+		});
+		i++;
+	} else {
+		lines.push({
+			op: "+",
+			text: b[j] ?? ""
+		});
+		j++;
+	}
+	const changed = [];
+	lines.forEach((line, index) => {
+		if (line.op !== " ") changed.push(index);
+	});
+	const out = [];
+	let start = 0;
+	while (start < changed.length) {
+		let end = start;
+		while (end + 1 < changed.length && (changed[end + 1] ?? 0) - (changed[end] ?? 0) <= context * 2) end++;
+		const from = Math.max(0, (changed[start] ?? 0) - context);
+		const to = Math.min(lines.length - 1, (changed[end] ?? 0) + context);
+		out.push("@@");
+		for (const line of lines.slice(from, to + 1)) out.push(`${line.op}${line.text}`);
+		start = end + 1;
+	}
+	return out.join("\n");
+}
+// src/update/history.ts
+/** The generated route imports the agent config by a path that differs per project. */
+const CONFIG_IMPORT = /^import agent from ['"]([^'"]+)['"]/m;
+/** Must match normalize() in scripts/template-history.mjs. */
+function normalize(text) {
+	return text.replace(/\r\n/g, "\n").replace(CONFIG_IMPORT, "import agent from '<config>'");
+}
+function templateHash(text) {
+	return createHash("sha256").update(normalize(text)).digest("hex").slice(0, 16);
+}
+let cached;
+function templateHistory() {
+	cached ??= JSON.parse(readTemplate("history.json"));
+	return cached;
+}
+/** The dopus version whose untouched template this is, or undefined if the user changed it. */
+function shippedIn(key, text) {
+	return templateHistory()[key]?.[templateHash(text)];
+}
+// src/update/run.ts
+/** Packages the chat UI imports (the rest were added by `init` and are needed by the route too). */
+const UI_DEPENDENCIES = [
+	["@ai-sdk/react", "@ai-sdk/react@^4"],
+	["react-markdown", "react-markdown@^10"],
+	["remark-gfm", "remark-gfm@^4"]
+];
+/** Which preset an existing preset.ts came from: by its hash, else the one it shares most lines with. */
+function presetKey(text) {
+	const keys = PRESETS.map((preset) => `prompts/presets/${preset.id}.ts`);
+	const exact = keys.find((key) => shippedIn(key, text));
+	if (exact) return exact;
+	const lines = new Set(text.split("\n").map((line) => line.trim()));
+	const shared = (key) => readTemplate(key).split("\n").filter((line) => line.trim() && lines.has(line.trim())).length;
+	return keys.reduce((best, key) => shared(key) > shared(best) ? key : best);
+}
+/**
+* Brings the files `dopus init` copied (chat UI, route, preset prompt) up to this version's templates.
+* Untouched copies of an older version are replaced; copies the user edited are never replaced without
+* asking. agent.config.ts, app.ts and .env.local are the user's and are never touched.
+*/
+async function runUpdate(options, io) {
+	const project = detectProject(options.cwd);
+	const { root } = project;
+	const at = (path) => join(project.configDir, path);
+	const read = (file) => readFileSync(join(root, file), "utf8");
+	const exists = (file) => existsSync(join(root, file));
+	const result = {
+		files: [],
+		installed: [],
+		missingDependencies: []
+	};
+	const chatFile = at("components/agent/agent-chat.tsx");
+	const routeFile = join(project.appDir, "api", "agent", "route.ts");
+	const presetFile = at("agent/prompts/preset.ts");
+	const targets = [{
+		file: chatFile,
+		key: "ui/agent-chat.tsx",
+		latest: readTemplate("ui/agent-chat.tsx")
+	}, {
+		file: at("components/agent/agent-chat.css"),
+		key: "ui/agent-chat.css",
+		latest: readTemplate("ui/agent-chat.css"),
+		create: exists(chatFile)
+	}];
+	if (exists(routeFile)) {
+		const configImport = read(routeFile).match(CONFIG_IMPORT)?.[1] ?? toImportPath(routeFile, at("agent.config"));
+		targets.push({
+			file: routeFile,
+			key: "route",
+			latest: routeTemplate(configImport)
+		});
+	} else result.files.push({
+		file: routeFile,
+		status: "missing"
+	});
+	if (exists(presetFile)) {
+		const key = presetKey(read(presetFile));
+		targets.push({
+			file: presetFile,
+			key,
+			latest: readTemplate(key)
+		});
+	} else result.files.push({
+		file: presetFile,
+		status: "missing"
+	});
+	const write = (file, content) => {
+		if (!options.dryRun) writeFileSync(join(root, file), content);
+	};
+	for (const target of targets) {
+		const { file, latest } = target;
+		if (!exists(file)) {
+			if (target.create) {
+				write(file, latest);
+				result.files.push({
+					file,
+					status: "created"
+				});
+			} else result.files.push({
+				file,
+				status: "missing"
+			});
+			continue;
+		}
+		const current = read(file);
+		if (normalize(current) === normalize(latest)) {
+			result.files.push({
+				file,
+				status: "up-to-date"
+			});
+			continue;
+		}
+		const from = shippedIn(target.key, current);
+		if (from) {
+			write(file, latest);
+			result.files.push({
+				file,
+				status: "updated",
+				from
+			});
+			continue;
+		}
+		let choice;
+		if (options.dryRun) {
+			result.files.push({
+				file,
+				status: "modified"
+			});
+			continue;
+		} else if (options.force) choice = "overwrite";
+		else if (options.yes) choice = "new";
+		else do {
+			choice = await io.choose(`${file} has your changes. Replace it with the new template?`, [
+				{
+					value: "diff",
+					label: "Show the diff (yours → new)"
+				},
+				{
+					value: "new",
+					label: `Keep yours, save the new one as ${file}.new`
+				},
+				{
+					value: "overwrite",
+					label: "Replace (your changes are lost)"
+				},
+				{
+					value: "skip",
+					label: "Keep yours, skip"
+				}
+			]);
+			if (choice === "diff") io.diff(unifiedDiff(current, latest));
+		} while (choice === "diff");
+		if (choice === "overwrite") {
+			write(file, latest);
+			result.files.push({
+				file,
+				status: "overwritten"
+			});
+		} else if (choice === "new") {
+			write(`${file}.new`, latest);
+			result.files.push({
+				file,
+				status: "saved-new"
+			});
+		} else result.files.push({
+			file,
+			status: "kept"
+		});
+	}
+	const chatReplaced = result.files.some((f) => f.file === chatFile && (f.status === "updated" || f.status === "overwritten"));
+	const oldModule = at("components/agent/agent-chat.module.css");
+	if (chatReplaced && exists(oldModule)) io.warn(`${oldModule} is no longer used by the chat UI (it now imports agent-chat.css). Delete it.`);
+	if (exists(chatFile)) {
+		const missing = UI_DEPENDENCIES.filter(([name]) => !project.dependencies[name]).map(([, spec]) => spec);
+		if (missing.length > 0) {
+			if (!options.dryRun && options.install !== false && (options.yes || options.force || await io.confirm(`Install ${missing.join(", ")}?`, true))) {
+				await io.install(project.packageManager, missing, root);
+				result.installed = missing;
+			} else {
+				result.missingDependencies = missing;
+				io.warn(`The chat UI needs: ${project.packageManager} ${installArgs(project.packageManager, missing).join(" ")}`);
+			}
+		}
+	}
+	return result;
+}
 // src/cli.ts
 const HELP = `dopus ${VERSION}
 
 Usage:
   dopus init [options]        Add an AI agent to this Next.js app
+  dopus update [options]      Update the chat UI, route and preset prompt that init copied
   dopus infra aws [options]   Prepare the agent route for AWS Lambda (OpenNext streaming + SST snippet)
   dopus infra cloudflare      Prepare the app for Cloudflare Workers (@opennextjs/cloudflare)
   dopus infra gcp             Prepare the app for Cloud Run (standalone build + Dockerfile)
@@ -826,6 +1064,13 @@ Options for init:
   --force                Overwrite generated files that already exist
   --cwd <dir>            Project root (default: current directory)
 
+Options for update (first install the new version: pnpm add dopus@latest):
+  --dry-run              Show what would change; write nothing
+  -y, --yes              Do not ask: files you edited get the new template next to them as <file>.new
+  --force                Replace files you edited too
+  --no-install           Do not install dependencies
+  --cwd <dir>            Project root
+
 Options for infra:
   -y, --yes              Do not ask before installing @opennextjs/aws
   --no-install           Print the install command instead
@@ -928,6 +1173,62 @@ async function init(args) {
 	p.note(steps.map((s, i) => `${i + 1}. ${s}`).join("\n"), "Next steps");
 	p.outro("Done.");
 }
+const STATUS = {
+	"up-to-date": "up to date",
+	updated: "updated",
+	created: "created",
+	modified: "has your changes: would ask (run without --dry-run)",
+	overwritten: "replaced (your changes are gone)",
+	kept: "kept your version",
+	"saved-new": "kept your version; new template saved as .new next to it",
+	missing: "not found (not created by dopus init?)"
+};
+function colorDiff(text) {
+	if (!process.stdout.isTTY) return text;
+	return text.split("\n").map((line) => line.startsWith("+") ? `\x1b[32m${line}\x1b[0m` : line.startsWith("-") ? `\x1b[31m${line}\x1b[0m` : line.startsWith("@@") ? `\x1b[36m${line}\x1b[0m` : line).join("\n");
+}
+async function update(args) {
+	const { values } = parseArgs({
+		args,
+		options: {
+			"dry-run": { type: "boolean" },
+			yes: {
+				type: "boolean",
+				short: "y"
+			},
+			force: { type: "boolean" },
+			install: {
+				type: "boolean",
+				default: true
+			},
+			"no-install": { type: "boolean" },
+			cwd: { type: "string" }
+		},
+		allowNegative: true
+	});
+	p.intro(`dopus ${VERSION} · update${values["dry-run"] ? " (dry run)" : ""}`);
+	p.log.info(`Templates come from the installed dopus (${VERSION}). For the newest, run \`pnpm add dopus@latest\` first.`);
+	const updateIO = {
+		...io,
+		async choose(message, options) {
+			return cancelled(await p.select({
+				message,
+				options
+			}));
+		},
+		diff: (text) => console.log(colorDiff(text || "(no differences)"))
+	};
+	const result = await runUpdate({
+		cwd: values.cwd ?? process.cwd(),
+		dryRun: values["dry-run"],
+		yes: values.yes,
+		force: values.force,
+		install: values["no-install"] ? false : values.install
+	}, updateIO);
+	p.note(result.files.map(({ file, status, from }) => `${file}: ${STATUS[status]}${from ? ` (was ${from})` : ""}`).join("\n"), "Files");
+	if (result.files.some((f) => f.status === "saved-new")) p.log.info("Merge each .new file into yours, then delete it.");
+	p.outro("What changed: https://github.com/akodm/dopus/blob/main/CHANGELOG.md");
+}
 async function infra(args) {
 	const [target, ...rest] = args;
 	const runners = {
@@ -970,6 +1271,7 @@ async function main() {
 	if (rest.includes("--help") || rest.includes("-h")) return console.log(HELP);
 	if (command === "init") return init(rest);
 	if (command === "infra") return infra(rest);
+	if (command === "update") return update(rest);
 	console.log(HELP);
 	if (command && command !== "--help" && command !== "-h") process.exitCode = 1;
 }

package/dist/index.d.ts

@@ -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> {
@@ -210,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.5";
+export declare const VERSION = "0.2.7";
 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-DmrGrSmM.js";
+import { n as PROVIDERS, t as VERSION } from "./version-DqzDElrt.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");
@@ -198,7 +226,13 @@ function buildTools(tools, ctx) {
 						toolCallId,
 						abortSignal
 					});
-					const output = 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",
@@ -284,6 +318,7 @@ function createAgentHandler(config, options = {}) {
 		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,
@@ -313,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),

package/dist/{version-DmrGrSmM.js → version-DqzDElrt.js}

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dopus",
-  "version": "0.2.5",
-  "description": "Drop an AI agent into your existing Next.js app — your server functions become its tools.",
+  "version": "0.2.7",
+  "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": {

package/templates/history.json

@@ -0,0 +1,35 @@
+{
+  "ui/agent-chat.tsx": {
+    "ff662fe56e84cfd0": "0.1.0",
+    "89475c1e29eb011b": "0.2.2",
+    "af6a34c9f15d4bef": "0.2.5",
+    "e0ff5f54b6823dba": "0.2.6",
+    "a3542945427a3dfa": "0.2.7"
+  },
+  "ui/agent-chat.module.css": {
+    "8ecfa2904dee75e9": "0.1.0"
+  },
+  "prompts/presets/general.ts": {
+    "10068289d8dfbf09": "0.1.0",
+    "fc75d0ecdeb38b7f": "0.2.2"
+  },
+  "prompts/presets/customer-support.ts": {
+    "2fdd5a26b25c23ae": "0.1.0",
+    "95bd1451466fb32b": "0.2.2"
+  },
+  "prompts/presets/internal-ops.ts": {
+    "2b150cc147d78e44": "0.1.0",
+    "c4b308fa69493fb8": "0.2.2",
+    "d5e08199cf6b45c2": "0.2.3"
+  },
+  "route": {
+    "17498e892a470ee4": "0.1.0",
+    "c44baa5927649535": "0.2.4"
+  },
+  "ui/agent-chat.css": {
+    "72f30cfb90fe5255": "0.2.2",
+    "65d193ef3df15ecc": "0.2.5",
+    "a33f338eb017ad66": "0.2.6",
+    "155c72a570d1ee5e": "0.2.7"
+  }
+}

package/templates/ui/agent-chat.css

@@ -142,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);
 }
@@ -251,6 +257,7 @@
 }
 
 .dopus-launcher {
+  position: relative;
   width: 52px;
   height: 52px;
   border-radius: 50%;
@@ -262,6 +269,20 @@
   box-shadow: 0 6px 20px rgb(0 0 0 / 0.2);
 }
 
+/* A reply arrived while the panel was closed (e.g. a background job's follow-up). */
+.dopus-launcher[data-unread]::after {
+  content: "";
+  position: absolute;
+  top: 2px;
+  right: 2px;
+  width: 12px;
+  height: 12px;
+  border-radius: 50%;
+  /* The launcher sits outside .dopus-chat, where the --dopus-* variables live, so its colors are fixed too. */
+  background: #dc2626;
+  border: 2px solid #ffffff;
+}
+
 /* Assistant replies (Markdown). Compact spacing for a chat bubble. */
 .dopus-markdown {
   white-space: normal;

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 {
@@ -19,6 +20,7 @@ import {
   type FormEvent,
   type KeyboardEvent,
   useEffect,
+  useMemo,
   useRef,
   useState,
 } from 'react'
@@ -44,7 +46,10 @@ const DEFAULT_LABELS = {
   declined: 'Declined',
   failed: 'Failed',
   details: 'Details',
+  jobRunning: 'Working in the background',
+  jobDone: 'Background task finished',
   open: 'Open assistant',
+  unread: 'New reply',
   close: 'Close assistant',
 }
 
@@ -57,6 +62,37 @@ 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
+  /** Called when the agent finishes a reply. `AgentWidget` uses it to mark the closed launcher as unread. */
+  onReply?: () => void
+}
+
+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 }>
@@ -78,12 +114,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':
@@ -187,11 +232,16 @@ 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) => {
@@ -207,7 +257,16 @@ function Message({
           )
         }
         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
       })}
@@ -220,9 +279,17 @@ export function AgentChat({
   labels: labelOverrides,
   suggestions = [],
   className,
+  channel,
+  maxJobFollowUps = 3,
+  onReply,
 }: AgentChatProps) {
   const labels = { ...DEFAULT_LABELS, ...labelOverrides }
   const router = useRouter()
+  // useChat keeps the callbacks it was created with; read the latest onReply through a ref.
+  const onReplyRef = useRef(onReply)
+  useEffect(() => {
+    onReplyRef.current = onReply
+  })
   const [transport] = useState(
     () =>
       new DefaultChatTransport({
@@ -250,12 +317,62 @@ export function AgentChat({
       if (message.parts.some((part) => isToolUIPart(part) && part.state === 'output-available')) {
         router.refresh()
       }
+      onReplyRef.current?.()
     },
   })
   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' })
@@ -322,7 +439,13 @@ 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 && (
@@ -365,19 +488,34 @@ export function AgentChat({
 /** Floating button that opens the chat in a panel. Put it once in your root layout. */
 export function AgentWidget(props: AgentChatProps) {
   const [open, setOpen] = useState(false)
+  // A reply finished while the panel was closed, e.g. the agent continuing after a background job.
+  const [unread, setUnread] = useState(false)
   const labels = { ...DEFAULT_LABELS, ...props.labels }
   return (
     <div className="dopus-widget">
       {/* Hidden rather than unmounted, so closing the panel keeps the conversation. */}
       <div hidden={!open}>
-        <AgentChat {...props} className="dopus-panel" />
+        <AgentChat
+          {...props}
+          className="dopus-panel"
+          onReply={() => {
+            if (!open) setUnread(true)
+            props.onReply?.()
+          }}
+        />
       </div>
       <button
         type="button"
         className="dopus-launcher"
         aria-expanded={open}
-        aria-label={open ? labels.close : labels.open}
-        onClick={() => setOpen((value) => !value)}
+        aria-label={
+          open ? labels.close : unread ? `${labels.open} (${labels.unread})` : labels.open
+        }
+        data-unread={!open && unread ? '' : undefined}
+        onClick={() => {
+          setOpen((value) => !value)
+          setUnread(false)
+        }}
       >
         {open ? '×' : '✦'}
       </button>