@timqi/pier 0.0.1

package/dist/secrets.js

@@ -0,0 +1,191 @@
+// Layer-1 secret encryption: the credentials Pier must read by itself
+// (channel tokens, provider API keys, OAuth tokens) are stored as ciphertext
+// and pass through here. Two keys, standard envelope: a KEK from
+// `~/.pier/master.key` wraps a DEK, and only the DEK touches data — so
+// rotating the KEK rewrites one file and zero data rows. The KEK is either a
+// `vt://` record (decrypted through vt, one approval per process start) or a
+// raw key in the file (the no-vt fallback — same at-rest level as the
+// plaintext files it replaces, and the mode is the operator's explicit
+// choice, never a silent downgrade).
+//
+// Both keys live in `master.key` (JSON: kek, wrapped dek, dek id), not the
+// database: rotation is then a single atomic rename, with no crash window
+// where the file holds the new KEK and the database a DEK wrapped by the old
+// one. Layer 2 — secrets needing per-use approval — never passes through
+// here: those stay `vt://` strings Pier cannot read, and the agent runs vt
+// itself.
+import { spawn } from "node:child_process";
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+import { chmodSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { logger } from "./log.js";
+import { pierPath } from "./paths.js";
+const log = logger("secrets");
+const KEY_BYTES = 32; // AES-256
+const IV_BYTES = 12; // GCM standard nonce
+export class Secrets {
+    path;
+    vt;
+    #dek;
+    #kek;
+    #file;
+    /** Why decrypt is refused right now — "" once unlocked. */
+    #lockedReason = "unlock() has not run";
+    constructor(path = pierPath("master.key"), vt = vtCli) {
+        this.path = path;
+        this.vt = vt;
+    }
+    get state() {
+        return this.#dek ? "unlocked" : "locked";
+    }
+    get mode() {
+        return this.#file ? (this.#file.kek.startsWith("vt://") ? "vt" : "file") : undefined;
+    }
+    /** Why decrypt is refused right now — "" once unlocked. Shown in the
+     *  Console's Security tab, which is where a refused unlock gets repaired. */
+    get lockedReason() {
+        return this.#lockedReason;
+    }
+    /**
+     * Load master.key — created on first boot, file mode, so an unattended
+     * start needs no ceremony; vt mode is entered later via rotate. Throws on a
+     * failed vt approval or a corrupt file, and remembers why: the process must
+     * keep serving (web is how the operator unlocks or repairs), but every
+     * refused decrypt names the reason instead of pretending to be empty.
+     */
+    async unlock() {
+        try {
+            let raw;
+            try {
+                raw = readFileSync(this.path, "utf8");
+            }
+            catch {
+                this.#file = this.#create();
+                log.info(`created ${this.path} (file mode)`);
+                raw = readFileSync(this.path, "utf8");
+            }
+            const file = JSON.parse(raw);
+            if (!file.kek || !file.dek || !file.dekId)
+                throw new Error(`${this.path} is malformed`);
+            this.#kek = file.kek.startsWith("vt://")
+                ? Buffer.from(await this.vt.read(file.kek), "base64")
+                : Buffer.from(file.kek, "base64");
+            if (this.#kek.length !== KEY_BYTES)
+                throw new Error(`${this.path} KEK is not ${KEY_BYTES} bytes`);
+            this.#dek = open(this.#kek, file.dek, `kek:${file.dekId}`);
+            this.#file = file;
+            this.#lockedReason = "";
+            log.info(`secrets unlocked (${this.mode} mode, dek ${file.dekId})`);
+        }
+        catch (err) {
+            this.#lockedReason = String(err);
+            throw err;
+        }
+    }
+    encrypt(plaintext) {
+        const { dek, file } = this.#unlocked();
+        return `v1:${file.dekId}:${seal(dek, plaintext, `v1:${file.dekId}`)}`;
+    }
+    decrypt(blob) {
+        const { dek, file } = this.#unlocked();
+        const [v, dekId, ...rest] = blob.split(":");
+        if (v !== "v1" || rest.length !== 3)
+            throw new Error("not a v1 secret envelope");
+        if (dekId !== file.dekId)
+            throw new Error(`sealed by unknown key ${dekId}, have ${file.dekId}`);
+        return open(dek, rest.join(":"), `v1:${dekId}`).toString("utf8");
+    }
+    /**
+     * New KEK, same DEK: every stored envelope stays valid. `mode` switches how
+     * the new KEK is protected (entering vt mode runs `vt create`, one
+     * approval); omitted, the current mode is kept. The rewrapped file lands by
+     * atomic rename — a crash leaves either the old working file or the new one.
+     */
+    async rotateKek(mode = this.mode ?? "file") {
+        const { file } = this.#unlocked();
+        const kek = randomBytes(KEY_BYTES);
+        const next = {
+            kek: mode === "vt" ? await this.vt.create(kek.toString("base64")) : kek.toString("base64"),
+            dek: seal(kek, this.#dek, `kek:${file.dekId}`),
+            dekId: file.dekId,
+        };
+        if (mode === "vt" && !next.kek.startsWith("vt://")) {
+            throw new Error("vt create did not return a vt:// record");
+        }
+        this.#write(next);
+        this.#kek = kek;
+        this.#file = next;
+        log.info(`KEK rotated (${mode} mode, dek ${file.dekId} unchanged)`);
+    }
+    /** First boot: random KEK and DEK, file mode. */
+    #create() {
+        const kek = randomBytes(KEY_BYTES);
+        const dekId = randomBytes(4).toString("hex");
+        const file = {
+            kek: kek.toString("base64"),
+            dek: seal(kek, randomBytes(KEY_BYTES), `kek:${dekId}`),
+            dekId,
+        };
+        this.#write(file);
+        return file;
+    }
+    #write(file) {
+        const tmp = `${this.path}.tmp`;
+        writeFileSync(tmp, `${JSON.stringify(file, null, 2)}\n`, { mode: 0o600 });
+        chmodSync(tmp, 0o600); // mode above is masked by umask; this is not
+        renameSync(tmp, this.path);
+    }
+    #unlocked() {
+        if (!this.#dek || !this.#file)
+            throw new Error(`secrets locked: ${this.#lockedReason}`);
+        return { dek: this.#dek, file: this.#file };
+    }
+}
+/** AES-256-GCM, `iv:ct:tag` base64. `aad` binds ciphertext to its role, so an
+ *  envelope pasted into another slot fails closed instead of decrypting. */
+function seal(key, plaintext, aad) {
+    const iv = randomBytes(IV_BYTES);
+    const cipher = createCipheriv("aes-256-gcm", key, iv);
+    cipher.setAAD(Buffer.from(aad));
+    const ct = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+    return [iv, ct, cipher.getAuthTag()].map((b) => b.toString("base64")).join(":");
+}
+function open(key, sealed, aad) {
+    const [iv, ct, tag] = sealed.split(":").map((part) => Buffer.from(part, "base64"));
+    if (!iv || !ct || !tag)
+        throw new Error("malformed ciphertext");
+    const decipher = createDecipheriv("aes-256-gcm", key, iv);
+    decipher.setAAD(Buffer.from(aad));
+    decipher.setAuthTag(tag);
+    return Buffer.concat([decipher.update(ct), decipher.final()]);
+}
+/** The real vt CLI. Absent binary or denied approval both surface as the
+ *  spawn/exit error — unlock() records it and the operator reads it. */
+export const vtCli = {
+    read: (record) => run("vt", ["read", record]),
+    create: async (plaintext) => {
+        const out = await run("vt", ["create"], plaintext);
+        const record = out.match(/vt:\/\/\S+/)?.[0];
+        if (!record)
+            throw new Error("vt create printed no vt:// record");
+        return record;
+    },
+};
+function run(cmd, args, stdin) {
+    return new Promise((resolvePromise, reject) => {
+        const child = spawn(cmd, args, { stdio: ["pipe", "pipe", "pipe"] });
+        let out = "";
+        let err = "";
+        child.stdout.on("data", (d) => (out += d.toString()));
+        child.stderr.on("data", (d) => (err += d.toString()));
+        child.on("error", reject);
+        child.on("close", (code) => {
+            if (code === 0)
+                resolvePromise(out.trim());
+            else
+                reject(new Error(`${cmd} ${args[0]} exited ${code}: ${err.trim() || out.trim()}`));
+        });
+        if (stdin !== undefined)
+            child.stdin.write(stdin);
+        child.stdin.end();
+    });
+}

package/dist/service.js

@@ -0,0 +1,134 @@
+// The systemd user unit Pier writes for itself.
+//
+// A *user* unit, not a system one: Pier runs as you, reads your Pi
+// configuration and drives sessions in your own directories. As root or a
+// dedicated service user it would be an agent that cannot touch the files you
+// wanted it to work on.
+//
+// Writing this file is a command rather than a page of documentation to copy
+// because two of its lines are only knowable at runtime: the absolute path of
+// the node that is running (systemd starts with a minimal PATH, so a node
+// installed by fnm/nvm/asdf is not on it) and the absolute path of the
+// installed entry point.
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { homedir, userInfo } from "node:os";
+import { dirname, join } from "node:path";
+export const UNIT_NAME = "pier.service";
+/** `~/.config/systemd/user/pier.service` — where a user unit belongs. */
+export const unitPath = (home = homedir()) => join(home, ".config", "systemd", "user", UNIT_NAME);
+/** The drop-in Pier writes once and never touches again: what the unit may
+ *  consume is the operator's call, not ours. */
+export const limitsPath = (home = homedir()) => join(dirname(unitPath(home)), `${UNIT_NAME}.d`, "limits.conf");
+export function renderUnit({ execPath, entry, host, port, pierHome }) {
+    return `[Unit]
+Description=Pier — agent workspace
+Documentation=https://github.com/timqi/pier
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+WorkingDirectory=%h
+# Absolute paths on purpose: systemd starts with a minimal PATH, and the node
+# that installed Pier is usually not on it.
+ExecStart=${execPath} ${entry}
+Environment=NODE_ENV=production
+# Loopback by default. Put a reverse proxy in front before widening this —
+# whoever reaches this port can drive an agent that runs a shell.
+Environment=HOST=${host}
+Environment=PORT=${port}
+${pierHome ? `# Where the database, the boards and the password hash live.\nEnvironment=PIER_HOME=${pierHome}\n` : ""}Restart=always
+RestartSec=2
+# The journal is where the first-run password is printed, so keep it readable.
+StandardOutput=journal
+StandardError=journal
+# Otherwise every line is tagged "node"; this makes \`journalctl -t pier\` work.
+SyslogIdentifier=pier
+
+[Install]
+WantedBy=default.target
+`;
+}
+/**
+ * Sized as a share of the machine, not as "how much should Pier need": the
+ * limit covers node, every subagent and every command a turn ran, and it
+ * exists to protect the OS and sshd outside it. Written commented so the
+ * operator tuning it can see what each line buys.
+ */
+export function renderLimits() {
+    return `[Service]
+# Soft ceiling: past this the kernel reclaims hard and lets the unit crawl
+# instead of killing anything. This is the one that should bite first.
+MemoryHigh=60%
+# Hard ceiling: the kernel OOM-kills *inside this cgroup*, so what it leaves
+# behind is for everything outside it.
+MemoryMax=75%
+# Swapping an agent is worse than failing it.
+MemorySwapMax=0
+# A runaway command an agent ran can fork as well as allocate.
+TasksMax=512
+# Prefer this unit's processes if the *machine* runs out anyway.
+OOMScoreAdjust=200
+# A child being OOM-killed must not take the service with it.
+OOMPolicy=continue
+`;
+}
+/** Best-effort: a step that fails says so and the rest still runs, because a
+ *  half-installed service the operator knows about beats a stack trace. */
+const runner = (say) => (argv) => {
+    try {
+        execFileSync(argv[0], argv.slice(1), { stdio: "pipe" });
+        return true;
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message.split("\n")[0] : String(err);
+        say(`! ${argv.join(" ")} — ${detail}`);
+        return false;
+    }
+};
+export function install(options) {
+    const { force, home = homedir(), say, exec, ...unit } = options;
+    const run = exec ?? runner(say);
+    const path = unitPath(home);
+    if (existsSync(path) && !force) {
+        say(`${path} already exists — nothing written. Re-run with --force to replace it.`);
+        return;
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, renderUnit(unit), { mode: 0o644 });
+    say(`wrote ${path}`);
+    const limits = limitsPath(home);
+    if (existsSync(limits)) {
+        say(`kept ${limits}`); // tuned by hand, by definition
+    }
+    else {
+        mkdirSync(dirname(limits), { recursive: true });
+        writeFileSync(limits, renderLimits(), { mode: 0o644 });
+        say(`wrote ${limits}`);
+    }
+    run(["systemctl", "--user", "daemon-reload"]);
+    // Without lingering, the user manager stops at logout and takes every
+    // scheduled task with it. It can need a polkit prompt, hence best-effort.
+    if (!run(["loginctl", "enable-linger", userInfo().username])) {
+        say(`  run it yourself so Pier survives logout: loginctl enable-linger ${userInfo().username}`);
+    }
+    if (run(["systemctl", "--user", "enable", "--now", UNIT_NAME])) {
+        say(`started. The first run prints a password once: journalctl --user -u pier -e`);
+    }
+}
+export function uninstall(home = homedir(), say = console.log, exec) {
+    const run = exec ?? runner(say);
+    run(["systemctl", "--user", "disable", "--now", UNIT_NAME]);
+    for (const path of [unitPath(home), limitsPath(home)]) {
+        if (!existsSync(path))
+            continue;
+        rmSync(path, { force: true });
+        say(`removed ${path}`);
+    }
+    rmSync(dirname(limitsPath(home)), { force: true, recursive: true });
+    run(["systemctl", "--user", "daemon-reload"]);
+    // Left alone on purpose: the database, the boards, and linger — none of them
+    // are this command's to decide about.
+    say(`$PIER_HOME is untouched; linger is still enabled.`);
+}

package/dist/settings.js

@@ -0,0 +1,57 @@
+// Instance settings: the facts about *this* Pier that are neither a credential
+// nor per-session. Today there is one — the URL it is reached at from outside,
+// which nothing in the process can discover for itself: a request's Host header
+// is whatever a proxy chose to pass on, and an agent writing a board has no
+// request at all.
+//
+// A key-value table, so the next setting is not the next table and not a third
+// kind of storage. It used to be a JSON file, justified by "the agent reads it
+// too" — the agent is told the URL in its system prompt (core/reply.ts), and
+// nothing outside this process ever opened that file.
+import { pierDb } from "./db.js";
+/**
+ * `""` clears it, `null` rejects it. Rejecting rather than repairing: a
+ * mistyped host quietly turned into a URL produces board links that 404 for
+ * the person they were sent to, and the sender never finds out.
+ */
+export function normalizePublicUrl(raw) {
+    const text = raw.trim();
+    if (!text)
+        return "";
+    let url;
+    try {
+        // Scheme-less input is the common way to type a host, and https is the
+        // only guess worth making for something on the internet.
+        url = new URL(text.includes("://") ? text : `https://${text}`);
+    }
+    catch {
+        return null;
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:")
+        return null;
+    if (url.search || url.hash || url.username || url.password)
+        return null;
+    return `${url.origin}${url.pathname}`.replace(/\/+$/, "");
+}
+export class SettingsStore {
+    #db;
+    constructor(db = pierDb()) {
+        this.#db = db;
+    }
+    get() {
+        return { publicUrl: this.#value("publicUrl") ?? "" };
+    }
+    /** Store an already-normalized value — validation belongs at the boundary
+     *  that received it, so this never has to guess what the caller meant. */
+    setPublicUrl(publicUrl) {
+        this.#db.prepare(`
+      INSERT INTO settings(key, value) VALUES ('publicUrl', ?)
+      ON CONFLICT(key) DO UPDATE SET value = excluded.value
+    `).run(publicUrl);
+        return this.get();
+    }
+    #value(key) {
+        const row = this.#db.prepare("SELECT value FROM settings WHERE key = ?").get(key);
+        return row?.value;
+    }
+}

package/dist/tasks/agent.js

@@ -0,0 +1,197 @@
+import { Router } from "../core/router.js";
+import { TaskMessenger } from "./messages.js";
+import { TaskStore } from "./store.js";
+const MAX_ACTIVE_AGENTS = 4;
+const MAX_ACTIVE_PER_ROOT = 4;
+export class AgentTaskRunner {
+    factory;
+    router;
+    store;
+    messages;
+    changed;
+    active = new Set();
+    slotWaiters = new Set();
+    sessionTails = new Map();
+    constructor(factory, router, store, messages, changed) {
+        this.factory = factory;
+        this.router = router;
+        this.store = store;
+        this.messages = messages;
+        this.changed = changed;
+    }
+    async execute(run, action, signal, start) {
+        await this.acquireSlot(run, signal);
+        try {
+            const session = await this.resolveSession(run, action);
+            return await this.withSession(session.id, async () => {
+                await this.waitUntilIdle(session, signal);
+                start();
+                // No input is no block: `<task_input>\nnull\n</task_input>` is four
+                // lines telling the agent nothing, on every run that has no input.
+                const input = run.input === undefined || run.input === null
+                    ? ""
+                    : `\n\n<task_input>\n${JSON.stringify(run.input, null, 2)}\n</task_input>`;
+                const prompt = run.context.resumePrompt ?? `${action.prompt}${input}`;
+                run.context.sessionId = session.id;
+                run.context.model = session.model;
+                run.context.renderedPrompt = prompt;
+                this.store.saveRun(run);
+                let text = "";
+                const unsubscribe = session.subscribe((event) => {
+                    if (event.type === "turn-end")
+                        text = event.text;
+                });
+                const abort = () => void session.abort();
+                signal.addEventListener("abort", abort, { once: true });
+                // A pre-aborted signal never fires the listener: check before the
+                // prompt starts or a cancelled run would hang until its timeout.
+                if (signal.aborted)
+                    throw new Error("cancelled");
+                try {
+                    const turn = session.systemInput(prompt, {
+                        kind: "task-delegation",
+                        taskId: run.taskId,
+                        runId: run.id,
+                        sourceSessionId: run.sourceSessionId,
+                    }, "prompt");
+                    await Promise.resolve();
+                    this.messages.deliverPendingControls(run);
+                    await turn;
+                    if (signal.aborted)
+                        throw new Error("cancelled");
+                    if (!text) {
+                        const history = await session.history();
+                        text = [...history].reverse().find((turn) => turn.role === "assistant")?.text ?? "";
+                    }
+                    return { type: "agent", text, sessionId: session.id };
+                }
+                finally {
+                    signal.removeEventListener("abort", abort);
+                    unsubscribe();
+                }
+            });
+        }
+        finally {
+            this.releaseSlot(run.id);
+        }
+    }
+    async resolveSession(run, action) {
+        if (run.targetSessionId) {
+            return this.router.ensure({ channelId: "task", conversationId: run.targetSessionId });
+        }
+        const listed = await this.factory.list();
+        const source = run.sourceSessionId
+            ? listed.find((session) => session.id === run.sourceSessionId)
+            : undefined;
+        const policy = action.session;
+        let cwd;
+        if (run.sessionMode === "fork") {
+            if (!run.sourceSessionId)
+                throw new Error("fork requires a source session");
+            cwd = policy.mode === "fork" && policy.cwd ? policy.cwd : source?.cwd ?? "";
+        }
+        else if (policy.mode === "fresh") {
+            cwd = policy.cwd;
+        }
+        else if (policy.mode === "reuse") {
+            cwd = listed.find((session) => session.id === policy.sessionId)?.cwd ?? "";
+        }
+        else {
+            cwd = policy.cwd ?? source?.cwd ?? "";
+        }
+        if (!cwd)
+            throw new Error("could not resolve child working directory");
+        const opts = {
+            cwd,
+            name: `${run.context.definition.name} [${run.id.slice(0, 8)}]`,
+            // Unspecified model inherits the caller's live model, not the global
+            // default; falls back to the default when the caller isn't attached.
+            model: action.launch?.model ??
+                (run.sourceSessionId ? this.router.modelOf(run.sourceSessionId) : undefined),
+            thinking: action.launch?.thinking,
+            capabilities: action.launch?.capabilities,
+        };
+        const session = run.sessionMode === "fork"
+            ? await this.factory.fork(run.sourceSessionId, opts)
+            : await this.factory.create(opts);
+        run.targetSessionId = session.id;
+        run.context.sessionId = session.id;
+        run.context.cwd = cwd;
+        this.store.saveRun(run);
+        this.router.attach({ channelId: "task", conversationId: session.id }, session);
+        this.changed(run);
+        return session;
+    }
+    async acquireSlot(run, signal) {
+        while (this.active.size >= MAX_ACTIVE_AGENTS || this.activeForRoot(run.rootRunId) >= MAX_ACTIVE_PER_ROOT) {
+            if (signal.aborted)
+                throw new Error("cancelled");
+            await new Promise((resolve, reject) => {
+                const wake = () => {
+                    signal.removeEventListener("abort", abort);
+                    this.slotWaiters.delete(wake);
+                    resolve();
+                };
+                const abort = () => {
+                    this.slotWaiters.delete(wake);
+                    reject(new Error("cancelled"));
+                };
+                this.slotWaiters.add(wake);
+                signal.addEventListener("abort", abort, { once: true });
+            });
+        }
+        this.active.add(run.id);
+    }
+    activeForRoot(rootRunId) {
+        let count = 0;
+        for (const id of this.active) {
+            if (this.store.getRun(id)?.rootRunId === rootRunId)
+                count += 1;
+        }
+        return count;
+    }
+    releaseSlot(id) {
+        this.active.delete(id);
+        for (const wake of this.slotWaiters)
+            wake();
+    }
+    async withSession(sessionId, fn) {
+        const previous = this.sessionTails.get(sessionId) ?? Promise.resolve();
+        let release = () => { };
+        const gate = new Promise((resolve) => { release = resolve; });
+        const tail = previous.then(() => gate);
+        this.sessionTails.set(sessionId, tail);
+        await previous;
+        try {
+            return await fn();
+        }
+        finally {
+            release();
+            if (this.sessionTails.get(sessionId) === tail)
+                this.sessionTails.delete(sessionId);
+        }
+    }
+    async waitUntilIdle(session, signal) {
+        // The session's own event stream is the only busy/idle signal — no polling.
+        while (session.state === "streaming") {
+            if (signal.aborted)
+                throw new Error("cancelled");
+            await new Promise((resolve, reject) => {
+                const settle = (error) => {
+                    unsubscribe();
+                    signal.removeEventListener("abort", onAbort);
+                    if (error)
+                        reject(error);
+                    else
+                        resolve();
+                };
+                const onAbort = () => settle(new Error("cancelled"));
+                const unsubscribe = session.subscribe((event) => {
+                    if (event.type === "state" && event.state === "idle")
+                        settle();
+                });
+                signal.addEventListener("abort", onAbort, { once: true });
+            });
+        }
+    }
+}