agent-bundle 0.1.0

package/dist/test-helpers/mock-agent.d.ts

@@ -0,0 +1,56 @@
+import type { ResponseEvent, ResponseInput, ResponseOutput } from "../agent-loop/types.js";
+import type { Agent, AgentStatus, RespondStreamOptions } from "../agent/types.js";
+export type DemoScenarioStep = {
+    type: "text";
+    content: string;
+    delayMs?: number;
+} | {
+    type: "tool_call";
+    name: string;
+    delayMs?: number;
+} | {
+    type: "tool_result";
+    output: string;
+    isError?: boolean;
+} | {
+    type: "tool_execution_update";
+    chunk: string;
+    delayMs?: number;
+} | {
+    type: "file_write";
+    path: string;
+    content: string;
+};
+export type DemoScenario = {
+    name: string;
+    description: string;
+    /** Keyword patterns to match user input against this scenario. */
+    triggers: string[];
+    steps: DemoScenarioStep[];
+};
+export type MockAgentOptions = {
+    name: string;
+    scenarios: DemoScenario[];
+    /** Fallback message when no scenario matches. */
+    fallbackMessage?: string;
+    /** Callback when agent "writes" a file (for sandbox sync). */
+    onFileWrite?: (path: string, content: string) => Promise<void>;
+};
+/**
+ * Mock agent for demo purposes. Does not call any LLM or sandbox.
+ * Instead, plays back scripted scenarios matching user input.
+ */
+export declare class MockAgent implements Agent {
+    readonly name: string;
+    private statusValue;
+    private readonly scenarios;
+    private readonly fallbackMessage;
+    private readonly onFileWrite?;
+    constructor(options: MockAgentOptions);
+    get status(): AgentStatus;
+    respond(input: ResponseInput): Promise<ResponseOutput>;
+    respondStream(input: ResponseInput, options?: RespondStreamOptions): AsyncIterable<ResponseEvent>;
+    shutdown(): Promise<void>;
+    private playScenario;
+    private streamText;
+}

package/dist/test-helpers/mock-agent.js

