create-stitchkit 0.4.3 → 0.5.0

package/CHANGELOG.md

@@ -12,6 +12,84 @@ step is overwritten by the next release.
 
 ## [Unreleased]
 
+## [0.5.0] — 2026-09-01
+
+### ⚠️ Breaking changes
+
+**Who must act:** two audiences. Anyone holding a generated **Agent** project
+changes one key in one object, and nothing reports it when it goes wrong.
+**Everyone** re-reads the Zod item: an API that accepted a timestamp without
+seconds stops accepting it, which is a change in what your endpoints admit, not
+in what your code compiles to.
+
+- **The Agent approval policy keys `edit_file`, not `apply_patch`.** Stitchkit
+  0.71.0 replaced `apply_patch` with a one-call `edit_file`, and `toolApproval`
+  names tools by string. A key matching no tool is not an error — an unlisted
+  tool falls through to "no approval required", so the effect of leaving the old
+  name is not that editing breaks. It is that editing stops asking: the one tool
+  the policy existed to gate now runs unattended, and the only visible sign is an
+  approval prompt that never appears.
+  `// before: toolApproval: { apply_patch: 'user-approval' }` →
+  `// after: toolApproval: { edit_file: 'user-approval' }`
+
+- **Zod 4.5 makes seconds mandatory in `z.iso.datetime()`.** The template moves
+  to `zod@4.5.4`, and the tightening travels with it: `2026-08-08T00:15Z`
+  validated before and is refused now. Nothing in the generated code changes —
+  what changes is the set of inputs your API accepts, so a client that omitted
+  seconds starts receiving `BAD_REQUEST`. If you need the old latitude, say so
+  in the schema rather than by holding the version back:
+  `// before: z.iso.datetime()` → `// after: z.iso.datetime()  // seconds now required`
+  The same release regenerates the committed **surface snapshots**: 4.5 encodes
+  a nullable as `type: ['string','null']` where 4.4 wrote `anyOf`, so every
+  affected shape fingerprint moves. A project of your own carrying
+  `surface.snapshot.json` regenerates it with `bun run surface:snapshot` and
+  reviews the diff — the hashes move, the operations do not.
+
+### Changed
+
+- **The generated project targets the published `stitchkit@0.71.0` line.** The
+  catalog target and the frozen lockfile move together, so a fresh scaffold
+  receives `edit_file`, `list_directory`, `glob`, the typed coding-tool refusals
+  a model can act on, the context usage a step reports, and the peer-free
+  `stitchkit/telegram` leaf.
+- **The whole toolchain moves to its current releases** — Zod 4.5.4 (see the
+  breaking note above), Biome 2.5.11, `@types/node` 26.4.0, and `ai` 7.0.87 in
+  the Agent template. One Zod resolves across the repository and both templates,
+  which is now a gate rather than a coincidence: two minors of Zod are two
+  incompatible type systems, and the error that surfaces names neither Zod nor
+  the file that moved it.
+- **The Agent approval policy is exhaustive again.** 0.71.0 added
+  `list_directory` and `glob`; both are read-only and both were therefore
+  running under the framework's default rather than under the project's own
+  policy. They are now named `'approved'` beside `read_file` and `search_files`.
+  Nothing about what happens changes — what changes is that the file says so,
+  which is the whole reason the map is written out rather than defaulted.
+
+## [0.4.4] — 2026-08-30
+
+### Changed
+
+- **The generated project now targets the published `stitchkit@0.70.1` line and includes the
+  maintained `stitchkit-tui` Agent profile.** The catalog and frozen lockfile move together, so a
+  fresh scaffold receives the macOS contained-file fix, bounded realtime shutdown and the terminal
+  harness package already validated by the same release train.
+
+### Added
+
+- **An explicit Agent template opens a durable OpenRouter coding session in the terminal.**
+  `bun create stitchkit my-agent --template agent` generates an OpenTUI host over the published
+  headless harness, Bun SQLite storage, lazy skills, direct coding tools, signed approvals and
+  recovery. The default production application and its repository overlay are unchanged. The
+  Agent development source follows framework HEAD locally, while generated projects receive the
+  application starter's one canonical Stitchkit catalog target. Startup requires only an API key:
+  a bounded picker reads the current popular tool-capable models and their provider-owned context
+  windows directly from OpenRouter. → ADR 0132.
+- **The Agent template now composes the official terminal package instead of copying a product
+  shell.** `stitchkit.agent.ts` is the editable typed entrypoint; `/model`, durable sessions,
+  approvals, scrolling and local `send`/`interrupt` attachment come from `stitchkit-tui`. The
+  generated manifest receives portable catalog dependencies while the repository fixture tests
+  both packages from source. → ADR 0133.
+
 ## [0.4.3] — 2026-08-28
 
 ### Fixed

package/README.md

@@ -13,6 +13,25 @@ The generated Bun workspace contains a Next.js frontend, a separate Stitchkit
 API, Prisma/PostgreSQL, typed shared contracts, Socket.IO, MCP, CLI tools and a
 complete production UI system.
 
+To start from a terminal coding agent instead:
+
+```bash
+bun create stitchkit my-agent --template agent
+cd my-agent
+cp .env.example .env
+# Set OPENROUTER_API_KEY, then choose a live model in the terminal.
+bun run dev
+```
+
+This opt-in profile is deliberately smaller. It composes the published headless
+harness, Bun SQLite store, OpenRouter adapter, lazy filesystem skills and direct
+coding tools behind an OpenTUI shell. Reads/search run directly; writes, edits,
+patches and shell calls require a signed durable `Y`/`N` approval. `bun --watch`
+restarts source while the ignored `.stitchkit/` directory retains conversation
+and recovery state. The bounded startup picker reads current tool-capable models and their context
+windows from OpenRouter instead of duplicating provider metadata in environment variables. The
+workspace path is a containment boundary, not an OS sandbox.
+
 It uses one conventional `packages/*` namespace: `backend`, `frontend`,
 `config`, `db` and `shared`. The destination name becomes the generated slug;
 `--display-name` sets the human title. Both are recorded once in

package/UPGRADING.md

@@ -60,6 +60,71 @@ the first scaffolder release with a migration channel of its own.
 
 ---
 
+## Released migration: 0.5.0
+
+### the approval policy names a tool that no longer exists
+
+One code edit, and one thing to do to a machine that was left mid-question.
+
+1. **Rename the key.** In `src/runtime.ts`, inside `loop.toolApproval`, replace
+   `apply_patch: 'user-approval'` with `edit_file: 'user-approval'`. While you
+   are in that object, add `list_directory: 'approved'` and `glob: 'approved'`
+   beside `read_file` and `search_files` — 0.71.0 added both, they are read-only,
+   and an unlisted tool is governed by the framework's default rather than by
+   this file.
+
+   Do this **before** you start the upgraded agent, not after. The failure mode
+   is silent in the direction that costs you: a key matching no tool does not
+   raise, it simply stops gating, so the first edit after the upgrade is applied
+   without asking and looks exactly like an edit you approved.
+
+2. **Operator step — a durable session left waiting on the old tool cannot be
+   answered.** If an agent was interrupted while a `apply_patch` approval was
+   pending, that approval names a call for a tool the framework no longer
+   defines: approving it cannot execute anything, and the run will not move.
+   Interrupt that run, or drop the local state directory — `.stitchkit/` holds
+   `agent.sqlite`, the approval secret and the TUI logs, all of it local and
+   regenerated on the next start. There is nothing durable in it that a server
+   owns.
+
+   A session with no pending approval needs none of this and resumes normally.
+
+3. **The framework's own move is separate.** Going from a `0.70.x` line to
+   `0.71.0` is a Stitchkit upgrade with its own breaking notes — the coding-tool
+   surface changed for anyone calling it directly, not only through this
+   template. Read
+   [`docs/guide/upgrading.md`](../../docs/guide/upgrading.md), section
+   `Released migration: 0.71.0`.
+
+### the timestamp your API accepts got narrower
+
+Zod moved to 4.5, and `z.iso.datetime()` now requires seconds. This is not a
+code change — it is a change in what your endpoints admit, and it arrives the
+moment you install.
+
+1. **Decide before you deploy, not after.** If any client sends
+   `2026-08-08T00:15Z`, it now receives `BAD_REQUEST` where it used to receive
+   `200`. Search your schemas for `z.iso.datetime()` and check who fills those
+   fields. A machine-to-machine caller you control is a one-line fix on its
+   side; a caller you do not control is a decision, and the honest form of it is
+   an explicit schema that accepts what you mean to accept — not a pinned Zod
+   version, which only moves the same day to a later one.
+
+2. **Regenerate your surface snapshot in the same commit.** 4.5 encodes a
+   nullable as `type: ["string","null"]` where 4.4 wrote `anyOf`, so the shape
+   fingerprints in `packages/backend/src/surface.snapshot.json` move without any
+   operation changing. Run `bun run surface:snapshot` and read the diff: only
+   `inputShape` / `outputShape` values may differ. If an operation appeared,
+   vanished, or changed its HTTP or tool exposure, that is **your** change and
+   Zod did not cause it.
+
+3. **Move one Zod, not several.** If your project vendors or links packages that
+   depend on Zod themselves, they must resolve the same minor. Two minors are
+   two incompatible type systems, and what surfaces is
+   `TS2589: Type instantiation is excessively deep` in a file you did not touch.
+   No operator step: nothing about a running machine changes.
+
+
 ## Released migration: 0.4.1
 
 ### a release refuses a stale artifact, and cleanup is bounded

