dopus 0.1.0 → 0.2.1

package/README.md

@@ -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
 
@@ -184,6 +184,67 @@ defineAgent({
 })
 ```
 
+## Deploying
+
+**Vercel / any Node server.** Nothing extra. The route streams. Raise `maxDuration` in `app/api/agent/route.ts` if your plan allows it.
+
+**AWS (OpenNext / SST).**
+
+```bash
+pnpm dopus infra aws
+```
+
+The command writes `open-next.config.ts` with Lambda response streaming (`aws-lambda-streaming`) and installs `@opennextjs/aws`. It also prints an `sst.aws.Nextjs` snippet that passes your API key and `DOPUS_APPROVAL_SECRET` as SST secrets.
+
+SST reads OpenNext's streaming flag and sets the Function URL to `RESPONSE_STREAM`. Nothing is deployed for you.
+
+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.
+- **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.
+
+`pnpm aws:emu` in this repo builds the example with OpenNext and invokes the Lambda handler locally through a stand-in for the streaming runtime. It checks that the response streams and that tools still read the caller's cookie.
+
+**Cloudflare Workers (OpenNext).**
+
+```bash
+pnpm dopus infra cloudflare
+```
+
+The command writes `open-next.config.ts` (`defineCloudflareConfig`), `wrangler.jsonc` (`nodejs_compat`) and `.dev.vars`. It also adds `cf:preview` and `cf:deploy` scripts, git-ignores `.open-next`, `.dev.vars` and `.wrangler`, and installs `@opennextjs/cloudflare` and `wrangler`.
+
+Wrangler reads `.dev.vars` instead of `.env.local`. So the command offers to copy your API key and `DOPUS_APPROVAL_SECRET` into `.dev.vars` for the local preview. The values are never printed.
+
+For production, set the same two values with `npx wrangler secret put`.
+
+Things to know:
+
+- **No wall-clock limit.** A Worker can keep streaming as long as the client stays connected, and waiting on the LLM does not count as CPU time.
+- **CPU time.** Rendering and tool code do count toward CPU time. Paid plans allow 30 s by default and up to 5 min with `limits.cpu_ms`. The free plan allows 10 ms per request, which a Next.js app usually exceeds.
+- **Node runtime.** OpenNext runs the Node.js runtime, so remove `export const runtime = 'edge'`.
+
+`pnpm cf:e2e` in this repo copies the example and runs `dopus infra cloudflare` on it. It then builds the copy, serves it with `wrangler dev` (local workerd) and runs the same e2e suite against it, covering cookies, ownership checks and signed approvals.
+
+**Google Cloud Run.**
+
+```bash
+pnpm dopus infra gcp
+```
+
+The command sets `output: 'standalone'` in `next.config` (it asks first). It writes a multi-stage `Dockerfile` that pins your pnpm or yarn version through corepack. It also writes a `.dockerignore` that keeps `.env*` and `.dev.vars` out of the image.
+
+It then prints the deploy commands: Secret Manager setup, and `gcloud run deploy --source . --timeout 3600 --set-secrets ...`.
+
+Things to know:
+
+- **Timeout.** A request may last up to 60 min (`--timeout 3600`; the default is 5 min). The timeout covers the whole streamed reply.
+- **Longer work.** Use Cloud Run Jobs and pass the user explicitly (`identify` → `ctx.user`), because there are no cookies outside the request.
+- **Build-time variables.** `.env` files are not copied into the image. If your build needs `NEXT_PUBLIC_*` values, pass them as build args.
+
+`pnpm gcp:e2e` in this repo copies the example and runs `dopus infra gcp` on it. It builds the image with Docker and runs it the way Cloud Run does (`PORT=8080`, secrets as env vars). It checks that a canary secret from `.env.local` is not in the image, then runs the e2e suite against the container.
+
 ## Providers
 
 | Provider  | Package             | API key env                    | Default model       |
@@ -200,11 +261,10 @@ Swap in a scripted `MockLanguageModelV4` from `ai/test` behind an environment va
 
 ## Status and roadmap
 
-dopus is at 0.1, so expect breaking changes before 1.0. It is tested on Next.js 16 with the Node.js runtime.
+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:
 
-- infra adapters for long-running agents (AWS first, then Cloudflare, then GCP);
 - `dopus prompts diff` to compare your copies with newer templates;
 - tool input schemas inferred from TypeScript types.
 
@@ -214,7 +274,11 @@ 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
+pnpm gcp:e2e                             # dopus infra gcp → docker build/run (Cloud Run style) → e2e
 ```
 
 Design notes: [`docs/design.md`](docs/design.md).

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { n as PROVIDERS, t as VERSION } from "./version-BPyQRLlj.js";
+import { n as PROVIDERS, t as VERSION } from "./version-BWFAqCId.js";
 import { execFileSync, spawn } from "node:child_process";
 import { parseArgs } from "node:util";
 import * as p from "@clack/prompts";
