@nlindstedt/zag-agent 0.2.3

package/README.md

@@ -0,0 +1,110 @@
+# Zag TypeScript Binding
+
+TypeScript binding for [zag](https://github.com/niclaslindstedt/zag) — a unified CLI for AI coding agents.
+
+## Prerequisites
+
+- Node.js 18+
+- The `zag` CLI binary installed and on your `PATH` (or set via `ZAG_BIN` env var)
+
+## Installation
+
+```bash
+npm install @nlindstedt/zag-agent
+```
+
+### Development setup
+
+To work with the binding from source:
+
+```bash
+cd bindings/typescript
+npm install
+npm run build
+```
+
+## Quick start
+
+```typescript
+import { ZagBuilder } from "@nlindstedt/zag-agent";
+
+// Non-interactive execution
+const output = await new ZagBuilder()
+  .provider("claude")
+  .model("sonnet")
+  .autoApprove()
+  .exec("write a hello world program");
+
+console.log(output.result);
+```
+
+## Streaming
+
+```typescript
+import { ZagBuilder } from "@nlindstedt/zag-agent";
+
+// Stream events as they arrive (NDJSON)
+for await (const event of new ZagBuilder().provider("claude").stream("analyze code")) {
+  console.log(event.type, event);
+}
+```
+
+## Builder methods
+
+| Method | Description |
+|--------|-------------|
+| `.provider(name)` | Set provider: `"claude"`, `"codex"`, `"gemini"`, `"copilot"`, `"ollama"` |
+| `.model(name)` | Set model name or size alias (`"small"`, `"medium"`, `"large"`) |
+| `.systemPrompt(text)` | Set a system prompt |
+| `.root(path)` | Set the working directory |
+| `.autoApprove()` | Skip permission prompts |
+| `.addDir(path)` | Add an additional directory (chainable) |
+| `.json()` | Request JSON output |
+| `.jsonSchema(schema)` | Validate output against a JSON schema (implies `.json()`) |
+| `.jsonStream()` | Enable streaming NDJSON output |
+| `.worktree(name?)` | Run in an isolated git worktree |
+| `.sandbox(name?)` | Run in a Docker sandbox |
+| `.sessionId(uuid)` | Use a specific session ID |
+| `.outputFormat(fmt)` | Set output format (`"text"`, `"json"`, `"json-pretty"`, `"stream-json"`) |
+| `.inputFormat(fmt)` | Set input format (`"text"`, `"stream-json"` — Claude only) |
+| `.replayUserMessages()` | Re-emit user messages on stdout (Claude only) |
+| `.includePartialMessages()` | Include partial message chunks (Claude only) |
+| `.maxTurns(n)` | Set the maximum number of agentic turns |
+| `.showUsage()` | Show token usage statistics (JSON output mode) |
+| `.size(size)` | Set Ollama model parameter size (e.g., `"2b"`, `"9b"`, `"35b"`) |
+| `.verbose()` | Enable verbose output |
+| `.quiet()` | Suppress non-essential output |
+| `.debug()` | Enable debug logging |
+| `.bin(path)` | Override the `zag` binary path |
+
+## Terminal methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `.exec(prompt)` | `Promise<AgentOutput>` | Run non-interactively, return structured output |
+| `.stream(prompt)` | `AsyncGenerator<Event>` | Stream NDJSON events |
+| `.execStreaming(prompt)` | `StreamingSession` | Bidirectional streaming (Claude only) |
+| `.run(prompt?)` | `Promise<void>` | Start an interactive session (inherits stdio) |
+| `.resume(sessionId)` | `Promise<void>` | Resume a previous session by ID |
+| `.continueLast()` | `Promise<void>` | Resume the most recent session |
+
+## How it works
+
+The SDK spawns the `zag` CLI as a subprocess (`zag exec -o json` or `-o stream-json`) and parses the JSON/NDJSON output into typed models. Zero external runtime dependencies — only Node.js built-ins.
+
+## Testing
+
+```bash
+npm run build && npm test
+```
+
+## See also
+
+- [Python SDK](../python/README.md)
+- [C# SDK](../csharp/README.md)
+- [Rust API (zag-agent)](../../zag-agent/README.md)
+- [All bindings](../README.md)
+
+## License
+
+[MIT](../../LICENSE)

package/dist/src/builder.d.ts

@@ -0,0 +1,151 @@
+import type { AgentOutput, Event } from "./types.js";
+import type { StreamingSession } from "./process.js";
+/**
+ * Fluent builder for configuring and running zag agent sessions.
+ *
+ * @example
+ * ```ts
+ * import { ZagBuilder } from "zag-agent";
+ *
+ * const output = await new ZagBuilder()
+ *   .provider("claude")
+ *   .model("sonnet")
+ *   .autoApprove()
+ *   .exec("write a hello world program");
+ *
+ * console.log(output.result);
+ * ```
+ */
+export declare class ZagBuilder {
+    private _bin;
+    private _provider?;
+    private _model?;
+    private _systemPrompt?;
+    private _root?;
+    private _autoApprove;
+    private _addDirs;
+    private _json;
+    private _jsonSchema?;
+    private _jsonStream;
+    private _worktree?;
+    private _sandbox?;
+    private _verbose;
+    private _quiet;
+    private _debug;
+    private _sessionId?;
+    private _outputFormat?;
+    private _inputFormat?;
+    private _replayUserMessages;
+    private _includePartialMessages;
+    private _maxTurns?;
+    private _showUsage;
+    private _size?;
+    /** Override the zag binary path (default: `ZAG_BIN` env or `"zag"`). */
+    bin(path: string): this;
+    /** Set the provider (e.g., "claude", "codex", "gemini", "copilot", "ollama"). */
+    provider(p: string): this;
+    /** Set the model (e.g., "sonnet", "opus", "small", "large"). */
+    model(m: string): this;
+    /** Set a system prompt to configure agent behavior. */
+    systemPrompt(p: string): this;
+    /** Set the root directory for the agent to operate in. */
+    root(r: string): this;
+    /** Enable auto-approve mode (skip permission prompts). */
+    autoApprove(a?: boolean): this;
+    /** Add an additional directory for the agent to include. */
+    addDir(d: string): this;
+    /** Request JSON output from the agent. */
+    json(): this;
+    /** Set a JSON schema for structured output validation. Implies json(). */
+    jsonSchema(s: object): this;
+    /** Enable streaming JSON output (NDJSON format). */
+    jsonStream(): this;
+    /** Enable worktree mode with an optional name. */
+    worktree(name?: string): this;
+    /** Enable sandbox mode with an optional name. */
+    sandbox(name?: string): this;
+    /** Enable verbose output. */
+    verbose(v?: boolean): this;
+    /** Enable quiet mode. */
+    quiet(q?: boolean): this;
+    /** Enable debug logging. */
+    debug(d?: boolean): this;
+    /** Pre-set a session ID (UUID). */
+    sessionId(id: string): this;
+    /** Set the output format (e.g., "text", "json", "json-pretty", "stream-json"). */
+    outputFormat(f: string): this;
+    /** Set the input format (Claude only, e.g., "text", "stream-json"). */
+    inputFormat(f: string): this;
+    /** Re-emit user messages from stdin on stdout (Claude only). */
+    replayUserMessages(r?: boolean): this;
+    /** Include partial message chunks in streaming output (Claude only). */
+    includePartialMessages(i?: boolean): this;
+    /** Set the maximum number of agentic turns. */
+    maxTurns(n: number): this;
+    /** Show token usage statistics (only applies to JSON output mode). */
+    showUsage(s?: boolean): this;
+    /** Set the Ollama model parameter size (e.g., "2b", "9b", "35b"). */
+    size(s: string): this;
+    /** Build the shared CLI flags (before the subcommand). */
+    private buildGlobalArgs;
+    /** Build CLI args for exec mode. */
+    private buildExecArgs;
+    /**
+     * Run the agent non-interactively and return structured output.
+     *
+     * @example
+     * ```ts
+     * const output = await new ZagBuilder()
+     *   .provider("claude")
+     *   .exec("say hello");
+     * console.log(output.result);
+     * ```
+     */
+    exec(prompt: string): Promise<AgentOutput>;
+    /**
+     * Run the agent in streaming mode, yielding events as they arrive.
+     *
+     * @example
+     * ```ts
+     * for await (const event of new ZagBuilder()
+     *   .provider("claude")
+     *   .stream("analyze this code")) {
+     *   console.log(event.type);
+     * }
+     * ```
+     */
+    stream(prompt: string): AsyncGenerator<Event>;
+    /**
+     * Run the agent with streaming input and output (Claude only).
+     *
+     * Returns a StreamingSession with piped stdin for sending NDJSON messages
+     * and an async iterator for reading events. Automatically enables
+     * `--input-format stream-json`, `--replay-user-messages`, and
+     * `-o stream-json`.
+     *
+     * @example
+     * ```ts
+     * const session = new ZagBuilder()
+     *   .provider("claude")
+     *   .execStreaming("initial prompt");
+     *
+     * session.send('{"type":"user_message","content":"hello"}');
+     *
+     * for await (const event of session.events()) {
+     *   console.log(event.type);
+     * }
+     *
+     * await session.wait();
+     * ```
+     */
+    execStreaming(prompt: string): StreamingSession;
+    /**
+     * Start an interactive agent session.
+     * Inherits stdin/stdout/stderr.
+     */
+    run(prompt?: string): Promise<void>;
+    /** Resume a previous session by ID. */
+    resume(sessionId: string): Promise<void>;
+    /** Resume the most recent session. */
+    continueLast(): Promise<void>;
+}

package/dist/src/builder.js

@@ -0,0 +1,322 @@
+import { defaultBin, execZag, runZag, streamZag, streamWithInput, } from "./process.js";
+/**
+ * Fluent builder for configuring and running zag agent sessions.
+ *
+ * @example
+ * ```ts
+ * import { ZagBuilder } from "zag-agent";
+ *
+ * const output = await new ZagBuilder()
+ *   .provider("claude")
+ *   .model("sonnet")
+ *   .autoApprove()
+ *   .exec("write a hello world program");
+ *
+ * console.log(output.result);
+ * ```
+ */
+export class ZagBuilder {
+    _bin = defaultBin();
+    _provider;
+    _model;
+    _systemPrompt;
+    _root;
+    _autoApprove = false;
+    _addDirs = [];
+    _json = false;
+    _jsonSchema;
+    _jsonStream = false;
+    _worktree;
+    _sandbox;
+    _verbose = false;
+    _quiet = false;
+    _debug = false;
+    _sessionId;
+    _outputFormat;
+    _inputFormat;
+    _replayUserMessages = false;
+    _includePartialMessages = false;
+    _maxTurns;
+    _showUsage = false;
+    _size;
+    /** Override the zag binary path (default: `ZAG_BIN` env or `"zag"`). */
+    bin(path) {
+        this._bin = path;
+        return this;
+    }
+    /** Set the provider (e.g., "claude", "codex", "gemini", "copilot", "ollama"). */
+    provider(p) {
+        this._provider = p;
+        return this;
+    }
+    /** Set the model (e.g., "sonnet", "opus", "small", "large"). */
+    model(m) {
+        this._model = m;
+        return this;
+    }
+    /** Set a system prompt to configure agent behavior. */
+    systemPrompt(p) {
+        this._systemPrompt = p;
+        return this;
+    }
+    /** Set the root directory for the agent to operate in. */
+    root(r) {
+        this._root = r;
+        return this;
+    }
+    /** Enable auto-approve mode (skip permission prompts). */
+    autoApprove(a = true) {
+        this._autoApprove = a;
+        return this;
+    }
+    /** Add an additional directory for the agent to include. */
+    addDir(d) {
+        this._addDirs.push(d);
+        return this;
+    }
+    /** Request JSON output from the agent. */
+    json() {
+        this._json = true;
+        return this;
+    }
+    /** Set a JSON schema for structured output validation. Implies json(). */
+    jsonSchema(s) {
+        this._jsonSchema = s;
+        this._json = true;
+        return this;
+    }
+    /** Enable streaming JSON output (NDJSON format). */
+    jsonStream() {
+        this._jsonStream = true;
+        return this;
+    }
+    /** Enable worktree mode with an optional name. */
+    worktree(name) {
+        this._worktree = name ?? true;
+        return this;
+    }
+    /** Enable sandbox mode with an optional name. */
+    sandbox(name) {
+        this._sandbox = name ?? true;
+        return this;
+    }
+    /** Enable verbose output. */
+    verbose(v = true) {
+        this._verbose = v;
+        return this;
+    }
+    /** Enable quiet mode. */
+    quiet(q = true) {
+        this._quiet = q;
+        return this;
+    }
+    /** Enable debug logging. */
+    debug(d = true) {
+        this._debug = d;
+        return this;
+    }
+    /** Pre-set a session ID (UUID). */
+    sessionId(id) {
+        this._sessionId = id;
+        return this;
+    }
+    /** Set the output format (e.g., "text", "json", "json-pretty", "stream-json"). */
+    outputFormat(f) {
+        this._outputFormat = f;
+        return this;
+    }
+    /** Set the input format (Claude only, e.g., "text", "stream-json"). */
+    inputFormat(f) {
+        this._inputFormat = f;
+        return this;
+    }
+    /** Re-emit user messages from stdin on stdout (Claude only). */
+    replayUserMessages(r = true) {
+        this._replayUserMessages = r;
+        return this;
+    }
+    /** Include partial message chunks in streaming output (Claude only). */
+    includePartialMessages(i = true) {
+        this._includePartialMessages = i;
+        return this;
+    }
+    /** Set the maximum number of agentic turns. */
+    maxTurns(n) {
+        this._maxTurns = n;
+        return this;
+    }
+    /** Show token usage statistics (only applies to JSON output mode). */
+    showUsage(s = true) {
+        this._showUsage = s;
+        return this;
+    }
+    /** Set the Ollama model parameter size (e.g., "2b", "9b", "35b"). */
+    size(s) {
+        this._size = s;
+        return this;
+    }
+    /** Build the shared CLI flags (before the subcommand). */
+    buildGlobalArgs() {
+        const args = [];
+        if (this._provider)
+            args.push("-p", this._provider);
+        if (this._model)
+            args.push("--model", this._model);
+        if (this._systemPrompt)
+            args.push("--system-prompt", this._systemPrompt);
+        if (this._root)
+            args.push("--root", this._root);
+        if (this._autoApprove)
+            args.push("--auto-approve");
+        for (const d of this._addDirs)
+            args.push("--add-dir", d);
+        if (this._worktree === true) {
+            args.push("-w");
+        }
+        else if (typeof this._worktree === "string") {
+            args.push("-w", this._worktree);
+        }
+        if (this._sandbox === true) {
+            args.push("--sandbox");
+        }
+        else if (typeof this._sandbox === "string") {
+            args.push("--sandbox", this._sandbox);
+        }
+        if (this._verbose)
+            args.push("--verbose");
+        if (this._quiet)
+            args.push("--quiet");
+        if (this._debug)
+            args.push("--debug");
+        if (this._sessionId)
+            args.push("--session", this._sessionId);
+        if (this._maxTurns != null)
+            args.push("--max-turns", String(this._maxTurns));
+        if (this._showUsage)
+            args.push("--show-usage");
+        if (this._size)
+            args.push("--size", this._size);
+        return args;
+    }
+    /** Build CLI args for exec mode. */
+    buildExecArgs(prompt, streaming) {
+        const args = this.buildGlobalArgs();
+        args.push("exec");
+        if (this._json)
+            args.push("--json");
+        if (this._jsonSchema) {
+            args.push("--json-schema", JSON.stringify(this._jsonSchema));
+        }
+        if (this._jsonStream || streaming)
+            args.push("--json-stream");
+        if (this._outputFormat)
+            args.push("-o", this._outputFormat);
+        if (this._inputFormat)
+            args.push("-i", this._inputFormat);
+        if (this._replayUserMessages)
+            args.push("--replay-user-messages");
+        if (this._includePartialMessages)
+            args.push("--include-partial-messages");
+        // For non-streaming exec, default to json output for structured parsing
+        if (!streaming && !this._outputFormat && !this._jsonStream) {
+            args.push("-o", "json");
+        }
+        args.push(prompt);
+        return args;
+    }
+    /**
+     * Run the agent non-interactively and return structured output.
+     *
+     * @example
+     * ```ts
+     * const output = await new ZagBuilder()
+     *   .provider("claude")
+     *   .exec("say hello");
+     * console.log(output.result);
+     * ```
+     */
+    async exec(prompt) {
+        const args = this.buildExecArgs(prompt, false);
+        return execZag(this._bin, args);
+    }
+    /**
+     * Run the agent in streaming mode, yielding events as they arrive.
+     *
+     * @example
+     * ```ts
+     * for await (const event of new ZagBuilder()
+     *   .provider("claude")
+     *   .stream("analyze this code")) {
+     *   console.log(event.type);
+     * }
+     * ```
+     */
+    async *stream(prompt) {
+        const args = this.buildExecArgs(prompt, true);
+        yield* streamZag(this._bin, args);
+    }
+    /**
+     * Run the agent with streaming input and output (Claude only).
+     *
+     * Returns a StreamingSession with piped stdin for sending NDJSON messages
+     * and an async iterator for reading events. Automatically enables
+     * `--input-format stream-json`, `--replay-user-messages`, and
+     * `-o stream-json`.
+     *
+     * @example
+     * ```ts
+     * const session = new ZagBuilder()
+     *   .provider("claude")
+     *   .execStreaming("initial prompt");
+     *
+     * session.send('{"type":"user_message","content":"hello"}');
+     *
+     * for await (const event of session.events()) {
+     *   console.log(event.type);
+     * }
+     *
+     * await session.wait();
+     * ```
+     */
+    execStreaming(prompt) {
+        const args = this.buildGlobalArgs();
+        args.push("exec");
+        args.push("-i", "stream-json");
+        args.push("-o", "stream-json");
+        args.push("--replay-user-messages");
+        if (this._includePartialMessages)
+            args.push("--include-partial-messages");
+        if (this._outputFormat)
+            args.push("-o", this._outputFormat);
+        args.push(prompt);
+        return streamWithInput(this._bin, args);
+    }
+    /**
+     * Start an interactive agent session.
+     * Inherits stdin/stdout/stderr.
+     */
+    async run(prompt) {
+        const args = this.buildGlobalArgs();
+        args.push("run");
+        if (this._json)
+            args.push("--json");
+        if (this._jsonSchema) {
+            args.push("--json-schema", JSON.stringify(this._jsonSchema));
+        }
+        if (prompt)
+            args.push(prompt);
+        return runZag(this._bin, args);
+    }
+    /** Resume a previous session by ID. */
+    async resume(sessionId) {
+        const args = this.buildGlobalArgs();
+        args.push("run", "--resume", sessionId);
+        return runZag(this._bin, args);
+    }
+    /** Resume the most recent session. */
+    async continueLast() {
+        const args = this.buildGlobalArgs();
+        args.push("run", "--continue");
+        return runZag(this._bin, args);
+    }
+}

package/dist/src/index.d.ts

@@ -0,0 +1,3 @@
+export { ZagBuilder } from "./builder.js";
+export type { AgentOutput, Usage, Event, InitEvent, AssistantMessageEvent, ToolExecutionEvent, ResultEvent, ErrorEvent, PermissionRequestEvent, ContentBlock, TextBlock, ToolUseBlock, ToolResult, } from "./types.js";
+export { ZagError } from "./types.js";

package/dist/src/index.js

@@ -0,0 +1,2 @@
+export { ZagBuilder } from "./builder.js";
+export { ZagError } from "./types.js";

package/dist/src/process.d.ts

@@ -0,0 +1,39 @@
+import type { AgentOutput, Event } from "./types.js";
+/** Default binary name — override with `ZAG_BIN` env var or builder option. */
+export declare function defaultBin(): string;
+/**
+ * Run `zag` and collect stdout as a parsed `AgentOutput`.
+ * Throws `ZagError` on non-zero exit.
+ */
+export declare function execZag(bin: string, args: string[]): Promise<AgentOutput>;
+/**
+ * Run `zag` in streaming mode and yield parsed `Event` objects (NDJSON).
+ */
+export declare function streamZag(bin: string, args: string[]): AsyncGenerator<Event>;
+/**
+ * A live streaming session with piped stdin and stdout.
+ *
+ * Send NDJSON messages via `send()`, read events via `events()`,
+ * then call `wait()` when done.
+ */
+export interface StreamingSession {
+    /** Send a raw NDJSON line to the agent's stdin. */
+    send(message: string): void;
+    /** Send a user message to the agent. */
+    sendUserMessage(content: string): void;
+    /** Close stdin to signal no more input. */
+    closeInput(): void;
+    /** Async iterator over parsed Event objects from stdout. */
+    events(): AsyncGenerator<Event>;
+    /** Wait for the process to exit. Throws ZagError on non-zero exit. */
+    wait(): Promise<void>;
+}
+/**
+ * Spawn `zag` with piped stdin and stdout for bidirectional streaming.
+ */
+export declare function streamWithInput(bin: string, args: string[]): StreamingSession;
+/**
+ * Run `zag` interactively with inherited stdio.
+ * Returns when the process exits.
+ */
+export declare function runZag(bin: string, args: string[]): Promise<void>;

package/dist/src/process.js

@@ -0,0 +1,134 @@
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import { ZagError } from "./types.js";
+/** Default binary name — override with `ZAG_BIN` env var or builder option. */
+export function defaultBin() {
+    return process.env.ZAG_BIN ?? "zag";
+}
+/**
+ * Run `zag` and collect stdout as a parsed `AgentOutput`.
+ * Throws `ZagError` on non-zero exit.
+ */
+export async function execZag(bin, args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(bin, args, { stdio: ["ignore", "pipe", "pipe"] });
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        child.stdout.on("data", (chunk) => stdoutChunks.push(chunk));
+        child.stderr.on("data", (chunk) => stderrChunks.push(chunk));
+        child.on("error", (err) => {
+            reject(new ZagError(`Failed to spawn '${bin}': ${err.message}`, null, Buffer.concat(stderrChunks).toString()));
+        });
+        child.on("close", (code) => {
+            const stdout = Buffer.concat(stdoutChunks).toString();
+            const stderr = Buffer.concat(stderrChunks).toString();
+            if (code !== 0) {
+                reject(new ZagError(`zag exited with code ${code}: ${stderr || stdout}`, code, stderr));
+                return;
+            }
+            try {
+                const output = JSON.parse(stdout);
+                resolve(output);
+            }
+            catch {
+                reject(new ZagError(`Failed to parse zag JSON output: ${stdout.slice(0, 200)}`, code, stderr));
+            }
+        });
+    });
+}
+/**
+ * Run `zag` in streaming mode and yield parsed `Event` objects (NDJSON).
+ */
+export async function* streamZag(bin, args) {
+    const child = spawn(bin, args, { stdio: ["ignore", "pipe", "pipe"] });
+    const stderrChunks = [];
+    child.stderr.on("data", (chunk) => stderrChunks.push(chunk));
+    const rl = createInterface({ input: child.stdout });
+    for await (const line of rl) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const event = JSON.parse(trimmed);
+            yield event;
+        }
+        catch {
+            // Skip unparseable lines
+        }
+    }
+    const exitCode = await new Promise((resolve) => {
+        child.on("close", resolve);
+    });
+    if (exitCode !== 0) {
+        const stderr = Buffer.concat(stderrChunks).toString();
+        throw new ZagError(`zag exited with code ${exitCode}`, exitCode, stderr);
+    }
+}
+/**
+ * Spawn `zag` with piped stdin and stdout for bidirectional streaming.
+ */
+export function streamWithInput(bin, args) {
+    const child = spawn(bin, args, { stdio: ["pipe", "pipe", "pipe"] });
+    const stderrChunks = [];
+    child.stderr.on("data", (chunk) => stderrChunks.push(chunk));
+    return {
+        send(message) {
+            child.stdin.write(message + "\n");
+        },
+        sendUserMessage(content) {
+            const msg = JSON.stringify({ type: "user_message", content });
+            child.stdin.write(msg + "\n");
+        },
+        closeInput() {
+            child.stdin.end();
+        },
+        async *events() {
+            const rl = createInterface({ input: child.stdout });
+            for await (const line of rl) {
+                const trimmed = line.trim();
+                if (!trimmed)
+                    continue;
+                try {
+                    const event = JSON.parse(trimmed);
+                    yield event;
+                }
+                catch {
+                    // Skip unparseable lines
+                }
+            }
+        },
+        wait() {
+            return new Promise((resolve, reject) => {
+                child.on("close", (code) => {
+                    if (code !== 0) {
+                        const stderr = Buffer.concat(stderrChunks).toString();
+                        reject(new ZagError(`zag exited with code ${code}`, code, stderr));
+                    }
+                    else {
+                        resolve();
+                    }
+                });
+            });
+        },
+    };
+}
+/**
+ * Run `zag` interactively with inherited stdio.
+ * Returns when the process exits.
+ */
+export async function runZag(bin, args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(bin, args, { stdio: "inherit" });
+        child.on("error", (err) => {
+            reject(new ZagError(`Failed to spawn '${bin}': ${err.message}`, null, ""));
+        });
+        child.on("close", (code) => {
+            if (code !== 0) {
+                reject(new ZagError(`zag exited with code ${code}`, code, ""));
+            }
+            else {
+                resolve();
+            }
+        });
+    });
+}

