@timqi/pier 0.0.1

package/dist/agent/pi.js

@@ -0,0 +1,296 @@
+// The ONLY file allowed to import @earendil-works/pi-*. Implements the
+// AgentFactory/AgentSession seam from src/core/types.ts on the Pi SDK.
+// No Pi type may appear in an exported signature.
+import { createAgentSession, DefaultResourceLoader, defineTool, ModelRuntime, SessionManager, } from "@earendil-works/pi-coding-agent";
+import { logger } from "../log.js";
+import { imageAt, toChatTurns, toSessionEvents, turnMetaAt, } from "./events.js";
+import { defaultAgentDir } from "./config.js";
+import { curateModels } from "./models.js";
+const log = logger("agent");
+const toImageContent = (images) => images?.map((i) => ({ type: "image", data: i.data, mimeType: i.mimeType }));
+/** Pi's bash tool has no default timeout, so a hung command holds the turn
+ * until someone aborts it — nobody is watching in a scheduled task. Kept below
+ * the task-run timeout (tasks/definitions.ts) so a stuck command comes back as
+ * a tool error the agent can retry with an explicit longer timeout, instead of
+ * killing the whole run. */
+const BASH_DEFAULT_TIMEOUT_SECONDS = 600;
+/** Patching the call is cheaper than replacing the tool: the built-in keeps its
+ * shell settings, and the agent spends no tokens deciding a timeout. */
+const bashTimeoutDefault = (pi) => {
+    pi.on("tool_call", (event) => {
+        if (event.toolName === "bash" && event.input.timeout === undefined) {
+            event.input.timeout = BASH_DEFAULT_TIMEOUT_SECONDS;
+        }
+    });
+};
+class PiSession {
+    pi;
+    constructor(pi) {
+        this.pi = pi;
+    }
+    get id() {
+        return this.pi.sessionId;
+    }
+    get state() {
+        return this.pi.isStreaming ? "streaming" : "idle";
+    }
+    get model() {
+        const m = this.pi.model;
+        return m ? { provider: m.provider, id: m.id } : undefined;
+    }
+    get thinkingLevel() {
+        return this.pi.thinkingLevel;
+    }
+    get contextUsage() {
+        const u = this.pi.getContextUsage();
+        return u ? { tokens: u.tokens, contextWindow: u.contextWindow } : undefined;
+    }
+    async setModel(ref) {
+        const m = this.pi.modelRuntime.getModel(ref.provider, ref.id);
+        if (!m) {
+            // Lazy discovery: the failure itself documents what is selectable.
+            const available = (await this.availableModels())
+                .slice(0, 8).map((entry) => `${entry.provider}/${entry.id}`).join(", ");
+            throw new Error(`unknown model: ${ref.provider}/${ref.id}; available: ${available}`);
+        }
+        await this.pi.setModel(m);
+    }
+    async availableModels() {
+        const available = await this.pi.modelRuntime.getAvailable();
+        const curated = curateModels(available.map((m) => ({ provider: m.provider, id: m.id, reasoning: m.reasoning })));
+        // The session's active model must stay selectable even when curation
+        // (or an older catalog) would hide it.
+        const current = this.model;
+        if (current && !curated.some((m) => m.provider === current.provider && m.id === current.id)) {
+            curated.unshift(current);
+        }
+        return curated;
+    }
+    availableThinkingLevels() {
+        return this.pi.getAvailableThinkingLevels();
+    }
+    setThinkingLevel(level) {
+        this.pi.setThinkingLevel(level);
+    }
+    async pendingQueue() {
+        return {
+            steering: [...this.pi.getSteeringMessages()],
+            followUp: [...this.pi.getFollowUpMessages()],
+        };
+    }
+    async clearQueue() {
+        return this.pi.clearQueue();
+    }
+    async history() {
+        return toChatTurns(this.pi.messages);
+    }
+    async image(ordinal) {
+        return imageAt(this.pi.messages, ordinal);
+    }
+    async rewindToUserTurn(index) {
+        const total = (await this.history()).filter((t) => t.role === "user").length;
+        // Anchor at the tail: branch entries keep compacted-away history that
+        // history() no longer shows, so only end-relative indices line up.
+        const back = total - index;
+        const users = this.pi.sessionManager
+            .getBranch()
+            .filter((e) => e.type === "message" && e.message.role === "user");
+        const target = back >= 1 ? users[users.length - back] : undefined;
+        if (!target)
+            throw new Error(`no user turn at index ${index}`);
+        // navigateTree on a user message moves the leaf to its parent — the old
+        // branch stays in the file but leaves the context.
+        const { cancelled } = await this.pi.navigateTree(target.id);
+        if (cancelled)
+            throw new Error("rewind cancelled");
+    }
+    prompt(text, images) {
+        return this.pi.prompt(text, { images: toImageContent(images) });
+    }
+    steer(text, images) {
+        return this.pi.steer(text, toImageContent(images));
+    }
+    followUp(text, images) {
+        return this.pi.followUp(text, toImageContent(images));
+    }
+    systemInput(text, origin, mode) {
+        return this.pi.sendCustomMessage({ customType: "pier.system-input", content: text, display: true, details: origin }, { triggerTurn: true, deliverAs: mode === "prompt" ? undefined : mode });
+    }
+    abort() {
+        return this.pi.abort();
+    }
+    subscribe(fn) {
+        return this.pi.subscribe((event) => {
+            for (const payload of toSessionEvents(event)) {
+                fn(payload.type === "turn-end" ? { ...payload, meta: this.lastTurnMeta() } : payload);
+            }
+        });
+    }
+    /** Meta of the just-finished turn; live path, so "now" is the completion. */
+    lastTurnMeta() {
+        const messages = this.pi.messages;
+        for (let i = messages.length - 1; i >= 0; i--) {
+            if (messages[i]?.role === "assistant")
+                return turnMetaAt(messages, i, Date.now());
+        }
+        return undefined;
+    }
+    async dispose() {
+        this.pi.dispose();
+    }
+}
+export class PiAgentFactory {
+    extraTools;
+    instructions;
+    skillPaths;
+    credentials;
+    constructor(extraTools = [], 
+    /** Appended as a virtual context file, so Pi's own prompt stays intact.
+     * Read per session, not captured once: it carries settings a user can
+     * change while the process runs, and the next session must say the new
+     * ones. */
+    instructions = () => "", 
+    /** Skills documenting Pier's own tools: loaded per session, never installed
+     * into the user's global or project skill directories. */
+    skillPaths = [], 
+    /** Provider credentials from pier.db instead of <agentDir>/auth.json.
+     * Optional only for bare test factories; main.ts always passes one, and
+     * every runtime built here reads and writes through it — an OAuth refresh
+     * persists to the database, never to a plaintext file. */
+    credentials) {
+        this.extraTools = extraTools;
+        this.instructions = instructions;
+        this.skillPaths = skillPaths;
+        this.credentials = credentials;
+    }
+    /** One runtime for the whole process; catalogs are global, not per session. */
+    catalog;
+    /** Structural fit: CredentialStore mirrors pi-ai's interface of the same
+     * name, so the SDK accepts it without this file exporting any SDK type. */
+    createRuntime() {
+        return ModelRuntime.create(this.credentials ? { credentials: this.credentials } : {});
+    }
+    async availableModels() {
+        this.catalog ??= this.createRuntime();
+        const available = await (await this.catalog).getAvailable();
+        return curateModels(available.map((m) => ({ provider: m.provider, id: m.id, reasoning: m.reasoning })));
+    }
+    /**
+     * Pi discovers AGENTS.md itself; we append one more, in memory, telling the
+     * agent what the surface it is talking to can render. Layered as a context
+     * file (not a systemPromptOverride) so the user's own instructions still win.
+     */
+    async resourceLoader(cwd) {
+        const loader = new DefaultResourceLoader({
+            cwd,
+            agentDir: defaultAgentDir(), // same discovery Pi would have done itself
+            additionalSkillPaths: this.skillPaths,
+            extensionFactories: [{ name: "pier-bash-timeout", factory: bashTimeoutDefault, hidden: true }],
+            agentsFilesOverride: (current) => {
+                const content = this.instructions();
+                return {
+                    agentsFiles: content
+                        ? [...current.agentsFiles, { path: "<pier>/AGENTS.md", content }]
+                        : current.agentsFiles,
+                };
+            },
+        });
+        await loader.reload();
+        return loader;
+    }
+    async open(cwd, sessionManager, opts = { cwd }) {
+        let live;
+        // Generic translation only — tool contracts are data owned by their feature.
+        const customTools = this.extraTools.map((tool) => defineTool({
+            name: tool.name,
+            label: tool.label,
+            description: tool.description,
+            parameters: tool.parameters,
+            execute: async (_id, params, signal) => {
+                const caller = live?.sessionId ?? "unknown";
+                log.debug(`tool ${tool.name} called by ${caller}`);
+                try {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                // Compact, not indented: pretty-printing a nested result
+                                // costs ~20% more tokens and buys the model nothing.
+                                text: JSON.stringify(await tool.execute(params, caller, signal)),
+                            },
+                        ],
+                        details: {},
+                    };
+                }
+                catch (err) {
+                    // Pi turns this into tool-result text the model reads, which is the
+                    // right recovery and the wrong record: rethrown, but logged first.
+                    log.warn(`tool ${tool.name} failed for ${caller}`, err);
+                    throw err;
+                }
+            },
+        }));
+        if (opts.name)
+            sessionManager.appendSessionInfo(opts.name);
+        // Locked Secrets is a refusal with a reason, here — not "provider is not
+        // configured" three calls later, and never a fall back to auth.json.
+        this.credentials?.assertUnlocked();
+        const tools = opts.capabilities === "read"
+            ? ["read", "grep", "find", "ls", ...this.extraTools.map((tool) => tool.name)]
+            : undefined;
+        const created = await createAgentSession({
+            cwd,
+            sessionManager,
+            customTools,
+            tools,
+            modelRuntime: await this.createRuntime(),
+            resourceLoader: await this.resourceLoader(cwd),
+        });
+        live = created.session;
+        const session = new PiSession(live);
+        if (opts.model)
+            await session.setModel(opts.model);
+        if (opts.thinking)
+            session.setThinkingLevel(opts.thinking);
+        log.info(`session ${session.id} open in ${cwd}${opts.name ? ` (${opts.name})` : ""}`);
+        return session;
+    }
+    async create(opts) {
+        return this.open(opts.cwd, SessionManager.create(opts.cwd), opts);
+    }
+    async fork(sourceSessionId, opts) {
+        const infos = await SessionManager.listAll();
+        const source = infos.find((session) => session.id === sourceSessionId);
+        if (!source)
+            throw new Error(`unknown session: ${sourceSessionId}`);
+        const targetDir = SessionManager.create(opts.cwd).getSessionDir();
+        const manager = SessionManager.open(source.path, targetDir, opts.cwd);
+        const branch = manager.getBranch();
+        const latest = branch.at(-1);
+        const hasPendingToolCall = latest?.type === "message" &&
+            latest.message.role === "assistant" &&
+            Array.isArray(latest.message.content) &&
+            latest.message.content.some((part) => part.type === "toolCall");
+        const leafId = hasPendingToolCall ? latest.parentId : latest?.id;
+        if (!leafId)
+            throw new Error("cannot fork a session before its first persisted input");
+        manager.createBranchedSession(leafId);
+        return this.open(opts.cwd, manager, opts);
+    }
+    async resume(sessionId) {
+        const infos = await SessionManager.listAll();
+        const info = infos.find((s) => s.id === sessionId);
+        if (!info)
+            throw new Error(`unknown session: ${sessionId}`);
+        return this.open(info.cwd || process.cwd(), SessionManager.open(info.path));
+    }
+    async list() {
+        const infos = await SessionManager.listAll();
+        return infos.map((s) => ({
+            id: s.id,
+            cwd: s.cwd,
+            createdAt: s.created.getTime(),
+            title: s.name ?? (s.firstMessage ? s.firstMessage.slice(0, 80) : undefined),
+        }));
+    }
+}