@@ -126,11 +126,25 @@ function upsertEnv(content, vars, replace = []) {
 }
 /** True if git (or, without git, .gitignore patterns) keeps `.env.local` out of the repo. */
 function isEnvLocalIgnored(root) {
+	return isGitIgnored(root, ".env.local", [
+		".env.local",
+		".env*.local",
+		".env*",
+		"*.local",
+		".env.*"
+	]);
+}
+/** True if git ignores `path`; outside a repo, falls back to exact lines in .gitignore. */
+function isGitIgnored(root, path, patterns = [
+	path,
+	`${path}/`,
+	`/${path}`
+]) {
 	try {
 		execFileSync("git", [
 			"check-ignore",
 			"-q",
-			".env.local"
+			path
 		], {
 			cwd: root,
 			stdio: "ignore"
@@ -141,13 +155,7 @@ function isEnvLocalIgnored(root) {
 	}
 	const gitignore = join(root, ".gitignore");
 	if (!existsSync(gitignore)) return false;
-	return readFileSync(gitignore, "utf8").split(/\r?\n/).map((l) => l.trim()).some((p) => [
-		".env.local",
-		".env*.local",
-		".env*",
-		"*.local",
-		".env.*"
-	].includes(p));
+	return readFileSync(gitignore, "utf8").split(/\r?\n/).map((l) => l.trim()).some((line) => patterns.includes(line));
 }
 // src/init/templates.ts
 const PRESETS = [
@@ -233,8 +241,12 @@ const ADD_COMMAND = {
 	yarn: ["add"],
 	bun: ["add"]
 };
-function installArgs(packageManager, packages) {
-	return [...ADD_COMMAND[packageManager], ...packages];
+function installArgs(packageManager, packages, dev = false) {
+	return [
+		...ADD_COMMAND[packageManager],
+		...dev ? ["-D"] : [],
+		...packages
+	];
 }
 function toImportPath(fromFile, toFileWithoutExt) {
 	const path = relative(dirname(fromFile), toFileWithoutExt).split("\\").join("/");
@@ -365,11 +377,442 @@ async function runInit(options, io) {
 	}
 	return result;
 }
+// src/infra/aws.ts
+const OPEN_NEXT_CONFIG = `import type { OpenNextConfig } from '@opennextjs/aws/types/open-next.js'
+
+/**
+ * Generated by \`dopus infra aws\`.
+ *
+ * Lambda response streaming lets /api/agent stream replies instead of buffering them. OpenNext marks the
+ * server as streaming in its build output; SST (sst.aws.Nextjs) reads that and sets the Function URL
+ * invoke mode to RESPONSE_STREAM. With your own CDK/Terraform, set InvokeMode RESPONSE_STREAM yourself.
+ */
+const config = {
+  default: {
+    override: {
+      wrapper: 'aws-lambda-streaming',
+    },
+  },
+} satisfies OpenNextConfig
+
+export default config
+`;
+/** Which provider agent.config.ts uses, so the deploy snippet names the right env var. */
+function detectConfiguredProvider(source) {
+	if (!source) return void 0;
+	return Object.values(PROVIDERS).find((info) => source.includes(`'${info.packageName}'`));
+}
+function secretName(envVar) {
+	return envVar.toLowerCase().split("_").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join("");
+}
+function sstSnippet(provider) {
+	const keyEnv = provider?.envVar ?? "OPENAI_API_KEY";
+	const keySecret = secretName(keyEnv);
+	const approval = secretName(APPROVAL_SECRET_ENV);
+	return `// sst.config.ts → run()
+const ${keySecret[0]?.toLowerCase()}${keySecret.slice(1)} = new sst.Secret('${keySecret}')
+const ${approval[0]?.toLowerCase()}${approval.slice(1)} = new sst.Secret('${approval}')
+
+new sst.aws.Nextjs('Web', {
+  server: {
+    // Lambda timeout; SST also uses it as the CloudFront read
+    // timeout (max 60 s, or up to 180 s with a quota increase).
+    timeout: '60 seconds',
+  },
+  environment: {
+    ${keyEnv}: ${keySecret[0]?.toLowerCase()}${keySecret.slice(1)}.value,
+    ${APPROVAL_SECRET_ENV}: ${approval[0]?.toLowerCase()}${approval.slice(1)}.value,
+  },
+})
+
+// then, once per stage:
+//   npx sst secret set ${keySecret} <your key>
+//   npx sst secret set ${approval} "$(openssl rand -base64 32)"`;
+}
+async function runInfraAws(options, io) {
+	const project = detectProject(options.cwd);
+	const { root } = project;
+	const ask = async (message, initial) => options.yes ? initial : io.confirm(message, initial);
+	const configFile = [
+		"open-next.config.ts",
+		"open-next.config.js",
+		"open-next.config.mjs"
+	].find((f) => existsSync(join(root, f)));
+	const agentConfig = [join(project.configDir, "agent.config.ts"), "agent.config.ts"].map((f) => join(root, f)).find((f) => existsSync(f));
+	const provider = detectConfiguredProvider(agentConfig ? readFileSync(agentConfig, "utf8") : void 0);
+	const result = {
+		configFile: configFile ?? "open-next.config.ts",
+		created: false,
+		streaming: false,
+		provider,
+		installed: []
+	};
+	if (configFile) {
+		result.streaming = readFileSync(join(root, configFile), "utf8").includes("aws-lambda-streaming");
+		if (result.streaming) io.info(`${configFile} already enables Lambda streaming — left unchanged.`);
+		else io.warn(`${configFile} exists and does not enable streaming. Add \`override: { wrapper: 'aws-lambda-streaming' }\` to the function that serves /api/agent (or to \`default\`).`);
+	} else {
+		writeFileSync(join(root, "open-next.config.ts"), OPEN_NEXT_CONFIG);
+		result.created = true;
+		result.streaming = true;
+		io.success("Created open-next.config.ts (Lambda response streaming)");
+	}
+	if (!project.dependencies["@opennextjs/aws"]) {
+		const spec = "@opennextjs/aws@^4";
+		if (options.install === false) io.warn(`Install it yourself: ${project.packageManager} ${installArgs(project.packageManager, [spec], true).join(" ")}`);
+		else if (await ask(`Install ${spec} (dev dependency) with ${project.packageManager}?`, true)) {
+			await io.install(project.packageManager, [spec], root, true);
+			result.installed = [spec];
+		}
+	}
+	if (!provider) io.warn("Could not tell the provider from agent.config.ts; the snippet below assumes OpenAI.");
+	io.note(sstSnippet(provider), "Deploy with SST");
+	io.note([
+		"Build: npx @opennextjs/aws build (SST runs it for you).",
+		"Keep-alive: dopus sends an SSE comment every 15 s while a tool",
+		"  runs. CloudFront times out on gaps between packets, not on",
+		"  total time, so long tool calls keep the stream open.",
+		"Limit: a turn must finish within the Lambda timeout: 60 s",
+		"  behind CloudFront by default, up to 15 min on a bare",
+		"  Function URL.",
+		"Avoid API Gateway HTTP APIs for /api/agent (30 s cap)."
+	].join("\n"), "AWS notes");
+	return result;
+}
+// src/infra/cloudflare.ts
+const CLOUDFLARE_OPEN_NEXT_CONFIG = `import { defineCloudflareConfig } from '@opennextjs/cloudflare'
+
+// Generated by \`dopus infra cloudflare\`. Add an incremental cache (R2/KV) here if your pages use ISR.
+export default defineCloudflareConfig({})
+`;
+/** Worker names: lowercase letters, digits and dashes, at most 63 characters. */
+function workerName(packageName) {
+	return (packageName ?? "next-app").replace(/^@[^/]+\//, "").toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 63) || "next-app";
+}
+/** A month back, so the installed workerd always supports it. */
+function compatibilityDate(now = /* @__PURE__ */ new Date()) {
+	return (/* @__PURE__ */ new Date(now.getTime() - 2592e6)).toISOString().slice(0, 10);
+}
+function wranglerConfig(name, date) {
+	return `{
+  // Generated by \`dopus infra cloudflare\` for @opennextjs/cloudflare.
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": "${name}",
+  "main": ".open-next/worker.js",
+  "compatibility_date": "${date}",
+  "compatibility_flags": ["nodejs_compat", "global_fetch_strictly_public"],
+  "assets": { "directory": ".open-next/assets", "binding": "ASSETS" },
+  "services": [{ "binding": "WORKER_SELF_REFERENCE", "service": "${name}" }],
+  // Waiting on the LLM does not count as CPU time, but rendering and tool code do (paid plans: 30 s default).
+  // "limits": { "cpu_ms": 60000 },
+  "observability": { "enabled": true }
+}
+`;
+}
+const SCRIPTS = {
+	"cf:preview": "opennextjs-cloudflare build && opennextjs-cloudflare preview",
+	"cf:deploy": "opennextjs-cloudflare build && opennextjs-cloudflare deploy"
+};
+async function runInfraCloudflare(options, io) {
+	const project = detectProject(options.cwd);
+	const { root } = project;
+	const ask = async (message, initial) => options.yes ? initial : io.confirm(message, initial);
+	const result = {
+		created: [],
+		skipped: [],
+		scripts: [],
+		installed: []
+	};
+	const openNext = [
+		"open-next.config.ts",
+		"open-next.config.js",
+		"open-next.config.mjs"
+	].find((f) => existsSync(join(root, f)));
+	if (openNext && !readFileSync(join(root, openNext), "utf8").includes("@opennextjs/cloudflare")) throw new InitError(`${openNext} is set up for another target (AWS?). OpenNext uses one config per app: move it away and rerun.`);
+	const pkgPath = join(root, "package.json");
+	const pkgSource = readFileSync(pkgPath, "utf8");
+	const pkg = JSON.parse(pkgSource);
+	const name = workerName(pkg.name);
+	const agentConfig = [join(project.configDir, "agent.config.ts"), "agent.config.ts"].map((f) => join(root, f)).find((f) => existsSync(f));
+	const keyEnv = detectConfiguredProvider(agentConfig ? readFileSync(agentConfig, "utf8") : void 0)?.envVar ?? "OPENAI_API_KEY";
+	const files = [
+		[
+			"open-next.config.ts",
+			CLOUDFLARE_OPEN_NEXT_CONFIG,
+			["open-next.config.js", "open-next.config.mjs"]
+		],
+		[
+			"wrangler.jsonc",
+			wranglerConfig(name, compatibilityDate()),
+			["wrangler.json", "wrangler.toml"]
+		],
+		[
+			".dev.vars",
+			"NEXTJS_ENV=development\n",
+			[]
+		]
+	];
+	for (const [file, content, alternatives] of files) {
+		const existing = [file, ...alternatives].find((f) => existsSync(join(root, f)));
+		if (existing) {
+			result.skipped.push(existing);
+			io.info(`${existing} exists — left unchanged.`);
+			continue;
+		}
+		writeFileSync(join(root, file), content, file === ".dev.vars" ? { mode: 384 } : void 0);
+		result.created.push(file);
+		io.success(`Created ${file}`);
+	}
+	const envLocal = join(root, ".env.local");
+	const devVars = join(root, ".dev.vars");
+	const local = existsSync(envLocal) ? parseEnvKeys(readFileSync(envLocal, "utf8")) : /* @__PURE__ */ new Map();
+	const present = existsSync(devVars) ? parseEnvKeys(readFileSync(devVars, "utf8")) : /* @__PURE__ */ new Map();
+	const copy = [keyEnv, APPROVAL_SECRET_ENV].filter((key) => local.get(key) && !present.get(key));
+	if (copy.length > 0 && await ask(`Copy ${copy.join(" and ")} from .env.local into .dev.vars for the local preview?`, true)) {
+		const vars = Object.fromEntries(copy.map((key) => [key, local.get(key) ?? ""]));
+		writeFileSync(devVars, upsertEnv(readFileSync(devVars, "utf8"), vars).content, { mode: 384 });
+		io.success(`.dev.vars: set ${copy.join(", ")}`);
+	}
+	if (result.skipped.some((f) => f.startsWith("wrangler."))) io.warn("Check that your wrangler config has main \".open-next/worker.js\" and the \"nodejs_compat\" flag.");
+	const scripts = { ...pkg.scripts };
+	for (const [key, command] of Object.entries(SCRIPTS)) if (!scripts[key]) {
+		scripts[key] = command;
+		result.scripts.push(key);
+	}
+	if (result.scripts.length > 0) {
+		const indent = /^(\s+)"/m.exec(pkgSource)?.[1] ?? "  ";
+		writeFileSync(pkgPath, `${JSON.stringify({
+			...pkg,
+			scripts
+		}, null, indent)}\n`);
+		io.success(`package.json: added ${result.scripts.join(", ")}`);
+	}
+	const ignore = [
+		".open-next",
+		".dev.vars",
+		".wrangler"
+	].filter((path) => !isGitIgnored(root, path));
+	if (ignore.length > 0) {
+		const gitignore = join(root, ".gitignore");
+		const prefix = existsSync(gitignore) && !readFileSync(gitignore, "utf8").endsWith("\n") ? "\n" : "";
+		appendFileSync(gitignore, `${prefix}\n# Cloudflare (dopus)\n${ignore.map((p) => `${p}\n`).join("")}`);
+		io.success(`.gitignore: added ${ignore.join(", ")}`);
+	}
+	const deps = [[
+		"@opennextjs/cloudflare",
+		"@opennextjs/cloudflare@^1",
+		false
+	], [
+		"wrangler",
+		"wrangler@^4",
+		true
+	]];
+	for (const dev of [false, true]) {
+		const missing = deps.filter(([n, , d]) => d === dev && !project.dependencies[n]).map(([, spec]) => spec);
+		if (missing.length === 0) continue;
+		if (options.install === false) io.warn(`Install yourself: ${project.packageManager} ${installArgs(project.packageManager, missing, dev).join(" ")}`);
+		else if (await ask(`Install ${missing.join(", ")}${dev ? " (dev)" : ""} with ${project.packageManager}?`, true)) {
+			await io.install(project.packageManager, missing, root, dev);
+			result.installed.push(...missing);
+		}
+	}
+	const run = project.packageManager === "npm" ? "npm run" : project.packageManager;
+	io.note([
+		`Local Workers runtime:  ${run} cf:preview`,
+		"  Wrangler reads .dev.vars (not .env.local): keep your key there too.",
+		"",
+		"Production secrets, once per Worker:",
+		`  npx wrangler secret put ${keyEnv}`,
+		`  npx wrangler secret put ${APPROVAL_SECRET_ENV}`,
+		`Deploy:  ${run} cf:deploy`
+	].join("\n"), "Deploy to Cloudflare Workers");
+	io.note([
+		"Duration: no wall-clock limit while the client is connected, and",
+		"  waiting on the LLM is not CPU time. CPU limit: 30 s by default on",
+		"  paid plans (limits.cpu_ms, max 5 min); the free plan allows 10 ms,",
+		"  which a Next.js app usually exceeds.",
+		"Keep-alive SSE comments (15 s) keep long tool calls open.",
+		"Remove `export const runtime = \"edge\"`: OpenNext runs the Node runtime."
+	].join("\n"), "Cloudflare notes");
+	return result;
+}
+// src/infra/gcp.ts
+const LOCKFILE = {
+	pnpm: "pnpm-lock.yaml",
+	npm: "package-lock.json",
+	yarn: "yarn.lock"
+};
+/**
+* The install line. pnpm/yarn come from corepack; without a `packageManager` field corepack would fetch the
+* newest release, whose policies (e.g. pnpm's minimumReleaseAge) can reject a lockfile your version accepted,
+* so pin the version the project uses.
+*/
+function installCommand(packageManager, pinned) {
+	if (packageManager === "npm") return "npm ci";
+	return `${pinned ? `corepack enable ${packageManager} && corepack prepare ${packageManager}@${pinned} --activate` : `corepack enable ${packageManager}`} && ${packageManager} install --frozen-lockfile`;
+}
+/** Version to pin when package.json has no `packageManager` field: the one installed here. */
+function localVersion(packageManager, cwd) {
+	try {
+		const version = execFileSync(packageManager, ["--version"], {
+			cwd,
+			encoding: "utf8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		}).trim();
+		return /^\d+\.\d+\.\d+/.test(version) ? version : void 0;
+	} catch {
+		return;
+	}
+}
+/** `pin`: version to activate with corepack; leave undefined when package.json declares `packageManager`. */
+function dockerfile(packageManager, pin) {
+	if (packageManager === "bun") throw new InitError("Bun projects: write your own Dockerfile (dopus generates npm, pnpm and yarn ones).");
+	return `# Generated by \`dopus infra gcp\`: Next.js standalone server for Cloud Run.
+# Secrets are not baked in: .dockerignore excludes .env files; Cloud Run injects them at runtime.
+FROM node:24-slim AS base
+ENV NEXT_TELEMETRY_DISABLED=1
+
+FROM base AS deps
+WORKDIR /app
+COPY package.json ${LOCKFILE[packageManager]} ./
+RUN ${installCommand(packageManager, pin)}
+
+FROM base AS build
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+RUN node_modules/.bin/next build && mkdir -p public
+
+FROM base AS run
+WORKDIR /app
+ENV NODE_ENV=production PORT=8080 HOSTNAME=0.0.0.0
+RUN groupadd --system --gid 1001 nodejs && useradd --system --uid 1001 --gid nodejs nextjs
+COPY --from=build --chown=nextjs:nodejs /app/.next/standalone ./
+COPY --from=build --chown=nextjs:nodejs /app/.next/static ./.next/static
+COPY --from=build --chown=nextjs:nodejs /app/public ./public
+USER nextjs
+EXPOSE 8080
+CMD ["node", "server.js"]
+`;
+}
+const DOCKERIGNORE = `# Generated by \`dopus infra gcp\`. Keep secrets and build output out of the image.
+node_modules
+.next
+.open-next
+.wrangler
+.git
+.env
+.env.*
+.dev.vars*
+npm-debug.log*
+Dockerfile
+.dockerignore
+`;
+const STANDALONE = /output\s*:\s*['"]standalone['"]/;
+/**
+* Adds `output: 'standalone'` to the usual `const nextConfig = {…}` / `export default {…}` shapes.
+* Returns undefined when the file does not match a shape it can edit safely.
+*/
+function addStandalone(source) {
+	if (STANDALONE.test(source)) return source;
+	if (/\boutput\s*:/.test(source)) return void 0;
+	for (const pattern of [
+		/(const\s+nextConfig(?:\s*:\s*NextConfig)?\s*=\s*)\{\s*\}/,
+		/(const\s+nextConfig(?:\s*:\s*NextConfig)?\s*=\s*)\{/,
+		/(export\s+default\s*)\{\s*\}/,
+		/(module\.exports\s*=\s*)\{\s*\}/
+	]) {
+		if (!pattern.test(source)) continue;
+		return source.replace(pattern, (match, head) => match.trimEnd().endsWith("}") ? `${head}{\n  output: 'standalone',\n}` : `${head}{\n  output: 'standalone',`);
+	}
+}
+function secretId(envVar) {
+	return envVar.toLowerCase().replaceAll("_", "-");
+}
+async function runInfraGcp(options, io) {
+	const project = detectProject(options.cwd);
+	const { root } = project;
+	const ask = async (message, initial) => options.yes ? initial : io.confirm(message, initial);
+	const result = {
+		created: [],
+		skipped: [],
+		standalone: false
+	};
+	const nextConfig = [
+		"next.config.ts",
+		"next.config.mjs",
+		"next.config.js"
+	].find((f) => existsSync(join(root, f)));
+	if (!nextConfig) {
+		writeFileSync(join(root, "next.config.mjs"), "/** @type {import('next').NextConfig} */\nexport default { output: 'standalone' }\n");
+		result.created.push("next.config.mjs");
+		result.standalone = true;
+		io.success("Created next.config.mjs with output: 'standalone'");
+	} else {
+		const source = readFileSync(join(root, nextConfig), "utf8");
+		const patched = addStandalone(source);
+		if (patched === source) result.standalone = true;
+		else if (patched && await ask(`Set output: 'standalone' in ${nextConfig}? (needed for the container)`, true)) {
+			writeFileSync(join(root, nextConfig), patched);
+			result.standalone = true;
+			io.success(`${nextConfig}: set output: 'standalone'`);
+		} else io.warn(`Set \`output: 'standalone'\` in ${nextConfig} yourself; the Dockerfile copies .next/standalone.`);
+	}
+	const files = [["Dockerfile", () => {
+		const declared = JSON.parse(readFileSync(join(root, "package.json"), "utf8")).packageManager;
+		return dockerfile(project.packageManager, declared ? void 0 : localVersion(project.packageManager, root));
+	}], [".dockerignore", () => DOCKERIGNORE]];
+	for (const [file, content] of files) {
+		if (existsSync(join(root, file))) {
+			result.skipped.push(file);
+			io.info(`${file} exists — left unchanged.`);
+			continue;
+		}
+		writeFileSync(join(root, file), content());
+		result.created.push(file);
+		io.success(`Created ${file}`);
+	}
+	if (result.skipped.includes(".dockerignore")) {
+		const ignore = readFileSync(join(root, ".dockerignore"), "utf8");
+		if (!/^\.env/m.test(ignore)) io.warn(".dockerignore does not exclude .env files: your secrets would end up in the image.");
+	}
+	const agentConfig = [join(project.configDir, "agent.config.ts"), "agent.config.ts"].map((f) => join(root, f)).find((f) => existsSync(f));
+	const keyEnv = detectConfiguredProvider(agentConfig ? readFileSync(agentConfig, "utf8") : void 0)?.envVar ?? "OPENAI_API_KEY";
+	const service = workerName(JSON.parse(readFileSync(join(root, "package.json"), "utf8")).name);
+	io.note([
+		"Secrets (Secret Manager), once per project:",
+		`  printf %s "$KEY" | gcloud secrets create ${secretId(keyEnv)} --data-file=-`,
+		`  openssl rand -base64 32 | tr -d '\\n' | gcloud secrets create ${secretId(APPROVAL_SECRET_ENV)} --data-file=-`,
+		"  (the Cloud Run service account needs roles/secretmanager.secretAccessor)",
+		"",
+		"Deploy (Cloud Build uses the Dockerfile):",
+		`  gcloud run deploy ${service} --source . --region <region> --timeout 3600 \\`,
+		`    --set-secrets ${keyEnv}=${secretId(keyEnv)}:latest,${APPROVAL_SECRET_ENV}=${secretId(APPROVAL_SECRET_ENV)}:latest`,
+		"",
+		"Local check:",
+		`  docker build -t ${service} . && docker run --rm -p 8080:8080 --env-file .env.local ${service}`
+	].join("\n"), "Deploy to Cloud Run");
+	io.note([
+		"Timeout: a request (the whole streamed reply) may last up to 60 min",
+		"  (--timeout 3600; default 5 min). For longer work use Cloud Run Jobs",
+		"  and pass the user explicitly (identify → ctx.user): no cookies there.",
+		"Instances are billed while a stream is open; keep-alive comments (15 s)",
+		"  keep load balancers and proxies from dropping long tool calls."
+	].join("\n"), "Cloud Run notes");
+	return result;
+}
 // src/cli.ts
 const HELP = `dopus ${VERSION}
 
 Usage:
-  dopus init [options]   Add an AI agent to this Next.js app
+  dopus init [options]        Add an AI agent to this Next.js app
+  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)
 
 Options for init:
   --provider <id>        openai | anthropic | google
@@ -380,6 +823,11 @@ Options for init:
   --force                Overwrite generated files that already exist
   --cwd <dir>            Project root (default: current directory)
 
+Options for infra:
+  -y, --yes              Do not ask before installing @opennextjs/aws
+  --no-install           Print the install command instead
+  --cwd <dir>            Project root
+
   -h, --help             Show this help
   -v, --version          Show the version
 `;
@@ -424,9 +872,9 @@ const io = {
 	info: (message) => p.log.info(message),
 	warn: (message) => p.log.warn(message),
 	success: (message) => p.log.success(message),
-	install(packageManager, packages, cwd) {
+	install(packageManager, packages, cwd, dev) {
 		return new Promise((resolve, reject) => {
-			const child = spawn(packageManager, installArgs(packageManager, packages), {
+			const child = spawn(packageManager, installArgs(packageManager, packages, dev), {
 				cwd,
 				stdio: "inherit",
 				shell: process.platform === "win32"
@@ -477,10 +925,47 @@ async function init(args) {
 	p.note(steps.map((s, i) => `${i + 1}. ${s}`).join("\n"), "Next steps");
 	p.outro("Done.");
 }
+async function infra(args) {
+	const [target, ...rest] = args;
+	const runners = {
+		aws: runInfraAws,
+		cloudflare: runInfraCloudflare,
+		gcp: runInfraGcp
+	};
+	if (!target || !(target in runners)) throw new InitError("Usage: dopus infra aws | cloudflare | gcp");
+	const { values } = parseArgs({
+		args: rest,
+		options: {
+			yes: {
+				type: "boolean",
+				short: "y"
+			},
+			install: {
+				type: "boolean",
+				default: true
+			},
+			"no-install": { type: "boolean" },
+			cwd: { type: "string" }
+		},
+		allowNegative: true
+	});
+	p.intro(`dopus ${VERSION} · infra ${target}`);
+	const run = runners[target];
+	await run({
+		cwd: values.cwd ?? process.cwd(),
+		yes: values.yes,
+		install: values["no-install"] ? false : values.install
+	}, {
+		...io,
+		note: (message, title) => p.note(message, title)
+	});
+	p.outro("Done. Nothing was deployed.");
+}
 async function main() {
 	const [command, ...rest] = process.argv.slice(2);
 	if (command === "--version" || command === "-v") return console.log(VERSION);
 	if (command === "init") return init(rest);
+	if (command === "infra") return infra(rest);
 	console.log(HELP);
 	if (command && command !== "--help" && command !== "-h") process.exitCode = 1;
 }

package/dist/index.d.ts

@@ -103,8 +103,13 @@ 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
+   * (CloudFront, ALB, nginx) do not drop the connection. Clients ignore comments. Default 15000; `false` disables.
+   */
+  keepAlive?: number | false;
 }
 /** Identity function that gives `agent.config.ts` type checking. */
 export declare function defineAgent<TOOLS extends DopusToolSet>(config: AgentConfig<TOOLS>): AgentConfig<TOOLS>;
@@ -145,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.1.0";
+export declare const VERSION = "0.2.1";
 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-BPyQRLlj.js";
+import { n as PROVIDERS, t as VERSION } from "./version-BWFAqCId.js";
 import { convertToModelMessages, createUIMessageStreamResponse, isStepCount, safeValidateUIMessages, streamText, toUIMessageStream, tool } from "ai";
 // src/next-errors.ts
 /**
@@ -112,6 +112,52 @@ function toolDescription(options) {
 	return usage ? `${description}\n\nWhen to use: ${usage}` : description;
 }
 // src/agent.ts
+const KEEP_ALIVE = new TextEncoder().encode(": keep-alive\n\n");
+/**
+* Inserts SSE comment lines while the body is idle. The UI message stream emits one complete
+* `data: …\n\n` event per chunk, so writing between chunks never splits an event.
+*/
+function withKeepAlive(response, intervalMs) {
+	const source = response.body;
+	if (!source || intervalMs <= 0) return response;
+	const reader = source.getReader();
+	let timer;
+	let lastWrite = Date.now();
+	const body = new ReadableStream({
+		start(controller) {
+			timer = setInterval(() => {
+				if (Date.now() - lastWrite >= intervalMs) {
+					controller.enqueue(KEEP_ALIVE);
+					lastWrite = Date.now();
+				}
+			}, Math.min(intervalMs, 1e3));
+		},
+		async pull(controller) {
+			try {
+				const { done, value } = await reader.read();
+				if (done) {
+					clearInterval(timer);
+					controller.close();
+					return;
+				}
+				lastWrite = Date.now();
+				controller.enqueue(value);
+			} catch (error) {
+				clearInterval(timer);
+				controller.error(error);
+			}
+		},
+		cancel(reason) {
+			clearInterval(timer);
+			return reader.cancel(reason);
+		}
+	});
+	return new Response(body, {
+		status: response.status,
+		statusText: response.statusText,
+		headers: response.headers
+	});
+}
 /** Identity function that gives `agent.config.ts` type checking. */
 function defineAgent(config) {
 	for (const [name, value] of Object.entries(config.tools)) {
@@ -217,15 +263,17 @@ function createAgentHandler(config) {
 			...approvalSecret ? { experimental_toolApprovalSecret: approvalSecret } : {},
 			onError: ({ error }) => report(error)
 		});
-		return createUIMessageStreamResponse({ stream: toUIMessageStream({
+		const response = createUIMessageStreamResponse({ stream: toUIMessageStream({
 			stream: result.stream,
 			tools,
 			originalMessages: messages,
 			onError: (error) => {
+				if (error instanceof ToolError) return error.message;
 				report(error);
 				return "Something went wrong. Please try again.";
 			}
 		}) });
+		return config.keepAlive === false ? response : withKeepAlive(response, config.keepAlive ?? 15e3);
 	};
 }
 export { CORE_PROMPT, PROVIDERS, ToolError, VERSION, buildInstructions, createAgentHandler, defineAgent, defineTool };

package/dist/{version-BPyQRLlj.js → version-BWFAqCId.js}

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

package/package.json

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