create-stitchkit 0.4.2 → 0.4.4

package/CHANGELOG.md

@@ -12,6 +12,46 @@ step is overwritten by the next release.
 
 ## [Unreleased]
 
+## [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
+
+- **Fresh projects use the current published Stitchkit line.** The template's
+  single catalog target is `^0.68.6`, and its frozen lockfile resolves exactly
+  `0.68.6`. A generated project therefore receives the current contract,
+  application and agent-runtime compatibility line instead of remaining below
+  `0.61.0` under pre-1.0 caret semantics.
+- **The repository variant carries its optional realtime client into browser
+  bundles.** Its `createRealtimeClient` composition supplies a literal
+  `socket.io-client` loader while preserving the framework target as the
+  template's single source of truth, so a packed scaffold resolves the optional
+  peer without adding a second framework range.
+
 ## [0.4.2] — 2026-08-25
 
 ### 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/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/frontend/src/lib/realtime/repository.ts

@@ -20,7 +20,14 @@ function buildSocket() {
   // browser actually dialled, read at connect time, exactly like the server
   // reads the request's origin. This function only ever runs in an effect.
   const url = optionalRealtimeOrigin() ?? window.location.origin;
-  return createRealtimeClient(repositoryRealtimeContract, { url });
+  // Keep this recipe source-compatible with the template's current published
+  // Stitchkit target: structural typing lets the older additive API ignore
+  // `peers`, while current Stitchkit consumes the literal loader.
+  const options = {
+    url,
+    peers: { client: () => import('socket.io-client') },
+  };
+  return createRealtimeClient(repositoryRealtimeContract, options);
 }
 
 function buildBridge() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-stitchkit",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "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.70.1",
     "typescript": "^7.0.2"
   },
   "engines": {

package/template/bun.lock

@@ -139,7 +139,7 @@
     },
   },
   "catalog": {
-    "stitchkit": "^0.60.1",
+    "stitchkit": "^0.70.1",
   },
   "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=="],
@@ -1118,7 +1118,7 @@
 
     "std-env": ["std-env@3.10.0", "", {}, "sha512-5GS12FdOZNliM5mAOxFRg7Ir0pWz8MdpYm6AY6VPkGpbA7ZzmbzNcBJQ0GPvvyWgcY7QAhCgf9Uy89I03faLkg=="],
 
-    "stitchkit": ["stitchkit@0.60.1", "", { "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-+ZXp+TaKuwBkOCT/8wpHFtRnaeoVIrzAnPFDGAVfjpN1tdP06Ve83cKV7aciMHHWrXmmy9EvenR004buhqn+Qg=="],
+    "stitchkit": ["stitchkit@0.70.1", "", { "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-UySE/DO1p7XZDmbISX3+U9RCYpepqsElovnL4IgUu0C9BpsFXGbYpoF0nL38vpY8SLV2frLiZXyy05gmmyrhrg=="],
 
     "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=="],
 

package/template/package.json

@@ -7,7 +7,7 @@
     "packages/*"
   ],
   "catalog": {
-    "stitchkit": "^0.60.1"
+    "stitchkit": "^0.70.1"
   },
   "scripts": {
     "dev": "bun scripts/dev.ts",

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": {
+    "stitchkit-tui": "file:../../../tui",
+    "@openrouter/ai-sdk-provider": "^3.0.0",
+    "ai": "^7.0.84",
+    "stitchkit": "file:../../../core",
+    "zod": "4.4.3"
+  },
+  "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,139 @@
+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',
+        read_resource: 'approved',
+        write_file: 'user-approval',
+        apply_patch: '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"]
+}