package/dist/src/types.d.ts

@@ -0,0 +1,87 @@
+/** Unified output from an agent session. */
+export interface AgentOutput {
+    agent: string;
+    session_id: string;
+    events: Event[];
+    result: string | null;
+    is_error: boolean;
+    total_cost_usd: number | null;
+    usage: Usage | null;
+}
+/** Usage statistics for an agent session. */
+export interface Usage {
+    input_tokens: number;
+    output_tokens: number;
+    cache_read_tokens?: number;
+    cache_creation_tokens?: number;
+    web_search_requests?: number;
+    web_fetch_requests?: number;
+}
+/** A single event in an agent session (tagged union on `type`). */
+export type Event = InitEvent | UserMessageEvent | AssistantMessageEvent | ToolExecutionEvent | ResultEvent | ErrorEvent | PermissionRequestEvent;
+export interface InitEvent {
+    type: "init";
+    model: string;
+    tools: string[];
+    working_directory: string | null;
+    metadata: Record<string, unknown>;
+}
+export interface UserMessageEvent {
+    type: "user_message";
+    content: ContentBlock[];
+}
+export interface AssistantMessageEvent {
+    type: "assistant_message";
+    content: ContentBlock[];
+    usage: Usage | null;
+}
+export interface ToolExecutionEvent {
+    type: "tool_execution";
+    tool_name: string;
+    tool_id: string;
+    input: unknown;
+    result: ToolResult;
+}
+export interface ResultEvent {
+    type: "result";
+    success: boolean;
+    message: string | null;
+    duration_ms: number | null;
+    num_turns: number | null;
+}
+export interface ErrorEvent {
+    type: "error";
+    message: string;
+    details: unknown | null;
+}
+export interface PermissionRequestEvent {
+    type: "permission_request";
+    tool_name: string;
+    description: string;
+    granted: boolean;
+}
+/** A block of content in an assistant message. */
+export type ContentBlock = TextBlock | ToolUseBlock;
+export interface TextBlock {
+    type: "text";
+    text: string;
+}
+export interface ToolUseBlock {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: unknown;
+}
+/** Result from a tool execution. */
+export interface ToolResult {
+    success: boolean;
+    output: string | null;
+    error: string | null;
+    data: unknown | null;
+}
+/** Error thrown when the zag process fails. */
+export declare class ZagError extends Error {
+    readonly exitCode: number | null;
+    readonly stderr: string;
+    constructor(message: string, exitCode: number | null, stderr: string);
+}

