agentic-pi 0.1.0

package/dist/sandbox/gondolin.js

@@ -0,0 +1,210 @@
+/**
+ * Gondolin sandbox backend for agentic-pi.
+ *
+ * Routes Pi's built-in `read`/`write`/`edit`/`bash` tools through a Gondolin
+ * micro-VM. The agent's tool calls execute against `/workspace` inside the
+ * VM, where the host's current working directory has been mounted RW. Files
+ * the agent writes appear on the host because RealFSProvider is a passthrough.
+ *
+ * Pattern adapted from gondolin/host/examples/pi-gondolin.ts but adjusted
+ * for SDK mode (no Pi extension hooks; we drive `createAgentSession`
+ * directly).
+ *
+ * Note: `grep`/`find`/`ls` are NOT routed through the VM in this version —
+ * they run on the host but they read the *same* files (because the mount
+ * is a passthrough), so the agent sees consistent state. This matches the
+ * upstream example. If full FS isolation is needed later, route those too.
+ */
+import path from "node:path";
+import { createBashTool, createEditTool, createReadTool, createWriteTool, } from "@earendil-works/pi-coding-agent";
+import { RealFSProvider, VM } from "@earendil-works/gondolin";
+const GUEST_WORKSPACE = "/workspace";
+function shQuote(value) {
+    // POSIX shell quoting: wrap in single quotes; escape any internal quote.
+    return "'" + value.replace(/'/g, "'\\''") + "'";
+}
+function toGuestPath(localCwd, localPath) {
+    const rel = path.relative(localCwd, localPath);
+    if (rel === "")
+        return GUEST_WORKSPACE;
+    if (rel.startsWith("..") || path.isAbsolute(rel)) {
+        throw new Error(`path escapes workspace: ${localPath}`);
+    }
+    const posixRel = rel.split(path.sep).join(path.posix.sep);
+    return path.posix.join(GUEST_WORKSPACE, posixRel);
+}
+function sanitizeEnv(env) {
+    if (!env)
+        return undefined;
+    const out = {};
+    for (const [k, v] of Object.entries(env)) {
+        if (typeof v === "string")
+            out[k] = v;
+    }
+    return out;
+}
+function createGondolinReadOps(vm, localCwd) {
+    return {
+        readFile: async (p) => {
+            const guestPath = toGuestPath(localCwd, p);
+            const r = await vm.exec(["/bin/cat", guestPath]);
+            if (!r.ok)
+                throw new Error(`cat failed (${r.exitCode}): ${r.stderr}`);
+            return r.stdoutBuffer;
+        },
+        access: async (p) => {
+            const guestPath = toGuestPath(localCwd, p);
+            const r = await vm.exec(["/bin/sh", "-lc", `test -r ${shQuote(guestPath)}`]);
+            if (!r.ok)
+                throw new Error(`not readable: ${p}`);
+        },
+        detectImageMimeType: async (p) => {
+            const guestPath = toGuestPath(localCwd, p);
+            try {
+                const r = await vm.exec([
+                    "/bin/sh",
+                    "-lc",
+                    `file --mime-type -b ${shQuote(guestPath)}`,
+                ]);
+                if (!r.ok)
+                    return null;
+                const m = r.stdout.trim();
+                return ["image/jpeg", "image/png", "image/gif", "image/webp"].includes(m) ? m : null;
+            }
+            catch {
+                return null;
+            }
+        },
+    };
+}
+function createGondolinWriteOps(vm, localCwd) {
+    return {
+        writeFile: async (p, content) => {
+            const guestPath = toGuestPath(localCwd, p);
+            const dir = path.posix.dirname(guestPath);
+            const b64 = Buffer.from(content, "utf8").toString("base64");
+            const script = [
+                `set -eu`,
+                `mkdir -p ${shQuote(dir)}`,
+                `echo ${shQuote(b64)} | base64 -d > ${shQuote(guestPath)}`,
+            ].join("\n");
+            const r = await vm.exec(["/bin/sh", "-lc", script]);
+            if (!r.ok)
+                throw new Error(`write failed (${r.exitCode}): ${r.stderr}`);
+        },
+        mkdir: async (dir) => {
+            const guestDir = toGuestPath(localCwd, dir);
+            const r = await vm.exec(["/bin/mkdir", "-p", guestDir]);
+            if (!r.ok)
+                throw new Error(`mkdir failed (${r.exitCode}): ${r.stderr}`);
+        },
+    };
+}
+function createGondolinEditOps(vm, localCwd) {
+    const r = createGondolinReadOps(vm, localCwd);
+    const w = createGondolinWriteOps(vm, localCwd);
+    return { readFile: r.readFile, access: r.access, writeFile: w.writeFile };
+}
+function createGondolinBashOps(vm, localCwd) {
+    return {
+        exec: async (command, cwd, { onData, signal, timeout, env }) => {
+            const guestCwd = toGuestPath(localCwd, cwd);
+            const ac = new AbortController();
+            const onAbort = () => ac.abort();
+            signal?.addEventListener("abort", onAbort, { once: true });
+            let timedOut = false;
+            const timer = timeout && timeout > 0
+                ? setTimeout(() => {
+                    timedOut = true;
+                    ac.abort();
+                }, timeout * 1000)
+                : undefined;
+            try {
+                const proc = vm.exec(["/bin/sh", "-lc", command], {
+                    cwd: guestCwd,
+                    signal: ac.signal,
+                    env: sanitizeEnv(env),
+                    stdout: "pipe",
+                    stderr: "pipe",
+                });
+                for await (const chunk of proc.output()) {
+                    onData(chunk.data);
+                }
+                const r = await proc;
+                return { exitCode: r.exitCode };
+            }
+            catch (err) {
+                if (signal?.aborted)
+                    throw new Error("aborted");
+                if (timedOut)
+                    throw new Error(`timeout:${timeout}`);
+                throw err;
+            }
+            finally {
+                if (timer)
+                    clearTimeout(timer);
+                signal?.removeEventListener("abort", onAbort);
+            }
+        },
+    };
+}
+/**
+ * Boot a Gondolin VM mounting `cwd` at /workspace, and build the four
+ * Pi tool overrides (read, write, edit, bash) that route through it.
+ *
+ * Throws if VM.create rejects. The preflight check is the caller's
+ * responsibility — call `preflightGondolin()` first.
+ */
+export async function buildGondolinSandbox(cwd) {
+    const t0 = Date.now();
+    const vm = await VM.create({
+        vfs: {
+            mounts: {
+                [GUEST_WORKSPACE]: new RealFSProvider(cwd),
+            },
+        },
+    });
+    const createMs = Date.now() - t0;
+    // Confirm the VM is actually executable before returning. Without this
+    // probe, a hung VM (see SPIKE-gondolin.md / upstream issue #51) would
+    // slip through and the orchestrator would inherit the hang at first
+    // tool call. Two-second budget is generous — a working guest responds in
+    // a few hundred ms.
+    const probe = await Promise.race([
+        vm.exec(["/bin/true"]),
+        new Promise((resolve) => setTimeout(() => resolve({ ok: false, exitCode: -1, stderr: "vm-exec-probe-timeout" }), 5_000)),
+    ]);
+    if (!probe.ok) {
+        await vm.close().catch(() => undefined);
+        throw new Error(`Gondolin VM started but is not executing commands ` +
+            `(probe: ${probe.stderr || "no stderr"}). ` +
+            `This matches upstream issue #51 — likely no working accelerator. ` +
+            `See SPIKE-gondolin.md.`);
+    }
+    // Names match Pi's built-ins (read/write/edit/bash). Pi's host
+    // versions are suppressed by the runner via noTools:"builtin" so these
+    // do not collide.
+    const customTools = [
+        createReadTool(cwd, { operations: createGondolinReadOps(vm, cwd) }),
+        createWriteTool(cwd, { operations: createGondolinWriteOps(vm, cwd) }),
+        createEditTool(cwd, { operations: createGondolinEditOps(vm, cwd) }),
+        createBashTool(cwd, { operations: createGondolinBashOps(vm, cwd) }),
+    ];
+    let closed = false;
+    return {
+        customTools,
+        status: {
+            backend: "gondolin",
+            cwd,
+            guestPath: GUEST_WORKSPACE,
+            createMs,
+        },
+        close: async () => {
+            if (closed)
+                return;
+            closed = true;
+            await vm.close().catch(() => undefined);
+        },
+    };
+}
+//# sourceMappingURL=gondolin.js.map

package/dist/sandbox/gondolin.js.map

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

package/dist/sandbox/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Sandbox backend dispatcher.
+ *
+ * Currently supports two backends: `none` (the default — Pi's built-in
+ * tools run on the host) and `gondolin` (tool ops routed through a
+ * micro-VM). See SPIKE-gondolin.md for the design context.
+ */
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { type GondolinSandbox } from "./gondolin.js";
+export type SandboxBackend = "none" | "gondolin";
+export interface SandboxNone {
+    backend: "none";
+    customTools: ToolDefinition<any>[];
+    /** Whether Pi's built-in read/write/edit/bash should be suppressed. */
+    suppressBuiltins: boolean;
+    close: () => Promise<void>;
+    status: Record<string, unknown>;
+}
+export type SandboxResult = SandboxNone | (Omit<GondolinSandbox, "status"> & {
+    backend: "gondolin";
+    suppressBuiltins: true;
+    status: GondolinSandbox["status"];
+});
+export interface BuildSandboxOptions {
+    backend: SandboxBackend;
+    cwd: string;
+}
+export type BuildSandboxOutcome = {
+    ok: true;
+    sandbox: SandboxResult;
+} | {
+    ok: false;
+    backend: SandboxBackend;
+    reason: string;
+    hint: string;
+};
+export declare function buildSandbox(opts: BuildSandboxOptions): Promise<BuildSandboxOutcome>;

package/dist/sandbox/index.js

@@ -0,0 +1,55 @@
+/**
+ * Sandbox backend dispatcher.
+ *
+ * Currently supports two backends: `none` (the default — Pi's built-in
+ * tools run on the host) and `gondolin` (tool ops routed through a
+ * micro-VM). See SPIKE-gondolin.md for the design context.
+ */
+import { buildGondolinSandbox } from "./gondolin.js";
+import { preflightGondolin } from "./preflight.js";
+export async function buildSandbox(opts) {
+    if (opts.backend === "none") {
+        return {
+            ok: true,
+            sandbox: {
+                backend: "none",
+                customTools: [],
+                suppressBuiltins: false,
+                close: async () => undefined,
+                status: { backend: "none" },
+            },
+        };
+    }
+    // backend === "gondolin"
+    const preflight = preflightGondolin();
+    if (!preflight.ok) {
+        return {
+            ok: false,
+            backend: "gondolin",
+            reason: preflight.reason,
+            hint: preflight.hint,
+        };
+    }
+    try {
+        const sandbox = await buildGondolinSandbox(opts.cwd);
+        return {
+            ok: true,
+            sandbox: {
+                backend: "gondolin",
+                customTools: sandbox.customTools,
+                suppressBuiltins: true,
+                close: sandbox.close,
+                status: sandbox.status,
+            },
+        };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            backend: "gondolin",
+            reason: "vm-create-failed",
+            hint: err.message,
+        };
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/sandbox/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/sandbox/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAAE,oBAAoB,EAAwB,MAAM,eAAe,CAAC;AAC3E,OAAO,EAAE,iBAAiB,EAAwB,MAAM,gBAAgB,CAAC;AAkCzE,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAAyB;IAC1D,IAAI,IAAI,CAAC,OAAO,KAAK,MAAM,EAAE,CAAC;QAC5B,OAAO;YACL,EAAE,EAAE,IAAI;YACR,OAAO,EAAE;gBACP,OAAO,EAAE,MAAM;gBACf,WAAW,EAAE,EAAE;gBACf,gBAAgB,EAAE,KAAK;gBACvB,KAAK,EAAE,KAAK,IAAI,EAAE,CAAC,SAAS;gBAC5B,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE;aAC5B;SACF,CAAC;IACJ,CAAC;IAED,yBAAyB;IACzB,MAAM,SAAS,GAAoB,iBAAiB,EAAE,CAAC;IACvD,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,CAAC;QAClB,OAAO;YACL,EAAE,EAAE,KAAK;YACT,OAAO,EAAE,UAAU;YACnB,MAAM,EAAE,SAAS,CAAC,MAAM;YACxB,IAAI,EAAE,SAAS,CAAC,IAAI;SACrB,CAAC;IACJ,CAAC;IAED,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,oBAAoB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACrD,OAAO;YACL,EAAE,EAAE,IAAI;YACR,OAAO,EAAE;gBACP,OAAO,EAAE,UAAU;gBACnB,WAAW,EAAE,OAAO,CAAC,WAAW;gBAChC,gBAAgB,EAAE,IAAI;gBACtB,KAAK,EAAE,OAAO,CAAC,KAAK;gBACpB,MAAM,EAAE,OAAO,CAAC,MAAM;aACvB;SACF,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO;YACL,EAAE,EAAE,KAAK;YACT,OAAO,EAAE,UAAU;YACnB,MAAM,EAAE,kBAAkB;YAC1B,IAAI,EAAG,GAAa,CAAC,OAAO;SAC7B,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/sandbox/preflight.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Pre-flight checks for the Gondolin sandbox backend.
+ *
+ * The reason this exists at all: per upstream issue #51, Gondolin's
+ * `VM.create()` returns a "VM ready" Promise even when the underlying QEMU
+ * guest never actually boots (silently hangs at ~95% CPU). That happens any
+ * time QEMU lacks a hypervisor accelerator — most commonly when running
+ * inside a container with no `/dev/kvm`. We refuse to start in those
+ * environments rather than let the orchestrator inherit a hung process.
+ *
+ * Empirically verified: works on macOS host (HVF auto-used by QEMU 11);
+ * fails inside Colima / Docker Desktop (no /dev/kvm exposed). See
+ * SPIKE-gondolin.md for the full evidence.
+ */
+export type PreflightStatus = {
+    ok: true;
+    detail: string;
+} | {
+    ok: false;
+    reason: PreflightFailureReason;
+    hint: string;
+};
+export type PreflightFailureReason = "qemu-not-installed" | "qemu-img-not-installed" | "linux-no-kvm" | "in-container-no-accel";
+export declare function preflightGondolin(): PreflightStatus;

package/dist/sandbox/preflight.js

@@ -0,0 +1,93 @@
+/**
+ * Pre-flight checks for the Gondolin sandbox backend.
+ *
+ * The reason this exists at all: per upstream issue #51, Gondolin's
+ * `VM.create()` returns a "VM ready" Promise even when the underlying QEMU
+ * guest never actually boots (silently hangs at ~95% CPU). That happens any
+ * time QEMU lacks a hypervisor accelerator — most commonly when running
+ * inside a container with no `/dev/kvm`. We refuse to start in those
+ * environments rather than let the orchestrator inherit a hung process.
+ *
+ * Empirically verified: works on macOS host (HVF auto-used by QEMU 11);
+ * fails inside Colima / Docker Desktop (no /dev/kvm exposed). See
+ * SPIKE-gondolin.md for the full evidence.
+ */
+import { existsSync, accessSync, constants } from "node:fs";
+import { execFileSync } from "node:child_process";
+function which(bin) {
+    try {
+        const out = execFileSync("/usr/bin/env", ["which", bin], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        return out || null;
+    }
+    catch {
+        return null;
+    }
+}
+function isReadable(path) {
+    try {
+        accessSync(path, constants.R_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Best-effort container detection. We're conservative — false negatives are
+ * tolerable (the only consequence is a slower failure inside QEMU itself).
+ * False positives would block valid native runs, so we only flag the
+ * obvious cases.
+ */
+function looksLikeContainer() {
+    if (existsSync("/.dockerenv"))
+        return true;
+    if (process.env.container)
+        return true;
+    return false;
+}
+export function preflightGondolin() {
+    const qemuX86 = which("qemu-system-x86_64");
+    const qemuArm = which("qemu-system-aarch64");
+    const qemu = qemuX86 || qemuArm;
+    if (!qemu) {
+        return {
+            ok: false,
+            reason: "qemu-not-installed",
+            hint: "Install QEMU on the host: 'brew install qemu' (macOS) or " +
+                "'apt install qemu-system-x86 qemu-system-arm qemu-utils' (Debian/Ubuntu). " +
+                "See SPIKE-gondolin.md for context.",
+        };
+    }
+    const qemuImg = which("qemu-img");
+    if (!qemuImg) {
+        return {
+            ok: false,
+            reason: "qemu-img-not-installed",
+            hint: "qemu-img missing. On Debian/Ubuntu install 'qemu-utils'; on macOS " +
+                "the 'qemu' brew formula already includes it — re-check $PATH.",
+        };
+    }
+    // On Linux, the only practical accelerator is KVM. Without /dev/kvm,
+    // Gondolin falls into the upstream-#51 silent-hang bug. Refuse early.
+    if (process.platform === "linux" && !isReadable("/dev/kvm")) {
+        const inContainer = looksLikeContainer();
+        return {
+            ok: false,
+            reason: inContainer ? "in-container-no-accel" : "linux-no-kvm",
+            hint: inContainer
+                ? "Detected container environment with no readable /dev/kvm. " +
+                    "Gondolin requires KVM and Docker-in-Docker nested virt is not viable. " +
+                    "Run agentic-pi natively, or expose /dev/kvm with 'docker run --device /dev/kvm'."
+                : "/dev/kvm not readable. Add the running user to the 'kvm' group, " +
+                    "or run as a user with read access. Without it Gondolin hangs (upstream issue #51).",
+        };
+    }
+    // macOS: QEMU 11 auto-uses Hypervisor.framework (HVF). No /dev/kvm
+    // needed. Empirically verified in SPIKE-gondolin.md.
+    const accel = process.platform === "darwin" ? "HVF (auto)" : "KVM (/dev/kvm)";
+    return { ok: true, detail: `qemu=${qemu} qemu-img=${qemuImg} accel=${accel}` };
+}
+//# sourceMappingURL=preflight.js.map

package/dist/sandbox/preflight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preflight.js","sourceRoot":"","sources":["../../src/sandbox/preflight.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAYlD,SAAS,KAAK,CAAC,GAAW;IACxB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,cAAc,EAAE,CAAC,OAAO,EAAE,GAAG,CAAC,EAAE;YACvD,QAAQ,EAAE,MAAM;YAChB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC;SACpC,CAAC,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,GAAG,IAAI,IAAI,CAAC;IACrB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAS,UAAU,CAAC,IAAY;IAC9B,IAAI,CAAC;QACH,UAAU,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC;QACjC,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,SAAS,kBAAkB;IACzB,IAAI,UAAU,CAAC,aAAa,CAAC;QAAE,OAAO,IAAI,CAAC;IAC3C,IAAI,OAAO,CAAC,GAAG,CAAC,SAAS;QAAE,OAAO,IAAI,CAAC;IACvC,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,iBAAiB;IAC/B,MAAM,OAAO,GAAG,KAAK,CAAC,oBAAoB,CAAC,CAAC;IAC5C,MAAM,OAAO,GAAG,KAAK,CAAC,qBAAqB,CAAC,CAAC;IAC7C,MAAM,IAAI,GAAG,OAAO,IAAI,OAAO,CAAC;IAEhC,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,oBAAoB;YAC5B,IAAI,EACF,2DAA2D;gBAC3D,4EAA4E;gBAC5E,oCAAoC;SACvC,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,KAAK,CAAC,UAAU,CAAC,CAAC;IAClC,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,wBAAwB;YAChC,IAAI,EACF,oEAAoE;gBACpE,+DAA+D;SAClE,CAAC;IACJ,CAAC;IAED,qEAAqE;IACrE,sEAAsE;IACtE,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAC5D,MAAM,WAAW,GAAG,kBAAkB,EAAE,CAAC;QACzC,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,uBAAuB,CAAC,CAAC,CAAC,cAAc;YAC9D,IAAI,EAAE,WAAW;gBACf,CAAC,CAAC,4DAA4D;oBAC5D,wEAAwE;oBACxE,kFAAkF;gBACpF,CAAC,CAAC,kEAAkE;oBAClE,oFAAoF;SACzF,CAAC;IACJ,CAAC;IAED,mEAAmE;IACnE,qDAAqD;IACrD,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,gBAAgB,CAAC;IAC9E,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,IAAI,aAAa,OAAO,UAAU,KAAK,EAAE,EAAE,CAAC;AACjF,CAAC"}

package/dist/stdin.d.ts

@@ -0,0 +1 @@
+export declare function readStdin(): Promise<string>;

package/dist/stdin.js

@@ -0,0 +1,11 @@
+export async function readStdin() {
+    if (process.stdin.isTTY)
+        return "";
+    const chunks = [];
+    return await new Promise((resolve, reject) => {
+        process.stdin.on("data", (chunk) => chunks.push(chunk));
+        process.stdin.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+        process.stdin.on("error", reject);
+    });
+}
+//# sourceMappingURL=stdin.js.map

package/dist/stdin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdin.js","sourceRoot":"","sources":["../src/stdin.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,KAAK,UAAU,SAAS;IAC7B,IAAI,OAAO,CAAC,KAAK,CAAC,KAAK;QAAE,OAAO,EAAE,CAAC;IACnC,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,OAAO,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC3C,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;QAChE,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QAC/E,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;AACL,CAAC"}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "agentic-pi",
+  "version": "0.1.0",
+  "description": "A drop-in coding-agent harness built on earendil-works/pi, designed to replace opencode in workflow-driven systems like lastlight.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "agentic-pi": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "start": "node dist/cli.js",
+    "test": "node scripts/run-tests.mjs",
+    "test:unit": "node scripts/run-tests.mjs --unit",
+    "test:integration": "node scripts/run-tests.mjs --integration",
+    "check": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@earendil-works/gondolin": "^0.12.0",
+    "@earendil-works/pi-ai": "^0.75.4",
+    "@earendil-works/pi-coding-agent": "^0.75.4",
+    "@octokit/auth-app": "^7.1.4",
+    "@octokit/rest": "^21.0.2",
+    "@sinclair/typebox": "^0.34.0",
+    "@types/jsonwebtoken": "^9.0.10",
+    "jsonwebtoken": "^9.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}