@andreprado/agentkit 0.1.0-alpha.21 → 0.1.0-alpha.22

package/docs/guides/add-managed-composio.md

@@ -79,7 +79,7 @@ Expected readiness:
 
 ## Connect Apps
 
-After deploy, create a hosted Composio Connect Link:
+The Composio connect link is deploy-scoped, so declare `composioManaged(...)` first, deploy, then connect. After deploy, create a hosted Composio Connect Link:
 
 ```sh
 agentkit integrations connect composio --toolkit gmail
@@ -90,6 +90,8 @@ AgentKit prints a URL. Send that URL to the person who owns the app account.
 
 If the deploy has only one toolkit, `--toolkit` can be omitted.
 
+`agentkit deploy` prints the recommended `integrations connect composio --toolkit <slug>` command for each configured toolkit in its production handoff.
+
 ## Calendar Defaults
 
 For Google Calendar agents, include read and write actions together. Do not expose only `GOOGLECALENDAR_CREATE_EVENT`; users naturally ask to see availability before booking.

package/docs/guides/add-tool.md

@@ -112,6 +112,8 @@ Direct tool test:
 npm run agentkit -- tool lookup_order --input '{"orderId":"A100"}'
 ```
 
+When the tool touches live data, writes externally, or enforces business rules, also add deterministic checks. Use fixtures, eval-safe branches, seed data, or direct tool inputs for success and failure paths such as missing confirmation, validation errors, provider 429s/timeouts, unavailable records, and privacy/no-leak behavior. Add an eval when the agent should call the tool with specific inputs or refuse to call it until required intake or confirmation is complete.
+
 Expected output:
 
 ```json
@@ -129,9 +131,10 @@ Use this when a tool needs agent-owned tables and must work locally and after de
 
 Recommended contract:
 
-- Put all agent-owned tables in `schema.sql`.
+- Put the idempotent bootstrap view of agent-owned tables in `schema.sql`.
+- For production-shaped schema evolution, add ordered `migrations/*.sql` files such as `migrations/0001_clients.sql`.
 - Keep deploy-ready capsules on `storage.driver: "agentkit"`.
-- Local `agentkit chat`, `agentkit tool`, `agentkit dev`, and eval runs apply `schema.sql` to local development storage.
+- Local `agentkit chat`, `agentkit tool`, `agentkit dev`, and eval runs apply ordered local migrations before `schema.sql`.
 - Use `agentkit db migrate`, `agentkit db reset --yes`, `agentkit db seed [--file seed.sql]`, and `agentkit db shell` for local database setup and inspection.
 - Hosted deploy migrates/provisions the managed database internally and applies the same `schema.sql`.
 - Tools use `ctx.db` as the canonical helper. `ctx.database` and `ctx.storage.sql` are supported aliases.
@@ -176,7 +179,7 @@ CREATE TABLE IF NOT EXISTS appointments (
 );
 ```
 
-`schema.sql` is an idempotent bootstrap file in v1. Prefer `CREATE TABLE IF NOT EXISTS`, `CREATE INDEX IF NOT EXISTS`, and safe additive `ALTER TABLE` statements. AgentKit does not run destructive schema changes or ordered `migrations/*.sql` automatically yet.
+`schema.sql` is an idempotent bootstrap file. Prefer `CREATE TABLE IF NOT EXISTS`, `CREATE INDEX IF NOT EXISTS`, and safe additive `ALTER TABLE` statements. Use ordered `migrations/*.sql` for production-shaped schema evolution; `agentkit db migrate` applies unapplied local migrations before `schema.sql`.
 
 `tools/schedule-appointment.ts`:
 

package/docs/guides/create-agent.md

@@ -89,7 +89,7 @@ Runtime files created after chat:
 
 ## Handoff To A Coding Agent
 
-The owner does not need to fill a separate brief file. The natural-language request they type into Codex, Claude Code, or another coding agent is the brief.
+The owner does not need to run a brief wizard or fill a separate brief file. The natural-language request they type into Codex, Claude Code, or another coding agent is the brief.
 
 Primary flow:
 
@@ -97,9 +97,9 @@ Primary flow:
 Develop an appointment and intake agent for an ophthalmology office.
 ```
 
-The generated `AGENTS.md`, `AGENTKIT.md`, `CLAUDE.md`, and `skills/` pack tell the coding agent which files to edit, which task skill to load, and which verification commands to run. There is no wizard or recipe layer: the coding agent edits the capsule directly from the scaffold, contract, and owner request. The default router is `skills/agentkit-capsule/SKILL.md`; `llms-full.txt` is reserved for complete-contract checks.
+The generated `AGENTS.md`, `AGENTKIT.md`, `CLAUDE.md`, and `skills/` pack tell the coding agent which files to edit, which task skill to load, and which verification commands to run. There is no AgentKit CLI wizard in the normal flow: the coding agent edits the capsule directly from the scaffold, contract, and owner request. The default router is `skills/agentkit-capsule/SKILL.md`; `llms-full.txt` is reserved for complete-contract checks.
 
-After the owner gives the general idea, the coding agent should create or update the implementation contract itself:
+After the owner gives the general idea inside the coding-agent chat, the coding agent should create or update the implementation contract itself:
 
 ```sh
 npm run agentkit -- spec init --brief "Develop an appointment and intake agent for an ophthalmology office."
@@ -108,6 +108,8 @@ npm run agentkit -- spec check
 
 `AGENT_SPEC.md` is an internal working contract for the coding agent. It is not a form the owner must fill before work starts.
 
+The coding agent should build a testable capsule, not only a prompt. For each meaningful requirement in the brief or `AGENT_SPEC.md`, decide whether it needs a prompt instruction, tool, schema/migration, fixture, eval, direct tool check, or deploy/readiness check. Privacy, confirmation, external writes, bookings, customer data, business hours, dates, and integration failures should have evals or deterministic checks before the capsule is called done.
+
 Optional shortcut when copying a prompt into another coding agent:
 
 ```sh
@@ -176,7 +178,7 @@ npm run agentkit -- chat-ui --deploy
 
 Open the printed `Chat:` URL and tell the owner this local UI is connected to the hosted deploy.
 
-`test/fake` is deterministic. It validates the scaffold, direct tool checks, and fake-provider evals, but it does not validate natural conversation quality. Before claiming real conversation behavior is tested, ask the owner which provider to use: OpenRouter, OpenAI, Anthropic, or another supported provider.
+`test/fake` is deterministic. It validates the scaffold, direct tool checks, and fake-provider evals, but it does not validate natural conversation quality. Before claiming real conversation behavior is tested, ask the owner which provider to use: OpenRouter, OpenAI, Anthropic, OpenCode Zen, OpenCode Go, or another supported provider.
 
 ## Safety Rules
 

package/docs/guides/prepare-deploy.md

@@ -154,7 +154,7 @@ npm run agentkit -- chat-ui --deploy
 npm run agentkit -- access token list
 ```
 
-For hosted deploys, `npm run agentkit -- deploy` writes the local chat/UI access token to `.agentkit/chat-access-token.json`. Use `npm run agentkit -- deploy --smoke "hello"` for the official hosted chat smoke, and use `npm run agentkit -- chat-ui --deploy` for hosted UI testing. The hosted Chat UI shows the conversation id, tool calls, tool errors, and a new-conversation control; use `npm run agentkit -- conversations trace <conversation-id> --deploy` to pull the hosted trace from the last deploy. Use `npm run agentkit -- access token create <name> --out <path>` only for additional clients.
+For hosted deploys, `npm run agentkit -- deploy` writes the local chat/UI access token to `.agentkit/chat-access-token.json` and prints a production handoff with the deploy URL, UI command, secret status, database/schema artifact, integration connect commands, smoke status, and next recommended command. Use `npm run agentkit -- deploy --smoke "hello"` for the official hosted chat smoke, and use `npm run agentkit -- chat-ui --deploy` for hosted UI testing. The hosted Chat UI shows the conversation id, tool calls, tool errors, and a new-conversation control; use `npm run agentkit -- conversations trace <conversation-id> --deploy` to pull the hosted trace from the last deploy. Use `npm run agentkit -- access token create <name> --out <path>` only for additional clients.
 
 When the UI is running, open the printed `Chat:` URL and tell the owner the exact URL. If the capsule is still on `test/fake`, say the UI was tested only with the deterministic fake provider.
 

package/docs/guides/run-evals.md

@@ -22,6 +22,8 @@ Run evals:
 agentkit eval run
 ```
 
+`agentkit eval run` uses temporary local SQLite storage for eval execution. This keeps eval conversations and tool calls isolated from `.agentkit/agentkit.db`, so evals can run while a local chat or dev server is using the normal development database.
+
 If the capsule uses npm scripts and Windows PowerShell blocks `npm.ps1`, use:
 
 ```sh
@@ -54,6 +56,8 @@ Create or edit:
 evals/<name>.eval.ts
 ```
 
+Create evals proactively from the agent brief and `AGENT_SPEC.md`. High-value evals cover identity and scope, required intake fields, confirmation before writes, no-leak/privacy rules, timezone and business-hour behavior, default durations or limits, tool-call payloads, unavailable slots, empty results, missing auth, rate limits, and timeouts. If a real conversation reveals a bug, add the smallest regression eval that would have failed before the fix.
+
 Use conversations as source material:
 
 ```txt
@@ -152,7 +156,7 @@ export default defineEval({
 });
 ```
 
-`tools.persisted` validates the tool call saved in local SQLite `tool_calls`, not a provider-specific raw response shape. It can be a tool name string or an object with `name`, `input`, `output`, `rendered`, `status`, and/or `visibility`.
+`tools.persisted` validates the tool call saved in the eval run's local SQLite `tool_calls`, not a provider-specific raw response shape. It can be a tool name string or an object with `name`, `input`, `output`, `rendered`, `status`, and/or `visibility`.
 
 Use `tools.count` for the exact number of persisted calls in that turn, `tools.calledOnce` for exactly one call by name, and `tools.order` for required relative order. `tools.order` allows extra calls before, between, or after the named calls; pair it with `tools.count` when the exact call set matters.
 

package/docs/guides/use-provider.md

@@ -6,7 +6,7 @@ Switch a capsule from the offline `test/fake` provider to a Pi-backed provider.
 
 ## When To Use This
 
-Use this when local fake responses are no longer enough and the agent needs model behavior from OpenRouter, OpenAI, Anthropic, or another supported provider.
+Use this when local fake responses are no longer enough and the agent needs model behavior from OpenRouter, OpenAI, Anthropic, OpenCode Zen, OpenCode Go, or another supported provider.
 
 The coding agent should not choose a real provider automatically. Ask the owner which provider to use, then update the capsule.
 
@@ -87,6 +87,30 @@ secrets: ["OPENROUTER_API_KEY"],
 
 Prefer model ids or aliases listed by the installed Pi SDK when available, such as `~google/gemini-flash-latest`. If an OpenRouter model id is newer than the Pi model registry, AgentKit passes the id through to OpenRouter using Pi's OpenAI-compatible transport with conservative unknown-model metadata. The provider may still reject the request if the id is invalid, inaccessible, or does not support the tools/features the agent uses.
 
+OpenCode Zen:
+
+```ts
+provider: {
+  name: "opencode",
+  model: "big-pickle",
+},
+secrets: ["OPENCODE_API_KEY"],
+```
+
+Use an OpenCode Zen model id listed by the installed Pi SDK, such as `big-pickle`, `deepseek-v4-flash-free`, `claude-sonnet-4-5`, or `gpt-5.4-mini`. OpenCode Zen uses `OPENCODE_API_KEY`.
+
+OpenCode Go:
+
+```ts
+provider: {
+  name: "opencode-go",
+  model: "deepseek-v4-flash",
+},
+secrets: ["OPENCODE_API_KEY"],
+```
+
+Use an OpenCode Go model id listed by the installed Pi SDK, such as `deepseek-v4-flash`, `deepseek-v4-pro`, `glm-5.1`, `kimi-k2.6`, `minimax-m2.7`, or `qwen3.6-plus`. OpenCode Go also uses `OPENCODE_API_KEY`.
+
 ## UI Verification
 
 After the provider is configured and the local secret is set, test through chat and UI:
@@ -135,7 +159,7 @@ npm run agentkit -- inspect
 
 `provider_model_unsupported`:
 
-For OpenAI or Anthropic, use a model id known to the installed Pi SDK for that provider. For OpenRouter, prefer a known Pi alias when possible; otherwise a raw OpenRouter model id is passed through and any remaining model error comes from OpenRouter.
+For OpenAI, Anthropic, OpenCode Zen, or OpenCode Go, use a model id known to the installed Pi SDK for that provider. For OpenRouter, prefer a known Pi alias when possible; otherwise a raw OpenRouter model id is passed through and any remaining model error comes from OpenRouter.
 
 Provider returns auth failure:
 

package/docs/llms-full.txt

@@ -161,7 +161,7 @@ Then open the folder in Codex, Claude Code, or another coding agent and ask dire
 Develop an appointment and intake agent for an ophthalmology office.
 ```
 
-The coding agent should infer the first useful version, edit `prompts/instructions.md`, `agentkit.config.ts`, `schema.sql`, `tools/`, and `evals/`, then run the verification commands before finishing. Do not wait for a wizard or recipe. AgentKit provides the scaffold and contract; the coding agent implements directly in the capsule.
+The coding agent should infer the first useful version, edit `prompts/instructions.md`, `agentkit.config.ts`, `schema.sql`, `tools/`, and `evals/`, then run the verification commands before finishing. Do not send the owner back to a CLI brief wizard. AgentKit provides the scaffold, contract, and skills; the coding agent implements directly in the capsule from the owner's chat message.
 
 Optional handoff shortcut:
 
@@ -217,6 +217,8 @@ test
 openai
 anthropic
 openrouter
+opencode
+opencode-go
 custom
 ```
 
@@ -227,6 +229,8 @@ test/fake
 openai via Pi SDK
 anthropic via Pi SDK
 openrouter via Pi SDK
+opencode via Pi SDK
+opencode-go via Pi SDK
 ```
 
 `custom` is a reserved config value. It is not implemented as a local provider adapter yet.
@@ -245,7 +249,7 @@ secrets: [],
 
 `test/fake` is deterministic. It is useful for scaffold checks, direct tool checks, and fake-provider evals, but it does not validate natural conversation quality.
 
-Before claiming real conversation behavior has been tested, ask the owner which provider to use: OpenRouter, OpenAI, Anthropic, or another supported provider. Do not choose for them. After the owner chooses, update `agentkit.config.ts`, `.env.schema`, local secrets, hosted secrets if deploying, then rerun chat/UI checks.
+Before claiming real conversation behavior has been tested, ask the owner which provider to use: OpenRouter, OpenAI, Anthropic, OpenCode Zen, OpenCode Go, or another supported provider. Do not choose for them. After the owner chooses, update `agentkit.config.ts`, `.env.schema`, local secrets, hosted secrets if deploying, then rerun chat/UI checks.
 
 OpenAI example:
 
@@ -270,6 +274,30 @@ If a provider key is missing, the runtime returns `secret_not_found`.
 
 For OpenRouter, prefer model ids or aliases known to the installed Pi SDK, such as `~google/gemini-flash-latest`. If an OpenRouter id is newer than Pi's registry, AgentKit passes the raw id through to OpenRouter with conservative unknown-model metadata. OpenRouter can still reject invalid, inaccessible, or unsupported models, and unknown-model cost/capability metadata is not authoritative.
 
+OpenCode Zen example:
+
+```ts
+provider: {
+  name: "opencode",
+  model: "big-pickle",
+},
+secrets: ["OPENCODE_API_KEY"],
+```
+
+Use an OpenCode Zen model id listed by the installed Pi SDK, such as `big-pickle`, `deepseek-v4-flash-free`, `claude-sonnet-4-5`, or `gpt-5.4-mini`.
+
+OpenCode Go example:
+
+```ts
+provider: {
+  name: "opencode-go",
+  model: "deepseek-v4-flash",
+},
+secrets: ["OPENCODE_API_KEY"],
+```
+
+Use an OpenCode Go model id listed by the installed Pi SDK, such as `deepseek-v4-flash`, `deepseek-v4-pro`, `glm-5.1`, `kimi-k2.6`, `minimax-m2.7`, or `qwen3.6-plus`.
+
 ## Knowledge Contract
 
 Knowledge is AgentKit's native retrieval layer for facts the agent should ground in source files. Use it for FAQs, prices, policies, service descriptions, procedures, CSV tables, and reference docs. Do not put secrets, credentials, `.env` contents, or live customer/payment records in Knowledge. Use tools for live or authorization-sensitive data.
@@ -602,7 +630,7 @@ CREATE TABLE IF NOT EXISTS appointments (
 );
 ```
 
-`schema.sql` is an idempotent bootstrap file in v1. Use `CREATE TABLE IF NOT EXISTS`, `CREATE INDEX IF NOT EXISTS`, and only safe additive `ALTER TABLE` statements. AgentKit does not automatically run destructive changes or ordered `migrations/*.sql` yet.
+`schema.sql` is an idempotent bootstrap file. Use `CREATE TABLE IF NOT EXISTS`, `CREATE INDEX IF NOT EXISTS`, and only safe additive `ALTER TABLE` statements. Use ordered `migrations/*.sql` for production-shaped schema evolution; `agentkit db migrate` applies unapplied local migrations before `schema.sql`.
 
 Example tool:
 
@@ -831,7 +859,7 @@ tools.order
 tools.persisted
 ```
 
-Import `defineEval` from `@andreprado/agentkit` when writing new evals. `tools.persisted` validates the tool call saved in local SQLite `tool_calls`, not a provider-specific raw response shape. It can be a tool name string or an object with `name`, `input`, `output`, `rendered`, `status`, and/or `visibility`. `tool_call` and `persisted_tool_call` remain accepted as backwards-compatible aliases, but new evals should use `tools.persisted`.
+Import `defineEval` from `@andreprado/agentkit` when writing new evals. `tools.persisted` validates the tool call saved in the eval run's local SQLite `tool_calls`, not a provider-specific raw response shape. It can be a tool name string or an object with `name`, `input`, `output`, `rendered`, `status`, and/or `visibility`. `tool_call` and `persisted_tool_call` remain accepted as backwards-compatible aliases, but new evals should use `tools.persisted`.
 
 For date-sensitive evals, set top-level `now` to an ISO timestamp with an explicit timezone designator such as `Z` or `-05:00`. AgentKit uses that fixed clock for every turn and tool call in the eval so "today", "tomorrow", and weekdays remain deterministic while normal chat continues to use the real current date.
 
@@ -939,7 +967,7 @@ agentkit deploy smoke --message "hello"
 agentkit chat-ui --deploy
 ```
 
-`agentkit deploy doctor` checks AgentKit Cloud login, hosted deploy entitlement, online deploy capacity, hosted secrets, local `.env` names that still need `agentkit secret set`, managed Composio API/auth-config readiness by toolkit, and private-access runtime token handling. `agentkit deploy` sends the capsule to AgentKit Cloud, runs the same readiness check automatically before building and uploading, updates the current project deploy slot by default, and writes the local chat/UI deploy access token to `.agentkit/chat-access-token.json` for hosted deploys. `agentkit deploy --smoke "hello"` deploys and then tests `/v1/chat` with the deploy access token. `agentkit deploy smoke --message "hello"` repeats that smoke against the last local deploy. `agentkit chat-ui --deploy` serves a local UI pointed at the hosted deploy using that token without exposing it to browser code, shows the conversation id and tool calls, and supports starting a new conversation. Use `agentkit conversations trace <conversation-id> --deploy` to pull hosted conversation messages and tool calls from the last deploy. Production deploys require an account with `cloudflare_deploy_alpha` or purchased/manual deploy slots; local commands and dry-run builds do not require login. AgentKit owns infrastructure selection, backend migration, managed secrets, and public URL creation.
+`agentkit deploy doctor` checks AgentKit Cloud login, hosted deploy entitlement, online deploy capacity, hosted secrets, local `.env` names that still need `agentkit secret set`, managed Composio API/auth-config readiness by toolkit, and private-access runtime token handling. `agentkit deploy` sends the capsule to AgentKit Cloud, runs the same readiness check automatically before building and uploading, updates the current project deploy slot by default, writes the local chat/UI deploy access token to `.agentkit/chat-access-token.json`, and prints a production handoff with URL, UI command, secret status, database/schema artifact, integration connect commands, smoke status, and the next recommended command. `agentkit deploy --smoke "hello"` deploys and then tests `/v1/chat` with the deploy access token. `agentkit deploy smoke --message "hello"` repeats that smoke against the last local deploy. `agentkit chat-ui --deploy` serves a local UI pointed at the hosted deploy using that token without exposing it to browser code, shows the conversation id and tool calls, and supports starting a new conversation. Use `agentkit conversations trace <conversation-id> --deploy` to pull hosted conversation messages and tool calls from the last deploy. Production deploys require an account with `cloudflare_deploy_alpha` or purchased/manual deploy slots; local commands and dry-run builds do not require login. AgentKit owns infrastructure selection, backend migration, managed secrets, and public URL creation.
 
 The CLI defaults to the hosted AgentKit Cloud API at `https://agentkit-cloud.aibuilders.com.br`. Use `AGENTKIT_CLOUD_API_URL` or `agentkit deploy --api <url>` only when the owner gives you a non-default AgentKit Cloud API URL.
 

package/docs/llms.txt

@@ -95,16 +95,18 @@ agentkit open
 
 On Windows PowerShell, if `npm.ps1` or `npx.ps1` is blocked with `PSSecurityException`, run capsule scripts through the `.cmd` shims, for example `npm.cmd run agentkit -- inspect`, `npm.cmd run agentkit -- knowledge sync`, or `npm.cmd run eval`.
 
-Generated capsules include `AGENTKIT.md`, `AGENTS.md`, and a repo-local `skills/` pack so Codex, Claude Code, or another coding agent can treat the owner's natural-language request as the brief and start building immediately without loading the full contract by default. Start with `skills/agentkit-capsule/SKILL.md`, then load the task skill for the current work. `agentkit handoff codex "Develop an ophthalmology office intake agent"` is an optional prompt-printing shortcut for users who are not already inside a coding-agent workspace. There is no wizard or recipe layer: the coding agent edits the capsule directly from the scaffold and contract.
+Generated capsules include `AGENTKIT.md`, `AGENTS.md`, and a repo-local `skills/` pack so Codex, Claude Code, or another coding agent can treat the owner's natural-language request as the brief and start building immediately without loading the full contract by default. Start with `skills/agentkit-capsule/SKILL.md`, then load the task skill for the current work. `agentkit handoff codex "Develop an ophthalmology office intake agent"` is an optional prompt-printing shortcut for users who are not already inside a coding-agent workspace. There is no AgentKit CLI wizard in the normal flow: the coding agent edits the capsule directly from the scaffold and contract.
 
 UI testing is part of the handoff. For local UI testing, run `agentkit dev`, open the printed `Chat:` URL, and tell the owner the exact URL. After hosted deploy, run `agentkit chat-ui --deploy`, open the printed `Chat:` URL, and tell the owner it is connected to the deploy.
 
 Hosted Chat UI shows the current conversation id, tool calls, tool errors, and a new-conversation control. Use `agentkit conversations trace <conversation-id> --deploy` to pull the hosted trace from the last deploy.
 
-`test/fake` is deterministic and validates scaffold, direct tool calls, and fake-provider evals. It does not validate natural conversation quality. Before claiming real conversation behavior has been tested, ask the owner which provider to use: OpenRouter, OpenAI, Anthropic, or another supported provider. Do not choose for them.
+`test/fake` is deterministic and validates scaffold, direct tool calls, and fake-provider evals. It does not validate natural conversation quality. Before claiming real conversation behavior has been tested, ask the owner which provider to use: OpenRouter, OpenAI, Anthropic, OpenCode Zen, OpenCode Go, or another supported provider. Do not choose for them.
 
 For OpenRouter, prefer model ids or aliases known to the installed Pi SDK, such as `~google/gemini-flash-latest`. If an OpenRouter id is newer than Pi's registry, AgentKit passes the raw id through to OpenRouter with conservative unknown-model metadata; OpenRouter can still reject invalid, inaccessible, or unsupported models.
 
+For OpenCode Zen, use `provider: { name: "opencode", model: "big-pickle" }`. For OpenCode Go, use `provider: { name: "opencode-go", model: "deepseek-v4-flash" }`. Both use `OPENCODE_API_KEY` in `secrets` and `.env.schema`.
+
 AgentKit injects the current ISO timestamp, local date, weekday, local date/time, and timezone dynamically into every chat run. Set `timeZone` in `agentkit.config.ts` for scheduling agents so "today", "tomorrow", and weekdays resolve in the business/user timezone; otherwise AgentKit falls back to `AGENTKIT_TIME_ZONE`, valid `TZ`, then the runtime default. Do not hardcode today's date in prompts.
 
 Current local endpoints from `agentkit dev`:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andreprado/agentkit",
-  "version": "0.1.0-alpha.21",
+  "version": "0.1.0-alpha.22",
   "private": false,
   "type": "module",
   "repository": {

package/src/cli/deploy-chat-ui.ts

@@ -1,5 +1,5 @@
 import { readFile } from "node:fs/promises";
-import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
 import { join, relative, resolve } from "node:path";
 
 import { findAgentCapsuleRoot } from "../runtime/config";
@@ -9,8 +9,15 @@ import { defaultDeployChatAccessTokenName, defaultDeployChatAccessTokenPath } fr
 
 export async function startDeployChatUiServer(
   cwd: string,
-  options: { port: number; tokenFile?: string },
-): Promise<{ url: string; deployUrl: string; tokenSource: string; stop(): Promise<void> }> {
+  options: { port: number; tokenFile?: string; autoPort?: boolean },
+): Promise<{
+  url: string;
+  deployUrl: string;
+  tokenSource: string;
+  port: number;
+  portConflict: { port: number } | null;
+  stop(): Promise<void>;
+}> {
   const root = await findAgentCapsuleRoot(cwd);
   const state = await readLocalDeployStateIfExists(root);
 
@@ -23,9 +30,37 @@ export async function startDeployChatUiServer(
     : join(root, defaultDeployChatAccessTokenPath);
   const hostname = "localhost";
   const deployUrl = state.url;
+  const start = await listenForDeployChatUiServer({
+    hostname,
+    requestedPort: options.port,
+    autoPort: options.autoPort === true,
+    create: () => createDeployChatUiHttpServer({ root, tokenPath, hostname, requestedPort: options.port, deployUrl }),
+  });
+
+  return {
+    url: `http://${hostname}:${start.port}`,
+    deployUrl,
+    tokenSource: process.env.AGENTKIT_DEPLOY_ACCESS_TOKEN ? "AGENTKIT_DEPLOY_ACCESS_TOKEN" : relativePath(root, tokenPath),
+    port: start.port,
+    portConflict: start.portConflict,
+    stop: () =>
+      new Promise<void>((resolvePromise, reject) => {
+        start.server.close((error) => (error ? reject(error) : resolvePromise()));
+      }),
+  };
+}
+
+function createDeployChatUiHttpServer(input: {
+  root: string;
+  tokenPath: string;
+  hostname: string;
+  requestedPort: number;
+  deployUrl: string;
+}): Server {
+  const { root, tokenPath, hostname, requestedPort, deployUrl } = input;
   const server = createServer(async (request, response) => {
     try {
-      const requestUrl = new URL(request.url ?? "/", `http://${request.headers.host ?? `${hostname}:${options.port}`}`);
+      const requestUrl = new URL(request.url ?? "/", `http://${request.headers.host ?? `${hostname}:${requestedPort}`}`);
 
       if (request.method === "GET" && requestUrl.pathname === "/") {
         sendHtml(response, renderDeployChatUi({ deployUrl }));
@@ -102,23 +137,59 @@ export async function startDeployChatUiServer(
     }
   });
 
-  await new Promise<void>((resolvePromise, reject) => {
+  return server;
+}
+
+async function listenForDeployChatUiServer(input: {
+  hostname: string;
+  requestedPort: number;
+  autoPort: boolean;
+  create: () => Server;
+}): Promise<{ server: Server; port: number; portConflict: { port: number } | null }> {
+  let firstConflict: { port: number } | null = null;
+  const lastPort = input.autoPort ? input.requestedPort + 50 : input.requestedPort;
+
+  for (let port = input.requestedPort; port <= lastPort; port += 1) {
+    const server = input.create();
+
+    try {
+      await listen(server, input.hostname, port);
+      return { server, port, portConflict: port === input.requestedPort ? null : firstConflict };
+    } catch (error) {
+      await closeServerAfterListenError(server);
+
+      if (!input.autoPort || !isAddressInUseError(error)) {
+        throw error;
+      }
+
+      firstConflict ??= { port };
+    }
+  }
+
+  throw new AgentKitError(
+    "runtime_error",
+    `Could not allocate a local AgentKit hosted chat UI port after ${input.requestedPort}-${lastPort}.`,
+  );
+}
+
+function listen(server: Server, hostname: string, port: number): Promise<void> {
+  return new Promise((resolvePromise, reject) => {
     server.once("error", reject);
-    server.listen(options.port, hostname, () => {
+    server.listen(port, hostname, () => {
       server.off("error", reject);
       resolvePromise();
     });
   });
+}
 
-  return {
-    url: `http://${hostname}:${options.port}`,
-    deployUrl,
-    tokenSource: process.env.AGENTKIT_DEPLOY_ACCESS_TOKEN ? "AGENTKIT_DEPLOY_ACCESS_TOKEN" : relativePath(root, tokenPath),
-    stop: () =>
-      new Promise<void>((resolvePromise, reject) => {
-        server.close((error) => (error ? reject(error) : resolvePromise()));
-      }),
-  };
+async function closeServerAfterListenError(server: Server): Promise<void> {
+  await new Promise<void>((resolvePromise) => {
+    server.close(() => resolvePromise());
+  });
+}
+
+function isAddressInUseError(error: unknown): boolean {
+  return Boolean(error && typeof error === "object" && "code" in error && error.code === "EADDRINUSE");
 }
 
 export async function readDeployAccessTokenForUi(tokenPath: string): Promise<string> {

package/src/cli/index.ts

@@ -109,6 +109,8 @@ async function main() {
     throw new Error("Usage: agentkit help [commands]");
   }
 
+  warnIfUnsupportedNode();
+
   if (args.command === "new") {
     const [name] = args.positional;
     const template = String(args.flags.template ?? "blank");
@@ -136,8 +138,8 @@ async function main() {
       console.log("  npm install");
     }
     console.log("  open this folder in Codex or Claude Code");
-    console.log("  coding agents start at skills/agentkit-capsule/SKILL.md");
-    console.log('  ask: "Develop an appointment and intake agent for an ophthalmology office"');
+    console.log('  ask Codex: "Develop an appointment and intake agent for an ophthalmology office"');
+    console.log("  Codex starts at skills/agentkit-capsule/SKILL.md and treats your request as the brief");
     console.log('  npm run chat -- --message "hello"');
     console.log("  npm run dev");
     console.log("  npm run agentkit -- deploy");
@@ -187,16 +189,25 @@ async function main() {
       throw new Error("Usage: agentkit chat-ui --deploy [--port <number>] [--token-file <path>]");
     }
 
-    const port = parsePort(args.flags.port, "agentkit chat-ui --deploy --port <number>") ?? 4124;
+    const requestedPort = parsePort(args.flags.port, "agentkit chat-ui --deploy --port <number>");
+    const port = requestedPort ?? 4124;
     const tokenFile = parseOptionalStringFlag(
       args.flags["token-file"],
       "token-file",
       "agentkit chat-ui --deploy --token-file <path>",
     );
-    const server = await startDeployChatUiServer(process.cwd(), { port, tokenFile });
+    const server = await startDeployChatUiServer(process.cwd(), {
+      port,
+      tokenFile,
+      autoPort: requestedPort === undefined,
+    });
 
     console.log("AgentKit hosted chat UI running");
     console.log("");
+    if (server.portConflict) {
+      console.log(`Port ${server.portConflict.port} is already used. Started hosted chat UI at ${server.url}.`);
+      console.log("");
+    }
     console.log(`Chat:       ${server.url}`);
     console.log(`Production: ${server.deployUrl}`);
     console.log(`Token:      ${server.tokenSource}`);
@@ -936,14 +947,16 @@ async function main() {
       return;
     }
 
+    let readinessReport: Awaited<ReturnType<typeof checkDeployReadiness>> | null = null;
+
     if (!args.flags["dry-run"] && !args.flags["local-wrangler"]) {
-      const report = await checkDeployReadiness({
+      readinessReport = await checkDeployReadiness({
         apiUrl: await resolveCloudApiUrl(args.flags.api),
         requireLogin: !anonymous,
       });
 
-      if (!report.ok) {
-        printDeployReadinessReport(report);
+      if (!readinessReport.ok) {
+        printDeployReadinessReport(readinessReport);
         throw new AgentKitError(
           "deploy_readiness_failed",
           "Fix deploy readiness failures before running agentkit deploy.",
@@ -1016,6 +1029,14 @@ async function main() {
             : undefined,
       });
     }
+    printDeployProductionHandoff({
+      deployUrl: deploy.deploy.url,
+      statePath,
+      chatAccess,
+      databaseSchemaPath: result.tursoSchemaPath,
+      readinessReport,
+      smokeMessage,
+    });
     return;
   }
 
@@ -1362,7 +1383,7 @@ Rules:
 - Edit the agent contract in agentkit.config.ts.
 - Add TypeScript tools under tools/.
 - Keep the first useful version runnable with test/fake unless the owner has already chosen a real provider.
-- Before testing real conversation behavior, ask the owner to choose OpenRouter, OpenAI, Anthropic, or another supported provider. Do not choose for them.
+- Before testing real conversation behavior, ask the owner to choose OpenRouter, OpenAI, Anthropic, OpenCode Zen, OpenCode Go, or another supported provider. Do not choose for them.
 - Keep local secrets in .env only.
 - Do not commit or print secret values.
 - Do not edit .agentkit/ directly.
@@ -1402,6 +1423,84 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
+function warnIfUnsupportedNode(): void {
+  const major = majorNodeVersion(process.versions.node);
+
+  if (major !== null && major < 24) {
+    console.warn(
+      `Warning: @andreprado/agentkit requires Node >=24; current Node is ${process.versions.node}. Use Node 24+ before relying on local runtime or deploy commands.`,
+    );
+  }
+}
+
+function majorNodeVersion(version: string): number | null {
+  const [major] = version.split(".");
+  const parsed = Number(major);
+  return Number.isInteger(parsed) ? parsed : null;
+}
+
+function printDeployProductionHandoff(input: {
+  deployUrl: string;
+  statePath: string;
+  chatAccess: Awaited<ReturnType<typeof ensureDeployChatAccessToken>>;
+  databaseSchemaPath: string | null;
+  readinessReport: Awaited<ReturnType<typeof checkDeployReadiness>> | null;
+  smokeMessage?: string;
+}): void {
+  const context = input.readinessReport?.context;
+  const userSecrets = context?.userManagedSecrets ?? [];
+  const managedSecrets = context?.agentKitManagedSecrets ?? [];
+  const composio = context?.integrations.managedComposio;
+
+  console.log("");
+  console.log("Production handoff");
+  console.log(`URL:          ${input.deployUrl}`);
+  console.log(`UI:           npm run agentkit -- chat-ui --deploy`);
+  console.log(`State:        ${input.statePath}`);
+  console.log(
+    `Secrets:      ${
+      userSecrets.length > 0
+        ? `user-managed set (${userSecrets.join(", ")})`
+        : "no user-managed hosted secrets required"
+    }${managedSecrets.length > 0 ? `; AgentKit-managed: ${managedSecrets.join(", ")}` : ""}`,
+  );
+  console.log(
+    `Database:     ${
+      input.databaseSchemaPath
+        ? `AgentKit-managed; schema artifact ${input.databaseSchemaPath}`
+        : "AgentKit-managed; no application schema artifact"
+    }`,
+  );
+
+  if (composio?.enabled) {
+    console.log(`Integrations: managed Composio configured for ${composio.toolkits.join(", ")}`);
+    for (const toolkit of composio.toolkits) {
+      console.log(`Connect:      npm run agentkit -- integrations connect composio --toolkit ${toolkit}`);
+    }
+  } else {
+    console.log("Integrations: none configured");
+  }
+
+  if (input.smokeMessage) {
+    console.log(`Smoke:        verified with ${JSON.stringify(input.smokeMessage)}`);
+  } else {
+    console.log('Smoke:        not run; next check: npm run agentkit -- deploy smoke --message "hello"');
+  }
+
+  if (input.chatAccess.status === "ready") {
+    console.log(`Chat token:   ${relativePath(process.cwd(), input.chatAccess.path)}`);
+  } else if (input.chatAccess.status === "skipped") {
+    console.log("Chat token:   not created for anonymous deploy");
+  } else {
+    console.log(`Chat token:   failed; run npm run agentkit -- access token create ${defaultDeployChatAccessTokenName} --out ${defaultDeployChatAccessTokenPath}`);
+  }
+
+  const nextCommand = composio?.enabled && composio.toolkits.length > 0
+    ? `npm run agentkit -- integrations connect composio --toolkit ${composio.toolkits[0]}`
+    : "npm run agentkit -- chat-ui --deploy";
+  console.log(`Next:         ${nextCommand}`);
+}
+
 async function ensureDeployChatAccessToken(options: {
   apiUrl: string;
   root: string;

package/src/index.ts

@@ -1,5 +1,5 @@
 export type AgentRuntime = "local" | "edge";
-export type AgentProviderName = "test" | "openai" | "anthropic" | "openrouter" | "custom";
+export type AgentProviderName = "test" | "openai" | "anthropic" | "openrouter" | "opencode" | "opencode-go" | "custom";
 export type AccessMode = "private" | "token" | "public";
 export type ToolVisibility = "user" | "internal";
 export type ChannelType = "website" | "telegram" | "whatsapp" | "discord" | "slack" | "webhook";