agentic-pi 0.1.0

package/dist/run.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Programmatic entry point.
+ *
+ * Use this when calling agentic-pi in-process from a Node host (e.g.
+ * lastlight). It returns a fully-resolved `RunResult` carrying the same
+ * information lastlight's `opencode-executor` needs from the JSONL stream
+ * (sessionId, finalText, tokens, cost, sandbox + GitHub status, etc.)
+ * plus the raw event records so the caller can do anything else they want
+ * with them.
+ *
+ * Never writes to `process.stdout` or `process.stderr`. Hand it an
+ * `onEvent` and/or `onWarn` callback if you want to observe live.
+ */
+/**
+ * Pi thinking level. Matches Pi's `thinkingLevel` enum. Kept as a local
+ * string-union rather than imported from `@earendil-works/pi-agent-core`
+ * (which is a transitive dep we don't import directly — see AGENTS.md
+ * hard rule #3).
+ */
+export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
+import { type EmitterRecord, type EmitterSink } from "./emitter.js";
+import { type RunOnceExitCode } from "./runner.js";
+export interface RunOptions {
+    /** "provider/model_id", e.g. "anthropic/claude-haiku-4-5". */
+    model: string;
+    /** The prompt to send to the agent. */
+    prompt: string;
+    /** Pi thinking level. */
+    thinking?: ThinkingLevel;
+    /** GitHub profile: "read" | "issues-write" | "review-write" | "repo-write". */
+    profile?: string;
+    /** Sandbox backend. Default: "none". */
+    sandbox?: "none" | "gondolin";
+    /** Working directory. Default: process.cwd(). */
+    cwd?: string;
+    /** Skip session persistence. Default: false. */
+    noSession?: boolean;
+    /** Override session storage directory. */
+    sessionDir?: string;
+    /** Disable Pi's built-in tools (read/write/edit/bash/grep/find/ls). */
+    noBuiltinTools?: boolean;
+    /** Explicit tool allowlist. */
+    tools?: string[];
+    /**
+     * Called for every emitted JSONL record in order. Same shape that the
+     * CLI writes to stdout, with `sessionId` and `timestamp` already injected.
+     * Use this to mirror events into your own jsonl file, push deltas to a
+     * UI, or persist sessionId early.
+     */
+    onEvent?: (record: EmitterRecord) => void;
+    /**
+     * Called for human-readable warnings (e.g. partial GitHub creds). The
+     * CLI writes these to stderr; in-process callers usually want to log
+     * them somewhere structured.
+     */
+    onWarn?: (message: string) => void;
+    /**
+     * Extra sink to fan records out to (in addition to the internal
+     * collector that powers `result.records`). Useful if you want to write
+     * the shim jsonl directly without buffering through onEvent.
+     */
+    extraSink?: EmitterSink;
+}
+/** Outcome of one agentic-pi run. */
+export interface RunResult {
+    /** Exit code the CLI would have returned (0 = ok, 1 = runtime error, 2 = config error). */
+    exitCode: RunOnceExitCode;
+    /** True iff `exitCode === 0`. */
+    ok: boolean;
+    /** True iff Pi emitted an `agent_end` (clean termination). */
+    agentEnded: boolean;
+    /** True iff at least one tool returned an error. */
+    toolErrors: boolean;
+    /** If a fatal error short-circuited the run, this is set. */
+    fatalError?: {
+        name: string;
+        message: string;
+    };
+    /** Pi session id (from the session header line). May be undefined if preflight failed. */
+    sessionId?: string;
+    /** cwd the agent ran in. */
+    cwd?: string;
+    /** ISO timestamp of session start. */
+    startedAt?: string;
+    /** Concatenated final assistant text (the agent's "answer"). */
+    finalText: string;
+    /** Full message array from `agent_end` (user + assistant + toolResult messages). */
+    messages: unknown[];
+    /** Stats from the synthesized `usage_snapshot` event. */
+    stats?: {
+        userMessages: number;
+        assistantMessages: number;
+        toolCalls: number;
+        toolResults: number;
+        tokens: {
+            input: number;
+            output: number;
+            cacheRead: number;
+            cacheWrite: number;
+            total: number;
+        };
+        cost: number;
+    };
+    /** Mirrors of the `sandbox_status` and `extension_status` lines. */
+    sandbox?: {
+        backend: string;
+        status: Record<string, unknown>;
+    };
+    github?: {
+        status: "configured" | "skipped";
+        reason?: string;
+        message?: string;
+        profile?: string;
+        toolCount: number;
+    };
+    /** Every JSONL record the run emitted, in order. */
+    records: EmitterRecord[];
+    /** Warnings that would have gone to stderr in CLI mode. */
+    warnings: string[];
+}
+/**
+ * Run agentic-pi in-process and return a fully-derived result.
+ *
+ * @example
+ * ```ts
+ * import { run } from "agentic-pi";
+ *
+ * const result = await run({
+ *   model: "anthropic/claude-haiku-4-5",
+ *   prompt: "list the open PRs on owner/repo",
+ *   profile: "read",
+ *   noSession: true,
+ * });
+ *
+ * console.log(result.finalText);
+ * console.log(result.stats?.cost, "USD");
+ * ```
+ */
+export declare function run(options: RunOptions): Promise<RunResult>;