package/dist/boards/boards.js

@@ -0,0 +1,200 @@
+// Boards: a folder of static files an agent writes to present something at a
+// stable URL. The filesystem is the source of truth — boards are derived by
+// scanning $PIER_HOME/boards, never registered. See docs/design/05-boards.md.
+//
+// Only <board>/site is reachable over HTTP: sources, README and the manifest
+// itself stay off the wire, so a public board leaks nothing about how it was
+// made. `public` is a data state, not yet a security boundary — nothing in
+// Pier authenticates today (docs/architecture.md, Open Questions).
+import { readdir, readFile, realpath, rename, stat, writeFile } from "node:fs/promises";
+import { extname, join, resolve, sep } from "node:path";
+import { logger } from "../log.js";
+import { pierPath } from "../paths.js";
+export const defaultBoardsDir = () => pierPath("boards");
+/** Deleted boards keep their bytes under `<slug>.deleted-<ts>`, which this
+ *  pattern excludes from every scan — one rename is the whole delete path. */
+const SLUG = /^[a-z0-9][a-z0-9-]{0,63}$/;
+// A board ships fonts and images, so the list is wider than the attachment
+// route's — but still a whitelist: an unlisted extension is not served at all.
+const TYPES = {
+    ".html": "text/html; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".json": "application/json; charset=utf-8",
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".avif": "image/avif",
+    ".ico": "image/x-icon",
+    ".woff2": "font/woff2",
+    ".txt": "text/plain; charset=utf-8",
+    ".csv": "text/plain; charset=utf-8",
+};
+// A published board must not be able to phone home: no third-party fetches, no
+// framing, no beacons. Inline style/script stay allowed — a single-file board
+// is the normal shape.
+const CSP = "default-src 'self'; img-src 'self' data:; style-src 'self' 'unsafe-inline'; " +
+    "script-src 'self' 'unsafe-inline'; connect-src 'none'; frame-ancestors 'none'";
+/** Malformed boards are reported once, not on every scan. */
+const warned = new Set();
+/** The one choke point where a slug becomes a path, so the slug is validated
+ *  here and nowhere else: an unvalidated `../../etc` would read outside the
+ *  boards dir, and a NUL byte would throw instead of 404. Unknown fields get
+ *  defaults, a broken file is skipped whole, and extra keys are the agent's
+ *  business — they survive a write. */
+async function readManifest(dir, slug) {
+    if (!SLUG.test(slug))
+        return null;
+    const file = join(dir, slug, "board.json");
+    let raw;
+    try {
+        raw = JSON.parse(await readFile(file, "utf8"));
+    }
+    catch (err) {
+        // Missing file = not a board; unparsable = a board someone broke.
+        if (err.code !== "ENOENT" && !warned.has(file)) {
+            warned.add(file);
+            logger("boards").warn(`ignoring unreadable manifest ${file}`, err);
+        }
+        return null;
+    }
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+        return null;
+    const m = raw;
+    return {
+        ...m,
+        title: typeof m.title === "string" && m.title ? m.title : slug,
+        description: typeof m.description === "string" ? m.description : "",
+        sessions: Array.isArray(m.sessions) ? m.sessions.filter((s) => typeof s === "string") : [],
+        public: m.public === true,
+    };
+}
+/** Freshness is the site's mtime, not a manifest field — the filesystem
+ *  already knows, and an agent rewriting a page cannot forget to say so. */
+async function updatedAt(dir, slug) {
+    const info = (await stat(join(dir, slug, "site")).catch(() => null)) ??
+        (await stat(join(dir, slug)).catch(() => null));
+    return (info?.mtime ?? new Date()).toISOString();
+}
+export async function listBoards(dir) {
+    let entries;
+    try {
+        entries = (await readdir(dir, { withFileTypes: true }))
+            .filter((e) => e.isDirectory() && SLUG.test(e.name))
+            .map((e) => e.name);
+    }
+    catch {
+        return []; // no boards yet
+    }
+    const boards = [];
+    for (const slug of entries.sort()) {
+        const manifest = await readManifest(dir, slug);
+        if (!manifest)
+            continue;
+        const { title, description, sessions, public: isPublic } = manifest;
+        boards.push({ slug, title, description, sessions, public: isPublic, updatedAt: await updatedAt(dir, slug) });
+    }
+    return boards;
+}
+/** Containment, not normalization: the resolved realpath must sit inside the
+ *  board's own site dir or nothing is served. */
+async function resolveFile(dir, slug, rest) {
+    let relative;
+    try {
+        relative = decodeURIComponent(rest);
+    }
+    catch {
+        return null;
+    }
+    if (relative.includes("\0"))
+        return null;
+    if (!relative || relative.endsWith("/"))
+        relative += "index.html";
+    let root;
+    try {
+        root = await realpath(join(dir, slug, "site"));
+    }
+    catch {
+        return null;
+    }
+    let file;
+    try {
+        file = await realpath(resolve(root, relative));
+    }
+    catch {
+        return null;
+    }
+    if (file !== root && !file.startsWith(root + sep))
+        return null;
+    const info = await stat(file);
+    if (info.isDirectory())
+        return resolveFile(dir, slug, `${relative}/`);
+    return info.isFile() ? file : null;
+}
+async function serveFile(c, dir, slug, rest, publicOnly) {
+    const manifest = await readManifest(dir, slug);
+    // 404, never 403: a private board's existence is not public information.
+    if (!manifest || (publicOnly && !manifest.public))
+        return c.notFound();
+    const file = await resolveFile(dir, slug, rest);
+    if (!file)
+        return c.notFound();
+    const type = TYPES[extname(file).toLowerCase()];
+    if (!type)
+        return c.notFound();
+    const headers = {
+        "content-type": type,
+        "x-content-type-options": "nosniff",
+        // HTML is the page an agent keeps rewriting; assets are fingerprinted or
+        // rare enough that five minutes is safe.
+        "cache-control": type.startsWith("text/html") ? "no-store" : "max-age=300",
+    };
+    if (publicOnly)
+        headers["content-security-policy"] = CSP;
+    return c.body(await readFile(file), 200, headers);
+}
+export function registerBoardRoutes(app, dir = defaultBoardsDir()) {
+    app.get("/api/boards", async (c) => c.json(await listBoards(dir)));
+    // Publishing is the one decision a human owns; every other field belongs to
+    // the agent that wrote the board.
+    app.patch("/api/boards/:slug", async (c) => {
+        const slug = c.req.param("slug");
+        const body = (await c.req.json().catch(() => null));
+        if (typeof body?.public !== "boolean")
+            return c.json({ error: "public must be a boolean" }, 400);
+        const manifest = await readManifest(dir, slug);
+        if (!manifest)
+            return c.json({ error: "no such board" }, 404);
+        manifest.public = body.public;
+        await writeFile(join(dir, slug, "board.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+        return c.json({ public: manifest.public });
+    });
+    app.delete("/api/boards/:slug", async (c) => {
+        const slug = c.req.param("slug");
+        if (!(await readManifest(dir, slug)))
+            return c.json({ error: "no such board" }, 404);
+        await rename(join(dir, slug), join(dir, `${slug}.deleted-${Date.now()}`));
+        return c.json({ deleted: slug });
+    });
+    // Declared before the wildcards below: `_assets` is not a slug.
+    app.get("/boards/_assets/pier.css", async (c) => {
+        const file = new URL("./pier.css", import.meta.url);
+        return c.body(await readFile(file), 200, {
+            "content-type": "text/css; charset=utf-8",
+            "cache-control": "max-age=300",
+        });
+    });
+    // Trailing slash matters: without it a board's relative asset paths resolve
+    // against /boards instead of the board.
+    for (const prefix of ["/boards", "/p"]) {
+        app.get(`${prefix}/:slug`, (c) => c.redirect(`${prefix}/${c.req.param("slug")}/`));
+        app.get(`${prefix}/:slug/*`, (c) => {
+            const slug = c.req.param("slug");
+            const rest = c.req.path.slice(`${prefix}/${slug}/`.length);
+            return serveFile(c, dir, slug, rest, prefix === "/p");
+        });
+    }
+}