dopus 0.2.5 → 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:
@@ -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,7 +203,8 @@ 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.
 
@@ -288,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).**
@@ -370,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-DmrGrSmM.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";

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.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-DmrGrSmM.js";
+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");
@@ -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-Dm8IBEUF.js}

@@ -27,5 +27,5 @@ const PROVIDERS = {
 	}
 };
 // src/version.ts
-const VERSION = "0.2.5";
+const VERSION = "0.2.6";
 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.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": {

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);
 }

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,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',
 }
@@ -57,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 }>
@@ -78,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':
@@ -187,11 +229,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 +254,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,6 +276,8 @@ export function AgentChat({
   labels: labelOverrides,
   suggestions = [],
   className,
+  channel,
+  maxJobFollowUps = 3,
 }: AgentChatProps) {
   const labels = { ...DEFAULT_LABELS, ...labelOverrides }
   const router = useRouter()
@@ -256,6 +314,55 @@ export function AgentChat({
   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 +429,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 && (