dopus 0.2.0 → 0.2.2

package/README.md

@@ -27,13 +27,13 @@ pnpm dopus init
 
 `init` asks for a provider, an API key and a prompt preset, then:
 
-| Writes                                              | What it is                                                                    |
-| --------------------------------------------------- | ----------------------------------------------------------------------------- |
-| `.env.local`                                        | Your API key and a generated `DOPUS_APPROVAL_SECRET`. Never `.env`. Mode 600. |
-| `agent.config.ts`                                   | Model, tools and prompt layers. Edit this.                                    |
-| `agent/prompts/preset.ts`, `agent/prompts/app.ts`   | Your prompt layers. Yours to edit.                                            |
-| `app/api/agent/route.ts`                            | `POST /api/agent`. It speaks the AI SDK `useChat` protocol.                   |
-| `components/agent/agent-chat.tsx` (+ `.module.css`) | Chat panel and floating widget.                                               |
+| Writes                                            | What it is                                                                    |
+| ------------------------------------------------- | ----------------------------------------------------------------------------- |
+| `.env.local`                                      | Your API key and a generated `DOPUS_APPROVAL_SECRET`. Never `.env`. Mode 600. |
+| `agent.config.ts`                                 | Model, tools and prompt layers. Edit this.                                    |
+| `agent/prompts/preset.ts`, `agent/prompts/app.ts` | Your prompt layers. Yours to edit.                                            |
+| `app/api/agent/route.ts`                          | `POST /api/agent`. It speaks the AI SDK `useChat` protocol.                   |
+| `components/agent/agent-chat.tsx` (+ `.css`)      | Chat panel and floating widget. Plain CSS with `dopus-` classes.              |
 
 It also installs whatever is missing of `ai`, `zod`, `@ai-sdk/react` and the provider package. It checks that `.env.local` is git-ignored.
 
@@ -115,7 +115,7 @@ Only two kinds of error message reach the model:
 - a `ToolError` you throw on purpose, such as `throw new ToolError('Order o-1 has already shipped')`;
 - Next.js `redirect()`, `notFound()`, `forbidden()` and `unauthorized()`, which are translated into plain messages such as "the user is not signed in".
 
-Any other error goes to `onError` and is replaced with a generic message, so database errors and stack details stay on the server. The browser only ever sees a generic error text.
+Any other error goes to `onError` and is replaced with a generic message, so database errors and stack details stay on the server. The browser sees the same text as the model: the `ToolError` message, or the generic one.
 
 ## Permissions and security
 
@@ -156,9 +156,9 @@ Anthropic gets an explicit cache breakpoint after layer 3. OpenAI and Gemini cac
 
 Both accept `api`, `suggestions`, `labels` (every UI string, for translation) and `className`.
 
-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. 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. 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 a plain CSS module themed through `--dopus-*` variables, with dark mode included. It needs no Tailwind and no component library. The file is yours, so restyle it or swap in your own components.
+Styling is one plain CSS file (`agent-chat.css`) whose classes all start with `dopus-`, themed through `--dopus-*` variables, with dark mode included. It is deliberately not a CSS Module: create-next-app's Tailwind setup routes every `*.css` file, modules included, through its own Turbopack loader, which left module classes unstyled. It needs no Tailwind and no component library. The file is yours, so restyle it or swap in your own components.
 
 ## Configuration
 
@@ -274,6 +274,7 @@ Planned next:
 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 aws:emu                             # OpenNext build → local Lambda streaming invoke
 pnpm cf:e2e                              # dopus infra cloudflare → wrangler dev (workerd) → e2e

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { n as PROVIDERS, t as VERSION } from "./version-DOEBWDfi.js";
+import { n as PROVIDERS, t as VERSION } from "./version-DKjmKSap.js";
 import { execFileSync, spawn } from "node:child_process";
 import { parseArgs } from "node:util";
 import * as p from "@clack/prompts";
@@ -342,8 +342,8 @@ async function runInit(options, io) {
 			[]
 		],
 		[
-			at("components/agent/agent-chat.module.css"),
-			() => readTemplate("ui/agent-chat.module.css"),
+			at("components/agent/agent-chat.css"),
+			() => readTemplate("ui/agent-chat.css"),
 			[]
 		]
 	];
