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

package/src/cli/index.ts

@@ -57,6 +57,8 @@ import {
 } from "./cloud-client";
 import {
   checkDeployReadiness,
+  formatDeployCloudAuthSummary,
+  formatDeployOnlineCapacity,
   formatReadinessError,
   printDeployReadinessReport,
   resolveProjectIdForSecretCommand,
@@ -109,6 +111,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 +140,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 +191,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 +949,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.",
@@ -989,6 +1004,7 @@ async function main() {
     console.log(`Project:   ${deploy.project.id}`);
     console.log(`Deploy:    ${deploy.deploy.id}`);
     console.log(`State:     ${statePath}`);
+    printDeployCloudSummary(readinessReport);
 
     if (chatAccess?.status === "ready") {
       console.log(`Chat auth: ${relativePath(process.cwd(), chatAccess.path)}`);
@@ -1016,6 +1032,14 @@ async function main() {
             : undefined,
       });
     }
+    printDeployProductionHandoff({
+      deployUrl: deploy.deploy.url,
+      statePath,
+      chatAccess,
+      databaseSchemaPath: result.tursoSchemaPath,
+      readinessReport,
+      smokeMessage,
+    });
     return;
   }
 
@@ -1362,7 +1386,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 +1426,103 @@ 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}`);
+}
+
+function printDeployCloudSummary(report: Awaited<ReturnType<typeof checkDeployReadiness>> | null): void {
+  if (!report) {
+    return;
+  }
+
+  const authSummary = formatDeployCloudAuthSummary(report);
+
+  if (authSummary) {
+    console.log(`Account:   ${authSummary.account}`);
+    console.log(`Auth:      ${authSummary.source}`);
+  }
+
+  const capacitySummary = formatDeployOnlineCapacity(report, "before deploy");
+
+  if (capacitySummary) {
+    console.log(`Capacity:  ${capacitySummary}`);
+  }
+}
+
 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";

package/src/providers/pi.ts

@@ -17,7 +17,7 @@ import type { AgentProviderName, AgentTool } from "../index";
 import { AgentKitError } from "../runtime/errors";
 import type { ProviderAdapter, ProviderRunInput, ProviderRunResult } from "./types";
 
-const PI_PROVIDER_NAMES = ["openai", "anthropic", "openrouter"] as const satisfies AgentProviderName[];
+const PI_PROVIDER_NAMES = ["openai", "anthropic", "openrouter", "opencode", "opencode-go"] as const satisfies AgentProviderName[];
 const MAX_TOOL_TURNS = 8;
 const OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1";
 const UNKNOWN_OPENROUTER_CONTEXT_WINDOW = 128000;
@@ -159,7 +159,13 @@ async function runPiTurn(
 }
 
 function toPiProvider(provider: string): Provider {
-  if (provider === "openai" || provider === "anthropic" || provider === "openrouter") {
+  if (
+    provider === "openai" ||
+    provider === "anthropic" ||
+    provider === "openrouter" ||
+    provider === "opencode" ||
+    provider === "opencode-go"
+  ) {
     return provider;
   }
 
@@ -181,6 +187,10 @@ function requireProviderApiKey(provider: Provider, env: Record<string, string |
 }
 
 function defaultProviderSecretNames(provider: Provider): string[] {
+  if (provider === "opencode" || provider === "opencode-go") {
+    return ["OPENCODE_API_KEY"];
+  }
+
   return [`${provider.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}_API_KEY`];
 }
 

package/src/runtime/chat.ts

@@ -20,6 +20,7 @@ export type RunAgentMessageOptions = {
   signal?: AbortSignal;
   runtime?: Partial<ToolRuntimeContext>;
   now?: Date;
+  localStoragePath?: string;
 };
 
 export type AgentRunResult = ProviderRunResult & PersistedChatRun;
@@ -28,7 +29,8 @@ export async function runAgentMessageFromCwd(
   cwd: string,
   options: RunAgentMessageOptions,
 ): Promise<AgentRunResult> {
-  return runAgentMessage(await loadAgentCapsule(cwd), options);
+  const capsule = await loadAgentCapsule(cwd);
+  return runAgentMessage(withLocalStoragePath(capsule, options.localStoragePath), options);
 }
 
 export async function runAgentMessage(
@@ -208,6 +210,10 @@ function normalizeConversationId(value: string | undefined): string | undefined
   return conversationId;
 }
 
+function withLocalStoragePath(capsule: LoadedAgentCapsule, storagePath?: string): LoadedAgentCapsule {
+  return storagePath ? { ...capsule, storagePath } : capsule;
+}
+
 function withToolVisibilityInstructions(instructions: string, tools: LoadedAgentCapsule["config"]["tools"] = []): string {
   const internalTools = tools.filter((tool) => tool.visibility === "internal").map((tool) => tool.name).sort();
 

package/src/runtime/config.ts

@@ -27,7 +27,7 @@ import { isValidTimeZone } from "./prompt-context";
 
 const CONFIG_FILE = "agentkit.config.ts";
 const AGENT_RUNTIMES = new Set<AgentRuntime>(["local", "edge"]);
-const PROVIDERS = new Set<AgentProviderName>(["test", "openai", "anthropic", "openrouter", "custom"]);
+const PROVIDERS = new Set<AgentProviderName>(["test", "openai", "anthropic", "openrouter", "opencode", "opencode-go", "custom"]);
 const ACCESS_MODES = new Set<AccessMode>(["private", "token", "public"]);
 const TOOL_VISIBILITIES = new Set<ToolVisibility>(["user", "internal"]);
 const CHANNEL_TYPES = new Set<ChannelType>(["website", "telegram", "whatsapp", "discord", "slack", "webhook"]);

package/src/runtime/evals.ts

@@ -1,5 +1,6 @@
-import { mkdir, readdir, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, readdir, rm, writeFile } from "node:fs/promises";
 import type { Dirent } from "node:fs";
+import { tmpdir } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 
@@ -243,35 +244,49 @@ async function runEvalCase(
   const failures: string[] = [];
   let output = "";
   const now = resolveEvalNow(file, evalCase.now);
+  const evalStore = await createEvalStore();
 
-  for (const [index, turn] of turns.entries()) {
-    try {
-      const run = await runAgentMessageFromCwd(root, {
-        message: turn.input,
-        conversationId,
-        now,
-        runtime: {
-          environment: "eval",
-          invocation: "eval",
-        },
-      });
-      const persistedToolCalls = await loadPersistedToolCalls(root, run.runId);
-      const turnFailures = evaluateExpectations(turn.expect ?? {}, run, persistedToolCalls);
-
-      for (const failure of turnFailures) {
-        failures.push(turns.length === 1 ? failure : `turn ${index + 1}: ${failure}`);
+  try {
+    for (const [index, turn] of turns.entries()) {
+      try {
+        const run = await runAgentMessageFromCwd(root, {
+          message: turn.input,
+          conversationId,
+          now,
+          localStoragePath: evalStore.databasePath,
+          runtime: {
+            environment: "eval",
+            invocation: "eval",
+          },
+        });
+        const persistedToolCalls = await loadPersistedToolCalls(root, run.runId, evalStore.databasePath);
+        const turnFailures = evaluateExpectations(turn.expect ?? {}, run, persistedToolCalls);
+
+        for (const failure of turnFailures) {
+          failures.push(turns.length === 1 ? failure : `turn ${index + 1}: ${failure}`);
+        }
+
+        output = run.message.content;
+      } catch (error) {
+        failures.push(turns.length === 1 ? formatEvalFailure(error) : `turn ${index + 1}: ${formatEvalFailure(error)}`);
+        break;
       }
-
-      output = run.message.content;
-    } catch (error) {
-      failures.push(turns.length === 1 ? formatEvalFailure(error) : `turn ${index + 1}: ${formatEvalFailure(error)}`);
-      break;
     }
+  } finally {
+    await rm(evalStore.directory, { recursive: true, force: true });
   }
 
   return { failures, output };
 }
 
+async function createEvalStore(): Promise<{ directory: string; databasePath: string }> {
+  const directory = await mkdtemp(join(tmpdir(), "agentkit-eval-"));
+  return {
+    directory,
+    databasePath: join(directory, "agentkit.db"),
+  };
+}
+
 function resolveEvalNow(file: string, value: EvalCase["now"]): Date | undefined {
   if (value === undefined) {
     return undefined;
@@ -382,9 +397,9 @@ async function loadEvalCase(file: string): Promise<EvalCase> {
   return module.default;
 }
 
-async function loadPersistedToolCalls(root: string, runId: string): Promise<ToolCallSnapshot[]> {
+async function loadPersistedToolCalls(root: string, runId: string, localStoragePath?: string): Promise<ToolCallSnapshot[]> {
   const capsule = await loadAgentCapsule(root);
-  const store = await openCapsuleStore(capsule);
+  const store = await openCapsuleStore(localStoragePath ? { ...capsule, storagePath: localStoragePath } : capsule);
 
   try {
     return store.listToolCallsForRun(runId).map(toolCallSnapshotFromStored);

package/src/templates/blank.ts

@@ -66,6 +66,7 @@ node_modules/
 OPENAI_API_KEY=
 ANTHROPIC_API_KEY=
 OPENROUTER_API_KEY=
+OPENCODE_API_KEY=
 `,
       },
       {
@@ -148,7 +149,7 @@ The capsule root is the runtime boundary. Run, inspect, evaluate, and deploy fro
 
 ## Coding Agent Workflow
 
-When the owner opens this folder in Codex, Claude Code, or another coding agent and asks for a specific agent, treat that request as the product brief.
+When the owner opens this folder in Codex, Claude Code, or another coding agent and asks for a specific agent, treat that request as the product brief. The owner should not need to run a separate AgentKit wizard or prepare a brief file.
 
 Start building immediately:
 
@@ -158,11 +159,26 @@ Start building immediately:
 - Edit \`prompts/instructions.md\` for the agent behavior.
 - Edit \`agentkit.config.ts\` for provider, tools, secrets, access, and storage.
 - Add TypeScript tools under \`tools/\` when the requested agent needs actions or external data.
+- When the agent needs to save durable records, complete the full slice: schema/migration, tool, config registration, prompt instructions, direct tool check, and eval.
 - Add \`sync.ts\`, \`seed.sql\`, and ordered \`migrations/*.sql\` when the requested agent depends on external catalogs or production-shaped data changes.
 - Do not wait for a wizard or recipe. AgentKit provides the scaffold and contract; you decide the implementation from the owner's brief.
 - Ask follow-up questions only when missing information blocks a safe local implementation.
 - State assumptions in the final response.
 
+## Proactive Agent Builder Contract
+
+Do not only edit prompts. For every meaningful requirement in the owner's request or \`AGENT_SPEC.md\`, decide what should enforce it:
+
+- spec entry for the product contract;
+- prompt instruction for behavior, tone, boundaries, intake, and escalation;
+- tool plus config registration for actions, live data, external writes, or authorization-sensitive data;
+- schema/migration plus tool for durable records;
+- eval for privacy, confirmation, required fields, date/time behavior, business rules, and regressions;
+- fixture, seed data, fake branch, or direct tool check for integrations and failure paths;
+- deploy/readiness check for hosted secrets, channels, integrations, or production access.
+
+If a rule protects privacy, money, bookings, external writes, customer data, business hours, or safety, it must have an eval or deterministic check before you call the capsule done. If a real conversation exposes a bug, convert it into the smallest regression eval before or alongside the fix.
+
 ## Local Commands
 
 - \`npm install\`: restore capsule dependencies if this capsule used \`--no-install\`, install failed, or \`node_modules\` was deleted.
@@ -188,7 +204,7 @@ Start building immediately:
 - Local UI: run \`npm run dev\`, open the printed \`Chat:\` URL, and tell the owner the exact URL.
 - Hosted UI: after \`npm run agentkit -- deploy\`, run \`npm run agentkit -- chat-ui --deploy\`, open the printed \`Chat:\` URL, and tell the owner it is connected to the hosted deploy.
 - \`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 is tested, ask the owner which provider to use: OpenRouter, OpenAI, Anthropic, or another supported provider. Do not choose for them.
+- 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. Do not choose for them.
 
 This blank capsule starts with the built-in \`test/fake\` provider, so local chat works without secrets or internet access. It is also deploy-ready by default: the user can edit the prompt, add tools, and run \`npm run agentkit -- deploy\`.
 
@@ -253,7 +269,9 @@ This folder is an AgentKit Agent Capsule.
 
 ## Start Here
 
-If the owner asks you to build an agent in natural language, that request is the brief. Do not ask them to fill another file first.
+If the owner asks you to build an agent in natural language, that request is the brief. Do not ask them to run a wizard or fill another file first.
+
+Build a testable capsule, not only a prompt.
 
 Example owner request:
 
@@ -265,7 +283,10 @@ Turn the request into a working local capsule:
 - Create or update \`AGENT_SPEC.md\` with \`npm run agentkit -- spec init --brief "<owner request>"\`. The owner gives the general idea; the coding agent turns it into the structured contract.
 - Update \`agentkit.config.ts\` when tools, secrets, provider, or access rules change.
 - Add TypeScript tools under \`tools/\` for real actions or external data.
+- For durable records, implement the full schema/tool/prompt/eval slice instead of only adding a table or only adding a tool.
 - Use \`npm run agentkit -- sync init\` when the agent needs catalog sync, fixture seed data, or ordered migrations.
+- For every privacy, confirmation, required-intake, timezone, business-hour, integration-error, or no-leak rule, add an eval, fixture, fake branch, or direct tool check.
+- Convert failed or surprising real conversations into regression evals with \`npm run agentkit -- eval from-conversation <conversation-id>\`.
 - Keep the first version runnable with \`test/fake\` unless the owner explicitly asks for a real provider.
 - Do not use a wizard or recipe. Build the capsule directly from the scaffold, the AgentKit contract, and the owner's brief.
 - Make practical assumptions and list them in your final response.
@@ -281,6 +302,8 @@ npm run chat -- --message "hello"
 
 \`test/fake\` proves the scaffold and deterministic tool paths. It does not prove natural conversation quality.
 
+Before saying the agent is done, make sure important requirements have matching checks. Prompt-only changes are not enough for privacy, external writes, bookings, customer data, business hours, or integration failures.
+
 \`agentkit new\` installs dependencies by default. Run \`npm install\` only if the capsule was created with \`--no-install\`, install failed, or \`node_modules\` was deleted.
 
 Set local development secrets without opening code:
@@ -310,7 +333,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.
 
-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 they choose, 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 they choose, update \`agentkit.config.ts\`, \`.env.schema\`, local secrets, hosted secrets if deploying, then rerun chat/UI checks.
 
 If you add a tool, also run a fake-provider tool smoke test:
 
@@ -354,7 +377,7 @@ Use AgentKit conventions when editing this project.
 - Local runtime state lives in \`.agentkit/\` and should not be committed.
 - The default provider is \`test/fake\`, which needs no secrets.
 - Real providers run through AgentKit's internal Pi SDK backend.
-- Ask the owner which real provider to use before switching from \`test/fake\`; do not choose OpenRouter, OpenAI, or Anthropic automatically.
+- Ask the owner which real provider to use before switching from \`test/fake\`; do not choose OpenRouter, OpenAI, Anthropic, OpenCode Zen, or OpenCode Go automatically.
 - Production secrets must be managed secrets, not committed files.
 - Keep required local secret names in \`.env.schema\` and values in ignored \`.env\`. AgentKit local commands load \`.env\` directly.
 - Treat the owner's natural-language request as the brief and start implementing inside this capsule.
@@ -383,7 +406,7 @@ When a real provider or tool needs a local development secret, keep the required
 
 For UI testing, run \`npm run dev\` and open the printed \`Chat:\` URL. After hosted deploy, run \`npm run agentkit -- chat-ui --deploy\` and open its printed \`Chat:\` URL.
 
-\`test/fake\` does not validate real conversation quality. The owner must choose OpenRouter, OpenAI, Anthropic, or another supported provider before real model behavior is tested.
+\`test/fake\` does not validate real conversation quality. The owner must choose OpenRouter, OpenAI, Anthropic, OpenCode Zen, OpenCode Go, or another supported provider before real model behavior is tested.
 
 ## Files
 

package/src/templates/dentista.ts

@@ -64,6 +64,7 @@ node_modules/
 OPENAI_API_KEY=
 ANTHROPIC_API_KEY=
 OPENROUTER_API_KEY=
+OPENCODE_API_KEY=
 `,
       },
       {
@@ -865,7 +866,21 @@ Esta é uma AgentKit Agent Capsule para a Clara, atendente em português de um c
 
 A Clara conversa com clientes, coleta nome, email e telefone, consulta disponibilidade e agenda consultas em slots de 30 minutos. Ela também consulta e altera o próprio horário do cliente usando email e telefone como verificação mínima.
 
-Quando o dono pedir mudanças em linguagem natural, crie ou atualize \`AGENT_SPEC.md\` com \`npm run agentkit -- spec init --brief "<pedido do dono>"\`. O dono dá a ideia geral; o agente de código transforma isso no contrato estruturado.
+Quando o dono pedir mudanças em linguagem natural, trate a mensagem como o brief. O dono não deve precisar rodar wizard ou preparar arquivo de brief. Crie ou atualize \`AGENT_SPEC.md\` com \`npm run agentkit -- spec init --brief "<pedido do dono>"\`; o agente de código transforma a ideia geral no contrato estruturado.
+
+## Contrato Proativo De Produto Testável
+
+Não edite apenas o prompt. Para cada requisito relevante do pedido ou do \`AGENT_SPEC.md\`, decida qual artefato deve garantir o comportamento:
+
+- entrada no spec para o contrato de produto;
+- instrução no prompt para comportamento, tom, limites, coleta de dados e escalonamento;
+- ferramenta mais registro no config para ações, dados vivos, escritas externas ou dados sensíveis;
+- schema/migration mais ferramenta para dados duráveis;
+- eval para privacidade, confirmação, campos obrigatórios, horário comercial, datas, duração e regressões;
+- fixture, seed, branch fake ou teste direto de ferramenta para integrações e caminhos de erro;
+- checagem de deploy/readiness para secrets hosted, canais, integrações ou acesso de produção.
+
+Regras que protegem privacidade, agendamento, confirmação, dados de cliente, horário comercial ou segurança precisam de eval ou checagem determinística antes de dizer que a cápsula está pronta. Se uma conversa real revelar bug, transforme em uma eval de regressão pequena antes ou junto da correção.
 
 ## Regras de Produto
 
@@ -908,16 +923,19 @@ Quando o dono pedir mudanças em linguagem natural, crie ou atualize \`AGENT_SPE
 - UI local: rode \`npm run dev\`, abra a URL impressa em \`Chat:\` e informe essa URL exata ao dono.
 - UI pós-deploy: depois de \`npm run agentkit -- deploy\`, rode \`npm run agentkit -- chat-ui --deploy\`, abra a URL impressa em \`Chat:\` e informe que ela está conectada ao deploy hospedado.
 - \`test/fake\` é determinístico. Ele valida scaffold, ferramentas e evals previsíveis, mas não valida qualidade de conversa natural.
-- Antes de dizer que a conversa real foi testada, pergunte ao dono qual provider usar: OpenRouter, OpenAI, Anthropic ou outro provider suportado. Não escolha pelo dono.
+- Antes de dizer que a conversa real foi testada, pergunte ao dono qual provider usar: OpenRouter, OpenAI, Anthropic, OpenCode Zen, OpenCode Go ou outro provider suportado. Não escolha pelo dono.
 
 ## Regras de Implementação
 
 - Use \`ctx.db\` nas ferramentas. Não importe drivers SQLite, Turso ou Node-only APIs.
 - Mantenha \`schema.sql\` idempotente com \`CREATE TABLE IF NOT EXISTS\` e \`CREATE INDEX IF NOT EXISTS\`. Use \`migrations/*.sql\` ordenadas para evolução de schema com cara de produção.
+- Quando a mudança exigir persistência nova, implemente a fatia completa: schema/migration, ferramenta, registro no config, instruções no prompt, teste direto da ferramenta e eval.
 - Use \`npm run agentkit -- sync init\` quando a agente depender de catálogo externo, fixture local ou seed padronizado.
+- Para regras de privacidade, confirmação, campos obrigatórios, timezone, horário comercial, duração, erro de integração ou no-leak, adicione uma eval, fixture, branch fake ou teste direto de ferramenta.
+- Transforme conversas reais com falhas em regressão com \`npm run agentkit -- eval from-conversation <conversation-id>\`.
 - Mantenha segredos em \`.env\`, nunca em arquivos versionados.
 - Não espere wizard ou recipe. AgentKit fornece o scaffold e o contrato; implemente diretamente conforme o brief do dono.
-- Para trocar para um provider real, o dono deve escolher OpenRouter, OpenAI, Anthropic ou outro provider suportado. Depois edite \`agentkit.config.ts\`, atualize \`.env.schema\` e configure secrets locais/hosted.
+- Para trocar para um provider real, o dono deve escolher OpenRouter, OpenAI, Anthropic, OpenCode Zen, OpenCode Go ou outro provider suportado. Depois edite \`agentkit.config.ts\`, atualize \`.env.schema\` e configure secrets locais/hosted.
 - Quando a próxima ação não for óbvia, comece por \`skills/agentkit-capsule/SKILL.md\`.
 `,
       },
