@andreprado/agentkit 0.1.0-alpha.10

package/src/templates/blank.ts

@@ -0,0 +1,394 @@
+import type { AgentTemplate } from ".";
+
+export const blankTemplate: AgentTemplate = {
+  name: "blank",
+  files(projectName: string, context = {}) {
+    const storageName = projectName.toLowerCase().replace(/_/g, "-");
+
+    return [
+      {
+        path: "package.json",
+        contents: `${JSON.stringify(
+          {
+            name: projectName,
+            private: true,
+            type: "module",
+            scripts: {
+              agentkit: "agentkit",
+              dev: "agentkit dev",
+              chat: "agentkit chat",
+              eval: "agentkit eval run",
+              typecheck: "tsc --noEmit",
+            },
+            dependencies: {
+              "@andreprado/agentkit": context.agentkitDependency ?? "workspace:*",
+            },
+            devDependencies: {
+              "@types/node": "^24.12.4",
+              typescript: "^5.9.3",
+            },
+          },
+          null,
+          2,
+        )}
+`,
+      },
+      {
+        path: "tsconfig.json",
+        contents: `${JSON.stringify(
+          {
+            compilerOptions: {
+              target: "ES2022",
+              module: "ESNext",
+              moduleResolution: "Bundler",
+              strict: true,
+              skipLibCheck: true,
+              noEmit: true,
+              types: ["node"],
+            },
+            include: ["**/*.ts"],
+          },
+          null,
+          2,
+        )}
+`,
+      },
+      {
+        path: ".gitignore",
+        contents: `.env
+.agentkit/
+node_modules/
+`,
+      },
+      {
+        path: ".env.schema",
+        contents: `# Optional: only needed after switching agentkit.config.ts to a Pi-backed real provider.
+OPENAI_API_KEY=
+ANTHROPIC_API_KEY=
+OPENROUTER_API_KEY=
+`,
+      },
+      {
+        path: "agentkit.config.ts",
+        contents: `import { defineAgent } from "@andreprado/agentkit";
+
+export default defineAgent({
+  name: "${projectName}",
+  runtime: "edge",
+  provider: {
+    name: "test",
+    model: "fake",
+  },
+  instructions: "./prompts/instructions.md",
+  secrets: [],
+  tools: [],
+  access: {
+    mode: "private",
+  },
+  storage: {
+    driver: "agentkit",
+    path: ".agentkit/agentkit.db",
+    database: {
+      driver: "turso",
+      schema: "./schema.sql",
+    },
+    files: {
+      driver: "r2",
+      bucket: "agentkit-${storageName}-files",
+      prefix: "${projectName}",
+    },
+  },
+});
+`,
+      },
+      {
+        path: "schema.sql",
+        contents: `CREATE TABLE IF NOT EXISTS agent_notes (
+  id TEXT PRIMARY KEY,
+  content TEXT NOT NULL,
+  created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+`,
+      },
+      {
+        path: "src/agent.ts",
+        contents: `export { default } from "../agentkit.config";
+`,
+      },
+      {
+        path: "prompts/instructions.md",
+        contents: `You are ${projectName}, a focused AI agent.
+
+Answer clearly, ask for missing context when needed, and do not claim to have performed actions you did not perform.
+`,
+      },
+      {
+        path: "evals/smoke.eval.ts",
+        contents: `export default {
+  name: "smoke",
+  input: "Say hello in one short sentence.",
+  expect: {
+    contains: "hello",
+  },
+};
+`,
+      },
+      {
+        path: "AGENTS.md",
+        contents: `# ${projectName}
+
+This is an AgentKit Agent Capsule.
+
+The capsule root is the runtime boundary. Run, inspect, evaluate, and deploy from this directory.
+
+## 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.
+
+Start building immediately:
+
+- Start with \`skills/agentkit-capsule/SKILL.md\`, then use \`npm run agentkit -- docs llms\` as the docs router.
+- Create or update \`AGENT_SPEC.md\` from the owner's request with \`npm run agentkit -- spec init --brief "<owner request>"\`; the owner should not fill this file by hand before work starts.
+- Infer the first useful version from the owner's request.
+- 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.
+- 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.
+
+## Local Commands
+
+- \`npm install\`: restore capsule dependencies if this capsule used \`--no-install\`, install failed, or \`node_modules\` was deleted.
+- \`npm run dev\`: run the local Agent Capsule runtime.
+- \`npm run chat -- --message "hello"\`: send one local chat message.
+- \`npm run eval\`: run agent evals.
+- \`npm run agentkit -- spec check\`: verify the local agent implementation contract exists.
+- \`npm run agentkit -- eval from-conversation <conversation-id>\`: turn a real conversation into a regression eval.
+- \`npm run agentkit -- conversations trace <conversation-id>\`: inspect messages, runs, tool calls, inputs, outputs, rendered output, and final responses.
+- \`npm run agentkit -- tool <name> --input fixtures/input.json\`: run one registered tool directly.
+- \`npm run agentkit -- db migrate\`: apply internal migrations and \`schema.sql\` locally.
+- \`npm run agentkit -- db reset --yes\`: recreate the local SQLite database and reapply schema.
+- \`npm run agentkit -- db seed --file seed.sql\`: apply local fixture data after migrate.
+- \`npm run agentkit -- db shell\`: inspect local development data when needed.
+- \`npm run agentkit -- inspect\`: print machine-readable capsule state.
+- \`printf %s "$VALUE" | npm run agentkit -- env set <NAME> --stdin\`: write a local secret value to ignored \`.env\` without putting it in shell history.
+- \`npm run agentkit -- env list\`: list local secret names without printing values.
+- \`npm run agentkit -- docs llms\`: print the lightweight AgentKit docs router.
+- \`npm run agentkit -- docs full\`: print the full AgentKit contract path only when a skill asks for it.
+
+## Testing With A UI
+
+- 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.
+
+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\`.
+
+## Local Runtime Contract
+
+\`agentkit dev\`, \`agentkit chat\`, and \`agentkit tool\` use AgentKit-managed local development storage. If the capsule has \`schema.sql\`, AgentKit applies it before tools run. Hosted deploy migrates/provisions the managed backend internally.
+
+- Chat: \`http://localhost:4123\`
+- API: \`http://localhost:4123/v1/chat\`
+- Inspect: \`http://localhost:4123/_agentkit\`
+- Storage: \`.agentkit/agentkit.db\`
+
+## Database Tools
+
+Tools should use the runtime database helper from the tool context:
+
+\`\`\`ts
+export const myTool = defineTool({
+  name: "my_tool",
+  description: "Writes to the agent database.",
+  inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  async execute(_input, ctx) {
+    await ctx.db.execute("INSERT INTO agent_notes (id, content) VALUES (?, ?)", [
+      crypto.randomUUID(),
+      "created by the AgentKit managed database runtime",
+    ]);
+    return { ok: true };
+  },
+});
+\`\`\`
+
+Use \`ctx.db\` as the canonical helper. \`ctx.database\` and \`ctx.storage.sql\` are aliases. Use \`ctx.db.batch([...])\` for atomic writes; local tools can also use \`ctx.db.transaction(async (tx) => ...)\`. Do not import local database drivers or Node-only APIs in tools. AgentKit owns local and hosted database routing.
+
+\`schema.sql\` is an idempotent bootstrap file. Use \`CREATE TABLE IF NOT EXISTS\`, \`CREATE INDEX IF NOT EXISTS\`, and safe additive changes. Use ordered \`migrations/*.sql\` for production-shaped schema evolution; \`npm run agentkit -- db migrate\` applies unapplied local migrations before \`schema.sql\`.
+
+## Hosted Deploy
+
+- \`npm run agentkit -- deploy\`: deploy the capsule.
+- AgentKit owns the hosted runtime, managed database, file storage, and production secret injection.
+- Local scaffold, dev, chat, eval, inspect, database, and build commands are token-free.
+- Hosted deploy requires an invited AgentKit Cloud alpha token. If no token is stored yet, ask the owner for one and run \`npm run agentkit -- login --token <token>\`.
+- Put production secret values into managed secrets with \`npm run agentkit -- secret set <NAME> --from-local-env\`, \`--from-env\`, or \`--stdin\`, not into committed files or shell history.
+- The user should not choose a deploy target, create hosted databases, create buckets, copy production secrets into this capsule, or run operator/admin commands.
+- Hosted deploy writes the local chat/UI deploy access token to \`.agentkit/chat-access-token.json\`. Create extra client-facing tokens with \`npm run agentkit -- access token create <name> --out <path>\`.
+- Use \`npm run agentkit -- deploy --smoke "hello"\` or \`npm run agentkit -- deploy smoke --message "hello"\` for an official hosted chat smoke check.
+
+## Rules
+
+- Keep required local secret names in \`.env.schema\` and values in ignored \`.env\`. AgentKit local commands load \`.env\` directly.
+- Real providers are resolved by AgentKit through the internal Pi SDK backend; keep project code on \`@andreprado/agentkit\`.
+- The owner must choose the real provider before you switch from \`test/fake\`. Update \`agentkit.config.ts\`, \`.env.schema\`, and local/hosted secrets after that choice.
+- Do not commit \`.env\` or \`.agentkit/\`.
+- Edit the agent contract in \`agentkit.config.ts\`.
+- Edit instructions in \`prompts/instructions.md\`.
+`,
+      },
+      {
+        path: "AGENTKIT.md",
+        contents: `# AgentKit Docs
+
+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.
+
+Example owner request:
+
+> Develop an appointment and intake agent for an ophthalmology office.
+
+Turn the request into a working local capsule:
+
+- Update \`prompts/instructions.md\` with domain-specific behavior, boundaries, intake questions, and escalation rules.
+- 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.
+- Use \`npm run agentkit -- sync init\` when the agent needs catalog sync, fixture seed data, or ordered migrations.
+- 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.
+- Ask follow-up questions only when missing information blocks a safe local implementation.
+
+## Local Commands
+
+\`\`\`sh
+npm run typecheck
+npm run agentkit -- inspect
+npm run chat -- --message "hello"
+\`\`\`
+
+\`test/fake\` proves the scaffold and deterministic tool paths. It does not prove natural conversation quality.
+
+\`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:
+
+\`\`\`sh
+printf %s "$OPENAI_API_KEY" | npm run agentkit -- env set OPENAI_API_KEY --stdin
+npm run agentkit -- inspect
+npm run chat -- --message "hello"
+\`\`\`
+
+## Testing With A UI
+
+Local UI:
+
+\`\`\`sh
+npm run dev
+\`\`\`
+
+Open the printed \`Chat:\` URL and tell the owner the exact URL.
+
+Hosted deploy UI:
+
+\`\`\`sh
+npm run agentkit -- deploy
+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.
+
+If you add a tool, also run a fake-provider tool smoke test:
+
+\`\`\`sh
+npm run agentkit -- tool tool_name --input '{}'
+\`\`\`
+
+For the lightweight docs router, read the path printed by:
+
+\`\`\`sh
+npm run agentkit -- docs llms
+\`\`\`
+
+Read the full framework contract with \`npm run agentkit -- docs full\` only when a skill asks for it.
+
+## Hosted Deploy
+
+This capsule is hosted-deploy ready by default.
+
+1. Keep \`runtime: "edge"\` and \`storage.driver: "agentkit"\`.
+2. Put agent-owned tables in \`schema.sql\`. AgentKit applies it locally and migrates/provisions hosted storage during deploy.
+3. Run \`npm run agentkit -- build\` only when you want to validate the artifact locally.
+4. If the owner has not logged in yet, ask for an invited AgentKit Cloud alpha token and run \`npm run agentkit -- login --token <token>\`.
+5. Put production secrets into managed secrets with \`npm run agentkit -- secret set <NAME> --from-local-env\`, \`--from-env\`, or \`--stdin\`.
+6. Run \`npm run agentkit -- deploy\`.
+7. Run \`npm run agentkit -- chat-ui --deploy\` to test the hosted agent through a local UI using the auto-created \`.agentkit/chat-access-token.json\`. Create extra client-facing deploy access tokens with \`npm run agentkit -- access token create <name> --out <path>\` when a separate website or app needs its own credential.
+8. Use \`npm run agentkit -- deploy --smoke "hello"\` during deploy or \`npm run agentkit -- deploy smoke --message "hello"\` afterward for an official hosted smoke check.
+
+AgentKit owns hosted infrastructure and production secrets. Do not put production secret values in this capsule. Do not run operator/admin commands from a user capsule.
+`,
+      },
+      {
+        path: "CLAUDE.md",
+        contents: `# ${projectName}
+
+Use AgentKit conventions when editing this project.
+
+- This folder is an Agent Capsule.
+- The agent contract lives in \`agentkit.config.ts\`.
+- The primary prompt lives in \`prompts/instructions.md\`.
+- 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.
+- 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.
+- Start with \`skills/agentkit-capsule/SKILL.md\` when the task is not obvious.
+`,
+      },
+      {
+        path: "README.md",
+        contents: `# ${projectName}
+
+Generated by AgentKit as an Agent Capsule.
+
+## Setup
+
+\`\`\`sh
+npm run chat -- --message "hello"
+npm run dev
+\`\`\`
+
+\`agentkit new\` installs dependencies by default. Run \`npm install\` only if this capsule was created with \`--no-install\`, install failed, or \`node_modules\` was deleted.
+
+\`agentkit.config.ts\` uses the built-in \`test/fake\` provider by default, so the first chat works without editing \`.env\`.
+When a real provider or tool needs a local development secret, keep the required name in \`.env.schema\`, keep the value in ignored \`.env\`, and run AgentKit commands normally; the local runtime loads \`.env\` directly.
+
+\`npm run dev\` runs the whole capsule locally. It should expose local chat, API, inspect, and storage endpoints.
+
+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.
+
+## Files
+
+- \`agentkit.config.ts\`: agent contract.
+- \`schema.sql\`: source of truth for agent-owned tables. Applied locally during development and migrated/provisioned internally during hosted deploys.
+- \`prompts/instructions.md\`: agent instructions.
+- \`evals/\`: eval cases.
+- \`.agentkit/\`: local runtime state.
+`,
+      },
+    ];
+  },
+};