@@ -964,6 +964,7 @@ async function infra(args) {
 async function main() {
 	const [command, ...rest] = process.argv.slice(2);
 	if (command === "--version" || command === "-v") return console.log(VERSION);
+	if (rest.includes("--help") || rest.includes("-h")) return console.log(HELP);
 	if (command === "init") return init(rest);
 	if (command === "infra") return infra(rest);
 	console.log(HELP);

package/dist/index.d.ts

@@ -103,7 +103,7 @@ interface AgentConfig<TOOLS extends DopusToolSet = DopusToolSet> {
   approvalSecret?: string;
   /** Extra `streamText` settings (temperature, providerOptions, ...). */
   callOptions?: Pick<StreamTextOptions, 'temperature' | 'maxOutputTokens' | 'providerOptions' | 'maxRetries' | 'headers' | 'onEnd' | 'onStepEnd'>;
-  /** Called for errors; the client only ever sees a generic message. */
+  /** Called for unexpected errors (not `ToolError`); the client only sees a generic message for those. */
   onError?: (error: unknown) => void;
   /**
    * While the stream is idle (e.g. a slow tool), send an SSE comment every this many ms so proxies
@@ -150,5 +150,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.0";
+export declare const VERSION = "0.2.2";
 export type { AgentConfig, AgentUser, ClientContext, ConfirmOption, DopusTool, DopusToolSet, PromptLayers, ProviderId, ProviderInfo, RuntimeContext, ToolContext, ToolOptions };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { n as PROVIDERS, t as VERSION } from "./version-DOEBWDfi.js";
+import { n as PROVIDERS, t as VERSION } from "./version-DKjmKSap.js";
 import { convertToModelMessages, createUIMessageStreamResponse, isStepCount, safeValidateUIMessages, streamText, toUIMessageStream, tool } from "ai";
 // src/next-errors.ts
 /**
@@ -268,6 +268,7 @@ function createAgentHandler(config) {
 			tools,
 			originalMessages: messages,
 			onError: (error) => {
+				if (error instanceof ToolError) return error.message;
 				report(error);
 				return "Something went wrong. Please try again.";
 			}

package/dist/{version-DOEBWDfi.js → version-DKjmKSap.js}

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dopus",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Drop an AI agent into your existing Next.js app — your server functions become its tools.",
   "license": "MIT",
   "author": "akodm",
@@ -68,6 +68,7 @@
     "@types/node": "^24.0.0",
     "@types/react": "19.3.0",
     "ai": "7.0.166",
+    "next": "16.4.6",
     "react": "19.3.1",
     "tsdown": "0.23.7",
     "typescript": "6.0.3",

package/templates/prompts/app.ts

@@ -6,12 +6,14 @@
  * Keep it stable: it is part of the cached prompt prefix, so per-request values belong in `runtime`
  * in agent.config.ts instead.
  */
-export default `Service: <name> — <what it does, in one sentence>
+const appPrompt = `Service: <name> — <what it does, in one sentence>
 Users: <who uses it and what they usually come to do>
 Key concepts: <the nouns your users use, e.g. "workspace", "order", "plan", and what they mean>
 Rules: <anything the agent must know, e.g. refund policy, business hours>
 Human help: <how users reach a person, e.g. support@example.com or the Help page>`
 
+export default appPrompt
+
 /** Optional notes per language (tone, terminology). The one matching the request locale is used. */
 export const locales: Record<string, string> = {
   // ko: '존댓말을 사용하고, "주문"과 "발주"를 구분해서 쓰세요.',

package/templates/prompts/presets/customer-support.ts

@@ -2,7 +2,7 @@
  * Layer 2 — Preset: customer support. Copied by `dopus init`; this file is yours to edit.
  * It sits between dopus' core rules and your app context (agent/prompts/app.ts).
  */
-export default `Role: you are the support assistant for this service's customers.
+const presetPrompt = `Role: you are the support assistant for this service's customers.
 
 How to work:
 - Look up the customer's own data (account, orders, tickets) with the tools before answering questions about it.
@@ -11,3 +11,5 @@ How to work:
 - Do not promise refunds, compensation, delivery dates or exceptions unless a tool result or the app context states that policy.
 - Never ask for passwords, full card numbers or full ID numbers.
 - When you cannot resolve the issue, when the customer is upset, or when they ask for a person, explain how to reach a human (see the app context) and summarise the case so they do not have to repeat it.`
+
+export default presetPrompt

package/templates/prompts/presets/general.ts

@@ -2,7 +2,7 @@
  * Layer 2 — Preset: general assistant. Copied by `dopus init`; this file is yours to edit.
  * It sits between dopus' core rules and your app context (agent/prompts/app.ts).
  */
-export default `Role: you are the in-app assistant. You answer questions about the app and do tasks for the user with the available tools.
+const presetPrompt = `Role: you are the in-app assistant. You answer questions about the app and do tasks for the user with the available tools.
 
 How to work:
 - If a tool can do what the user asks, do it rather than explaining how to do it by hand.
@@ -10,3 +10,5 @@ How to work:
 - After a tool runs, report the outcome in plain words: what changed, or what you found.
 - When a request is ambiguous, offer the two or three most likely interpretations and ask which one.
 - If something is outside what the tools allow, point to where in the app the user can do it.`
+
+export default presetPrompt

package/templates/prompts/presets/internal-ops.ts

@@ -2,7 +2,7 @@
  * Layer 2 — Preset: internal operations (admin / back office). Copied by `dopus init`; this file is yours to edit.
  * It sits between dopus' core rules and your app context (agent/prompts/app.ts).
  */
-export default `Role: you are an assistant for staff working in an internal admin tool.
+const presetPrompt = `Role: you are an assistant for staff working in an internal admin tool.
 
 How to work:
 - Be precise and terse. Use lists or tables for more than two records and always include identifiers.
@@ -11,3 +11,5 @@ How to work:
 - For bulk changes, confirm the scope (filters and count) before starting.
 - After changes, report counts of what succeeded and list anything that failed with the reason.
 - Show personal data only when the task needs it.`
+
+export default presetPrompt

package/templates/ui/{agent-chat.module.css → agent-chat.css}

@@ -1,5 +1,9 @@
-/* Styles for agent-chat.tsx. Copied by `dopus init`; yours to edit. Theme with the --dopus-* variables. */
-.chat {
+/*
+ * Styles for agent-chat.tsx. Copied by `dopus init`; yours to edit. Theme with the --dopus-* variables.
+ * Plain global CSS (not a CSS Module) so it works in every setup, including Tailwind's Turbopack loader;
+ * every class starts with `dopus-`, so it does not clash with your own.
+ */
+.dopus-chat {
   --dopus-bg: #ffffff;
   --dopus-fg: #18181b;
   --dopus-muted: #71717a;
@@ -27,7 +31,7 @@
 }
 
 @media (prefers-color-scheme: dark) {
-  .chat {
+  .dopus-chat {
     --dopus-bg: #18181b;
     --dopus-fg: #f4f4f5;
     --dopus-muted: #a1a1aa;
@@ -39,13 +43,13 @@
   }
 }
 
-.header {
+.dopus-header {
   padding: 12px 16px;
   font-weight: 600;
   border-bottom: 1px solid var(--dopus-border);
 }
 
-.messages {
+.dopus-messages {
   flex: 1;
   overflow-y: auto;
   padding: 16px;
@@ -54,31 +58,31 @@
   gap: 12px;
 }
 
-.message {
+.dopus-message {
   display: flex;
   flex-direction: column;
   gap: 6px;
   max-width: 85%;
 }
 
-.message[data-role="user"] {
+.dopus-message[data-role="user"] {
   align-self: flex-end;
   align-items: flex-end;
 }
 
-.text {
+.dopus-text {
   white-space: pre-wrap;
   overflow-wrap: anywhere;
 }
 
-.message[data-role="user"] .text {
+.dopus-message[data-role="user"] .dopus-text {
   background: var(--dopus-accent);
   color: var(--dopus-accent-fg);
   padding: 8px 12px;
   border-radius: var(--dopus-radius);
 }
 
-.tool {
+.dopus-tool {
   font-size: 13px;
   color: var(--dopus-muted);
   background: var(--dopus-surface);
@@ -86,15 +90,15 @@
   padding: 6px 10px;
 }
 
-.tool summary {
+.dopus-tool summary {
   cursor: pointer;
 }
 
-.tool[data-state="error"] {
+.dopus-tool[data-state="error"] {
   color: var(--dopus-danger);
 }
 
-.approval {
+.dopus-approval {
   margin: 0;
   min-inline-size: 0;
   border: 1px solid var(--dopus-border);
@@ -105,19 +109,19 @@
   gap: 8px;
 }
 
-.approvalTitle {
+.dopus-approval-title {
   float: left;
   width: 100%;
   padding: 0;
   font-weight: 600;
 }
 
-.approvalActions {
+.dopus-approval-actions {
   display: flex;
   gap: 8px;
 }
 
-.json {
+.dopus-json {
   margin: 0;
   font:
     12px / 1.4 ui-monospace,
@@ -130,21 +134,21 @@
   overflow: auto;
 }
 
-.thinking {
+.dopus-thinking {
   color: var(--dopus-muted);
 }
 
-.error {
+.dopus-error {
   color: var(--dopus-danger);
 }
 
-.suggestions {
+.dopus-suggestions {
   display: flex;
   flex-wrap: wrap;
   gap: 8px;
 }
 
-.suggestion {
+.dopus-suggestion {
   border: 1px solid var(--dopus-border);
   background: transparent;
   color: inherit;
@@ -154,14 +158,14 @@
   font: inherit;
 }
 
-.form {
+.dopus-form {
   display: flex;
   gap: 8px;
   padding: 12px;
   border-top: 1px solid var(--dopus-border);
 }
 
-.input {
+.dopus-input {
   flex: 1;
   resize: none;
   border: 1px solid var(--dopus-border);
@@ -173,32 +177,32 @@
   max-height: 160px;
 }
 
-.primary,
-.secondary {
+.dopus-primary,
+.dopus-secondary {
   border-radius: 8px;
   padding: 8px 14px;
   font: inherit;
   cursor: pointer;
 }
 
-.primary {
+.dopus-primary {
   background: var(--dopus-accent);
   color: var(--dopus-accent-fg);
   border: 1px solid var(--dopus-accent);
 }
 
-.primary:disabled {
+.dopus-primary:disabled {
   opacity: 0.4;
   cursor: default;
 }
 
-.secondary {
+.dopus-secondary {
   background: transparent;
   color: inherit;
   border: 1px solid var(--dopus-border);
 }
 
-.link {
+.dopus-link {
   background: none;
   border: 0;
   padding: 0;
@@ -208,7 +212,7 @@
   font: inherit;
 }
 
-.spinner {
+.dopus-spinner {
   display: inline-block;
   width: 10px;
   height: 10px;
@@ -225,7 +229,7 @@
   }
 }
 
-.widget {
+.dopus-widget {
   position: fixed;
   right: 20px;
   bottom: 20px;
@@ -236,13 +240,13 @@
   gap: 12px;
 }
 
-.panel {
+.dopus-panel {
   width: min(400px, calc(100vw - 40px));
   height: min(600px, calc(100vh - 120px));
   box-shadow: 0 12px 40px rgb(0 0 0 / 0.18);
 }
 
-.launcher {
+.dopus-launcher {
   width: 52px;
   height: 52px;
   border-radius: 50%;

package/templates/ui/agent-chat.tsx

@@ -2,7 +2,8 @@
 
 /**
  * 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.module.css
+ * 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).
  */
 import { useChat } from '@ai-sdk/react'
 import {
@@ -12,8 +13,9 @@ import {
   lastAssistantMessageIsCompleteWithApprovalResponses,
   type UIMessage,
 } from 'ai'
+import { useRouter } from 'next/navigation'
 import { type FormEvent, type KeyboardEvent, useEffect, useRef, useState } from 'react'
-import styles from './agent-chat.module.css'
+import './agent-chat.css'
 
 const DEFAULT_LABELS = {
   title: 'Assistant',
@@ -58,7 +60,7 @@ function humanize(name: string) {
 }
 
 function Json({ value }: { value: unknown }) {
-  return <pre className={styles.json}>{JSON.stringify(value, null, 2)}</pre>
+  return <pre className="dopus-json">{JSON.stringify(value, null, 2)}</pre>
 }
 
 function ToolCall({
@@ -76,28 +78,28 @@ function ToolCall({
     case 'input-streaming':
     case 'input-available':
       return (
-        <div className={styles.tool} data-state="running">
-          <span className={styles.spinner} aria-hidden /> {labels.running}: {name}
+        <div className="dopus-tool" data-state="running">
+          <span className="dopus-spinner" aria-hidden /> {labels.running}: {name}
         </div>
       )
     case 'approval-requested':
       return (
-        <fieldset className={styles.approval}>
-          <legend className={styles.approvalTitle}>
+        <fieldset className="dopus-approval">
+          <legend className="dopus-approval-title">
             {name} · {labels.needsApproval}
           </legend>
           <Json value={part.input} />
-          <div className={styles.approvalActions}>
+          <div className="dopus-approval-actions">
             <button
               type="button"
-              className={styles.primary}
+              className="dopus-primary"
               onClick={() => onRespond(part.approval.id, true)}
             >
               {labels.approve}
             </button>
             <button
               type="button"
-              className={styles.secondary}
+              className="dopus-secondary"
               onClick={() => onRespond(part.approval.id, false)}
             >
               {labels.decline}
@@ -107,26 +109,26 @@ function ToolCall({
       )
     case 'approval-responded':
       return (
-        <div className={styles.tool} data-state={part.approval.approved ? 'running' : 'declined'}>
+        <div className="dopus-tool" data-state={part.approval.approved ? 'running' : 'declined'}>
           {part.approval.approved ? `${labels.approved}: ${name}` : `${labels.declined}: ${name}`}
         </div>
       )
     case 'output-available':
       return (
-        <details className={styles.tool} data-state="done">
+        <details className="dopus-tool" data-state="done">
           <summary>✓ {name}</summary>
           <Json value={part.output} />
         </details>
       )
     case 'output-error':
       return (
-        <div className={styles.tool} data-state="error">
+        <div className="dopus-tool" data-state="error">
           ✗ {name} · {labels.failed}
         </div>
       )
     case 'output-denied':
       return (
-        <div className={styles.tool} data-state="declined">
+        <div className="dopus-tool" data-state="declined">
           {labels.declined}: {name}
         </div>
       )
@@ -145,12 +147,12 @@ function Message({
   onRespond: (approvalId: string, approved: boolean) => void
 }) {
   return (
-    <div className={styles.message} data-role={message.role}>
+    <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 ? (
-            <div key={key} className={styles.text}>
+            <div key={key} className="dopus-text">
               {part.text}
             </div>
           ) : null
@@ -171,6 +173,7 @@ export function AgentChat({
   className,
 }: AgentChatProps) {
   const labels = { ...DEFAULT_LABELS, ...labelOverrides }
+  const router = useRouter()
   const [transport] = useState(
     () =>
       new DefaultChatTransport({
@@ -183,6 +186,13 @@ export function AgentChat({
     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)
@@ -217,18 +227,18 @@ export function AgentChat({
 
   return (
     <section
-      className={[styles.chat, className].filter(Boolean).join(' ')}
+      className={['dopus-chat', className].filter(Boolean).join(' ')}
       aria-label={labels.title}
     >
-      <header className={styles.header}>{labels.title}</header>
-      <div ref={listRef} className={styles.messages} aria-live="polite">
+      <header className="dopus-header">{labels.title}</header>
+      <div ref={listRef} className="dopus-messages" aria-live="polite">
         {messages.length === 0 && suggestions.length > 0 && (
-          <div className={styles.suggestions}>
+          <div className="dopus-suggestions">
             {suggestions.map((text) => (
               <button
                 key={text}
                 type="button"
-                className={styles.suggestion}
+                className="dopus-suggestion"
                 onClick={() => send(text)}
               >
                 {text}
@@ -239,19 +249,19 @@ export function AgentChat({
         {messages.map((message) => (
           <Message key={message.id} message={message} labels={labels} onRespond={respond} />
         ))}
-        {status === 'submitted' && <div className={styles.thinking}>{labels.thinking}</div>}
+        {status === 'submitted' && <div className="dopus-thinking">{labels.thinking}</div>}
         {error && (
-          <div className={styles.error} role="alert">
+          <div className="dopus-error" role="alert">
             {labels.error}{' '}
-            <button type="button" className={styles.link} onClick={() => regenerate()}>
+            <button type="button" className="dopus-link" onClick={() => regenerate()}>
               {labels.retry}
             </button>
           </div>
         )}
       </div>
-      <form className={styles.form} onSubmit={onSubmit}>
+      <form className="dopus-form" onSubmit={onSubmit}>
         <textarea
-          className={styles.input}
+          className="dopus-input"
           value={input}
           onChange={(event) => setInput(event.target.value)}
           onKeyDown={onKeyDown}
@@ -260,11 +270,11 @@ export function AgentChat({
           aria-label={labels.placeholder}
         />
         {busy ? (
-          <button type="button" className={styles.secondary} onClick={() => stop()}>
+          <button type="button" className="dopus-secondary" onClick={() => stop()}>
             {labels.stop}
           </button>
         ) : (
-          <button type="submit" className={styles.primary} disabled={!input.trim()}>
+          <button type="submit" className="dopus-primary" disabled={!input.trim()}>
             {labels.send}
           </button>
         )}
@@ -278,11 +288,14 @@ export function AgentWidget(props: AgentChatProps) {
   const [open, setOpen] = useState(false)
   const labels = { ...DEFAULT_LABELS, ...props.labels }
   return (
-    <div className={styles.widget}>
-      {open && <AgentChat {...props} className={styles.panel} />}
+    <div className="dopus-widget">
+      {/* Hidden rather than unmounted, so closing the panel keeps the conversation. */}
+      <div hidden={!open}>
+        <AgentChat {...props} className="dopus-panel" />
+      </div>
       <button
         type="button"
-        className={styles.launcher}
+        className="dopus-launcher"
         aria-expanded={open}
         aria-label={open ? labels.close : labels.open}
         onClick={() => setOpen((value) => !value)}