@@ -995,7 +1013,7 @@ npm run agentkit -- chat-ui --deploy
 
 Abra a URL impressa em \`Chat:\` e informe que essa UI local está conectada ao deploy hospedado.
 
-Antes de dizer que a conversa real foi testada, pergunte ao dono qual provider usar: OpenRouter, OpenAI, Anthropic ou outro provider suportado. Não escolha pelo dono. Depois configure \`agentkit.config.ts\`, \`.env.schema\`, secrets locais e secrets hosted se for deployar.
+Antes de dizer que a conversa real foi testada, pergunte ao dono qual provider usar: OpenRouter, OpenAI, Anthropic, OpenCode Zen, OpenCode Go ou outro provider suportado. Não escolha pelo dono. Depois configure \`agentkit.config.ts\`, \`.env.schema\`, secrets locais e secrets hosted se for deployar.
 
 ## Deploy
 

package/src/templates/skills/agentkit-build-agent/SKILL.md

@@ -7,6 +7,8 @@ description: Use when the owner gives a natural-language brief for a new or chan
 
 Use this when the owner asks for an agent in plain language.
 
+The owner should only need to run `agentkit new <name>`, open the capsule in Codex or another coding agent, and say what agent they want. Do not send them back to the CLI for a brief wizard. Treat their chat message as the brief and build the first useful local capsule.
+
 ## Workflow
 
 1. Read `agentkit.config.ts`, `prompts/instructions.md`, `schema.sql`, `evals/`, and existing `tools/`.
@@ -17,8 +19,34 @@ Use this when the owner asks for an agent in plain language.
 6. Add tools only when the agent needs action, live data, authorization-sensitive data, or durable writes.
 7. Add database tables to `schema.sql` or ordered `migrations/*.sql` when the agent owns records.
 8. Add `sync.ts` and `seed.sql` with `npm run agentkit -- sync init` when the agent depends on external catalogs or recurring imports.
-9. Add or update evals for the main flow. Prefer multi-turn `turns` evals for real conversations.
-10. Keep the capsule runnable on `test/fake` unless the owner has chosen a real provider.
+9. Turn requirements into checks as you build. Every privacy rule, external write, confirmation step, business-hour rule, timezone rule, required intake field, and customer-data boundary needs an eval, direct tool check, fixture, or deterministic fake path.
+10. Add or update evals for the main flow. Prefer multi-turn `turns` evals for real conversations.
+11. Keep the capsule runnable on `test/fake` unless the owner has chosen a real provider.
+
+## Requirement-To-Verification Loop
+
+For each item in the brief or `AGENT_SPEC.md`, classify it before finishing:
+
+- prompt-only behavior: add a prompt instruction and a response eval when the wording or boundary matters;
+- required intake such as name, phone, email, budget, or account id: add a multi-turn eval that proves the agent asks before acting;
+- tool call or external write: add a persisted tool-call eval and a direct `agentkit tool` check;
+- database record: implement the complete slice in the next section;
+- scheduling, deadlines, or timezone: set `timeZone`, freeze eval `now`, and assert the date/time sent to tools;
+- privacy/no-leak rule: add a no-leak eval with `notContains` or `notRegex`;
+- integration failure such as rate limit, timeout, unavailable slot, or missing auth: add a fixture, fake branch, or eval-safe tool behavior.
+
+If a requirement is important enough to mention in the spec, it is usually important enough to test. State any untested requirement in the final response.
+
+## Complete Slice
+
+When the brief implies durable records such as leads, clients, bookings, tickets, or notes, do the whole local slice:
+
+- add or update `schema.sql` and ordered `migrations/*.sql` when appropriate;
+- add the `defineTool` implementation under `tools/`;
+- register the tool in `agentkit.config.ts`;
+- teach `prompts/instructions.md` when and how to use the tool;
+- add a direct tool check fixture or command;
+- add an eval that proves the agent calls the tool in the expected flow.
 
 ## Templates
 

package/src/templates/skills/agentkit-capsule/SKILL.md

@@ -7,6 +7,27 @@ description: Use when working inside an AgentKit Agent Capsule, especially after
 
 Use this first inside an AgentKit Agent Capsule.
 
+## Owner-To-Codex Contract
+
+The owner has already done the setup work by running `agentkit new <name>` and opening this folder in a coding agent. When they ask for an agent in natural language, that message is the brief.
+
+- Do not ask the owner to run a wizard, fill a form, or prepare `AGENT_SPEC.md`.
+- Route immediately to `skills/agentkit-build-agent/SKILL.md`.
+- You create or update `AGENT_SPEC.md`, prompts, tools, schema, evals, and docs as needed.
+- Use the CLI for validation and deployment, not for business inference.
+
+## Proactive Builder Contract
+
+Do not stop at "the prompt was edited." For every meaningful requirement in the owner's brief or `AGENT_SPEC.md`, decide which artifact must enforce it:
+
+- behavior or tone: `prompts/instructions.md`;
+- action, live data, or external write: `tools/` plus `agentkit.config.ts`;
+- durable records: schema/migration, tool, config registration, prompt guidance, direct tool check, and eval;
+- privacy, confirmation, business hours, dates, money, safety, or client data: at least one eval or deterministic check;
+- production or integration dependency: deploy/readiness check and safe fixture or fake path.
+
+If a real conversation reveals a bug or risky behavior, convert it into a regression eval before or alongside the fix.
+
 ## Start
 
 1. Treat the directory containing `agentkit.config.ts` as the capsule root.

package/src/templates/skills/agentkit-database/SKILL.md

@@ -7,6 +7,17 @@ description: Use when adding AgentKit-managed database tables, editing schema.sq
 
 Use this when a capsule owns durable application records.
 
+## Complete Database Tool Slice
+
+When the owner asks the agent to save or update records, do not stop after adding a table. Ship the whole slice:
+
+1. Add or update `schema.sql`; for production-shaped evolution, add an ordered `migrations/*.sql` file too.
+2. Add a `defineTool` under `tools/` that uses `ctx.db`.
+3. Register the tool in `agentkit.config.ts`.
+4. Update `prompts/instructions.md` so the agent knows when to collect fields, confirm writes, and call the tool.
+5. Add or update an eval for the user flow that should persist the record.
+6. Run `db migrate`, a direct tool check, `typecheck`, and `eval`.
+
 ## Rules
 
 - Put the first idempotent bootstrap schema in `schema.sql`.