@andreprado/agentkit 0.1.0-alpha.2 → 0.1.0-alpha.20

package/src/storage/sqlite.ts

@@ -6,6 +6,7 @@ import type { DatabaseArgs, DatabaseResult, DatabaseRow, DatabaseStatement } fro
 import type { AgentMessageRole, ProviderRunResult } from "../providers";
 import type { LoadedAgentCapsule } from "../runtime/config";
 import { AgentKitError } from "../runtime/errors";
+import { applyKnowledgeSchema, KNOWLEDGE_MIGRATION_ID, KNOWLEDGE_SCHEMA_SQL } from "../runtime/knowledge/schema";
 
 export type ConversationSummary = {
   id: string;
@@ -41,12 +42,30 @@ export type StoredToolCall = {
   visibility: ToolCallVisibility;
   input: unknown;
   output: unknown;
+  rendered: unknown;
   status: ToolCallStatus;
   startedAt: string;
   completedAt: string | null;
   errorMessage: string | null;
 };
 
+export type StoredRun = {
+  id: string;
+  conversationId: string | null;
+  provider: string;
+  model: string;
+  status: RunStatus;
+  usage: {
+    inputTokens: number | null;
+    outputTokens: number | null;
+    totalTokens: number | null;
+  };
+  startedAt: string;
+  completedAt: string | null;
+  errorCode: string | null;
+  errorMessage: string | null;
+};
+
 export type PersistedChatRun = {
   conversationId: string;
   runId: string;
@@ -153,6 +172,17 @@ const MIGRATIONS = [
         ADD COLUMN visibility TEXT NOT NULL DEFAULT 'user';
     `,
   },
+  {
+    id: KNOWLEDGE_MIGRATION_ID,
+    sql: KNOWLEDGE_SCHEMA_SQL,
+  },
+  {
+    id: "0007_add_tool_call_rendered",
+    sql: `
+      ALTER TABLE tool_calls
+        ADD COLUMN rendered_json TEXT;
+    `,
+  },
 ] as const;
 
 export async function openCapsuleStore(capsule: LoadedAgentCapsule): Promise<SqliteAgentKitStore> {
@@ -218,10 +248,10 @@ export class SqliteAgentKitStore {
     this.db.close();
   }
 
-  createConversation(input: { agentName: string; title: string | null; now?: string }): ConversationSummary {
+  createConversation(input: { id?: string; agentName: string; title: string | null; now?: string }): ConversationSummary {
     return this.sqlite(() => {
       const now = input.now ?? new Date().toISOString();
-      const id = randomId();
+      const id = input.id ?? randomId();
 
       this.db
         .prepare(
@@ -457,6 +487,7 @@ export class SqliteAgentKitStore {
     toolCallId: string;
     status: ToolCallStatus;
     output?: unknown;
+    rendered?: unknown;
     completedAt?: string;
     errorMessage?: string;
     secretValues?: string[];
@@ -469,6 +500,7 @@ export class SqliteAgentKitStore {
         SET
           status = $status,
           output_json = $outputJson,
+          rendered_json = $renderedJson,
           completed_at = $completedAt,
           error_message = $errorMessage
         WHERE id = $toolCallId
@@ -478,6 +510,7 @@ export class SqliteAgentKitStore {
           $toolCallId: input.toolCallId,
           $status: input.status,
           $outputJson: input.output === undefined ? null : serializeJson(input.output, input.secretValues),
+          $renderedJson: input.rendered === undefined ? null : serializeJson(input.rendered, input.secretValues),
           $completedAt: input.completedAt ?? new Date().toISOString(),
           $errorMessage: redactSecrets(input.errorMessage ?? null, input.secretValues),
         });
@@ -550,6 +583,35 @@ export class SqliteAgentKitStore {
     });
   }
 
+  listRunsForConversation(conversationId: string): StoredRun[] {
+    return this.sqlite(() => {
+      const rows = this.db
+        .prepare(
+          `
+          SELECT
+            id,
+            conversation_id,
+            provider,
+            model,
+            status,
+            input_tokens,
+            output_tokens,
+            total_tokens,
+            started_at,
+            completed_at,
+            error_code,
+            error_message
+          FROM runs
+          WHERE conversation_id = $conversationId
+          ORDER BY started_at ASC
+        `,
+        )
+        .all({ $conversationId: conversationId }) as SqliteRow[];
+
+      return rows.map(storedRunFromRow);
+    });
+  }
+
   listToolCallsForRun(runId: string): StoredToolCall[] {
     return this.sqlite(() => {
       const rows = this.db
@@ -563,6 +625,7 @@ export class SqliteAgentKitStore {
             visibility,
             input_json,
             output_json,
+            rendered_json,
             status,
             started_at,
             completed_at,
@@ -578,6 +641,54 @@ export class SqliteAgentKitStore {
     });
   }
 
+  applyApplicationMigrations(migrations: Array<{ id: string; sql: string }>): { applied: string[]; skipped: string[] } {
+    return this.sqlite(() => {
+      if (migrations.length === 0) {
+        return { applied: [], skipped: [] };
+      }
+
+      this.db.exec(`
+        CREATE TABLE IF NOT EXISTS agentkit_app_migrations (
+          id TEXT PRIMARY KEY,
+          applied_at TEXT NOT NULL
+        )
+      `);
+
+      const applied = new Set(
+        (
+          this.db.prepare("SELECT id FROM agentkit_app_migrations").all() as Array<{
+            id: string;
+          }>
+        ).map((row) => row.id),
+      );
+      const result = {
+        applied: [] as string[],
+        skipped: [] as string[],
+      };
+
+      for (const migration of migrations) {
+        if (applied.has(migration.id)) {
+          result.skipped.push(migration.id);
+          continue;
+        }
+
+        const statements = splitSqlStatements(migration.sql);
+        this.transaction(() => {
+          for (const statement of statements) {
+            this.db.exec(statement);
+          }
+
+          this.db
+            .prepare("INSERT INTO agentkit_app_migrations (id, applied_at) VALUES ($id, $appliedAt)")
+            .run({ $id: migration.id, $appliedAt: new Date().toISOString() });
+        });
+        result.applied.push(migration.id);
+      }
+
+      return result;
+    });
+  }
+
   applyApplicationSchema(source: string): void {
     this.sqlite(() => {
       const statements = splitSqlStatements(source);
@@ -695,7 +806,12 @@ export class SqliteAgentKitStore {
           continue;
         }
 
-        this.db.exec(migration.sql);
+        if (migration.id === KNOWLEDGE_MIGRATION_ID) {
+          applyKnowledgeSchema(this.db);
+        } else {
+          this.db.exec(migration.sql);
+        }
+
         this.db
           .prepare("INSERT INTO agentkit_migrations (id, applied_at) VALUES ($id, $appliedAt)")
           .run({ $id: migration.id, $appliedAt: new Date().toISOString() });
@@ -785,6 +901,31 @@ function storedMessageFromRow(row: SqliteRow): StoredMessage {
   };
 }
 
+function storedRunFromRow(row: SqliteRow): StoredRun {
+  const status = String(row.status);
+
+  if (status !== "running" && status !== "completed" && status !== "failed") {
+    throw new AgentKitError("storage_error", `Invalid stored run status "${status}".`);
+  }
+
+  return {
+    id: String(row.id),
+    conversationId: row.conversation_id === null ? null : String(row.conversation_id),
+    provider: String(row.provider),
+    model: String(row.model),
+    status,
+    usage: {
+      inputTokens: nullableNumber(row.input_tokens),
+      outputTokens: nullableNumber(row.output_tokens),
+      totalTokens: nullableNumber(row.total_tokens),
+    },
+    startedAt: String(row.started_at),
+    completedAt: row.completed_at === null ? null : String(row.completed_at),
+    errorCode: row.error_code === null ? null : String(row.error_code),
+    errorMessage: row.error_message === null ? null : String(row.error_message),
+  };
+}
+
 function storedToolCallFromRow(row: SqliteRow): StoredToolCall {
   const status = String(row.status);
   const visibility = String(row.visibility);
@@ -805,6 +946,7 @@ function storedToolCallFromRow(row: SqliteRow): StoredToolCall {
     visibility,
     input: parseStoredJson(row.input_json),
     output: row.output_json === null ? undefined : parseStoredJson(row.output_json),
+    rendered: row.rendered_json === null ? undefined : parseStoredJson(row.rendered_json),
     status,
     startedAt: String(row.started_at),
     completedAt: row.completed_at === null ? null : String(row.completed_at),
@@ -812,6 +954,10 @@ function storedToolCallFromRow(row: SqliteRow): StoredToolCall {
   };
 }
 
+function nullableNumber(value: unknown): number | null {
+  return value === null || value === undefined ? null : Number(value);
+}
+
 function parseStoredJson(value: unknown): unknown {
   if (typeof value !== "string") {
     return value;

package/src/templates/blank.ts

@@ -65,6 +65,7 @@ node_modules/
         contents: `# Optional: only needed after switching agentkit.config.ts to a Pi-backed real provider.
 OPENAI_API_KEY=
 ANTHROPIC_API_KEY=
+OPENROUTER_API_KEY=
 `,
       },
       {
@@ -123,13 +124,18 @@ Answer clearly, ask for missing context when needed, and do not claim to have pe
       },
       {
         path: "evals/smoke.eval.ts",
-        contents: `export default {
+        contents: `import { defineEval } from "@andreprado/agentkit";
+
+export default defineEval({
   name: "smoke",
   input: "Say hello in one short sentence.",
   expect: {
-    contains: "hello",
+    response: {
+      caseInsensitiveContains: "hello",
+      maxLength: 160,
+    },
   },
-};
+});
 `,
       },
       {
@@ -146,29 +152,43 @@ When the owner opens this folder in Codex, Claude Code, or another coding agent
 
 Start building immediately:
 
-- Read \`AGENTKIT.md\` and the full docs path from \`npm run agentkit -- docs full\`.
+- 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\`: install capsule dependencies.
+- \`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.
-- \`npm run agentkit -- env set <NAME> <VALUE>\`: write a local secret value to ignored \`.env\`.
+- \`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 full\`: print the full AgentKit contract path.
+- \`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\`.
 
@@ -202,7 +222,7 @@ export const myTool = defineTool({
 
 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 in v1. Use \`CREATE TABLE IF NOT EXISTS\`, \`CREATE INDEX IF NOT EXISTS\`, and safe additive changes. AgentKit does not run destructive schema changes or ordered \`migrations/*.sql\` automatically yet.
+\`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
 
@@ -210,14 +230,16 @@ Use \`ctx.db\` as the canonical helper. \`ctx.database\` and \`ctx.storage.sql\`
 - 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> <VALUE>\`, not into committed files.
+- 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.
-- After a hosted deploy, create client-facing deploy access tokens with \`npm run agentkit -- access token create <name>\`.
+- 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\`.
@@ -240,41 +262,70 @@ Example owner request:
 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 install
 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
-npm run agentkit -- env set OPENAI_API_KEY "<value>"
+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 full framework contract, read the path printed by:
+For the lightweight docs router, read the path printed by:
 
 \`\`\`sh
-npm run agentkit -- docs full
+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.
@@ -283,9 +334,10 @@ This capsule is hosted-deploy ready by default.
 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> <VALUE>\`.
+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. Create client-facing deploy access tokens with \`npm run agentkit -- access token create <name>\` when a website or app needs to call the hosted agent.
+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.
 `,
@@ -302,9 +354,11 @@ 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.
 - 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.
 `,
       },
       {
@@ -316,16 +370,21 @@ Generated by AgentKit as an Agent Capsule.
 ## Setup
 
 \`\`\`sh
-npm install
 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.