@@ -0,0 +1,180 @@
+import { randomUUID } from "node:crypto";
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function matchScenario(input, scenarios) {
+    const lowered = input.toLowerCase();
+    for (const scenario of scenarios) {
+        for (const trigger of scenario.triggers) {
+            if (lowered.includes(trigger.toLowerCase())) {
+                return scenario;
+            }
+        }
+    }
+    return null;
+}
+function extractUserText(input) {
+    for (let i = input.length - 1; i >= 0; i--) {
+        const msg = input[i];
+        if (msg.role !== "user")
+            continue;
+        // Plain string content (matches the declared type)
+        if (typeof msg.content === "string") {
+            return msg.content;
+        }
+        // The WebSocket handler passes unvalidated JSON, so at runtime content may
+        // be an array of input parts (e.g. [{ type: "input_text", text: "..." }]).
+        // Cast through unknown to handle this gracefully.
+        const raw = msg.content;
+        if (Array.isArray(raw)) {
+            for (const part of raw) {
+                if (typeof part === "object" &&
+                    part !== null &&
+                    part.type === "input_text" &&
+                    typeof part.text === "string") {
+                    return part.text;
+                }
+            }
+        }
+    }
+    return "";
+}
+/**
+ * Mock agent for demo purposes. Does not call any LLM or sandbox.
+ * Instead, plays back scripted scenarios matching user input.
+ */
+export class MockAgent {
+    name;
+    statusValue = "ready";
+    scenarios;
+    fallbackMessage;
+    onFileWrite;
+    constructor(options) {
+        this.name = options.name;
+        this.scenarios = options.scenarios;
+        this.fallbackMessage = options.fallbackMessage ??
+            "I'm a demo agent. Try asking me to analyze data, format code, or convert a document.";
+        this.onFileWrite = options.onFileWrite;
+    }
+    get status() {
+        return this.statusValue;
+    }
+    async respond(input) {
+        let output = null;
+        for await (const event of this.respondStream(input)) {
+            if (event.type === "response.completed") {
+                output = event.output;
+            }
+            if (event.type === "response.error") {
+                throw new Error(event.error);
+            }
+        }
+        if (!output) {
+            throw new Error("MockAgent did not produce a response.");
+        }
+        return output;
+    }
+    async *respondStream(input, options) {
+        const signal = options?.signal;
+        this.statusValue = "running";
+        const responseId = `mock-${randomUUID()}`;
+        try {
+            yield { type: "response.created", responseId };
+            const userText = extractUserText(input);
+            const scenario = matchScenario(userText, this.scenarios);
+            if (!scenario) {
+                yield* this.streamText(this.fallbackMessage, signal);
+            }
+            else {
+                yield* this.playScenario(scenario, signal);
+            }
+            const outputText = scenario
+                ? scenario.steps
+                    .filter((s) => s.type === "text")
+                    .map((s) => s.content)
+                    .join("")
+                : this.fallbackMessage;
+            const responseOutput = {
+                id: responseId,
+                output: outputText,
+            };
+            yield {
+                type: "response.completed",
+                output: responseOutput,
+            };
+        }
+        finally {
+            const currentStatus = this.statusValue;
+            if (currentStatus !== "stopped") {
+                this.statusValue = "ready";
+            }
+        }
+    }
+    async shutdown() {
+        this.statusValue = "stopped";
+    }
+    // ---------------------------------------------------------------------------
+    // Scenario playback
+    // ---------------------------------------------------------------------------
+    async *playScenario(scenario, signal) {
+        let toolCallCounter = 0;
+        for (const step of scenario.steps) {
+            if (signal?.aborted)
+                break;
+            switch (step.type) {
+                case "text":
+                    yield* this.streamText(step.content, signal, step.delayMs);
+                    break;
+                case "tool_call": {
+                    const callId = `mock-call-${++toolCallCounter}`;
+                    yield {
+                        type: "response.tool_call.created",
+                        toolCall: { id: callId, name: step.name, input: {} },
+                    };
+                    if (step.delayMs)
+                        await sleep(step.delayMs);
+                    break;
+                }
+                case "tool_result":
+                    yield {
+                        type: "response.tool_call.done",
+                        result: { toolCallId: `mock-call-${toolCallCounter}`, output: step.output, isError: step.isError ?? false },
+                    };
+                    break;
+                case "tool_execution_update":
+                    yield {
+                        type: "tool_execution_update",
+                        toolCallId: `mock-call-${toolCallCounter}`,
+                        chunk: step.chunk,
+                    };
+                    if (step.delayMs)
+                        await sleep(step.delayMs);
+                    break;
+                case "file_write":
+                    if (this.onFileWrite) {
+                        await this.onFileWrite(step.path, step.content);
+                    }
+                    break;
+            }
+        }
+    }
+    async *streamText(text, signal, delayMs) {
+        // Stream character by character for realistic typing effect
+        const chunkSize = 3;
+        for (let i = 0; i < text.length; i += chunkSize) {
+            if (signal?.aborted)
+                break;
+            const chunk = text.slice(i, i + chunkSize);
+            yield {
+                type: "response.output_text.delta",
+                delta: chunk,
+            };
+            await sleep(delayMs ?? 15);
+        }
+        yield {
+            type: "response.output_text.done",
+            text,
+        };
+    }
+}
+//# sourceMappingURL=mock-agent.js.map

package/dist/test-helpers/mock-agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-agent.js","sourceRoot":"","sources":["../../src/test-helpers/mock-agent.ts"],"names":[],"mappings":"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"}

package/dist/test-helpers/mock-sandbox.d.ts

@@ -0,0 +1,33 @@
+import type { ExecOptions, ExecResult, FileEntry, Sandbox, SandboxStatus } from "../sandbox/types.js";
+/**
+ * In-memory `Sandbox` implementation for testing and demo purposes.
+ *
+ * All file and directory operations run against internal `Map` / `Set`
+ * data structures -- no real filesystem or network access is involved.
+ */
+export declare class MockSandbox implements Sandbox {
+    readonly id: string;
+    private currentStatus;
+    private readonly files;
+    private readonly directories;
+    constructor();
+    get status(): SandboxStatus;
+    start(): Promise<void>;
+    shutdown(): Promise<void>;
+    exec(command: string, opts?: ExecOptions): Promise<ExecResult>;
+    readonly file: {
+        read: (path: string) => Promise<string>;
+        write: (path: string, content: string | Buffer) => Promise<void>;
+        list: (path: string) => Promise<FileEntry[]>;
+        delete: (path: string) => Promise<void>;
+    };
+    /**
+     * Seeds the in-memory filesystem with additional files.
+     *
+     * Keys are absolute paths; values are file contents.
+     * Ancestor directories are created automatically.
+     */
+    prePopulate(files: Record<string, string>): void;
+    private seedDefaults;
+    private assertReady;
+}

