dopus 0.2.3 → 0.2.5

package/README.md

@@ -134,14 +134,14 @@ Any other error goes to `onError` and is replaced with a generic message, so dat
 
 **Prompt injection.** Assume the model can be talked into anything: by the user, or by text inside tool results that other people wrote (a task title, a comment, an email body). dopus does not rely on the model resisting it. The limits are structural:
 
-| Layer                  | What it guarantees                                                                                 |
-| ---------------------- | -------------------------------------------------------------------------------------------------- |
-| Permission inheritance | A tool can do only what the signed-in user can do through your server functions.                   |
-| `confirm: true`        | The user sees the exact input and must approve; signed approvals cannot be forged or edited.       |
-| Plain-text chat UI     | Replies render as text, never HTML or Markdown, so no XSS and no image-URL data leaks.             |
-| Request limits         | `limits.maxBodyBytes` (1 MB) and `limits.maxMessageChars` (8000) answer 413 before the model runs. |
-| `maxSteps`             | At most 10 model ↔ tool round trips per request.                                                   |
-| Core prompt            | Tells the model that tool results are data, not instructions. Helpful, but not a guarantee.        |
+| Layer                  | What it guarantees                                                                                                      |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| Permission inheritance | A tool can do only what the signed-in user can do through your server functions.                                        |
+| `confirm: true`        | The user sees the exact input and must approve; signed approvals cannot be forged or edited.                            |
+| Chat UI rendering      | Markdown without raw HTML, images never loaded, only http(s)/mailto/relative links: no XSS and no image-URL data leaks. |
+| Request limits         | `limits.maxBodyBytes` (1 MB) and `limits.maxMessageChars` (8000) answer 413 before the model runs.                      |
+| `maxSteps`             | At most 10 model ↔ tool round trips per request.                                                                        |
+| Core prompt            | Tells the model that tool results are data, not instructions. Helpful, but not a guarantee.                             |
 
 Your part, so an injected instruction cannot cause damage:
 
@@ -175,7 +175,7 @@ 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. When a tool has run, it calls `router.refresh()` so server components show the changed data. Closing the widget keeps the conversation. It also has stop and retry buttons, and it does not send on Enter while an IME (Korean, Japanese, Chinese) is still composing.
+The UI shows each tool call as it runs. It renders an approve/decline card for confirmed tools and continues automatically once the user answers. When a tool has run, it calls `router.refresh()` so server components show the changed data. Closing the widget keeps the conversation, and a "New chat" button clears it. Assistant replies render as Markdown (tables, lists, code) through `react-markdown` with `remark-gfm`, which `init` installs. Raw HTML is never rendered, images show only their alt text, and links keep only http(s), mailto and relative URLs. If a request is over the size limit (413), the UI says so and offers a new chat instead of a useless retry. It also has stop and retry buttons, and it does not send on Enter while an IME (Korean, Japanese, Chinese) is still composing.
 
 Styling is one plain CSS file (`agent-chat.css`) whose classes all start with `dopus-`, themed through `--dopus-*` variables, with dark mode included. It is deliberately not a CSS Module: create-next-app's Tailwind setup routes every `*.css` file, modules included, through its own Turbopack loader, which left module classes unstyled. It needs no Tailwind and no component library. The file is yours, so restyle it or swap in your own components.
 