package/dist/src/types.js

@@ -0,0 +1,11 @@
+/** Error thrown when the zag process fails. */
+export class ZagError extends Error {
+    exitCode;
+    stderr;
+    constructor(message, exitCode, stderr) {
+        super(message);
+        this.exitCode = exitCode;
+        this.stderr = stderr;
+        this.name = "ZagError";
+    }
+}

package/dist/tests/builder.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/builder.test.js

@@ -0,0 +1,133 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { ZagBuilder } from "../src/builder.js";
+import { ZagError } from "../src/types.js";
+describe("ZagBuilder", () => {
+    it("should construct with defaults", () => {
+        const builder = new ZagBuilder();
+        assert.ok(builder);
+    });
+    it("should support method chaining", () => {
+        const builder = new ZagBuilder()
+            .provider("claude")
+            .model("sonnet")
+            .systemPrompt("You are helpful")
+            .root("/tmp/test")
+            .autoApprove()
+            .addDir("/extra")
+            .verbose()
+            .quiet()
+            .debug()
+            .sessionId("abc-123")
+            .maxTurns(5)
+            .showUsage()
+            .size("9b");
+        assert.ok(builder);
+    });
+    it("should support json options", () => {
+        const builder = new ZagBuilder()
+            .json()
+            .jsonSchema({ type: "object" })
+            .jsonStream();
+        assert.ok(builder);
+    });
+    it("should support isolation modes", () => {
+        const wt = new ZagBuilder().worktree();
+        assert.ok(wt);
+        const wtNamed = new ZagBuilder().worktree("my-feature");
+        assert.ok(wtNamed);
+        const sb = new ZagBuilder().sandbox();
+        assert.ok(sb);
+        const sbNamed = new ZagBuilder().sandbox("my-sandbox");
+        assert.ok(sbNamed);
+    });
+    it("should support bin override", () => {
+        const builder = new ZagBuilder().bin("/usr/local/bin/zag");
+        assert.ok(builder);
+    });
+});
+describe("ZagError", () => {
+    it("should contain exit code and stderr", () => {
+        const err = new ZagError("test error", 1, "stderr output");
+        assert.equal(err.message, "test error");
+        assert.equal(err.exitCode, 1);
+        assert.equal(err.stderr, "stderr output");
+        assert.equal(err.name, "ZagError");
+        assert.ok(err instanceof Error);
+    });
+});
+describe("AgentOutput type", () => {
+    it("should parse a sample JSON output", () => {
+        const raw = `{
+      "agent": "claude",
+      "session_id": "sess-123",
+      "events": [
+        {
+          "type": "init",
+          "model": "sonnet",
+          "tools": ["Bash", "Read"],
+          "working_directory": "/home/user",
+          "metadata": {}
+        },
+        {
+          "type": "assistant_message",
+          "content": [{"type": "text", "text": "Hello!"}],
+          "usage": {"input_tokens": 100, "output_tokens": 50}
+        },
+        {
+          "type": "tool_execution",
+          "tool_name": "Bash",
+          "tool_id": "tool_123",
+          "input": {"command": "echo hello"},
+          "result": {"success": true, "output": "hello", "error": null, "data": null}
+        },
+        {
+          "type": "result",
+          "success": true,
+          "message": "Done",
+          "duration_ms": 1500,
+          "num_turns": 2
+        }
+      ],
+      "result": "Hello!",
+      "is_error": false,
+      "total_cost_usd": 0.01,
+      "usage": {"input_tokens": 100, "output_tokens": 50}
+    }`;
+        const output = JSON.parse(raw);
+        assert.equal(output.agent, "claude");
+        assert.equal(output.session_id, "sess-123");
+        assert.equal(output.events.length, 4);
+        assert.equal(output.result, "Hello!");
+        assert.equal(output.is_error, false);
+        assert.equal(output.total_cost_usd, 0.01);
+        assert.equal(output.usage?.input_tokens, 100);
+        // Check event types
+        assert.equal(output.events[0].type, "init");
+        assert.equal(output.events[1].type, "assistant_message");
+        assert.equal(output.events[2].type, "tool_execution");
+        assert.equal(output.events[3].type, "result");
+    });
+});
+describe("Event parsing", () => {
+    it("should parse NDJSON events", () => {
+        const lines = [
+            '{"type":"init","model":"opus","tools":[],"working_directory":null,"metadata":{}}',
+            '{"type":"assistant_message","content":[{"type":"text","text":"Hi"}],"usage":null}',
+            '{"type":"error","message":"oops","details":null}',
+            '{"type":"permission_request","tool_name":"Bash","description":"run cmd","granted":true}',
+        ];
+        const events = lines.map((l) => JSON.parse(l));
+        assert.equal(events.length, 4);
+        assert.equal(events[0].type, "init");
+        assert.equal(events[1].type, "assistant_message");
+        assert.equal(events[2].type, "error");
+        if (events[2].type === "error") {
+            assert.equal(events[2].message, "oops");
+        }
+        assert.equal(events[3].type, "permission_request");
+        if (events[3].type === "permission_request") {
+            assert.equal(events[3].granted, true);
+        }
+    });
+});

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@nlindstedt/zag-agent",
+  "version": "0.2.3",
+  "description": "TypeScript SDK for zag — a unified CLI for AI coding agents",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "node --test dist/tests/builder.test.js",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "@types/node": "^20.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/niclaslindstedt/zag",
+    "directory": "bindings/typescript"
+  },
+  "keywords": [
+    "zag",
+    "ai",
+    "agent",
+    "claude",
+    "codex",
+    "gemini",
+    "copilot",
+    "ollama"
+  ]
+}