package/dist/test-helpers/mock-sandbox.js

@@ -0,0 +1,200 @@
+import { randomUUID } from "node:crypto";
+import { posix } from "node:path";
+const DEFAULT_FILES = {
+    "/workspace/README.md": [
+        "# Workspace",
+        "",
+        "This is the default sandbox workspace.",
+        "Place your project files here to get started.",
+        "",
+    ].join("\n"),
+};
+const DEFAULT_DIRECTORIES = ["/workspace", "/workspace/data"];
+/**
+ * Normalizes a filesystem path by resolving `.` and `..` segments
+ * and stripping any trailing slash (except for root `/`).
+ */
+function normalizePath(raw) {
+    const resolved = posix.normalize(raw);
+    return resolved.length > 1 && resolved.endsWith("/")
+        ? resolved.slice(0, -1)
+        : resolved;
+}
+/**
+ * Collects every ancestor directory of `filePath` (excluding root `/`).
+ *
+ * Example: `/workspace/data/report.csv` yields
+ * `["/workspace", "/workspace/data"]`.
+ */
+function ancestorDirectories(filePath) {
+    const ancestors = [];
+    let current = posix.dirname(filePath);
+    while (current !== "/") {
+        ancestors.push(current);
+        current = posix.dirname(current);
+    }
+    return ancestors;
+}
+/**
+ * In-memory `Sandbox` implementation for testing and demo purposes.
+ *
+ * All file and directory operations run against internal `Map` / `Set`
+ * data structures -- no real filesystem or network access is involved.
+ */
+export class MockSandbox {
+    id;
+    currentStatus = "idle";
+    files;
+    directories;
+    constructor() {
+        this.id = `mock-${randomUUID()}`;
+        this.files = new Map();
+        this.directories = new Set();
+        this.seedDefaults();
+    }
+    // ---------------------------------------------------------------------------
+    // Sandbox status
+    // ---------------------------------------------------------------------------
+    get status() {
+        return this.currentStatus;
+    }
+    async start() {
+        if (this.currentStatus === "ready") {
+            return;
+        }
+        if (this.currentStatus === "starting" || this.currentStatus === "stopping") {
+            throw new Error(`Cannot start mock sandbox while status is "${this.currentStatus}".`);
+        }
+        this.currentStatus = "starting";
+        this.currentStatus = "ready";
+    }
+    async shutdown() {
+        if (this.currentStatus === "stopped") {
+            return;
+        }
+        this.currentStatus = "stopping";
+        this.currentStatus = "stopped";
+    }
+    // ---------------------------------------------------------------------------
+    // exec
+    // ---------------------------------------------------------------------------
+    async exec(command, opts) {
+        void opts;
+        this.assertReady();
+        return {
+            stdout: `[mock] ${command}\n`,
+            stderr: "",
+            exitCode: 0,
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // file operations
+    // ---------------------------------------------------------------------------
+    file = {
+        read: async (path) => {
+            this.assertReady();
+            const normalized = normalizePath(path);
+            const content = this.files.get(normalized);
+            if (content === undefined) {
+                throw new Error(`ENOENT: no such file "${normalized}".`);
+            }
+            return content;
+        },
+        write: async (path, content) => {
+            this.assertReady();
+            const normalized = normalizePath(path);
+            const payload = typeof content === "string" ? content : content.toString("utf8");
+            // Ensure all ancestor directories exist.
+            for (const dir of ancestorDirectories(normalized)) {
+                this.directories.add(dir);
+            }
+            this.files.set(normalized, payload);
+        },
+        list: async (path) => {
+            this.assertReady();
+            const normalized = normalizePath(path);
+            if (!this.directories.has(normalized)) {
+                throw new Error(`ENOENT: no such directory "${normalized}".`);
+            }
+            const entries = [];
+            const seen = new Set();
+            // Collect direct child files.
+            for (const filePath of this.files.keys()) {
+                if (posix.dirname(filePath) === normalized) {
+                    const name = posix.basename(filePath);
+                    if (!seen.has(name)) {
+                        seen.add(name);
+                        entries.push({ name, path: filePath, type: "file" });
+                    }
+                }
+            }
+            // Collect direct child directories.
+            for (const dirPath of this.directories) {
+                if (posix.dirname(dirPath) === normalized) {
+                    const name = posix.basename(dirPath);
+                    if (!seen.has(name)) {
+                        seen.add(name);
+                        entries.push({ name, path: dirPath, type: "directory" });
+                    }
+                }
+            }
+            entries.sort((a, b) => a.name.localeCompare(b.name));
+            return entries;
+        },
+        delete: async (path) => {
+            this.assertReady();
+            const normalized = normalizePath(path);
+            // Delete exact file match.
+            this.files.delete(normalized);
+            // Recursively delete directory and everything beneath it.
+            if (this.directories.has(normalized)) {
+                const prefix = `${normalized}/`;
+                for (const filePath of [...this.files.keys()]) {
+                    if (filePath.startsWith(prefix)) {
+                        this.files.delete(filePath);
+                    }
+                }
+                for (const dirPath of [...this.directories]) {
+                    if (dirPath === normalized || dirPath.startsWith(prefix)) {
+                        this.directories.delete(dirPath);
+                    }
+                }
+            }
+        },
+    };
+    // ---------------------------------------------------------------------------
+    // Test-helper API
+    // ---------------------------------------------------------------------------
+    /**
+     * Seeds the in-memory filesystem with additional files.
+     *
+     * Keys are absolute paths; values are file contents.
+     * Ancestor directories are created automatically.
+     */
+    prePopulate(files) {
+        for (const [rawPath, content] of Object.entries(files)) {
+            const normalized = normalizePath(rawPath);
+            for (const dir of ancestorDirectories(normalized)) {
+                this.directories.add(dir);
+            }
+            this.files.set(normalized, content);
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Internals
+    // ---------------------------------------------------------------------------
+    seedDefaults() {
+        for (const dir of DEFAULT_DIRECTORIES) {
+            this.directories.add(dir);
+        }
+        for (const [path, content] of Object.entries(DEFAULT_FILES)) {
+            this.files.set(path, content);
+        }
+    }
+    assertReady() {
+        if (this.currentStatus !== "ready") {
+            throw new Error(`Mock sandbox is not ready (current status: "${this.currentStatus}").`);
+        }
+    }
+}
+//# sourceMappingURL=mock-sandbox.js.map

package/dist/test-helpers/mock-sandbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-sandbox.js","sourceRoot":"","sources":["../../src/test-helpers/mock-sandbox.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAUlC,MAAM,aAAa,GAA2B;IAC5C,sBAAsB,EAAE;QACtB,aAAa;QACb,EAAE;QACF,wCAAwC;QACxC,+CAA+C;QAC/C,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC;CACb,CAAC;AAEF,MAAM,mBAAmB,GAAG,CAAC,YAAY,EAAE,iBAAiB,CAAC,CAAC;AAE9D;;;GAGG;AACH,SAAS,aAAa,CAAC,GAAW;IAChC,MAAM,QAAQ,GAAG,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IACtC,OAAO,QAAQ,CAAC,MAAM,GAAG,CAAC,IAAI,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC;QAClD,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACvB,CAAC,CAAC,QAAQ,CAAC;AACf,CAAC;AAED;;;;;GAKG;AACH,SAAS,mBAAmB,CAAC,QAAgB;IAC3C,MAAM,SAAS,GAAa,EAAE,CAAC;IAC/B,IAAI,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAEtC,OAAO,OAAO,KAAK,GAAG,EAAE,CAAC;QACvB,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACxB,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACnC,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,MAAM,OAAO,WAAW;IACN,EAAE,CAAS;IAEnB,aAAa,GAAkB,MAAM,CAAC;IAC7B,KAAK,CAAsB;IAC3B,WAAW,CAAc;IAE1C;QACE,IAAI,CAAC,EAAE,GAAG,QAAQ,UAAU,EAAE,EAAE,CAAC;QACjC,IAAI,CAAC,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;QACvC,IAAI,CAAC,WAAW,GAAG,IAAI,GAAG,EAAU,CAAC;QAErC,IAAI,CAAC,YAAY,EAAE,CAAC;IACtB,CAAC;IAED,8EAA8E;IAC9E,iBAAiB;IACjB,8EAA8E;IAE9E,IAAW,MAAM;QACf,OAAO,IAAI,CAAC,aAAa,CAAC;IAC5B,CAAC;IAEM,KAAK,CAAC,KAAK;QAChB,IAAI,IAAI,CAAC,aAAa,KAAK,OAAO,EAAE,CAAC;YACnC,OAAO;QACT,CAAC;QAED,IAAI,IAAI,CAAC,aAAa,KAAK,UAAU,IAAI,IAAI,CAAC,aAAa,KAAK,UAAU,EAAE,CAAC;YAC3E,MAAM,IAAI,KAAK,CAAC,8CAA8C,IAAI,CAAC,aAAa,IAAI,CAAC,CAAC;QACxF,CAAC;QAED,IAAI,CAAC,aAAa,GAAG,UAAU,CAAC;QAChC,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC;IAC/B,CAAC;IAEM,KAAK,CAAC,QAAQ;QACnB,IAAI,IAAI,CAAC,aAAa,KAAK,SAAS,EAAE,CAAC;YACrC,OAAO;QACT,CAAC;QAED,IAAI,CAAC,aAAa,GAAG,UAAU,CAAC;QAChC,IAAI,CAAC,aAAa,GAAG,SAAS,CAAC;IACjC,CAAC;IAED,8EAA8E;IAC9E,OAAO;IACP,8EAA8E;IAEvE,KAAK,CAAC,IAAI,CAAC,OAAe,EAAE,IAAkB;QACnD,KAAK,IAAI,CAAC;QACV,IAAI,CAAC,WAAW,EAAE,CAAC;QAEnB,OAAO;YACL,MAAM,EAAE,UAAU,OAAO,IAAI;YAC7B,MAAM,EAAE,EAAE;YACV,QAAQ,EAAE,CAAC;SACZ,CAAC;IACJ,CAAC;IAED,8EAA8E;IAC9E,kBAAkB;IAClB,8EAA8E;IAE9D,IAAI,GAAG;QACrB,IAAI,EAAE,KAAK,EAAE,IAAY,EAAmB,EAAE;YAC5C,IAAI,CAAC,WAAW,EAAE,CAAC;YACnB,MAAM,UAAU,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;YACvC,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;YAE3C,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC1B,MAAM,IAAI,KAAK,CAAC,yBAAyB,UAAU,IAAI,CAAC,CAAC;YAC3D,CAAC;YAED,OAAO,OAAO,CAAC;QACjB,CAAC;QAED,KAAK,EAAE,KAAK,EAAE,IAAY,EAAE,OAAwB,EAAiB,EAAE;YACrE,IAAI,CAAC,WAAW,EAAE,CAAC;YACnB,MAAM,UAAU,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;YACvC,MAAM,OAAO,GAAG,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;YAEjF,yCAAyC;YACzC,KAAK,MAAM,GAAG,IAAI,mBAAmB,CAAC,UAAU,CAAC,EAAE,CAAC;gBAClD,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC5B,CAAC;YAED,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;QACtC,CAAC;QAED,IAAI,EAAE,KAAK,EAAE,IAAY,EAAwB,EAAE;YACjD,IAAI,CAAC,WAAW,EAAE,CAAC;YACnB,MAAM,UAAU,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;YAEvC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC;gBACtC,MAAM,IAAI,KAAK,CAAC,8BAA8B,UAAU,IAAI,CAAC,CAAC;YAChE,CAAC;YAED,MAAM,OAAO,GAAgB,EAAE,CAAC;YAChC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;YAE/B,8BAA8B;YAC9B,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;gBACzC,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,UAAU,EAAE,CAAC;oBAC3C,MAAM,IAAI,GAAG,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;oBAEtC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;wBACpB,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;wBACf,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;oBACvD,CAAC;gBACH,CAAC;YACH,CAAC;YAED,oCAAoC;YACpC,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;gBACvC,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,UAAU,EAAE,CAAC;oBAC1C,MAAM,IAAI,GAAG,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;oBAErC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;wBACpB,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;wBACf,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC;oBAC3D,CAAC;gBACH,CAAC;YACH,CAAC;YAED,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;YAErD,OAAO,OAAO,CAAC;QACjB,CAAC;QAED,MAAM,EAAE,KAAK,EAAE,IAAY,EAAiB,EAAE;YAC5C,IAAI,CAAC,WAAW,EAAE,CAAC;YACnB,MAAM,UAAU,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;YAEvC,2BAA2B;YAC3B,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;YAE9B,0DAA0D;YAC1D,IAAI,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC;gBACrC,MAAM,MAAM,GAAG,GAAG,UAAU,GAAG,CAAC;gBAEhC,KAAK,MAAM,QAAQ,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;oBAC9C,IAAI,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;wBAChC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;oBAC9B,CAAC;gBACH,CAAC;gBAED,KAAK,MAAM,OAAO,IAAI,CAAC,GAAG,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC;oBAC5C,IAAI,OAAO,KAAK,UAAU,IAAI,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;wBACzD,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;oBACnC,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;KACF,CAAC;IAEF,8EAA8E;IAC9E,kBAAkB;IAClB,8EAA8E;IAE9E;;;;;OAKG;IACI,WAAW,CAAC,KAA6B;QAC9C,KAAK,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACvD,MAAM,UAAU,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;YAE1C,KAAK,MAAM,GAAG,IAAI,mBAAmB,CAAC,UAAU,CAAC,EAAE,CAAC;gBAClD,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC5B,CAAC;YAED,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;QACtC,CAAC;IACH,CAAC;IAED,8EAA8E;IAC9E,YAAY;IACZ,8EAA8E;IAEtE,YAAY;QAClB,KAAK,MAAM,GAAG,IAAI,mBAAmB,EAAE,CAAC;YACtC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC5B,CAAC;QAED,KAAK,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,CAAC;YAC5D,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAChC,CAAC;IACH,CAAC;IAEO,WAAW;QACjB,IAAI,IAAI,CAAC,aAAa,KAAK,OAAO,EAAE,CAAC;YACnC,MAAM,IAAI,KAAK,CAAC,+CAA+C,IAAI,CAAC,aAAa,KAAK,CAAC,CAAC;QAC1F,CAAC;IACH,CAAC;CACF"}

package/dist/tui/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./render.js";
+export * from "./tui.js";

package/dist/tui/index.js

@@ -0,0 +1,3 @@
+export * from "./render.js";
+export * from "./tui.js";
+//# sourceMappingURL=index.js.map

package/dist/tui/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tui/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC"}

package/dist/tui/render.d.ts

@@ -0,0 +1,8 @@
+import type { ResponseEvent } from "../agent-loop/types.js";
+export declare function renderEvent(event: ResponseEvent): string;
+export declare function renderReady(agentName: string): string;
+export declare function renderInterrupted(): string;
+export declare function renderShuttingDown(): string;
+export declare function renderExitHint(): string;
+export declare function renderError(message: string): string;
+export declare function renderCommandNotFound(name: string): string;

package/dist/tui/render.js

@@ -0,0 +1,40 @@
+import chalk from "chalk";
+export function renderEvent(event) {
+    switch (event.type) {
+        case "response.output_text.delta":
+            return event.delta;
+        case "response.tool_call.created":
+            return chalk.dim(`\n[tool: ${event.toolCall.name}] running...\n`);
+        case "response.tool_call.done":
+            return event.result.isError
+                ? chalk.red(`[tool error] ${String(event.result.output)}\n`)
+                : chalk.dim("[tool: done]\n");
+        case "tool_execution_update":
+            return chalk.dim(event.chunk);
+        case "response.error":
+            return chalk.red(`\nError: ${event.error}\n`);
+        case "response.created":
+        case "response.output_text.done":
+        case "response.completed":
+            return "";
+    }
+}
+export function renderReady(agentName) {
+    return chalk.green(`Agent "${agentName}" is ready.\n`);
+}
+export function renderInterrupted() {
+    return chalk.yellow("\n(Interrupted)\n");
+}
+export function renderShuttingDown() {
+    return chalk.yellow("\nShutting down...\n");
+}
+export function renderExitHint() {
+    return chalk.yellow("\n(Press Ctrl+C again to exit)\n");
+}
+export function renderError(message) {
+    return chalk.red(`\nError: ${message}\n`);
+}
+export function renderCommandNotFound(name) {
+    return chalk.red(`\nUnknown command: /${name}\n`);
+}
+//# sourceMappingURL=render.js.map

package/dist/tui/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../../src/tui/render.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAI1B,MAAM,UAAU,WAAW,CAAC,KAAoB;IAC9C,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;QACnB,KAAK,4BAA4B;YAC/B,OAAO,KAAK,CAAC,KAAK,CAAC;QACrB,KAAK,4BAA4B;YAC/B,OAAO,KAAK,CAAC,GAAG,CAAC,YAAY,KAAK,CAAC,QAAQ,CAAC,IAAI,gBAAgB,CAAC,CAAC;QACpE,KAAK,yBAAyB;YAC5B,OAAO,KAAK,CAAC,MAAM,CAAC,OAAO;gBACzB,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,gBAAgB,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC;gBAC5D,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;QAClC,KAAK,uBAAuB;YAC1B,OAAO,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAChC,KAAK,gBAAgB;YACnB,OAAO,KAAK,CAAC,GAAG,CAAC,YAAY,KAAK,CAAC,KAAK,IAAI,CAAC,CAAC;QAChD,KAAK,kBAAkB,CAAC;QACxB,KAAK,2BAA2B,CAAC;QACjC,KAAK,oBAAoB;YACvB,OAAO,EAAE,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,SAAiB;IAC3C,OAAO,KAAK,CAAC,KAAK,CAAC,UAAU,SAAS,eAAe,CAAC,CAAC;AACzD,CAAC;AAED,MAAM,UAAU,iBAAiB;IAC/B,OAAO,KAAK,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC;AAC3C,CAAC;AAED,MAAM,UAAU,kBAAkB;IAChC,OAAO,KAAK,CAAC,MAAM,CAAC,sBAAsB,CAAC,CAAC;AAC9C,CAAC;AAED,MAAM,UAAU,cAAc;IAC5B,OAAO,KAAK,CAAC,MAAM,CAAC,kCAAkC,CAAC,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,OAAO,KAAK,CAAC,GAAG,CAAC,YAAY,OAAO,IAAI,CAAC,CAAC;AAC5C,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,IAAY;IAChD,OAAO,KAAK,CAAC,GAAG,CAAC,uBAAuB,IAAI,IAAI,CAAC,CAAC;AACpD,CAAC"}

package/dist/tui/tui.d.ts

@@ -0,0 +1,19 @@
+import type { ResponseEvent, ResponseInput } from "../agent-loop/types.js";
+import type { Agent } from "../agent/types.js";
+import type { Command } from "../commands/types.js";
+export type TUIOptions = {
+    input?: NodeJS.ReadableStream;
+    output?: NodeJS.WritableStream;
+    commands?: readonly Command[];
+};
+type TUIState = "idle" | "streaming" | "shutting_down";
+export type SigintAction = "ignore" | "abort" | "shutdown" | "exit_hint";
+export declare function determineSigintAction(state: TUIState, hasAbort: boolean, msSinceLastCtrlC: number): SigintAction;
+export type ParsedSlashCommand = {
+    commandName: string;
+    args: string;
+};
+export declare function parseSlashCommand(input: string): ParsedSlashCommand | null;
+export declare function resolveSlashInput(trimmed: string, commands: readonly Command[], write: (text: string) => void): string | null;
+export declare function serveTUI(agent: Agent, options?: TUIOptions): Promise<void>;
+export type { ResponseEvent, ResponseInput };