@ai-hero/sandcastle 0.1.8 → 0.2.1

package/README.md

@@ -49,9 +49,10 @@ npx tsx .sandcastle/main.ts
 
 ```typescript
 // 3. Run the agent via the JS API
-import { run } from "@ai-hero/sandcastle";
+import { run, claudeCode } from "@ai-hero/sandcastle";
 
 await run({
+  agent: claudeCode("claude-opus-4-6"),
   promptFile: ".sandcastle/prompt.md",
 });
 ```
@@ -61,9 +62,10 @@ await run({
 Sandcastle exports a programmatic `run()` function for use in scripts, CI pipelines, or custom tooling.
 
 ```typescript
-import { run } from "@ai-hero/sandcastle";
+import { run, claudeCode } from "@ai-hero/sandcastle";
 
 const result = await run({
+  agent: claudeCode("claude-opus-4-6"),
   promptFile: ".sandcastle/prompt.md",
 });
 
@@ -75,9 +77,12 @@ console.log(result.branch); // target branch name
 ### All options
 
 ```typescript
-import { run } from "@ai-hero/sandcastle";
+import { run, claudeCode } from "@ai-hero/sandcastle";
 
 const result = await run({
+  // Agent provider — required. Pass a model string to claudeCode().
+  agent: claudeCode("claude-opus-4-6"),
+
   // Prompt source — provide one of these, not both:
   promptFile: ".sandcastle/prompt.md", // path to a prompt file
   // prompt: "Fix issue #42 in this repo", // OR an inline prompt string
@@ -90,11 +95,11 @@ const result = await run({
   // Maximum number of agent iterations to run before stopping. Default: 1
   maxIterations: 5,
 
-  // Branch the agent commits to inside the sandbox.
-  branch: "agent/fix-42",
-
-  // Claude model passed to the agent. Default: "claude-opus-4-6"
-  model: "claude-opus-4-6",
+  // Worktree mode for sandbox work. Defaults to { mode: 'temp-branch' }.
+  // { mode: 'none' } — bind-mount host working directory directly (no worktree).
+  // { mode: 'temp-branch' } — create a temp worktree, merge back.
+  // { mode: 'branch', branch } — create a worktree on an explicit branch.
+  worktree: { mode: "branch", branch: "agent/fix-42" },
 
   // Docker image used for the sandbox. Default: "sandcastle:<repo-dir-name>"
   imageName: "sandcastle:local",
@@ -119,8 +124,8 @@ const result = await run({
   // Default: "<promise>COMPLETE</promise>"
   completionSignal: "<promise>COMPLETE</promise>",
 
-  // Idle timeout in seconds — resets whenever the agent produces output. Default: 300 (5 minutes)
-  idleTimeoutSeconds: 300,
+  // Idle timeout in seconds — resets whenever the agent produces output. Default: 600 (10 minutes)
+  idleTimeoutSeconds: 600,
 });
 
 console.log(result.iterationsRun); // number of iterations executed
@@ -129,6 +134,119 @@ console.log(result.commits); // array of { sha } for commits created
 console.log(result.branch); // target branch name
 ```
 
+### `createSandbox()` — reusable sandbox
+
+Use `createSandbox()` when you need to run multiple agents (or multiple rounds of the same agent) inside a single sandbox. It creates the worktree and container once, and you call `sandbox.run()` as many times as you need. This avoids repeated container startup costs and keeps all runs on the same branch.
+
+Use `run()` instead when you only need a single one-shot invocation — it handles sandbox lifecycle automatically.
+
+#### Basic single-run usage
+
+```typescript
+import { createSandbox, claudeCode } from "@ai-hero/sandcastle";
+
+await using sandbox = await createSandbox({
+  branch: "agent/fix-42",
+});
+
+const result = await sandbox.run({
+  agent: claudeCode("claude-opus-4-6"),
+  prompt: "Fix issue #42 in this repo.",
+});
+
+console.log(result.commits); // [{ sha: "abc123" }]
+```
+
+#### Multi-run implement-then-review
+
+```typescript
+import { createSandbox, claudeCode } from "@ai-hero/sandcastle";
+
+await using sandbox = await createSandbox({
+  branch: "agent/fix-42",
+  hooks: { onSandboxReady: [{ command: "npm install" }] },
+});
+
+// Step 1: implement
+const implResult = await sandbox.run({
+  agent: claudeCode("claude-opus-4-6"),
+  promptFile: ".sandcastle/implement.md",
+  maxIterations: 5,
+});
+
+// Step 2: review on the same branch, same container
+const reviewResult = await sandbox.run({
+  agent: claudeCode("claude-sonnet-4-6"),
+  prompt: "Review the changes and fix any issues.",
+});
+```
+
+Commits from all `run()` calls accumulate on the same branch. The sandbox container stays alive between runs, so installed dependencies and build artifacts persist.
+
+#### Automatic cleanup with `await using`
+
+`await using` calls `sandbox.close()` automatically when the block exits. If the worktree has uncommitted changes, it is preserved on disk; if clean, both container and worktree are removed.
+
+#### Manual `close()` with `CloseResult`
+
+```typescript
+const sandbox = await createSandbox({ branch: "agent/fix-42" });
+// ... run agents ...
+const closeResult = await sandbox.close();
+if (closeResult.preservedWorktreePath) {
+  console.log(`Worktree preserved at ${closeResult.preservedWorktreePath}`);
+}
+```
+
+#### `CreateSandboxOptions`
+
+| Option          | Type     | Default                      | Description                                                         |
+| --------------- | -------- | ---------------------------- | ------------------------------------------------------------------- |
+| `branch`        | string   | —                            | **Required.** Explicit branch for the worktree                      |
+| `imageName`     | string   | `sandcastle:<repo-dir-name>` | Docker image name                                                   |
+| `hooks`         | object   | —                            | Lifecycle hooks (`onSandboxReady`) — run once at creation time      |
+| `copyToSandbox` | string[] | —                            | Host-relative file paths to copy into the worktree at creation time |
+
+#### `Sandbox`
+
+| Property / Method       | Type                                               | Description                                 |
+| ----------------------- | -------------------------------------------------- | ------------------------------------------- |
+| `branch`                | string                                             | The branch the worktree is on               |
+| `worktreePath`          | string                                             | Host path to the worktree                   |
+| `run(options)`          | `(SandboxRunOptions) => Promise<SandboxRunResult>` | Invoke an agent inside the existing sandbox |
+| `close()`               | `() => Promise<CloseResult>`                       | Tear down the container and worktree        |
+| `[Symbol.asyncDispose]` | `() => Promise<void>`                              | Auto teardown via `await using`             |
+
+#### `SandboxRunOptions`
+
+| Option               | Type               | Default                       | Description                                                         |
+| -------------------- | ------------------ | ----------------------------- | ------------------------------------------------------------------- |
+| `agent`              | AgentProvider      | —                             | **Required.** Agent provider (e.g. `claudeCode("claude-opus-4-6")`) |
+| `prompt`             | string             | —                             | Inline prompt (mutually exclusive with `promptFile`)                |
+| `promptFile`         | string             | —                             | Path to prompt file (mutually exclusive with `prompt`)              |
+| `promptArgs`         | PromptArgs         | —                             | Key-value map for `{{KEY}}` placeholder substitution                |
+| `maxIterations`      | number             | `1`                           | Maximum iterations to run                                           |
+| `completionSignal`   | string \| string[] | `<promise>COMPLETE</promise>` | String(s) the agent emits to stop the iteration loop early          |
+| `idleTimeoutSeconds` | number             | `600`                         | Idle timeout in seconds — resets on each agent output event         |
+| `name`               | string             | —                             | Display name for the run                                            |
+| `logging`            | object             | file (auto-generated)         | `{ type: 'file', path }` or `{ type: 'stdout' }`                    |
+
+#### `SandboxRunResult`
+
+| Field              | Type        | Description                                                        |
+| ------------------ | ----------- | ------------------------------------------------------------------ |
+| `iterationsRun`    | number      | Number of iterations executed                                      |
+| `completionSignal` | string?     | The matched completion signal string, or `undefined` if none fired |
+| `stdout`           | string      | Combined agent output from all iterations                          |
+| `commits`          | `{ sha }[]` | Commits created during the run                                     |
+| `logFilePath`      | string?     | Path to the log file (only when logging to a file)                 |
+
+#### `CloseResult`
+
+| Field                   | Type    | Description                                                              |
+| ----------------------- | ------- | ------------------------------------------------------------------------ |
+| `preservedWorktreePath` | string? | Host path to the preserved worktree, set when it had uncommitted changes |
+
 ## How it works
 
 Sandcastle uses a worktree-based architecture for agent execution:
@@ -138,7 +256,7 @@ Sandcastle uses a worktree-based architecture for agent execution:
 - **No sync needed**: Because the agent writes directly to the host filesystem, there are no sync-in or sync-out operations. Commits made by the agent are immediately visible on the host.
 - **Merge back**: After the run completes, the temp worktree branch is fast-forward merged back to the target branch, and the worktree is cleaned up.
 
-From your point of view, you just run `sandcastle.run({ branch: 'foo' })`, and get a commit on branch `foo` once it's complete. All 100% local.
+From your point of view, you just run `sandcastle.run({ worktree: { mode: 'branch', branch: 'foo' } })`, and get a commit on branch `foo` once it's complete. All 100% local.
 
 ## Prompts
 
@@ -259,9 +377,12 @@ Select a template during `sandcastle init` when prompted, or re-run init in a fr
 
 Scaffolds the `.sandcastle/` config directory and builds the Docker image. This is the first command you run in a new repo.
 
-| Option         | Required | Default                      | Description       |
-| -------------- | -------- | ---------------------------- | ----------------- |
-| `--image-name` | No       | `sandcastle:<repo-dir-name>` | Docker image name |
+| Option         | Required | Default                      | Description                                                          |
+| -------------- | -------- | ---------------------------- | -------------------------------------------------------------------- |
+| `--image-name` | No       | `sandcastle:<repo-dir-name>` | Docker image name                                                    |
+| `--agent`      | No       | Interactive prompt           | Agent to use (`claude-code`, `pi`, `codex`)                          |
+| `--model`      | No       | Agent's default model        | Model to use (e.g. `claude-sonnet-4-6`). Defaults to agent's default |
+| `--template`   | No       | Interactive prompt           | Template to scaffold (e.g. `blank`, `simple-loop`)                   |
 
 Creates the following files:
 
@@ -270,7 +391,7 @@ Creates the following files:
 ├── Dockerfile      # Sandbox environment (customize as needed)
 ├── prompt.md       # Agent instructions
 ├── .env.example    # Token placeholders
-└── .gitignore      # Ignores .env, patches/, logs/
+└── .gitignore      # Ignores .env, logs/, worktrees/
 ```
 
 Errors if `.sandcastle/` already exists to prevent overwriting customizations.
@@ -294,21 +415,21 @@ Removes the Docker image.
 
 ### `RunOptions`
 
-| Option               | Type               | Default                       | Description                                                                 |
-| -------------------- | ------------------ | ----------------------------- | --------------------------------------------------------------------------- |
-| `prompt`             | string             | —                             | Inline prompt (mutually exclusive with `promptFile`)                        |
-| `promptFile`         | string             | —                             | Path to prompt file (mutually exclusive with `prompt`)                      |
-| `maxIterations`      | number             | `1`                           | Maximum iterations to run                                                   |
-| `hooks`              | object             | —                             | Lifecycle hooks (`onSandboxReady`)                                          |
-| `branch`             | string             | —                             | Target branch for sandbox work                                              |
-| `model`              | string             | `claude-opus-4-6`             | Model to use for the agent                                                  |
-| `imageName`          | string             | `sandcastle:<repo-dir-name>`  | Docker image name for the sandbox                                           |
-| `name`               | string             | —                             | Display name for the run, shown as a prefix in log output                   |
-| `promptArgs`         | PromptArgs         | —                             | Key-value map for `{{KEY}}` placeholder substitution                        |
-| `copyToSandbox`      | string[]           | —                             | Host-relative file paths to copy into the worktree before start             |
-| `logging`            | object             | file (auto-generated)         | `{ type: 'file', path }` or `{ type: 'stdout' }`                            |
-| `completionSignal`   | string \| string[] | `<promise>COMPLETE</promise>` | String or array of strings the agent emits to stop the iteration loop early |
-| `idleTimeoutSeconds` | number             | `300`                         | Idle timeout in seconds — resets on each agent output event                 |
+| Option               | Type               | Default                       | Description                                                                                                             |
+| -------------------- | ------------------ | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `agent`              | AgentProvider      | —                             | **Required.** Agent provider (e.g. `claudeCode("claude-opus-4-6")`, `pi("claude-sonnet-4-6")`, `codex("gpt-5.4-mini")`) |
+| `prompt`             | string             | —                             | Inline prompt (mutually exclusive with `promptFile`)                                                                    |
+| `promptFile`         | string             | —                             | Path to prompt file (mutually exclusive with `prompt`)                                                                  |
+| `maxIterations`      | number             | `1`                           | Maximum iterations to run                                                                                               |
+| `hooks`              | object             | —                             | Lifecycle hooks (`onSandboxReady`)                                                                                      |
+| `worktree`           | WorktreeMode       | `{ mode: 'temp-branch' }`     | Worktree mode: `{ mode: 'none' }`, `{ mode: 'temp-branch' }`, or `{ mode: 'branch', branch }`                           |
+| `imageName`          | string             | `sandcastle:<repo-dir-name>`  | Docker image name for the sandbox                                                                                       |
+| `name`               | string             | —                             | Display name for the run, shown as a prefix in log output                                                               |
+| `promptArgs`         | PromptArgs         | —                             | Key-value map for `{{KEY}}` placeholder substitution                                                                    |
+| `copyToSandbox`      | string[]           | —                             | Host-relative file paths to copy into the worktree before start (not supported with `mode: 'none'`)                     |
+| `logging`            | object             | file (auto-generated)         | `{ type: 'file', path }` or `{ type: 'stdout' }`                                                                        |
+| `completionSignal`   | string \| string[] | `<promise>COMPLETE</promise>` | String or array of strings the agent emits to stop the iteration loop early                                             |
+| `idleTimeoutSeconds` | number             | `600`                         | Idle timeout in seconds — resets on each agent output event                                                             |
 
 ### `RunResult`
 

package/dist/AgentProvider.d.ts

@@ -1,8 +1,32 @@
+export interface TokenUsage {
+    readonly input_tokens: number;
+    readonly output_tokens: number;
+    readonly cache_read_input_tokens: number;
+    readonly cache_creation_input_tokens: number;
+    readonly total_cost_usd: number;
+    readonly num_turns: number;
+    readonly duration_ms: number;
+}
+export type ParsedStreamEvent = {
+    type: "text";
+    text: string;
+} | {
+    type: "result";
+    result: string;
+    usage: TokenUsage | null;
+} | {
+    type: "tool_call";
+    name: string;
+    args: string;
+};
 export interface AgentProvider {
     readonly name: string;
-    readonly envManifest: Record<string, string>;
-    readonly dockerfileTemplate: string;
+    buildPrintCommand(prompt: string): string;
+    buildInteractiveArgs(prompt: string): string[];
+    parseStreamLine(line: string): ParsedStreamEvent[];
 }
-export declare const claudeCodeProvider: AgentProvider;
-export declare const getAgentProvider: (name: string) => AgentProvider;
+export declare const DEFAULT_MODEL = "claude-opus-4-6";
+export declare const pi: (model: string) => AgentProvider;
+export declare const codex: (model: string) => AgentProvider;
+export declare const claudeCode: (model: string) => AgentProvider;
 //# sourceMappingURL=AgentProvider.d.ts.map

package/dist/AgentProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AgentProvider.d.ts","sourceRoot":"","sources":["../src/AgentProvider.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7C,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;CACrC;AAqCD,eAAO,MAAM,kBAAkB,EAAE,aAShC,CAAC;AAMF,eAAO,MAAM,gBAAgB,iCAQ5B,CAAC"}
+{"version":3,"file":"AgentProvider.d.ts","sourceRoot":"","sources":["../src/AgentProvider.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,uBAAuB,EAAE,MAAM,CAAC;IACzC,QAAQ,CAAC,2BAA2B,EAAE,MAAM,CAAC;IAC7C,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,MAAM,iBAAiB,GACzB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAA;CAAE,GAC5D;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAwFtD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1C,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC/C,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAAC;CACpD;AAED,eAAO,MAAM,aAAa,oBAAoB,CAAC;AAsD/C,eAAO,MAAM,EAAE,kCAcb,CAAC;AAwCH,eAAO,MAAM,KAAK,kCAchB,CAAC;AAMH,eAAO,MAAM,UAAU,kCAcrB,CAAC"}

package/dist/AgentProvider.js

@@ -1,54 +1,198 @@
-import { SANDBOX_WORKSPACE_DIR } from "./SandboxFactory.js";
-const CLAUDE_CODE_DOCKERFILE = `FROM node:22-bookworm
-
-# Install system dependencies
-RUN apt-get update && apt-get install -y \\
-  git \\
-  curl \\
-  jq \\
-  && rm -rf /var/lib/apt/lists/*
-
-# Install GitHub CLI
-RUN curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \\
-  | dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg \\
-  && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \\
-  | tee /etc/apt/sources.list.d/github-cli.list > /dev/null \\
-  && apt-get update && apt-get install -y gh \\
-  && rm -rf /var/lib/apt/lists/*
-
-# Create a non-root user for Claude to run as
-RUN useradd -m -s /bin/bash agent
-USER agent
-
-# Install Claude Code CLI
-RUN curl -fsSL https://claude.ai/install.sh | bash
-
-# Add Claude to PATH
-ENV PATH="/home/agent/.local/bin:$PATH"
-
-WORKDIR /home/agent
-
-# In worktree sandbox mode, Sandcastle bind-mounts the git worktree at ${SANDBOX_WORKSPACE_DIR}
-# and overrides the working directory to ${SANDBOX_WORKSPACE_DIR} at container start.
-# Structure your Dockerfile so that ${SANDBOX_WORKSPACE_DIR} can serve as the project root.
-ENTRYPOINT ["sleep", "infinity"]
-`;
-export const claudeCodeProvider = {
-    name: "claude-code",
-    envManifest: {
-        ANTHROPIC_API_KEY: "Anthropic API key",
-        GH_TOKEN: "GitHub personal access token",
-    },
-    dockerfileTemplate: CLAUDE_CODE_DOCKERFILE,
+const shellEscape = (s) => "'" + s.replace(/'/g, "'\\''") + "'";
+const extractUsage = (obj) => {
+    const usage = obj.usage;
+    if (!usage ||
+        typeof usage.input_tokens !== "number" ||
+        typeof usage.output_tokens !== "number") {
+        return null;
+    }
+    return {
+        input_tokens: usage.input_tokens,
+        output_tokens: usage.output_tokens,
+        cache_read_input_tokens: typeof usage.cache_read_input_tokens === "number"
+            ? usage.cache_read_input_tokens
+            : 0,
+        cache_creation_input_tokens: typeof usage.cache_creation_input_tokens === "number"
+            ? usage.cache_creation_input_tokens
+            : 0,
+        total_cost_usd: typeof obj.total_cost_usd === "number" ? obj.total_cost_usd : 0,
+        num_turns: typeof obj.num_turns === "number" ? obj.num_turns : 0,
+        duration_ms: typeof obj.duration_ms === "number" ? obj.duration_ms : 0,
+    };
+};
+/** Maps allowlisted tool names to the input field containing the display arg */
+const TOOL_ARG_FIELDS = {
+    Bash: "command",
+    WebSearch: "query",
+    WebFetch: "url",
+    Agent: "description",
+};
+const parseStreamJsonLine = (line) => {
+    if (!line.startsWith("{"))
+        return [];
+    try {
+        const obj = JSON.parse(line);
+        if (obj.type === "assistant" && Array.isArray(obj.message?.content)) {
+            const events = [];
+            const texts = [];
+            for (const block of obj.message.content) {
+                if (block.type === "text" && typeof block.text === "string") {
+                    texts.push(block.text);
+                }
+                else if (block.type === "tool_use" &&
+                    typeof block.name === "string" &&
+                    block.input !== undefined) {
+                    const argField = TOOL_ARG_FIELDS[block.name];
+                    if (argField === undefined)
+                        continue; // not allowlisted
+                    const argValue = block.input[argField];
+                    if (typeof argValue !== "string")
+                        continue; // missing/wrong arg field
+                    if (texts.length > 0) {
+                        events.push({ type: "text", text: texts.join("") });
+                        texts.length = 0;
+                    }
+                    events.push({
+                        type: "tool_call",
+                        name: block.name,
+                        args: argValue,
+                    });
+                }
+            }
+            if (texts.length > 0) {
+                events.push({ type: "text", text: texts.join("") });
+            }
+            return events;
+        }
+        if (obj.type === "result" && typeof obj.result === "string") {
+            return [{ type: "result", result: obj.result, usage: extractUsage(obj) }];
+        }
+    }
+    catch {
+        // Not valid JSON — skip
+    }
+    return [];
 };
-const AGENT_REGISTRY = {
-    "claude-code": claudeCodeProvider,
+export const DEFAULT_MODEL = "claude-opus-4-6";
+// ---------------------------------------------------------------------------
+// Pi agent provider
+// ---------------------------------------------------------------------------
+const parsePiStreamLine = (line) => {
+    if (!line.startsWith("{"))
+        return [];
+    try {
+        const obj = JSON.parse(line);
+        if (obj.type === "message_update" && Array.isArray(obj.content)) {
+            const texts = [];
+            for (const block of obj.content) {
+                if (block.type === "text_delta" && typeof block.text === "string") {
+                    texts.push(block.text);
+                }
+            }
+            if (texts.length > 0) {
+                return [{ type: "text", text: texts.join("") }];
+            }
+            return [];
+        }
+        if (obj.type === "tool_execution_start") {
+            const toolName = obj.tool_name;
+            if (typeof toolName !== "string")
+                return [];
+            const argField = TOOL_ARG_FIELDS[toolName];
+            if (argField === undefined)
+                return [];
+            const input = obj.input;
+            if (!input)
+                return [];
+            const argValue = input[argField];
+            if (typeof argValue !== "string")
+                return [];
+            return [{ type: "tool_call", name: toolName, args: argValue }];
+        }
+        if (obj.type === "agent_end" &&
+            typeof obj.last_assistant_message === "string") {
+            return [
+                {
+                    type: "result",
+                    result: obj.last_assistant_message,
+                    usage: extractUsage(obj),
+                },
+            ];
+        }
+    }
+    catch {
+        // Not valid JSON — skip
+    }
+    return [];
 };
-export const getAgentProvider = (name) => {
-    const provider = AGENT_REGISTRY[name];
-    if (!provider) {
-        throw new Error(`Unknown agent provider: "${name}". Available providers: ${Object.keys(AGENT_REGISTRY).join(", ")}`);
+export const pi = (model) => ({
+    name: "pi",
+    buildPrintCommand(prompt) {
+        return `pi -p --mode json --no-session --model ${shellEscape(model)} ${shellEscape(prompt)}`;
+    },
+    buildInteractiveArgs(_prompt) {
+        return ["pi", "--model", model];
+    },
+    parseStreamLine(line) {
+        return parsePiStreamLine(line);
+    },
+});
+// ---------------------------------------------------------------------------
+// Codex agent provider
+// ---------------------------------------------------------------------------
+const parseCodexStreamLine = (line) => {
+    if (!line.startsWith("{"))
+        return [];
+    try {
+        const obj = JSON.parse(line);
+        // item.completed with agent_message → text + result
+        if (obj.type === "item.completed" &&
+            obj.item?.type === "agent_message" &&
+            typeof obj.item.content === "string") {
+            const text = obj.item.content;
+            return [
+                { type: "text", text },
+                { type: "result", result: text, usage: extractUsage(obj) },
+            ];
+        }
+        // item.started with command_execution → tool call
+        if (obj.type === "item.started" &&
+            obj.item?.type === "command_execution" &&
+            typeof obj.item.command === "string") {
+            return [{ type: "tool_call", name: "Bash", args: obj.item.command }];
+        }
+        // turn.completed → skip
+    }
+    catch {
+        // Not valid JSON — skip
     }
-    return provider;
+    return [];
 };
+export const codex = (model) => ({
+    name: "codex",
+    buildPrintCommand(prompt) {
+        return `codex exec --json --dangerously-bypass-approvals-and-sandbox -m ${shellEscape(model)} ${shellEscape(prompt)}`;
+    },
+    buildInteractiveArgs(_prompt) {
+        return ["codex", "--model", model];
+    },
+    parseStreamLine(line) {
+        return parseCodexStreamLine(line);
+    },
+});
+// ---------------------------------------------------------------------------
+// Claude Code agent provider
+// ---------------------------------------------------------------------------
+export const claudeCode = (model) => ({
+    name: "claude-code",
+    buildPrintCommand(prompt) {
+        return `claude --print --verbose --dangerously-skip-permissions --output-format stream-json --model ${shellEscape(model)} -p ${shellEscape(prompt)}`;
+    },
+    buildInteractiveArgs(_prompt) {
+        return ["claude", "--dangerously-skip-permissions", "--model", model];
+    },
+    parseStreamLine(line) {
+        return parseStreamJsonLine(line);
+    },
+});
 //# sourceMappingURL=AgentProvider.js.map

package/dist/AgentProvider.js.map

@@ -1 +1 @@
-{"version":3,"file":"AgentProvider.js","sourceRoot":"","sources":["../src/AgentProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAQ5D,MAAM,sBAAsB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;yEA6B0C,qBAAqB;2CACnD,qBAAqB;sCAC1B,qBAAqB;;CAE1D,CAAC;AAEF,MAAM,CAAC,MAAM,kBAAkB,GAAkB;IAC/C,IAAI,EAAE,aAAa;IAEnB,WAAW,EAAE;QACX,iBAAiB,EAAE,mBAAmB;QACtC,QAAQ,EAAE,8BAA8B;KACzC;IAED,kBAAkB,EAAE,sBAAsB;CAC3C,CAAC;AAEF,MAAM,cAAc,GAAkC;IACpD,aAAa,EAAE,kBAAkB;CAClC,CAAC;AAEF,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,IAAY,EAAiB,EAAE;IAC9D,MAAM,QAAQ,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IACtC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CACb,4BAA4B,IAAI,2BAA2B,MAAM,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACpG,CAAC;IACJ,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC,CAAC"}
+{"version":3,"file":"AgentProvider.js","sourceRoot":"","sources":["../src/AgentProvider.ts"],"names":[],"mappings":"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"}

package/dist/InitService.d.ts

@@ -1,11 +1,24 @@
 import { FileSystem } from "@effect/platform";
 import { Effect } from "effect";
-import type { AgentProvider } from "./AgentProvider.js";
 export interface TemplateMetadata {
     name: string;
     description: string;
 }
 export declare const listTemplates: () => TemplateMetadata[];
-export declare function getNextStepsLines(template: string, provider: AgentProvider): string[];
-export declare const scaffold: (repoDir: string, provider: AgentProvider, templateName?: string) => Effect.Effect<void, Error, FileSystem.FileSystem>;
+export interface AgentEntry {
+    readonly name: string;
+    readonly label: string;
+    readonly defaultModel: string;
+    readonly factoryImport: string;
+    readonly dockerfileTemplate: string;
+}
+export declare const listAgents: () => AgentEntry[];
+export declare const getAgent: (name: string) => AgentEntry | undefined;
+export declare function getNextStepsLines(template: string): string[];
+export interface ScaffoldOptions {
+    agent: AgentEntry;
+    model: string;
+    templateName?: string;
+}
+export declare const scaffold: (repoDir: string, options: ScaffoldOptions) => Effect.Effect<void, Error, FileSystem.FileSystem>;
 //# sourceMappingURL=InitService.d.ts.map

package/dist/InitService.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"InitService.d.ts","sourceRoot":"","sources":["../src/InitService.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAGhC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAOxD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;CACrB;AAuBD,eAAO,MAAM,aAAa,0BAAsC,CAAC;AAEjE,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,aAAa,GACtB,MAAM,EAAE,CAyBV;AAyDD,eAAO,MAAM,QAAQ,wHA+CjB,CAAC"}
+{"version":3,"file":"InitService.d.ts","sourceRoot":"","sources":["../src/InitService.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAUhC,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;CACrB;AAuBD,eAAO,MAAM,aAAa,0BAAsC,CAAC;AAMjE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;CACrC;AA+HD,eAAO,MAAM,UAAU,oBAAqC,CAAC;AAE7D,eAAO,MAAM,QAAQ,0CACwB,CAAC;AAM9C,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAoB5D;AAmGD,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,UAAU,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,eAAO,MAAM,QAAQ,kGA4CjB,CAAC"}