@@ -190,6 +190,9 @@ defineAgent({
   identify: async (request) => ({ id: 'user-1' }), // optional
   maxSteps: 10, // model ↔ tool round trips per request
   limits: { maxBodyBytes: 1_000_000, maxMessageChars: 8_000 }, // over → 413
+  beforeRequest,
+  onToolCall,
+  onFinish, // see "Audit log, usage and rate limits"
   approvalSecret, // default: process.env.DOPUS_APPROVAL_SECRET
   callOptions: {
     temperature,
@@ -204,9 +207,93 @@ defineAgent({
 })
 ```
 
+## Audit log, usage and rate limits
+
+Three optional hooks in `defineAgent`. `user` in each comes from `identify`, so define it if you need to know who asked.
+
+```ts
+defineAgent({
+  // ...
+  identify: async () => {
+    const session = await getSession()
+    return session ? { id: session.userId } : undefined
+  },
+
+  // Before the model is called. Return a Response to answer with it instead.
+  beforeRequest: async ({ user, request, messages }) => {
+    const { success } = await ratelimit.limit(user?.id ?? ip(request))
+    if (!success) return Response.json({ error: 'Too many requests' }, { status: 429 })
+  },
+
+  // Every tool call: outcome 'success' | 'error' | 'denied' (the user declined the approval).
+  onToolCall: async ({ user, tool, input, outcome, output, error, durationMs }) => {
+    await db.auditLog.insert({ userId: user?.id, tool, input, outcome, error, durationMs })
+  },
+
+  // Once per request, when the reply is done: tokens summed over all steps.
+  onFinish: async ({ user, model, usage, steps, finishReason, durationMs }) => {
+    await db.usage.insert({ userId: user?.id, model: model.modelId, ...usage })
+  },
+})
+```
+
+- `onToolCall` gets the tool's original error message. It stays on the server; the model and the browser get the safe
+  message described under [Errors](#errors).
+- A hook that throws goes to `onError` and does not break the chat. Hooks are awaited, so a slow log write delays the
+  reply; queue the write if that matters.
+- `usage.cachedInputTokens` shows prompt caching at work. In the demo task board with Claude, about 90% of input tokens
+  were cache reads.
+- The chat UI shows a generic error for a 429. Pass your own `labels.error` if you want different wording.
+
+## Timeouts and long-running tools
+
+An agent turn can take a while: several model calls plus your tools. Two kinds of limits apply, handled differently.
+
+**Idle timeouts** (CloudFront, ALB, nginx: usually 60 s without a byte). Handled:
+
+- The route streams tokens and tool states as they happen; it never waits for the whole answer.
+- While a slow tool runs, an SSE comment (`: keep-alive`) goes out every 15 s (`keepAlive` option). Clients ignore it.
+- Waiting for an approval holds nothing open. The request ends at the approval card, and the answer starts a new one.
+
+**The platform's total limit** for one request (Vercel `maxDuration`, Lambda timeout, Cloud Run `--timeout`). It cannot be
+streamed around, so dopus stays inside it:
+
+```ts
+// app/api/agent/route.ts (as generated)
+export const maxDuration = 60
+export const POST = createAgentHandler(agent, { maxDuration })
+```
+
+With `maxDuration` passed, once 75% of it has passed the agent starts no more tool calls. It answers with what it has done
+and says what is left, and the user can reply "continue". Without it, a long turn is cut off mid-stream and the chat shows
+an error. A step already running (one model call or one tool) is not interrupted, so keep single tools well under the
+limit. `maxSteps` (default 10) also bounds a turn.
+
+**Tools that take longer than a request.** Exports, bulk updates, report generation and the like should not run inside a
+tool call. Split them into two tools:
+
+```ts
+startExport: defineTool((input) => startExportJob(input), {   // enqueue, return { jobId } at once
+  description: 'Starts a CSV export and returns a job id.',
+  input: z.object({ from: z.string(), to: z.string() }),
+  confirm: true,
+}),
+exportStatus: defineTool((input) => getExportJob(input.jobId), {   // { status, url? }
+  description: 'Returns the status of an export job and its download link when done.',
+  input: z.object({ jobId: z.string() }),
+}),
+```
+
+The job runs in your queue or background worker, outside the request, so it does not have the request's cookies. Check
+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.
+
+**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.
+
 ## Deploying
 
-**Vercel / any Node server.** Nothing extra. The route streams. Raise `maxDuration` in `app/api/agent/route.ts` if your plan allows it.
+**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).**
 
@@ -221,7 +308,7 @@ SST reads OpenNext's streaming flag and sets the Function URL to `RESPONSE_STREA
 Things to know:
 
 - **Keep-alive.** While a tool runs and nothing else is sent, dopus writes an SSE comment (`: keep-alive`) every 15 s (`keepAlive` option). Clients ignore it. CloudFront, ALB and nginx time out on gaps between packets, not on total time, so a slow tool does not cut the stream.
-- **Turn length.** A turn still has to finish within the Lambda timeout. Behind CloudFront that is 60 s by default (up to 180 s with a quota increase). A bare Function URL allows up to 15 min.
+- **Turn length.** A turn still has to finish within the Lambda timeout. Behind CloudFront that is 60 s by default (up to 180 s with a quota increase). A bare Function URL allows up to 15 min. Keep the route's `maxDuration` equal to the Lambda timeout so the time budget matches.
 - **No API Gateway.** Don't put API Gateway HTTP APIs in front of `/api/agent`. They cap requests at 30 s and buffer the response.
 - **Long-running work.** Work that outlives a request, such as queues and background jobs, loses the request's cookies. Use `identify` and pass `ctx.user` on explicitly.
 

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { n as PROVIDERS, t as VERSION } from "./version-CwDWliFC.js";
+import { n as PROVIDERS, t as VERSION } from "./version-DmrGrSmM.js";
 import { execFileSync, spawn } from "node:child_process";
 import { parseArgs } from "node:util";
 import * as p from "@clack/prompts";
@@ -227,10 +227,11 @@ function routeTemplate(configImport) {
 	return `import { createAgentHandler } from 'dopus'
 import agent from '${configImport}'
 
-// Agent replies stream for a while; raise this if your platform cuts requests short.
+// Seconds this route may run (your platform's limit applies). Passing it lets the agent stop calling tools at
+// 75% of it and answer with what it has, instead of being cut off mid-stream.
 export const maxDuration = 60
 
-export const POST = createAgentHandler(agent)
+export const POST = createAgentHandler(agent, { maxDuration })
 `;
 }
 // src/init/run.ts
@@ -366,7 +367,9 @@ async function runInit(options, io) {
 		["ai", "ai@^7"],
 		["zod", "zod@^4"],
 		[info.packageName, `${info.packageName}@^4`],
-		["@ai-sdk/react", "@ai-sdk/react@^4"]
+		["@ai-sdk/react", "@ai-sdk/react@^4"],
+		["react-markdown", "react-markdown@^10"],
+		["remark-gfm", "remark-gfm@^4"]
 	].filter(([name]) => !project.dependencies[name]).map(([, spec]) => spec);
 	if (missing.length > 0) {
 		if (options.install === false) io.warn(`Install these yourself: ${project.packageManager} ${installArgs(project.packageManager, missing).join(" ")}`);

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { LanguageModel, SystemModelMessage, streamText } from "ai";
+import { LanguageModel, SystemModelMessage, UIMessage, streamText } from "ai";
 import { z } from "zod";
 /**
  * Layer 1 (Core). Kept short: tool-use and safety rules that apply to every app.
@@ -94,6 +94,19 @@ interface AgentConfig<TOOLS extends DopusToolSet = DopusToolSet> {
    * needed when tools run outside the request. Return `undefined` for anonymous users.
    */
   identify?: (request: Request) => AgentUser | undefined | Promise<AgentUser | undefined>;
+  /**
+   * Runs before the model is called, after the body is validated. Return a `Response` (e.g. a 429 from your rate
+   * limiter) to answer with it instead; return nothing to continue.
+   */
+  beforeRequest?: (ctx: {
+    request: Request;
+    user: AgentUser | undefined;
+    messages: UIMessage[];
+  }) => Response | undefined | Promise<Response | undefined>;
+  /** Called once per tool call: ran (`success` / `error`) or declined by the user (`denied`). For audit logs. */
+  onToolCall?: (event: ToolCallEvent) => void | Promise<void>;
+  /** Called once per request when the reply is finished: tokens, steps, model. For usage tracking. */
+  onFinish?: (event: FinishEvent) => void | Promise<void>;
   /** Maximum model steps (tool round trips) per request. Default 10. */
   maxSteps?: number;
   /**
@@ -120,6 +133,37 @@ interface AgentConfig<TOOLS extends DopusToolSet = DopusToolSet> {
    */
   keepAlive?: number | false;
 }
+interface ToolCallEvent {
+  tool: string;
+  toolCallId: string;
+  input: unknown;
+  /** From `identify`; `undefined` if you did not define it. */
+  user: AgentUser | undefined;
+  outcome: 'success' | 'error' | 'denied';
+  /** The tool's return value (`success`). */
+  output?: unknown;
+  /** The original error message (`error`). Server-side only: the model and the browser see a safe message. */
+  error?: string;
+  /** Execution time (`success` / `error`). */
+  durationMs?: number;
+}
+interface FinishEvent {
+  user: AgentUser | undefined;
+  model: {
+    provider: string;
+    modelId: string;
+  };
+  /** Summed over all steps of this request. */
+  usage: {
+    inputTokens: number | undefined;
+    outputTokens: number | undefined;
+    totalTokens: number | undefined;
+    cachedInputTokens: number | undefined;
+  };
+  steps: number;
+  finishReason: string;
+  durationMs: number;
+}
 /** Identity function that gives `agent.config.ts` type checking. */
 export declare function defineAgent<TOOLS extends DopusToolSet>(config: AgentConfig<TOOLS>): AgentConfig<TOOLS>;
 /**
@@ -131,12 +175,19 @@ interface ClientContext {
   locale?: string;
   page?: string;
 }
+interface HandlerOptions {
+  /**
+   * The route's `maxDuration` in seconds (pass the exported constant). Once 75% of it has passed, the agent
+   * starts no further tool calls and answers with what it has, instead of being cut off by the platform.
+   */
+  maxDuration?: number;
+}
 /**
  * Creates a `POST` route handler that speaks the AI SDK UI message stream protocol (`useChat`).
  *
  * Tools execute inside this request, so server functions they call see the caller's cookies.
  */
-export declare function createAgentHandler(config: AgentConfig): (request: Request) => Promise<Response>;
+export declare function createAgentHandler(config: AgentConfig, options?: HandlerOptions): (request: Request) => Promise<Response>;
 /**
  * An error whose message is safe to show to the model (and, through it, the user).
  * Any other error thrown by a tool is reported via `onError` and replaced with a generic message,
@@ -159,5 +210,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.3";
-export type { AgentConfig, AgentUser, ClientContext, ConfirmOption, DopusTool, DopusToolSet, PromptLayers, ProviderId, ProviderInfo, RuntimeContext, ToolContext, ToolOptions };
+export declare const VERSION = "0.2.5";
+export type { AgentConfig, AgentUser, ClientContext, ConfirmOption, DopusTool, DopusToolSet, FinishEvent, HandlerOptions, PromptLayers, ProviderId, ProviderInfo, RuntimeContext, ToolCallEvent, ToolContext, ToolOptions };

package/dist/index.js

@@ -1,5 +1,5 @@
-import { n as PROVIDERS, t as VERSION } from "./version-CwDWliFC.js";
-import { convertToModelMessages, createUIMessageStreamResponse, isStepCount, safeValidateUIMessages, streamText, toUIMessageStream, tool } from "ai";
+import { n as PROVIDERS, t as VERSION } from "./version-DmrGrSmM.js";
+import { convertToModelMessages, createUIMessageStreamResponse, getToolName, isStepCount, isToolUIPart, safeValidateUIMessages, streamText, toUIMessageStream, tool } from "ai";
 // src/next-errors.ts
 /**
 * An error whose message is safe to show to the model (and, through it, the user).
@@ -167,6 +167,15 @@ function defineAgent(config) {
 	}
 	return config;
 }
+/** Runs a user hook; a failing hook is reported but never breaks the chat. */
+async function runHook(hook, event, report) {
+	if (!hook) return;
+	try {
+		await hook(event);
+	} catch (error) {
+		report?.(error);
+	}
+}
 function buildTools(tools, ctx) {
 	const aiTools = {};
 	const approval = {};
@@ -176,14 +185,34 @@ function buildTools(tools, ctx) {
 			description: toolDescription(options),
 			inputSchema: options.input,
 			execute: async (input, { toolCallId, abortSignal }) => {
+				const started = Date.now();
+				const base = {
+					tool: name,
+					toolCallId,
+					input,
+					user: ctx.user
+				};
 				try {
 					const result = await fn(input, {
 						user: ctx.user,
 						toolCallId,
 						abortSignal
 					});
-					return options.output ? options.output(result) : result;
+					const output = options.output ? options.output(result) : result;
+					await runHook(ctx.onToolCall, {
+						...base,
+						outcome: "success",
+						output,
+						durationMs: Date.now() - started
+					}, ctx.report);
+					return output;
 				} catch (error) {
+					await runHook(ctx.onToolCall, {
+						...base,
+						outcome: "error",
+						error: error instanceof Error ? error.message : String(error),
+						durationMs: Date.now() - started
+					}, ctx.report);
 					const translated = translateNextError(error);
 					if (translated instanceof ToolError) throw translated;
 					ctx.report?.(error);
@@ -220,15 +249,20 @@ function errorResponse(status, message) {
 		headers: JSON_HEADERS
 	});
 }
+/** Share of `maxDuration` after which no new tool calls start; the rest is left for the final answer. */
+const TIME_BUDGET_SHARE = .75;
+const TIME_UP = `Time for this request is almost up. Do not call any more tools. Answer now with what you have done and found so far. If work remains, say what is left so the user can ask you to continue.`;
 /**
 * Creates a `POST` route handler that speaks the AI SDK UI message stream protocol (`useChat`).
 *
 * Tools execute inside this request, so server functions they call see the caller's cookies.
 */
-function createAgentHandler(config) {
+function createAgentHandler(config, options = {}) {
 	const maxSteps = config.maxSteps ?? 10;
 	const report = config.onError ?? ((error) => console.error("[dopus]", error));
 	return async function handleAgentRequest(request) {
+		const started = Date.now();
+		const deadline = options.maxDuration ? Date.now() + options.maxDuration * 1e3 * TIME_BUDGET_SHARE : void 0;
 		const maxBodyBytes = config.limits?.maxBodyBytes ?? 1e6;
 		const maxMessageChars = config.limits?.maxMessageChars ?? 8e3;
 		if (Number(request.headers.get("content-length") ?? 0) > maxBodyBytes) return errorResponse(413, "Conversation is too long");
@@ -243,12 +277,29 @@ function createAgentHandler(config) {
 		const user = await config.identify?.(request);
 		const { tools, toolApproval } = buildTools(config.tools, {
 			user,
-			report
+			report,
+			onToolCall: config.onToolCall
 		});
 		const validated = await safeValidateUIMessages({ messages: body?.messages });
 		if (!validated.success) return errorResponse(400, "Invalid messages");
 		const messages = validated.data;
 		if (messages.some((message) => message.role === "user" && message.parts.some((part) => part.type === "text" && part.text.length > maxMessageChars))) return errorResponse(413, "Message is too long");
+		const early = await config.beforeRequest?.({
+			request,
+			user,
+			messages
+		});
+		if (early instanceof Response) return early;
+		for (const part of messages.at(-1)?.role === "assistant" ? messages.at(-1)?.parts ?? [] : []) {
+			if (!isToolUIPart(part) || part.state !== "approval-responded" || part.approval.approved) continue;
+			await runHook(config.onToolCall, {
+				tool: getToolName(part),
+				toolCallId: part.toolCallId,
+				input: part.input,
+				user,
+				outcome: "denied"
+			}, report);
+		}
 		const client = readClientContext(body, request);
 		const runtime = {
 			...client,
@@ -266,9 +317,41 @@ function createAgentHandler(config) {
 			tools,
 			toolApproval,
 			stopWhen: isStepCount(maxSteps),
+			prepareStep: ({ stepNumber, instructions }) => {
+				if (deadline === void 0 || stepNumber === 0 || Date.now() < deadline) return {};
+				return {
+					toolChoice: "none",
+					instructions: [...(instructions === void 0 ? [] : [instructions].flat()).map((m) => typeof m === "string" ? {
+						role: "system",
+						content: m
+					} : m).filter((m) => m.content !== TIME_UP), {
+						role: "system",
+						content: TIME_UP
+					}]
+				};
+			},
 			abortSignal: request.signal,
 			...approvalSecret ? { experimental_toolApprovalSecret: approvalSecret } : {},
-			onError: ({ error }) => report(error)
+			onError: ({ error }) => report(error),
+			onEnd: async (event) => {
+				await config.callOptions?.onEnd?.(event);
+				await runHook(config.onFinish, {
+					user,
+					model: {
+						provider: event.model.provider,
+						modelId: event.model.modelId
+					},
+					usage: {
+						inputTokens: event.totalUsage.inputTokens,
+						outputTokens: event.totalUsage.outputTokens,
+						totalTokens: event.totalUsage.totalTokens,
+						cachedInputTokens: event.totalUsage.inputTokenDetails?.cacheReadTokens
+					},
+					steps: event.stepNumber + 1,
+					finishReason: event.finishReason,
+					durationMs: Date.now() - started
+				}, report);
+			}
 		});
 		const response = createUIMessageStreamResponse({ stream: toUIMessageStream({
 			stream: result.stream,

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dopus",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Drop an AI agent into your existing Next.js app — your server functions become its tools.",
   "license": "MIT",
   "author": "akodm",
@@ -70,6 +70,8 @@
     "ai": "7.0.166",
     "next": "16.4.6",
     "react": "19.3.1",
+    "react-markdown": "10.1.0",
+    "remark-gfm": "4.0.1",
     "tsdown": "0.23.7",
     "typescript": "6.0.3",
     "vitest": "5.1.0",

package/templates/ui/agent-chat.css

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

package/templates/ui/agent-chat.tsx

@@ -14,7 +14,16 @@ import {
   type UIMessage,
 } from 'ai'
 import { useRouter } from 'next/navigation'
-import { type FormEvent, type KeyboardEvent, useEffect, useRef, useState } from 'react'
+import {
+  type ComponentProps,
+  type FormEvent,
+  type KeyboardEvent,
+  useEffect,
+  useRef,
+  useState,
+} from 'react'
+import Markdown, { defaultUrlTransform } from 'react-markdown'
+import remarkGfm from 'remark-gfm'
 import './agent-chat.css'
 
 const DEFAULT_LABELS = {
@@ -23,6 +32,8 @@ const DEFAULT_LABELS = {
   send: 'Send',
   stop: 'Stop',
   retry: 'Retry',
+  newChat: 'New chat',
+  tooLong: 'Too long to send. Start a new chat or shorten your message.',
   error: 'Something went wrong.',
   thinking: 'Thinking…',
   running: 'Running',
@@ -137,6 +148,41 @@ function ToolCall({
   }
 }
 
+/**
+ * Assistant replies are Markdown (tables, lists, bold). Rendered with react-markdown, which never renders raw HTML.
+ * Images are shown as their alt text and never loaded, and links keep only http(s), mailto and relative URLs:
+ * a reply influenced by prompt injection cannot load a URL that leaks data, or run script.
+ */
+const MARKDOWN_COMPONENTS: ComponentProps<typeof Markdown>['components'] = {
+  a: ({ href, children }) => (
+    <a href={href} target="_blank" rel="noopener noreferrer nofollow">
+      {children}
+    </a>
+  ),
+  img: ({ alt }) => (alt ? <span>[{alt}]</span> : null),
+  table: ({ children }) => (
+    <div className="dopus-table">
+      <table>{children}</table>
+    </div>
+  ),
+}
+
+function AssistantText({ text }: { text: string }) {
+  return (
+    <div className="dopus-text dopus-markdown">
+      <Markdown
+        remarkPlugins={[remarkGfm]}
+        components={MARKDOWN_COMPONENTS}
+        urlTransform={(url) =>
+          /^(https?:|mailto:|\/|#)/i.test(url) ? defaultUrlTransform(url) : ''
+        }
+      >
+        {text}
+      </Markdown>
+    </div>
+  )
+}
+
 function Message({
   message,
   labels,
@@ -151,11 +197,14 @@ function Message({
       {message.parts.map((part, index) => {
         const key = `${message.id}-${index}`
         if (part.type === 'text') {
-          return part.text ? (
+          if (!part.text) return null
+          return message.role === 'assistant' ? (
+            <AssistantText key={key} text={part.text} />
+          ) : (
             <div key={key} className="dopus-text">
               {part.text}
             </div>
-          ) : null
+          )
         }
         if (isToolUIPart(part)) {
           return <ToolCall key={key} part={part} labels={labels} onRespond={onRespond} />
@@ -182,18 +231,27 @@ export function AgentChat({
         body: () => ({ context: { page: window.location.pathname, locale: navigator.language } }),
       }),
   )
-  const { messages, sendMessage, status, stop, error, regenerate, addToolApprovalResponse } =
-    useChat({
-      transport,
-      sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses,
-      // A tool ran, so data the page shows may have changed (server actions call revalidatePath):
-      // re-render the current route's server components.
-      onFinish: ({ message }) => {
-        if (message.parts.some((part) => isToolUIPart(part) && part.state === 'output-available')) {
-          router.refresh()
-        }
-      },
-    })
+  const {
+    messages,
+    setMessages,
+    sendMessage,
+    status,
+    stop,
+    error,
+    clearError,
+    regenerate,
+    addToolApprovalResponse,
+  } = useChat({
+    transport,
+    sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses,
+    // A tool ran, so data the page shows may have changed (server actions call revalidatePath):
+    // re-render the current route's server components.
+    onFinish: ({ message }) => {
+      if (message.parts.some((part) => isToolUIPart(part) && part.state === 'output-available')) {
+        router.refresh()
+      }
+    },
+  })
   const [input, setInput] = useState('')
   const listRef = useRef<HTMLDivElement>(null)
   const busy = status === 'submitted' || status === 'streaming'
@@ -225,12 +283,29 @@ export function AgentChat({
 
   const respond = (id: string, approved: boolean) => addToolApprovalResponse({ id, approved })
 
+  function newChat() {
+    if (busy) stop()
+    clearError()
+    setMessages([])
+    setInput('')
+  }
+
+  // The route answers 413 when the history is over its size limit; retrying cannot help then.
+  const tooLong = (error as { statusCode?: number } | undefined)?.statusCode === 413
+
   return (
     <section
       className={['dopus-chat', className].filter(Boolean).join(' ')}
       aria-label={labels.title}
     >
-      <header className="dopus-header">{labels.title}</header>
+      <header className="dopus-header">
+        <span>{labels.title}</span>
+        {messages.length > 0 && (
+          <button type="button" className="dopus-link dopus-new-chat" onClick={newChat}>
+            {labels.newChat}
+          </button>
+        )}
+      </header>
       <div ref={listRef} className="dopus-messages" aria-live="polite">
         {messages.length === 0 && suggestions.length > 0 && (
           <div className="dopus-suggestions">
@@ -252,9 +327,13 @@ export function AgentChat({
         {status === 'submitted' && <div className="dopus-thinking">{labels.thinking}</div>}
         {error && (
           <div className="dopus-error" role="alert">
-            {labels.error}{' '}
-            <button type="button" className="dopus-link" onClick={() => regenerate()}>
-              {labels.retry}
+            {tooLong ? labels.tooLong : labels.error}{' '}
+            <button
+              type="button"
+              className="dopus-link"
+              onClick={() => (tooLong ? newChat() : regenerate())}
+            >
+              {tooLong ? labels.newChat : labels.retry}
             </button>
           </div>
         )}