package/dist/cli.js

@@ -207,10 +207,11 @@ function withIdentity(declaration, identity) {
 var HELP = `Create a production-shaped Stitchkit application.
 
 Usage:
-  bun create stitchkit <directory> [--display-name "Product Name"] [--example repository] [--no-install]
+  bun create stitchkit <directory> [--template application|agent] [--display-name "Product Name"] [--example repository] [--no-install]
 
 Options:
   --no-install  Generate files without installing dependencies
+  --template    Select the project shape (default: application)
   --example     Add an isolated runnable example (supported: repository)
   --display-name  Set the initial public application name
   --help        Show this help
@@ -221,7 +222,7 @@ function helpText() {
 function parseOptions(args) {
   if (args.includes("--help") || args.includes("-h"))
     return "help";
-  const unknown = args.filter((arg) => arg.startsWith("-") && arg !== "--no-install" && arg !== "--example" && arg !== "--display-name");
+  const unknown = args.filter((arg) => arg.startsWith("-") && arg !== "--no-install" && arg !== "--template" && arg !== "--example" && arg !== "--display-name");
   if (unknown.length > 0) {
     throw new Error(`Unknown option: ${unknown[0]}`);
   }
@@ -233,14 +234,26 @@ function parseOptions(args) {
   if (example !== undefined && example !== "repository") {
     throw new Error(`Unknown example: ${example}`);
   }
+  const templateFlagIndex = args.indexOf("--template");
+  const template = templateFlagIndex === -1 ? "application" : args[templateFlagIndex + 1];
+  if (templateFlagIndex !== -1 && template === undefined) {
+    throw new Error("--template requires a value");
+  }
+  if (template !== "application" && template !== "agent") {
+    throw new Error(`Unknown template: ${template}`);
+  }
+  if (template === "agent" && example !== undefined) {
+    throw new Error("--example is only supported by the application template");
+  }
   const displayNameFlagIndex = args.indexOf("--display-name");
   const displayName = displayNameFlagIndex === -1 ? undefined : args[displayNameFlagIndex + 1];
   if (displayNameFlagIndex !== -1 && displayName === undefined) {
     throw new Error("--display-name requires a value");
   }
   const consumedExampleIndex = exampleFlagIndex === -1 ? -1 : exampleFlagIndex + 1;
+  const consumedTemplateIndex = templateFlagIndex === -1 ? -1 : templateFlagIndex + 1;
   const consumedDisplayNameIndex = displayNameFlagIndex === -1 ? -1 : displayNameFlagIndex + 1;
-  const positionals = args.filter((arg, index) => !arg.startsWith("-") && index !== consumedExampleIndex && index !== consumedDisplayNameIndex);
+  const positionals = args.filter((arg, index) => !arg.startsWith("-") && index !== consumedExampleIndex && index !== consumedTemplateIndex && index !== consumedDisplayNameIndex);
   if (positionals.length !== 1) {
     throw new Error("Exactly one destination directory is required");
   }
@@ -250,6 +263,7 @@ function parseOptions(args) {
   return {
     destination,
     install: !args.includes("--no-install"),
+    template,
     ...example && { example },
     ...displayName && { displayName }
   };
@@ -283,9 +297,15 @@ var TEMPLATE_RENAMES = new Map([
   ["_env.example.append", ".env.example"],
   ["_gitignore", ".gitignore"]
 ]);
-var RootManifestSchema = z2.looseObject({ name: z2.string().min(1) });
+var RootManifestSchema = z2.looseObject({
+  name: z2.string().min(1),
+  catalog: z2.record(z2.string(), z2.string()).optional(),
+  dependencies: z2.record(z2.string(), z2.string()).optional(),
+  devDependencies: z2.record(z2.string(), z2.string()).optional()
+});
 var IGNORED_DIRECTORIES = new Set([
   ".next",
+  ".stitchkit",
   "coverage",
   "dist",
   "node_modules",
@@ -401,16 +421,43 @@ async function scaffoldProject(templateDirectory, destination, options = {}) {
     if (options.overlayDirectory) {
       await writeMaterialisedFiles(resolvedDestination, await materialiseTemplateFiles(options.overlayDirectory));
     }
+    if (options.lockfile === false) {
+      await rm(join(resolvedDestination, "bun.lock"), { force: true });
+    }
     const declarationPath = join(resolvedDestination, "project.json");
     const declaration = withIdentity(JSON.parse(await readFile(declarationPath, "utf8")), identity);
     await writeFile(declarationPath, `${JSON.stringify(declaration, undefined, 2)}
 `);
-    const identityPath = join(resolvedDestination, APP_IDENTITY_PATH);
-    await mkdir(dirname(identityPath), { recursive: true });
-    await writeFile(identityPath, renderAppIdentityModule(declaration.identity));
+    if (options.identityModule !== false) {
+      const identityPath = join(resolvedDestination, APP_IDENTITY_PATH);
+      await mkdir(dirname(identityPath), { recursive: true });
+      await writeFile(identityPath, renderAppIdentityModule(declaration.identity));
+    }
     const manifestPath = join(resolvedDestination, "package.json");
     const manifest = RootManifestSchema.parse(JSON.parse(await readFile(manifestPath, "utf8")));
-    await writeFile(manifestPath, `${JSON.stringify({ ...manifest, name: identity.slug }, undefined, 2)}
+    const catalog = options.stitchkitCatalogTarget ? { ...manifest.catalog ?? {}, stitchkit: options.stitchkitCatalogTarget } : manifest.catalog;
+    const replaceLocalPackages = (dependencies) => {
+      if (!dependencies)
+        return dependencies;
+      return {
+        ...dependencies,
+        ...dependencies.stitchkit?.startsWith("file:") && { stitchkit: "catalog:" },
+        ...dependencies["stitchkit-tui"]?.startsWith("file:") && {
+          "stitchkit-tui": "catalog:"
+        }
+      };
+    };
+    await writeFile(manifestPath, `${JSON.stringify({
+      ...manifest,
+      name: identity.slug,
+      ...catalog && { catalog },
+      ...manifest.dependencies && {
+        dependencies: replaceLocalPackages(manifest.dependencies)
+      },
+      ...manifest.devDependencies && {
+        devDependencies: replaceLocalPackages(manifest.devDependencies)
+      }
+    }, undefined, 2)}
 `);
   } catch (error) {
     if (!destinationExisted) {
@@ -432,11 +479,17 @@ async function run(args) {
       return 0;
     }
     const destination = resolve2(options.destination);
-    const templateDirectory = resolve2(import.meta.dir, "../template");
+    const applicationTemplateDirectory = resolve2(import.meta.dir, "../template");
+    const templateDirectory = options.template === "agent" ? resolve2(import.meta.dir, "../templates/agent") : applicationTemplateDirectory;
     const overlayDirectory = options.example ? resolve2(import.meta.dir, `../examples/${options.example}`) : undefined;
     await scaffoldProject(templateDirectory, destination, {
       ...overlayDirectory && { overlayDirectory },
-      ...options.displayName && { displayName: options.displayName }
+      ...options.displayName && { displayName: options.displayName },
+      ...options.template === "agent" && {
+        identityModule: false,
+        lockfile: false,
+        stitchkitCatalogTarget: await readStitchkitCatalogTarget(applicationTemplateDirectory)
+      }
     });
     if (options.install) {
       const install = spawn(["bun", "install"], {
@@ -449,7 +502,7 @@ async function run(args) {
       if (exitCode !== 0)
         throw new Error(`bun install failed with exit code ${exitCode}`);
     }
-    const mode = options.example ? ` with the ${options.example} example` : "";
+    const mode = options.template === "agent" ? " from the agent template" : options.example ? ` with the ${options.example} example` : "";
     process.stdout.write(`
 Created ${options.displayName ?? basename3(destination)}${mode}
 
@@ -471,6 +524,13 @@ Created ${options.displayName ?? basename3(destination)}${mode}
     return 1;
   }
 }
+async function readStitchkitCatalogTarget(templateDirectory) {
+  const manifest = JSON.parse(await readFile2(join2(templateDirectory, "package.json"), "utf8"));
+  if (typeof manifest !== "object" || manifest === null || !("catalog" in manifest) || typeof manifest.catalog !== "object" || manifest.catalog === null || !("stitchkit" in manifest.catalog) || typeof manifest.catalog.stitchkit !== "string") {
+    throw new Error("Application template is missing catalog.stitchkit");
+  }
+  return manifest.catalog.stitchkit;
+}
 if (import.meta.main) {
   process.exitCode = await run(Bun.argv.slice(2));
 }

package/examples/repository/packages/backend/src/surface.snapshot.json

@@ -6,7 +6,7 @@
     "hasInput": false,
     "hasOutput": true,
     "inputShape": null,
-    "outputShape": "49c1f81a53ca82ad",
+    "outputShape": "05d1386c30d82f6a",
     "http": [
       {
         "method": "GET",
@@ -26,7 +26,7 @@
     "hasInput": false,
     "hasOutput": true,
     "inputShape": null,
-    "outputShape": "49c1f81a53ca82ad",
+    "outputShape": "05d1386c30d82f6a",
     "http": [
       {
         "method": "POST",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-stitchkit",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "description": "Create a production-shaped Stitchkit application",
   "license": "MIT",
   "author": "Max Listov <maxlistov@gmail.com>",
@@ -16,11 +16,13 @@
   "files": [
     "dist",
     "template/**/*",
+    "templates/**/*",
     "examples/**/*",
     "!template/**/.env",
     "!template/**/.build-stamp.json",
     "!template/**/node_modules/**",
     "!template/**/.next/**",
+    "!template/**/.stitchkit/**",
     "!template/**/dist/**",
     "!template/**/playwright-report/**",
     "!template/**/test-results/**",
@@ -29,10 +31,25 @@
     "!template/**/*.log",
     "!template/**/*.tsbuildinfo",
     "!template/**/coverage/**",
+    "!templates/**/.env",
+    "!templates/**/.build-stamp.json",
+    "!templates/**/node_modules/**",
+    "!templates/**/.next/**",
+    "!templates/**/.stitchkit/**",
+    "!templates/**/dist/**",
+    "!templates/**/playwright-report/**",
+    "!templates/**/test-results/**",
+    "!templates/**/next-env.d.ts",
+    "!templates/**/src/generated/**",
+    "!templates/**/*.log",
+    "!templates/**/*.tsbuildinfo",
+    "!templates/**/coverage/**",
+    "!templates/agent/bun.lock",
     "!examples/**/.env",
     "!examples/**/.build-stamp.json",
     "!examples/**/node_modules/**",
     "!examples/**/.next/**",
+    "!examples/**/.stitchkit/**",
     "!examples/**/dist/**",
     "!examples/**/coverage/**",
     "!examples/**/playwright-report/**",
@@ -59,7 +76,14 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
+    "@opentui/core": "^0.5.9",
+    "@opentui/react": "^0.5.9",
+    "@openrouter/ai-sdk-provider": "^3.0.0",
     "@types/bun": "^1.4.0",
+    "@types/react": "^19.2.18",
+    "ai": "^7.0.84",
+    "react": "^19.2.8",
+    "stitchkit": "0.71.0",
     "typescript": "^7.0.2"
   },
   "engines": {

package/template/bun.lock

@@ -11,16 +11,16 @@
         "@app/config": "workspace:*",
         "@app/shared": "workspace:*",
         "@axe-core/playwright": "^4.13.0",
-        "@biomejs/biome": "^2.5.10",
+        "@biomejs/biome": "^2.5.11",
         "@modelcontextprotocol/client": "^2.0.0",
         "@playwright/test": "^1.62.1",
         "@types/bun": "^1.4.0",
-        "@types/node": "^26.3.0",
+        "@types/node": "^26.4.0",
         "oxc-parser": "^0.147.0",
         "socket.io-client": "^4.8.3",
         "stitchkit": "catalog:",
         "typescript": "^7.0.2",
-        "zod": "^4.4.3",
+        "zod": "^4.5.4",
       },
     },
     "packages/backend": {
@@ -139,7 +139,7 @@
     },
   },
   "catalog": {
-    "stitchkit": "^0.68.6",
+    "stitchkit": "^0.71.0",
   },
   "packages": {
     "@ai-sdk/gateway": ["@ai-sdk/gateway@4.0.63", "", { "dependencies": { "@ai-sdk/provider": "4.0.7", "@ai-sdk/provider-utils": "5.0.29", "@vercel/oidc": "3.2.0" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-D7BogSRg61QfTdr7AEcYn9h0I/e4QHvFXwIV1RW+DZZGJu1wSiX2cH06szZSYyKi7Eat50V4s4J8vggZUEs7eg=="],
@@ -168,23 +168,23 @@
 
     "@babel/types": ["@babel/types@7.29.8", "", { "dependencies": { "@babel/helper-string-parser": "^7.29.7", "@babel/helper-validator-identifier": "^7.29.7" } }, "sha512-Vj1jF3cPfxg7OAfoI7QnVKLoILlm2JF9pnVHrX8qx7AHMiYWT+NDAA7jChlNgRS4WTLc/fD1lXLmPixluj+3Gg=="],
 
-    "@biomejs/biome": ["@biomejs/biome@2.5.10", "", { "optionalDependencies": { "@biomejs/cli-darwin-arm64": "2.5.10", "@biomejs/cli-darwin-x64": "2.5.10", "@biomejs/cli-linux-arm64": "2.5.10", "@biomejs/cli-linux-arm64-musl": "2.5.10", "@biomejs/cli-linux-x64": "2.5.10", "@biomejs/cli-linux-x64-musl": "2.5.10", "@biomejs/cli-win32-arm64": "2.5.10", "@biomejs/cli-win32-x64": "2.5.10" }, "bin": { "biome": "bin/biome" } }, "sha512-WRKXARA3kTuiV5sxqTpobJ/I0MVd4vk3pOL6wnp5az4LntFIhWTj1RWZq3DI9PCEN3lXcqy7p5aqUHzvq8AXyQ=="],
+    "@biomejs/biome": ["@biomejs/biome@2.5.11", "", { "optionalDependencies": { "@biomejs/cli-darwin-arm64": "2.5.11", "@biomejs/cli-darwin-x64": "2.5.11", "@biomejs/cli-linux-arm64": "2.5.11", "@biomejs/cli-linux-arm64-musl": "2.5.11", "@biomejs/cli-linux-x64": "2.5.11", "@biomejs/cli-linux-x64-musl": "2.5.11", "@biomejs/cli-win32-arm64": "2.5.11", "@biomejs/cli-win32-x64": "2.5.11" }, "bin": { "biome": "bin/biome" } }, "sha512-Tj0dnkLPdW0ASjHfj2D/ZkkvPU2wrFmnE1jWTD2xzV1ycapV1DutbYXk4NDnR3rYTi1ZCbNFD4G2gRMEY65WaA=="],
 
-    "@biomejs/cli-darwin-arm64": ["@biomejs/cli-darwin-arm64@2.5.10", "", { "os": "darwin", "cpu": "arm64" }, "sha512-ItCrxKK6SXVT6flYs0qIuBd4AA3TTTl4d66Re6YI2FuGZnN85NmuYNzkiTJUyYw8qBLv69L5zTUB6uyWd++h3Q=="],
+    "@biomejs/cli-darwin-arm64": ["@biomejs/cli-darwin-arm64@2.5.11", "", { "os": "darwin", "cpu": "arm64" }, "sha512-6SGZxoKbXvUjMn1t6A98HqWISPnGNbYs0R/Rt2JarmXBSev+lva4QxUMWEBX9lX1Wo1XTJ78uk5xVDtG58SRZg=="],
 
-    "@biomejs/cli-darwin-x64": ["@biomejs/cli-darwin-x64@2.5.10", "", { "os": "darwin", "cpu": "x64" }, "sha512-yLsPU9pAmtChXDu8vhKAzErqe+LeeYuwuUB2FZMkRitsmdodxsYRa9KHrFispsUHzzOu+9HB3nP/TQxyia+Sjw=="],
+    "@biomejs/cli-darwin-x64": ["@biomejs/cli-darwin-x64@2.5.11", "", { "os": "darwin", "cpu": "x64" }, "sha512-nYkXY7tLBEgnGbYapDKAyKzgt44ZEyG+AKalvTXtCWKYgepI9dw327q+cVgedxm+Udi1ZzHKUyZrIusHi/KQbw=="],
 
-    "@biomejs/cli-linux-arm64": ["@biomejs/cli-linux-arm64@2.5.10", "", { "os": "linux", "cpu": "arm64" }, "sha512-VG8uQW/86a1roLaIFvtIbEigxIdzdJ190oGyg1tV7VYeQtOS+x10sflk7WbuXgw91EtZX5DlIIIej1YqkNLlcg=="],
+    "@biomejs/cli-linux-arm64": ["@biomejs/cli-linux-arm64@2.5.11", "", { "os": "linux", "cpu": "arm64" }, "sha512-3PVLSTD9RR73rvVPt5G3T1gc+ycggWEGfTD7RvzzbtcDPD27NxgxBbAFfpm7DXJKW6VLHWE1lLMGvFt2Qxjcow=="],
 
-    "@biomejs/cli-linux-arm64-musl": ["@biomejs/cli-linux-arm64-musl@2.5.10", "", { "os": "linux", "cpu": "arm64" }, "sha512-t1QAKZwQJRB4dvgJSgFiQ4BNfNPChg69BNonz854qLVxnjT3UvDzQg9mbkTJRu35ZqU0Rw10A73J8Urgbg2RPw=="],
+    "@biomejs/cli-linux-arm64-musl": ["@biomejs/cli-linux-arm64-musl@2.5.11", "", { "os": "linux", "cpu": "arm64" }, "sha512-qhyZUMyCbWYFV2bAwRNVvfMVZ+hv7WYl6mossGrxC+uiQQXhvsuWWU8zz6jYX0mChZd9MgQZbm4vozTmG/5iGw=="],
 
-    "@biomejs/cli-linux-x64": ["@biomejs/cli-linux-x64@2.5.10", "", { "os": "linux", "cpu": "x64" }, "sha512-4O6T0eq2heoHZN0a9UX+rWQoxXEBaKf+lRi2hbsGlHneUz9BWXM76nEWMK7Eeq8gzMxR1khQB6BFpAASpeXqGg=="],
+    "@biomejs/cli-linux-x64": ["@biomejs/cli-linux-x64@2.5.11", "", { "os": "linux", "cpu": "x64" }, "sha512-JOytptlsgM33B2MMFUg8iBrb4IKpbD5JnJrSeYiaFEeAj4vuXx0iQSQZ4qK7sqyMtfjZxxPdNdMZZVL4y/mFyA=="],
 
-    "@biomejs/cli-linux-x64-musl": ["@biomejs/cli-linux-x64-musl@2.5.10", "", { "os": "linux", "cpu": "x64" }, "sha512-pgDDqp9JybHm2I0KRgzN6i4+lt8xu4iqxUwLzglUMmOmyRTU1AYBGKzh9sNMOtIjah7xoWvKHlLVetvyifzoiQ=="],
+    "@biomejs/cli-linux-x64-musl": ["@biomejs/cli-linux-x64-musl@2.5.11", "", { "os": "linux", "cpu": "x64" }, "sha512-oRRlrchG5EfrEL/EmtT1qUjSNHk3/5LGeZhQqADBBAJF1b1ET6964xEKe7aGlGARzDfza8H/seEsFJl7S6Ql9w=="],
 
-    "@biomejs/cli-win32-arm64": ["@biomejs/cli-win32-arm64@2.5.10", "", { "os": "win32", "cpu": "arm64" }, "sha512-pxAbxduPO4xq/Cvgaa2lOrs9BB0hEXmmDqfMNP4ZOffGOkUrD1/QGw9UAMpFQpX2P8MqTIIRuQKcmetum4Oa6A=="],
+    "@biomejs/cli-win32-arm64": ["@biomejs/cli-win32-arm64@2.5.11", "", { "os": "win32", "cpu": "arm64" }, "sha512-e49E6K9hzH/ohJNx8Y26mY8HaV4I4ZViIeoqhKsmoXLKHhQnMeBAVqCgsGf2Wa3lXlS7RkporDXMHHWkzvZzFw=="],
 
-    "@biomejs/cli-win32-x64": ["@biomejs/cli-win32-x64@2.5.10", "", { "os": "win32", "cpu": "x64" }, "sha512-M+2dgBsl3lXRiTfgPVc2p3anS4Tocojke4rzFLScZ2Y/wmF+36dRb1iHCLiyGqOzQGyTplZH1HnEYviiAqi3nA=="],
+    "@biomejs/cli-win32-x64": ["@biomejs/cli-win32-x64@2.5.11", "", { "os": "win32", "cpu": "x64" }, "sha512-QSQr/KjOgXA7OzXJUWS+oguKyAZ3Q0l/lnlDGbu397eKo83atuWUjBPJrsqbKNF6CARGw8XXJLGzpHC8Ryhd4Q=="],
 
     "@electric-sql/pglite": ["@electric-sql/pglite@0.4.3", "", {}, "sha512-ichuWTgtd4mOM1G4SpyGJa5trT03lWbMypDV0fUXUCXg5hiHqVAz/bZyV68NqmkLB7WcYmj1RMJVSp8HV/v/ZQ=="],
 
@@ -620,7 +620,7 @@
 
     "@types/mdast": ["@types/mdast@4.0.4", "", { "dependencies": { "@types/unist": "*" } }, "sha512-kGaNbPh1k7AFzgpud/gMdvIm5xuECykRR+JnWKQno9TAXVa6WIVCGTPvYGekIDL4uwCZQSYbUxNBSb1aUo79oA=="],
 
-    "@types/node": ["@types/node@26.3.0", "", { "dependencies": { "undici-types": "~8.3.0" } }, "sha512-L3fgrnchriRC2ExBflb8j4uZZURHZfQsmQeyVzhjcHW4kkwVyo8/0h1B2MVzMTrYUJYu6G7EWs14hW/L9putqw=="],
+    "@types/node": ["@types/node@26.4.0", "", { "dependencies": { "undici-types": "~8.3.0" } }, "sha512-faiGnoIrLH/V8cibOMEAZ8pMw6oXqSukl29ra4mN8GdaB2ZewzeaLj+INpV5N+Z1eKWzY+IzaIZH2EIR6YZRNQ=="],
 
     "@types/pg": ["@types/pg@8.23.1", "", { "dependencies": { "@types/node": "*", "pg-protocol": "*", "pg-types": "^2.2.0" } }, "sha512-fKVHpikPdg4GKks3JuLEhvwSyvwzF23hnabPy6DD8ljVbC7+6J5dQzdv4arV6jqq57djnMgs1HKBxX4P8aBI3A=="],
 
@@ -1118,7 +1118,7 @@
 
     "std-env": ["std-env@3.10.0", "", {}, "sha512-5GS12FdOZNliM5mAOxFRg7Ir0pWz8MdpYm6AY6VPkGpbA7ZzmbzNcBJQ0GPvvyWgcY7QAhCgf9Uy89I03faLkg=="],
 
-    "stitchkit": ["stitchkit@0.68.6", "", { "dependencies": { "ky": "^2.0.2" }, "peerDependencies": { "@modelcontextprotocol/ext-apps": "^1.7.2", "@modelcontextprotocol/server": "^2.0.0", "@openrouter/ai-sdk-provider": "^3.0.0", "@opentelemetry/api": "^1.9.0", "@socket.io/bun-engine": "^0.1.1", "@socket.io/component-emitter": "^3.1.2", "@tanstack/react-query": ">=5", "@types/bun": "^1.3.14", "ai": "^7.0.0", "grammy": "^1.45.1", "react": ">=18", "react-query-kit": "^3.3.3", "socket.io": "^4.8.3", "socket.io-client": "^4.8.3", "srvx": "^0.12.5", "zod": "^4.4.3" }, "optionalPeers": ["@modelcontextprotocol/ext-apps", "@modelcontextprotocol/server", "@openrouter/ai-sdk-provider", "@opentelemetry/api", "@socket.io/bun-engine", "@socket.io/component-emitter", "@tanstack/react-query", "@types/bun", "ai", "grammy", "react", "react-query-kit", "socket.io", "socket.io-client", "srvx"] }, "sha512-fnniuyge5JEN55TVdI3qH+nN1XyGJ6MglwOraWeOk6FkYs7mv6ZZyEo1kkFVT1bcsYj4HZW7KJCiKwnsjDoyfw=="],
+    "stitchkit": ["stitchkit@0.71.0", "", { "dependencies": { "ky": "^2.0.2" }, "peerDependencies": { "@modelcontextprotocol/ext-apps": "^1.7.2", "@modelcontextprotocol/server": "^2.0.0", "@openrouter/ai-sdk-provider": "^3.0.0", "@opentelemetry/api": "^1.9.0", "@socket.io/bun-engine": "^0.1.1", "@socket.io/component-emitter": "^3.1.2", "@tanstack/react-query": ">=5", "@types/bun": "^1.3.14", "ai": "^7.0.0", "grammy": "^1.45.1", "react": ">=18", "react-query-kit": "^3.3.3", "socket.io": "^4.8.3", "socket.io-client": "^4.8.3", "srvx": "^0.12.5", "zod": "^4.4.3" }, "optionalPeers": ["@modelcontextprotocol/ext-apps", "@modelcontextprotocol/server", "@openrouter/ai-sdk-provider", "@opentelemetry/api", "@socket.io/bun-engine", "@socket.io/component-emitter", "@tanstack/react-query", "@types/bun", "ai", "grammy", "react", "react-query-kit", "socket.io", "socket.io-client", "srvx"] }, "sha512-HXqTD1Sv534rWt+KKJV1Gp535NTRzbGFxNMuRAvo9TzuU0kZxBDF18gu+WexF9O8Z4jkhlfvTjXeRy/oQrnHwA=="],
 
     "stringify-entities": ["stringify-entities@4.0.4", "", { "dependencies": { "character-entities-html4": "^2.0.0", "character-entities-legacy": "^3.0.0" } }, "sha512-IwfBptatlO+QCJUo19AqvrPNqlVMpW9YEL2LIVY+Rpv2qsjCGxaDLNRgeGsQWJhfItebuJhsGSLjaBbNSQ+ieg=="],
 
@@ -1186,10 +1186,13 @@
 
     "zeptomatch": ["zeptomatch@2.1.0", "", { "dependencies": { "grammex": "^3.1.11", "graphmatch": "^1.1.0" } }, "sha512-KiGErG2J0G82LSpniV0CtIzjlJ10E04j02VOudJsPyPwNZgGnRKQy7I1R7GMyg/QswnE4l7ohSGrQbQbjXPPDA=="],
 
-    "zod": ["zod@4.4.3", "", {}, "sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ=="],
+    "zod": ["zod@4.5.4", "", {}, "sha512-sC95tT5iHHH9gtpj6A81kh+NEaRAUFN+qlUPDUbRfOMvNf5QCBqsb3WgvnpVtK5Y+4UfA6KqufotuTvMGiTlsA=="],
 
     "zwitch": ["zwitch@2.0.4", "", {}, "sha512-bXE4cR/kVZhKZX/RjPEflHaKVhUVl85noU3v6b8apfQEc1x4A+zBxjZ4lN8LqGd6WZ3dl98pY4o717VFmoPp+A=="],
 
+
+
+
     "@prisma/adapter-pg/@types/pg": ["@types/pg@8.21.0", "", { "dependencies": { "@types/node": "*", "pg-protocol": "*", "pg-types": "^2.2.0" } }, "sha512-AYdtudzabjLZgVgRZmAnU8bAnVUXzuJX2IYHeSIiIHm68olD+LgQYCGWdtcNYnP0uq9c4S4NibVG3Ni7VbKW7Q=="],
 
     "@prisma/adapter-pg/pg": ["pg@8.22.0", "", { "dependencies": { "pg-connection-string": "^2.14.0", "pg-pool": "^3.14.0", "pg-protocol": "^1.15.0", "pg-types": "2.2.0", "pgpass": "1.0.5" }, "optionalDependencies": { "pg-cloudflare": "^1.4.0" }, "peerDependencies": { "pg-native": ">=3.0.1" }, "optionalPeers": ["pg-native"] }, "sha512-8wih1vVIBMxoUM2oB4soJsD9tDnDpLv4OXBJ+EJzFsvycD+lfyIreC2gGHq78f8jbLLt+bvlPTFdFZfJkOuzAA=="],
@@ -1220,6 +1223,8 @@
 
     "@types/cors/@types/node": ["@types/node@26.2.0", "", { "dependencies": { "undici-types": "~8.3.0" } }, "sha512-5IviulTZeRNp2vAJ514cc/HUlY5nZ9fCbq9DMyC52BrhFZACo3nI0R7qBxhQmo/d27NFe96ur/b7Wwxklda+kg=="],
 
+    "@types/pg/@types/node": ["@types/node@26.3.0", "", { "dependencies": { "undici-types": "~8.3.0" } }, "sha512-L3fgrnchriRC2ExBflb8j4uZZURHZfQsmQeyVzhjcHW4kkwVyo8/0h1B2MVzMTrYUJYu6G7EWs14hW/L9putqw=="],
+
     "@types/ws/@types/node": ["@types/node@26.2.0", "", { "dependencies": { "undici-types": "~8.3.0" } }, "sha512-5IviulTZeRNp2vAJ514cc/HUlY5nZ9fCbq9DMyC52BrhFZACo3nI0R7qBxhQmo/d27NFe96ur/b7Wwxklda+kg=="],
 
     "@visx/vendor/@types/d3-array": ["@types/d3-array@3.0.3", "", {}, "sha512-Reoy+pKnvsksN0lQUlcH6dOGjRZ/3WRwXR//m+/8lt1BXeI4xyaUZoqULNjyXXRuh0Mj4LNpkCvhUpQlY3X5xQ=="],
@@ -1236,6 +1241,8 @@
 
     "accepts/negotiator": ["negotiator@0.6.3", "", {}, "sha512-+EUsqGPLsM+j/zdChZjsnX51g4XrHFOIXwfnCVPGlQk/k5giakcKsuxCObBRu6DSm9opw/O6slWbJdghQM4bBg=="],
 
+    "bun-types/@types/node": ["@types/node@26.3.0", "", { "dependencies": { "undici-types": "~8.3.0" } }, "sha512-L3fgrnchriRC2ExBflb8j4uZZURHZfQsmQeyVzhjcHW4kkwVyo8/0h1B2MVzMTrYUJYu6G7EWs14hW/L9putqw=="],
+
     "engine.io/@types/node": ["@types/node@26.2.0", "", { "dependencies": { "undici-types": "~8.3.0" } }, "sha512-5IviulTZeRNp2vAJ514cc/HUlY5nZ9fCbq9DMyC52BrhFZACo3nI0R7qBxhQmo/d27NFe96ur/b7Wwxklda+kg=="],
 
     "pg-types/postgres-array": ["postgres-array@2.0.0", "", {}, "sha512-VpZrUqU5A69eQyW2c5CA1jtLecCsN2U/bD6VilrFDWq5+5UIEVO7nazS3TEcHf1zuPYO/sqGvUvW62g86RXZuA=="],

package/template/package.json

@@ -7,7 +7,7 @@
     "packages/*"
   ],
   "catalog": {
-    "stitchkit": "^0.68.6"
+    "stitchkit": "^0.71.0"
   },
   "scripts": {
     "dev": "bun scripts/dev.ts",
@@ -42,16 +42,16 @@
     "@app/config": "workspace:*",
     "@app/shared": "workspace:*",
     "@axe-core/playwright": "^4.13.0",
-    "@biomejs/biome": "^2.5.10",
+    "@biomejs/biome": "^2.5.11",
     "@modelcontextprotocol/client": "^2.0.0",
     "@playwright/test": "^1.62.1",
     "@types/bun": "^1.4.0",
-    "@types/node": "^26.3.0",
+    "@types/node": "^26.4.0",
     "oxc-parser": "^0.147.0",
     "socket.io-client": "^4.8.3",
     "stitchkit": "catalog:",
     "typescript": "^7.0.2",
-    "zod": "^4.4.3"
+    "zod": "^4.5.4"
   },
   "engines": {
     "bun": ">=1.2.0",

package/template/scripts/local-env.test.ts

@@ -30,4 +30,19 @@ describe('ensureLocalEnvironment', () => {
       await rm(root, { recursive: true, force: true });
     }
   });
+
+  test('a clean framework source tree reads the pre-scaffold example name', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'sk-source-env-'));
+    try {
+      await writeFile(
+        join(root, '_env.example'),
+        'DATABASE_URL=postgresql://USER:PASSWORD@127.0.0.1:5432/stitchkit_starter\n',
+      );
+      ensureLocalEnvironment(root);
+      const databaseName = appDeclaration.identity.slug.replaceAll('-', '_');
+      expect(await readFile(join(root, '.env'), 'utf8')).toContain(`5432/${databaseName}`);
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
 });

package/template/scripts/local-env.ts

@@ -3,8 +3,11 @@ import { resolve } from 'node:path';
 import { appIdentity } from '../packages/config/src/app-identity.generated';
 
 /**
- * Create `.env` from `.env.example` on first run, rendering the application
- * identity into the database name.
+ * Create `.env` from the public `.env.example` on first run, rendering the
+ * application identity into the database name. The framework repository keeps
+ * that same source as `_env.example` until the scaffolder performs its rename,
+ * so clean source-tree checks use it directly instead of depending on an
+ * ignored developer `.env`.
  *
  * Identity, not the whole declaration: this needs one slug, and the identity
  * module carries no dependencies. That matters here more than elsewhere —
@@ -19,7 +22,11 @@ import { appIdentity } from '../packages/config/src/app-identity.generated';
 export function ensureLocalEnvironment(root: string): void {
   const destination = resolve(root, '.env');
   if (existsSync(destination)) return;
-  const example = readFileSync(resolve(root, '.env.example'), 'utf8');
+  const publicExample = resolve(root, '.env.example');
+  const example = readFileSync(
+    existsSync(publicExample) ? publicExample : resolve(root, '_env.example'),
+    'utf8',
+  );
   const databaseName = appIdentity.slug.replaceAll('-', '_');
   writeFileSync(destination, example.replaceAll('stitchkit_starter', databaseName));
 }

package/template/scripts/shutdown-budget.test.ts

@@ -43,16 +43,23 @@ describe('the termination budget is an upper bound, not an estimate', () => {
   });
 
   test('the steps share one budget rather than each getting a full one', async () => {
+    const started: string[] = [];
+    const hangingClose = (name: string) => () => {
+      started.push(name);
+      return new Promise<void>(() => undefined);
+    };
+    const names = Array.from({ length: 10 }, (_, index) => `resource-${index + 1}`);
     const result = await closeWithinBudget(
-      [
-        { name: 'MCP', close: () => new Promise<void>(() => undefined) },
-        { name: 'database', close: () => new Promise<void>(() => undefined) },
-      ],
+      names.map((name) => ({ name, close: hangingClose(name) })),
       25,
     );
-    expect(result.unfinished).toEqual(['MCP', 'database']);
-    // Two steps, one budget: about one budget of wall clock, not two.
-    expect(result.durationMs).toBeLessThan(50);
+    expect(result.unfinished).toEqual(names);
+    // Timer rounding may let one close start on a sub-millisecond remainder,
+    // so no exact boundary is contractual. What a fresh per-step budget would
+    // do is start every close; one shared deadline must skip at least one. This
+    // proves the state transition directly without treating scheduler latency
+    // as a product failure.
+    expect(started.length).toBeLessThan(names.length);
   });
 
   test('a close that fails is a failure, and keeps its cause', async () => {

package/templates/agent/README.md

@@ -0,0 +1,41 @@
+# Stitchkit Agent
+
+A small, real terminal coding agent. The official TUI package owns terminal interaction while
+Stitchkit owns durable messages, runs, direct typed tools, approvals, recovery and resources.
+
+## Start
+
+```bash
+cp .env.example .env
+# Fill OPENROUTER_API_KEY.
+bun run dev
+```
+
+Use `/model` to choose any live tool-capable model. Weekly popularity and benchmark facts stay
+separate in the catalog. File reads and searches run directly. Writes, patches and shell commands
+show an approval card bound to the exact durable tool call; press `Y` or `N`.
+
+Source edits restart the terminal host through `bun --watch`, while `.stitchkit/agent.sqlite`
+retains durable conversations and recovery evidence. Every launch opens a fresh conversation;
+use `/resume` to return to an earlier one. `/clear` starts clean without deleting the conversation
+you are leaving.
+
+## Shape
+
+- `stitchkit.agent.ts` — the small, typed composition point for theme, catalog and runtime policy.
+- `src/runtime.ts` — host policy and composition of published Stitchkit primitives.
+- `stitchkit-tui` — commands, transcript, model/session pickers and local attach protocol.
+- `instructions/` — eager instructions with explicit provenance.
+- `skills/*/SKILL.md` — lazily discoverable skills read through the direct `read_resource` tool.
+- `.stitchkit/` — ignored local durable state, session descriptors, bounded metadata diagnostics
+  and approval secret.
+
+While the TUI is open, `/status` shows its session ID. Another local process can submit through
+the same controller without racing the runtime:
+
+```bash
+bunx stitchkit-agent send --session SESSION_ID -- "Inspect the current project"
+```
+
+The coding root is a path boundary, not an operating-system sandbox. Run the process in a container
+or another isolated environment before granting it access to untrusted projects or executables.

package/templates/agent/_env.example

@@ -0,0 +1,4 @@
+# Create an API key at https://openrouter.ai/settings/keys
+OPENROUTER_API_KEY=
+# Optional: preselect this exact row when the live model picker opens.
+OPENROUTER_MODEL=

package/templates/agent/_gitignore

@@ -0,0 +1,6 @@
+node_modules/
+dist/
+.env
+.stitchkit/
+coverage/
+*.log

package/templates/agent/biome.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.5.10/schema.json",
+  "files": {
+    "includes": ["**", "!!node_modules", "!!dist", "!!project.json", "!!**/.stitchkit"]
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 96
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "single",
+      "jsxQuoteStyle": "single",
+      "trailingCommas": "all",
+      "semicolons": "always"
+    }
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "preset": "recommended",
+      "suspicious": {
+        "noExplicitAny": "error",
+        "noUnknownAttribute": "off"
+      }
+    }
+  }
+}

package/templates/agent/instructions/AGENTS.md

@@ -0,0 +1,9 @@
+# Agent workspace
+
+You are a coding agent working inside this generated project.
+
+- Inspect existing files before changing them.
+- Keep edits inside the workspace root.
+- Use direct file and shell tools; never claim a command succeeded without reading its result.
+- Ask for approval through the tool protocol when a write, patch, edit or shell command requires it.
+- Prefer the smallest coherent implementation and leave the workspace in a checked state.

package/templates/agent/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "stitchkit-agent-starter",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "catalog": {
+    "stitchkit-tui": "^0.1.1"
+  },
+  "scripts": {
+    "dev": "bun --watch src/index.ts",
+    "start": "bun src/index.ts",
+    "check": "bun x tsgo --noEmit",
+    "lint": "bun x biome check --error-on-warnings .",
+    "lint:fix": "bun x biome check --write .",
+    "test": "bun test",
+    "build": "bun build src/index.ts --outdir dist --target bun --packages external"
+  },
+  "dependencies": {
+    "@openrouter/ai-sdk-provider": "^3.0.0",
+    "ai": "^7.0.87",
+    "stitchkit": "file:../../../core",
+    "stitchkit-tui": "file:../../../tui",
+    "zod": "4.5.4"
+  },
+  "devDependencies": {
+    "@typescript/native-preview": "7.0.0-dev.20260707.2",
+    "@types/bun": "^1.4.0",
+    "@types/react": "^19.2.14",
+    "typescript": "^7.0.2"
+  },
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "packageManager": "bun@1.3.14"
+}

package/templates/agent/project.json

@@ -0,0 +1,45 @@
+{
+  "schemaVersion": 1,
+  "kind": "application",
+  "identity": {
+    "slug": "stitchkit-agent-starter",
+    "name": "Stitchkit Agent Starter",
+    "version": "0.1.0",
+    "description": {
+      "en": "A durable terminal coding agent built with Stitchkit."
+    }
+  },
+  "roles": [
+    {
+      "name": "agent",
+      "workingDirectory": ".",
+      "commands": {
+        "development": {
+          "executable": "bun",
+          "args": ["--watch", "src/index.ts"]
+        },
+        "production": {
+          "executable": "bun",
+          "args": ["dist/index.js"]
+        }
+      },
+      "drainFloorMs": 1000
+    }
+  ],
+  "requires": [],
+  "release": {},
+  "env": {
+    "variables": [
+      {
+        "name": "OPENROUTER_API_KEY",
+        "shape": "string",
+        "required": true
+      },
+      {
+        "name": "OPENROUTER_MODEL",
+        "shape": "string",
+        "required": false
+      }
+    ]
+  }
+}

package/templates/agent/skills/verify/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: verify
+description: Check a completed change with the project's own Bun scripts before reporting success.
+---
+
+# Verify
+
+Read `package.json`, choose the narrowest relevant script, run it with the direct shell tool and
+report the exact result. Use `bun run check` and `bun test` when the change affects shared types or
+behavior. Do not invent a green result from code inspection alone.

package/templates/agent/src/config.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+
+const EnvironmentSchema = z
+  .object({
+    OPENROUTER_API_KEY: z.string().min(1, 'OPENROUTER_API_KEY is required'),
+    OPENROUTER_MODEL: z.string().min(1).optional(),
+  })
+  .loose();
+
+export interface AgentConfig {
+  apiKey: string;
+  preferredModelId?: string;
+}
+
+export function readAgentConfig(environment: Record<string, string | undefined>): AgentConfig {
+  const result = EnvironmentSchema.safeParse(environment);
+  if (!result.success) {
+    const fields = [
+      ...new Set(
+        result.error.issues
+          .map((issue) => issue.path[0])
+          .filter((field) => field !== undefined),
+      ),
+    ];
+    throw new Error(`Missing or invalid configuration: ${fields.join(', ')}`);
+  }
+  const parsed = result.data;
+  return {
+    apiKey: parsed.OPENROUTER_API_KEY,
+    ...(parsed.OPENROUTER_MODEL && { preferredModelId: parsed.OPENROUTER_MODEL }),
+  };
+}

package/templates/agent/src/index.ts

@@ -0,0 +1,4 @@
+import { runAgentTui } from 'stitchkit-tui';
+import config from '../stitchkit.agent';
+
+await runAgentTui(config);

package/templates/agent/src/runtime.ts

@@ -0,0 +1,141 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import {
+  type AgentLanguageModelProvider,
+  type AgentModelCatalog,
+  type AgentModelSelectionStore,
+  createAgentObservability,
+  defineAgentProtocol,
+} from 'stitchkit/agent-runtime';
+import { createAgentCodingTools } from 'stitchkit/agent-runtime/coding-tools';
+import {
+  createAgentHarnessFileResources,
+  createHeadlessAgentHarness,
+} from 'stitchkit/agent-runtime/harness';
+import { openRouterProvider } from 'stitchkit/agent-runtime/openrouter';
+import { createBunSqliteAgentRuntimeStore } from 'stitchkit/agent-runtime/sqlite/bun';
+import { mountAgent } from 'stitchkit/tools';
+import type { AgentTuiDiagnostics } from 'stitchkit-tui';
+import { z } from 'zod';
+import type { AgentConfig } from './config';
+
+const InputMetadataSchema = z.object({ modelId: z.string().min(1) }).strict();
+
+async function persistentApprovalSecret(stateDirectory: string): Promise<string> {
+  const filename = path.join(stateDirectory, 'approval-secret');
+  await mkdir(stateDirectory, { recursive: true });
+  try {
+    return (await readFile(filename, 'utf8')).trim();
+  } catch (error) {
+    if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT')) throw error;
+  }
+  const secret = crypto.randomUUID();
+  try {
+    await writeFile(filename, `${secret}\n`, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+    return secret;
+  } catch (error) {
+    if (!(error instanceof Error && 'code' in error && error.code === 'EEXIST')) throw error;
+    return (await readFile(filename, 'utf8')).trim();
+  }
+}
+
+export async function createStarterHarness(
+  config: AgentConfig,
+  workspace: string,
+  options: {
+    catalog: AgentModelCatalog;
+    selections: AgentModelSelectionStore;
+    provider?: AgentLanguageModelProvider;
+    diagnostics: AgentTuiDiagnostics;
+  },
+) {
+  const stateDirectory = path.join(workspace, '.stitchkit');
+  await mkdir(stateDirectory, { recursive: true });
+  const resources = createAgentHarnessFileResources({
+    roots: [
+      { id: 'instructions', path: path.join(workspace, 'instructions'), kind: 'instruction' },
+      { id: 'skills', path: path.join(workspace, 'skills'), kind: 'skill' },
+    ],
+  });
+  const codingTools = createAgentCodingTools({
+    root: workspace,
+    authorize: () => true,
+    executables: {
+      bun: process.execPath,
+      git: Bun.which('git') ?? '/usr/bin/git',
+      rg: Bun.which('rg') ?? '/usr/bin/rg',
+    },
+  });
+  const provider = options.provider ?? openRouterProvider({ apiKey: config.apiKey });
+  const sqlite = createBunSqliteAgentRuntimeStore({
+    filename: path.join(stateDirectory, 'agent.sqlite'),
+    initialize: true,
+  });
+  const observability = createAgentObservability({
+    includeInternalCause: true,
+    write: (event) => options.diagnostics.write(event),
+  });
+  const harness = createHeadlessAgentHarness({
+    protocol: defineAgentProtocol({
+      context: z.object({}),
+      inputMetadata: InputMetadataSchema,
+      terminalAcceptance: 'require-output',
+    }),
+    store: sqlite.store,
+    observe: observability,
+    models: {
+      async resolve({ conversationId, run, snapshot }) {
+        const input = snapshot.messages.find(({ id }) => id === run.inputMessageIds[0]);
+        const metadata = InputMetadataSchema.safeParse(input?.metadata);
+        const selected = metadata.success
+          ? metadata.data.modelId
+          : (await options.selections.load(conversationId))?.modelId;
+        const entry = options.catalog.models.find(({ id }) => id === selected);
+        if (!entry) throw new Error('The selected model is stale or unavailable');
+        return {
+          descriptor: entry.descriptor,
+          model: provider.create(entry.descriptor.modelId),
+          ...(provider.normalizeUsage && { normalizeUsage: provider.normalizeUsage }),
+        };
+      },
+    },
+    resources: { load: () => resources.load() },
+    promptBudget: ({ contextWindow }) => ({
+      contextWindow,
+      reservedOutput: Math.min(8_192, Math.floor(contextWindow / 4)),
+      toolSchemas: { provenance: 'unavailable' },
+      attachments: { value: 0, provenance: 'measured' },
+      providerOverhead: { provenance: 'unavailable' },
+    }),
+    tools: (context) =>
+      mountAgent([], {
+        runtimeTools: [...codingTools, ...resources.runtimeTools],
+        lifecycle: context.toolFenceLifecycle,
+      }),
+    loop: {
+      maxSteps: 50,
+      checkpointEveryEvents: 10,
+      toolApproval: {
+        read_file: 'approved',
+        search_files: 'approved',
+        list_directory: 'approved',
+        glob: 'approved',
+        read_resource: 'approved',
+        write_file: 'user-approval',
+        edit_file: 'user-approval',
+        run_command: 'user-approval',
+      },
+      toolApprovalSecret: await persistentApprovalSecret(stateDirectory),
+    },
+  });
+  const managedHarness = {
+    ...harness,
+    async close(closeOptions?: Parameters<typeof harness.close>[0]) {
+      const result = await harness.close(closeOptions);
+      await observability.close();
+      await sqlite.close();
+      return result;
+    },
+  };
+  return { harness: managedHarness, conversations: sqlite.conversations };
+}

package/templates/agent/stitchkit.agent.ts

@@ -0,0 +1,15 @@
+import { openRouterModelCatalog } from 'stitchkit/agent-runtime/openrouter';
+import { defineAgentTui } from 'stitchkit-tui';
+import { readAgentConfig } from './src/config';
+import { createStarterHarness } from './src/runtime';
+
+const environment = readAgentConfig(Bun.env);
+
+export default defineAgentTui({
+  title: 'Stitchkit agent',
+  context: () => ({}),
+  modelCatalog: openRouterModelCatalog({ apiKey: environment.apiKey }),
+  ...(environment.preferredModelId && { preferredModelId: environment.preferredModelId }),
+  createRuntime: ({ catalog, selections, diagnostics }) =>
+    createStarterHarness(environment, process.cwd(), { catalog, selections, diagnostics }),
+});

package/templates/agent/tests/config.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, test } from 'bun:test';
+import { readAgentConfig } from '../src/config';
+
+describe('agent config', () => {
+  test('requires only an OpenRouter credential and accepts an optional preferred model', () => {
+    expect(() => readAgentConfig({})).toThrow(
+      'Missing or invalid configuration: OPENROUTER_API_KEY',
+    );
+    expect(readAgentConfig({ OPENROUTER_API_KEY: 'secret' })).toEqual({ apiKey: 'secret' });
+    expect(
+      readAgentConfig({
+        OPENROUTER_API_KEY: 'secret',
+        OPENROUTER_MODEL: 'provider/model',
+      }),
+    ).toEqual({ apiKey: 'secret', preferredModelId: 'provider/model' });
+  });
+});

package/templates/agent/tests/runtime.test.ts

@@ -0,0 +1,90 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { simulateReadableStream } from 'ai';
+import { MockLanguageModelV4 } from 'ai/test';
+import {
+  AgentModelCatalogSchema,
+  createMemoryAgentModelSelectionStore,
+} from 'stitchkit/agent-runtime';
+import { createStarterHarness } from '../src/runtime';
+
+const roots: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
+describe('Agent starter runtime', () => {
+  test('runs one model turn and reopens its durable transcript', async () => {
+    const workspace = await mkdtemp(path.join(tmpdir(), 'stitchkit-agent-starter-'));
+    roots.push(workspace);
+    await mkdir(path.join(workspace, 'instructions'));
+    await mkdir(path.join(workspace, 'skills'));
+    await writeFile(path.join(workspace, 'instructions/AGENTS.md'), 'Answer directly.\n');
+    const usage = {
+      inputTokens: { total: 1, noCache: 1, cacheRead: undefined, cacheWrite: undefined },
+      outputTokens: { total: 1, text: 1, reasoning: undefined },
+    };
+    const model = new MockLanguageModelV4({
+      doStream: {
+        stream: simulateReadableStream({
+          chunks: [
+            { type: 'text-start', id: 'answer' },
+            { type: 'text-delta', id: 'answer', delta: 'Ready to build.' },
+            { type: 'text-end', id: 'answer' },
+            { type: 'finish', finishReason: { unified: 'stop', raw: undefined }, usage },
+          ],
+        }),
+      },
+    });
+    const config = { apiKey: 'fixture' };
+    const descriptor = {
+      provider: 'fixture',
+      modelId: 'fixture/model',
+      contextWindow: 32_000,
+      capabilities: ['tools'],
+    };
+    const catalog = AgentModelCatalogSchema.parse({
+      schemaVersion: 1,
+      source: 'fixture',
+      observedAt: '2026-08-30T00:00:00.000Z',
+      completeness: 'complete',
+      diagnostics: [],
+      models: [{ id: 'fixture/model', name: 'Fixture', descriptor, metrics: [] }],
+    });
+    const selections = createMemoryAgentModelSelectionStore();
+    await selections.save('main', {
+      modelId: 'fixture/model',
+      selectedAt: '2026-08-30T00:00:00.000Z',
+    });
+    const provider = { create: () => model };
+    const diagnostics = { write: () => undefined };
+    const first = await createStarterHarness(config, workspace, {
+      catalog,
+      selections,
+      provider,
+      diagnostics,
+    });
+    const result = await first.harness.submit({
+      conversationId: 'main',
+      idempotencyKey: 'first',
+      context: {},
+      parts: [{ type: 'text', text: 'Hello' }],
+      metadata: { modelId: 'fixture/model' },
+    }).result;
+    expect(result.reason).toBe('success');
+    expect(result.message.parts).toContainEqual({ type: 'text', text: 'Ready to build.' });
+    await first.harness.close();
+
+    const reopened = await createStarterHarness(config, workspace, {
+      catalog,
+      selections,
+      provider,
+      diagnostics,
+    });
+    expect((await reopened.harness.snapshot('main')).messages).toHaveLength(2);
+    await reopened.harness.close();
+  });
+});

package/templates/agent/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "lib": ["ESNext", "DOM"],
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "jsxImportSource": "@opentui/react",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "skipLibCheck": true,
+    "types": ["bun"]
+  },
+  "include": ["src", "tests"]
+}