dopus 0.2.3 → 0.2.4

package/README.md

@@ -204,9 +204,55 @@ defineAgent({
 })
 ```
 
+## 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 +267,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-CNF5aJ7W.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

package/dist/index.d.ts

@@ -131,12 +131,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 +166,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.4";
+export type { AgentConfig, AgentUser, ClientContext, ConfirmOption, DopusTool, DopusToolSet, HandlerOptions, PromptLayers, ProviderId, ProviderInfo, RuntimeContext, ToolContext, ToolOptions };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { n as PROVIDERS, t as VERSION } from "./version-CwDWliFC.js";
+import { n as PROVIDERS, t as VERSION } from "./version-CNF5aJ7W.js";
 import { convertToModelMessages, createUIMessageStreamResponse, isStepCount, safeValidateUIMessages, streamText, toUIMessageStream, tool } from "ai";
 // src/next-errors.ts
 /**
@@ -220,15 +220,19 @@ 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 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");
@@ -266,6 +270,19 @@ 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)

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dopus",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Drop an AI agent into your existing Next.js app — your server functions become its tools.",
   "license": "MIT",
   "author": "akodm",