package/dist/run.js

@@ -0,0 +1,131 @@
+/**
+ * Programmatic entry point.
+ *
+ * Use this when calling agentic-pi in-process from a Node host (e.g.
+ * lastlight). It returns a fully-resolved `RunResult` carrying the same
+ * information lastlight's `opencode-executor` needs from the JSONL stream
+ * (sessionId, finalText, tokens, cost, sandbox + GitHub status, etc.)
+ * plus the raw event records so the caller can do anything else they want
+ * with them.
+ *
+ * Never writes to `process.stdout` or `process.stderr`. Hand it an
+ * `onEvent` and/or `onWarn` callback if you want to observe live.
+ */
+import { CollectorSink, TeeSink, } from "./emitter.js";
+import { runOnce } from "./runner.js";
+/**
+ * Run agentic-pi in-process and return a fully-derived result.
+ *
+ * @example
+ * ```ts
+ * import { run } from "agentic-pi";
+ *
+ * const result = await run({
+ *   model: "anthropic/claude-haiku-4-5",
+ *   prompt: "list the open PRs on owner/repo",
+ *   profile: "read",
+ *   noSession: true,
+ * });
+ *
+ * console.log(result.finalText);
+ * console.log(result.stats?.cost, "USD");
+ * ```
+ */
+export async function run(options) {
+    const config = {
+        model: options.model,
+        thinking: options.thinking,
+        profile: options.profile,
+        cwd: options.cwd ?? process.cwd(),
+        noSession: options.noSession ?? false,
+        sessionDir: options.sessionDir,
+        noBuiltinTools: options.noBuiltinTools ?? false,
+        tools: options.tools,
+        dangerouslySkipPermissions: false,
+        sandbox: options.sandbox ?? "none",
+    };
+    const collector = new CollectorSink(options.onEvent);
+    const sink = options.extraSink
+        ? new TeeSink([collector, options.extraSink])
+        : collector;
+    const warnings = [];
+    const onWarn = (msg) => {
+        warnings.push(msg);
+        options.onWarn?.(msg);
+    };
+    const exitCode = await runOnce(config, options.prompt, { sink, onWarn });
+    return buildResult(exitCode, collector.records, warnings);
+}
+function buildResult(exitCode, records, warnings) {
+    const result = {
+        exitCode,
+        ok: exitCode === 0,
+        agentEnded: false,
+        toolErrors: false,
+        finalText: "",
+        messages: [],
+        records,
+        warnings,
+    };
+    for (const r of records) {
+        switch (r.type) {
+            case "session":
+                result.sessionId = r.id;
+                result.cwd = r.cwd;
+                result.startedAt = r.timestamp;
+                break;
+            case "sandbox_status":
+                result.sandbox = {
+                    backend: r.backend,
+                    status: r.status ?? {},
+                };
+                break;
+            case "extension_status":
+                if (r.extension === "github") {
+                    result.github = {
+                        status: r.status,
+                        reason: r.reason,
+                        message: r.message,
+                        profile: r.profile,
+                        toolCount: r.toolCount ?? 0,
+                    };
+                }
+                break;
+            case "message_end": {
+                // Accumulate assistant text. Pi's message structure:
+                // r.message = { role: "assistant", content: [{type:"text", text:"…"}, ...] }
+                const m = r.message;
+                if (m?.role === "assistant" && Array.isArray(m.content)) {
+                    // Keep only the LATEST assistant text (final answer overwrites
+                    // intermediate ones). Pi guarantees the last assistant message
+                    // before agent_end is the final answer.
+                    const text = m.content
+                        .filter((c) => c.type === "text" && typeof c.text === "string")
+                        .map((c) => c.text)
+                        .join("");
+                    if (text)
+                        result.finalText = text;
+                }
+                break;
+            }
+            case "tool_execution_end":
+                if (r.isError === true)
+                    result.toolErrors = true;
+                break;
+            case "agent_end":
+                result.agentEnded = true;
+                if (Array.isArray(r.messages)) {
+                    result.messages = r.messages;
+                }
+                break;
+            case "usage_snapshot":
+                result.stats = r.stats;
+                break;
+            case "fatal_error":
+                result.fatalError = r.error;
+                break;
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=run.js.map

package/dist/run.js.map

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

package/dist/runner.d.ts

@@ -0,0 +1,22 @@
+/**
+ * One-shot Pi SDK runner.
+ *
+ * Creates an AgentSession, subscribes to events, sends one prompt, waits for
+ * `agent_end`, emits a synthetic usage snapshot, and exits.
+ *
+ * The runner is sink-agnostic: events flow through an `Emitter` whose sink
+ * is provided by the caller. The CLI passes a `StdoutSink`; the
+ * programmatic `run()` API passes a `CollectorSink`. Warnings flow through
+ * an `onWarn` callback for the same reason — so library consumers never
+ * see `process.stderr` writes they didn't ask for.
+ */
+import type { RunConfig } from "./args.js";
+import { type EmitterSink } from "./emitter.js";
+export interface RunOnceDeps {
+    /** Sink for all JSONL records. Required. */
+    sink: EmitterSink;
+    /** Called with human-readable warning text. Default: no-op. */
+    onWarn?: (message: string) => void;
+}
+export type RunOnceExitCode = 0 | 1 | 2;
+export declare function runOnce(config: RunConfig, prompt: string, deps: RunOnceDeps): Promise<RunOnceExitCode>;

package/dist/runner.js

@@ -0,0 +1,143 @@
+/**
+ * One-shot Pi SDK runner.
+ *
+ * Creates an AgentSession, subscribes to events, sends one prompt, waits for
+ * `agent_end`, emits a synthetic usage snapshot, and exits.
+ *
+ * The runner is sink-agnostic: events flow through an `Emitter` whose sink
+ * is provided by the caller. The CLI passes a `StdoutSink`; the
+ * programmatic `run()` API passes a `CollectorSink`. Warnings flow through
+ * an `onWarn` callback for the same reason — so library consumers never
+ * see `process.stderr` writes they didn't ask for.
+ */
+import { AuthStorage, ModelRegistry, SessionManager, createAgentSession, } from "@earendil-works/pi-coding-agent";
+import { Emitter } from "./emitter.js";
+import { loadGitHubExtension, isMisconfigurationSkip } from "./extensions/github/index.js";
+import { resolveModel } from "./models.js";
+import { buildSandbox } from "./sandbox/index.js";
+export async function runOnce(config, prompt, deps) {
+    const warn = deps.onWarn ?? (() => undefined);
+    const authStorage = AuthStorage.create();
+    const modelRegistry = ModelRegistry.create(authStorage);
+    const model = resolveModel(config.model, modelRegistry);
+    const sessionManager = buildSessionManager(config);
+    // Build the sandbox backend (boots Gondolin VM if --sandbox gondolin).
+    // Done eagerly so VM-boot / preflight failures surface before any tokens
+    // are spent on a prompt.
+    const sandboxOutcome = await buildSandbox({ backend: config.sandbox, cwd: config.cwd });
+    if (!sandboxOutcome.ok) {
+        warn(`--sandbox=${sandboxOutcome.backend} failed (${sandboxOutcome.reason}): ${sandboxOutcome.hint}`);
+        return 2;
+    }
+    const sandbox = sandboxOutcome.sandbox;
+    // Build the GitHub extension up-front so we can surface auth issues before
+    // creating the session (rather than at first tool call).
+    const github = loadGitHubExtension(config.profile);
+    // Loud about misconfigurations (partial App creds, unreadable PEM) — the
+    // user almost certainly meant for GitHub to work. Silent about benign
+    // skips (no --profile, no creds at all).
+    if (isMisconfigurationSkip(github)) {
+        warn(`GitHub extension disabled (${github.reason}): ${github.message ?? ""}`);
+    }
+    else if (github.status === "skipped" &&
+        github.reason === "no-credentials" &&
+        config.profile) {
+        warn(`--profile=${config.profile} set but no GITHUB_APP_* or GITHUB_TOKEN env vars found; GitHub tools disabled`);
+    }
+    // When a sandbox is active it supplies its own read/write/edit/bash that
+    // route through the VM; Pi's host built-ins of the same names must be
+    // suppressed so they don't shadow ours.
+    const noToolsMode = config.noBuiltinTools ? "builtin" :
+        sandbox.suppressBuiltins ? "builtin" :
+            undefined;
+    const { session } = await createAgentSession({
+        cwd: config.cwd,
+        model,
+        thinkingLevel: config.thinking,
+        sessionManager,
+        authStorage,
+        modelRegistry,
+        tools: config.tools,
+        noTools: noToolsMode,
+        customTools: [...sandbox.customTools, ...github.customTools],
+    });
+    const emitter = new Emitter({
+        sessionId: session.sessionId,
+        cwd: config.cwd,
+        startedAt: new Date().toISOString(),
+    }, deps.sink);
+    emitter.sessionHeader();
+    emitter.event({
+        type: "sandbox_status",
+        backend: sandbox.backend,
+        status: sandbox.status,
+    });
+    emitter.event({
+        type: "extension_status",
+        extension: "github",
+        status: github.status,
+        reason: github.reason,
+        message: github.message,
+        profile: github.profile,
+        toolCount: github.toolNames.length,
+    });
+    let sawError = false;
+    let agentEndSeen = false;
+    const unsubscribe = session.subscribe((event) => {
+        emitter.event(event);
+        if (event.type === "tool_execution_end" && event.isError) {
+            sawError = true;
+        }
+        if (event.type === "agent_end") {
+            agentEndSeen = true;
+        }
+    });
+    try {
+        await session.prompt(prompt, { expandPromptTemplates: false });
+    }
+    catch (err) {
+        emitter.event({
+            type: "fatal_error",
+            error: { name: err.name, message: err.message },
+        });
+        unsubscribe();
+        session.dispose();
+        await sandbox.close();
+        return 1;
+    }
+    // Synthesize a usage snapshot from the session stats. Pi's event stream
+    // does not carry per-event token/cost; lastlight reads this terminal event.
+    try {
+        const stats = session.getSessionStats();
+        emitter.event({
+            type: "usage_snapshot",
+            stats: {
+                userMessages: stats.userMessages,
+                assistantMessages: stats.assistantMessages,
+                toolCalls: stats.toolCalls,
+                toolResults: stats.toolResults,
+                tokens: stats.tokens,
+                cost: stats.cost,
+            },
+        });
+    }
+    catch (err) {
+        emitter.event({
+            type: "usage_snapshot_error",
+            error: { message: err.message },
+        });
+    }
+    unsubscribe();
+    session.dispose();
+    await sandbox.close();
+    if (sawError && !agentEndSeen)
+        return 1;
+    return 0;
+}
+function buildSessionManager(config) {
+    if (config.noSession) {
+        return SessionManager.inMemory(config.cwd);
+    }
+    return SessionManager.create(config.cwd, config.sessionDir);
+}
+//# sourceMappingURL=runner.js.map

package/dist/runner.js.map

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

package/dist/sandbox/gondolin.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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 type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+export interface GondolinSandbox {
+    /** Tools to pass into `createAgentSession({ customTools })`. */
+    customTools: ToolDefinition<any>[];
+    /** Tear down the VM. Idempotent. */
+    close: () => Promise<void>;
+    /** For the `sandbox_status` event. */
+    status: {
+        backend: "gondolin";
+        cwd: string;
+        guestPath: string;
+        createMs: number;
+    };
+}
+/**
+ * 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 declare function buildGondolinSandbox(cwd: string): Promise<GondolinSandbox>;