@paxnax/berliner 0.0.0-stage → 0.2.0

package/dist/git.js

@@ -0,0 +1,42 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const run = promisify(execFile);
+// Each fact is best effort: no git, no repository, or a slow disk gives null.
+async function git(cwd, args) {
+    try {
+        return (await run("git", args, { cwd, timeout: 2000 })).stdout.trim();
+    }
+    catch {
+        return null;
+    }
+}
+// git@github.com:owner/name.git, ssh://git@github.com/owner/name.git, https://[user@]github.com/owner/name[.git]
+const GITHUB = /^(?:git@github\.com:|(?:https|ssh|git):\/\/(?:[^@/]+@)?github\.com\/)([\w.-]+\/[\w.-]+?)(?:\.git)?\/?$/i;
+// Any other SSH remote: [user@]host:owner/name[.git] or ssh://[user@]host[:port]/owner/name[.git]. The host never starts with
+// "-", so ssh can't read it as an option.
+const SSH = /^(?:(?:[^@/:]+@)?(\w[\w.-]*):|ssh:\/\/(?:[^@/]+@)?(\w[\w.-]*)(?::\d+)?\/)([\w.-]+\/[\w.-]+?)(?:\.git)?\/?$/i;
+// owner/name of a GitHub origin. An SSH host alias (Host github-work, HostName github.com) counts: `ssh -G` only prints the
+// config it resolves, without connecting. ssh.github.com is GitHub's SSH over port 443.
+async function repository(origin, sshConfig) {
+    const github = origin?.match(GITHUB)?.[1];
+    const ssh = github || !origin ? null : origin.match(SSH);
+    if (!ssh)
+        return github ?? null;
+    const config = await run("ssh", [...(sshConfig ? ["-F", sshConfig] : []), "-G", ssh[1] ?? ssh[2]], { timeout: 2000 }).then((r) => r.stdout, () => "");
+    return /^hostname (ssh\.)?github\.com$/im.test(config) ? ssh[3] : null;
+}
+// sshConfig is for tests only: ssh finds ~/.ssh/config through the user database, not $HOME, so a test passes its own file.
+export async function gitFacts(cwd, since, sshConfig) {
+    const [origin, branch, email] = await Promise.all([
+        git(cwd, ["remote", "get-url", "origin"]),
+        git(cwd, ["branch", "--show-current"]),
+        git(cwd, ["config", "user.email"]),
+    ]);
+    let commits = null;
+    if (since && email) {
+        // -F with the brackets matches the author's email exactly, not as a pattern or a part of a longer address.
+        const count = await git(cwd, ["rev-list", "--count", "-F", `--author=<${email}>`, `--since=${since}`, "HEAD"]);
+        commits = count === null ? null : Number(count);
+    }
+    return { repository: await repository(origin, sshConfig), branch: branch || null, commits };
+}

package/dist/index.js

@@ -0,0 +1,71 @@
+#!/bin/sh
+//usr/bin/true; exec "$(command -v node || command -v bun)" "$0" "$@"
+import { parse } from "./args.js";
+import { CliError } from "./client.js";
+import { del } from "./commands/delete.js";
+import { hook } from "./commands/hook.js";
+import { report } from "./commands/report.js";
+import { session } from "./commands/session.js";
+import { sessions } from "./commands/sessions.js";
+import { setup } from "./commands/setup.js";
+import { skill } from "./commands/skill.js";
+import { summary } from "./commands/summary.js";
+import { update } from "./commands/update.js";
+import { readConfig } from "./config.js";
+import { warn } from "./output.js";
+const usage = `Usage: berliner <command> [flags]
+
+Commands:
+  setup                 connect this terminal, install the CLI and skill [--yes --no-install --no-browser]
+  report --session-id <id> --title <t> --repo <owner/name> --cost <usd> --model <m> --plan <p>
+         [--task --task-url --project --started-at --ended-at --commits --coverage]
+         [--pr <url>[,merge=<state>][,ci=<state>]]... [--evidence <path>[::caption]]... [--json] [--strict]
+         inside Claude Code, Codex or OpenCode the session id, cost, model and repo are filled in,
+         and the server picks the plan (BERLINER_PLAN overrides it)
+  update <session-id>   same flags as report, all optional (no session id inside those tools)
+  sessions              [--repo --model --project --ci --merge --since <N>d | --from --to] [--limit <n>] [--json]
+  session <session-id>  [--json]
+  summary               same filters as sessions [--json]
+  delete <session-id>   [--evidence <id>] [--yes]
+  skill                 print the bundled SKILL.md
+  hook <tool>           run by the hooks of claude-code, codex or opencode; reads the payload on stdin
+
+Environment: BERLINER_TOKEN, BERLINER_URL, BERLINER_PLAN (replaces --plan)`;
+const args = parse(process.argv.slice(2));
+// Reporting must never fail the agent's own pipeline unless it asks to (anti-goal 1).
+const softFail = (args.command === "report" || args.command === "update") && !args.values.strict;
+const handled = new Set(["setup", "report", "update", "sessions", "session", "summary", "delete", "skill", "hook"]);
+const cfg = () => readConfig(process.env);
+try {
+    if (args.values.help)
+        console.log(usage);
+    // Before the usage check: the hook stays silent even when called wrongly, and logs instead.
+    else if (args.command === "hook")
+        await hook(process.env, args.positionals, args.values);
+    else if (args.error)
+        throw new CliError(args.error, "usage");
+    else if (args.command === "setup")
+        await setup(process.env, args.values);
+    else if (args.command === "report")
+        await report(cfg(), args.values, args.positionals, process.env);
+    else if (args.command === "update")
+        await update(cfg(), args.values, args.positionals, process.env);
+    else if (args.command === "sessions")
+        await sessions(cfg(), args.values);
+    else if (args.command === "session")
+        await session(cfg(), args.values, args.positionals);
+    else if (args.command === "summary")
+        await summary(cfg(), args.values);
+    else if (args.command === "delete")
+        await del(cfg(), args.values, args.positionals);
+    else if (args.command === "skill")
+        skill();
+    else
+        throw new CliError(args.command ? `unknown command "${args.command}"` : "missing command", "usage");
+}
+catch (err) {
+    warn(err instanceof Error ? err.message : String(err));
+    if (args.error === null && !handled.has(args.command ?? ""))
+        console.error(usage);
+    process.exitCode = softFail ? 0 : 1;
+}

package/dist/output.js

@@ -0,0 +1,28 @@
+export function print(result, json) {
+    console.log(json ? JSON.stringify(result.data, null, 2) : result.text);
+}
+// Always a single line, so agents and CI logs see exactly one warning.
+export function warn(msg) {
+    console.error(`berliner: ${msg.replace(/\s*\n\s*/g, " ")}`);
+}
+// Same wording as the web's mergeLabel (app/src/web/format.ts).
+const MERGE = { open: "Open", merged: "Merged", closed: "Closed", none: "No PRs" };
+export const mergeLabel = (s) => s.pr_count > 1 ? `${s.merged_count} of ${s.pr_count} merged` : (MERGE[s.merge] ?? s.merge);
+// Same wording as the web's subscriptionLabel (app/src/web/format.ts): "Claude Max x20".
+const VENDOR = { anthropic: "Claude", openai: "OpenAI" };
+const PLAN = {
+    free: "Free",
+    pro: "Pro",
+    max_x5: "Max x5",
+    max_x20: "Max x20",
+    team: "Team",
+    enterprise: "Enterprise",
+    go: "Go",
+    plus: "Plus",
+    pro_more: "Pro More",
+    pro_max: "Pro Max",
+    business: "Business",
+    business_premium: "Business Premium",
+    api: "API",
+};
+export const subscriptionLabel = (s) => `${VENDOR[s.vendor] ?? s.vendor} ${PLAN[s.plan] ?? s.plan}`;

package/dist/prices.js

@@ -0,0 +1,98 @@
+import { mkdir, readFile, rename, rm, stat, utimes, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { cacheDir } from "./config.js";
+const SOURCE = "https://models.dev/api.json";
+const DAY_MS = 24 * 60 * 60 * 1000;
+async function fetchSource(env) {
+    // BERLINER_PRICES_FILE stands in for models.dev so tests never touch the network. Deliberately undocumented: it's a test seam, not a setting.
+    if (env.BERLINER_PRICES_FILE)
+        return JSON.parse(await readFile(env.BERLINER_PRICES_FILE, "utf8"));
+    // Well inside the hook child's 15-second deadline, so a slow models.dev never costs the report.
+    const res = await fetch(SOURCE, { signal: AbortSignal.timeout(4_000) });
+    if (!res.ok)
+        throw new Error(`${SOURCE} answered ${res.status}`);
+    return res.json();
+}
+// Resellers repeat the first-party ids, so a model's price comes from anthropic, then openai, then the first provider listing it.
+function slim(data) {
+    if (typeof data !== "object" || data === null)
+        throw new Error("unexpected price list");
+    const providers = data;
+    const order = ["anthropic", "openai", ...Object.keys(providers).filter((p) => p !== "anthropic" && p !== "openai")];
+    const prices = {};
+    for (const provider of order) {
+        for (const [id, model] of Object.entries(providers[provider]?.models ?? {})) {
+            const c = model?.cost;
+            if (Object.hasOwn(prices, id) || typeof c?.input !== "number" || typeof c.output !== "number")
+                continue;
+            // shortcut: tiered prices by context size are ignored; upgrade if estimates drift from the tools' own figures.
+            const price = { input: c.input, output: c.output };
+            if (typeof c.cache_read === "number")
+                price.cache_read = c.cache_read;
+            if (typeof c.cache_write === "number")
+                price.cache_write = c.cache_write;
+            prices[id] = price;
+        }
+    }
+    return prices;
+}
+async function readCache(file) {
+    try {
+        const [text, info] = await Promise.all([readFile(file, "utf8"), stat(file)]);
+        const prices = JSON.parse(text);
+        if (typeof prices !== "object" || prices === null || !Object.keys(prices).length)
+            return null;
+        return { prices: prices, fresh: Date.now() - info.mtimeMs < DAY_MS };
+    }
+    catch {
+        return null;
+    }
+}
+// Prices cached for a day. A failed fetch falls back to the cache at any age; null when there is neither.
+export async function loadPrices(env) {
+    const file = join(cacheDir(env), "prices.json");
+    const cached = await readCache(file);
+    if (cached?.fresh)
+        return cached.prices;
+    let prices;
+    try {
+        prices = slim(await fetchSource(env));
+        // A list without a single price is a broken answer: never cached, never used.
+        if (!Object.keys(prices).length)
+            throw new Error("no prices");
+    }
+    catch {
+        // Touched, so the calls of the next day use the stale cache instead of waiting on the source again.
+        if (cached)
+            await utimes(file, new Date(), new Date()).catch(() => { });
+        return cached?.prices ?? null;
+    }
+    // The cache only saves a download; failing to write it is not an error. Renamed into place, so a reader never sees half of it.
+    const temp = `${file}.${process.pid}`;
+    await mkdir(cacheDir(env), { recursive: true })
+        .then(() => writeFile(temp, JSON.stringify(prices)))
+        .then(() => rename(temp, file))
+        .catch(() => rm(temp, { force: true }).catch(() => { }));
+    return prices;
+}
+// A missing cache price is charged at the input price. models.dev's cache_write is the 5-minute rate; Anthropic bills 1-hour
+// cache writes at twice the input price.
+export function estimateCost(tokensByModel, prices) {
+    let costUsd = 0;
+    const unpriced = [];
+    for (const [model, t] of Object.entries(tokensByModel)) {
+        const p = Object.hasOwn(prices, model) ? prices[model] : undefined;
+        if (!p) {
+            unpriced.push(model);
+            continue;
+        }
+        costUsd +=
+            (t.input * p.input +
+                t.output * p.output +
+                t.cacheRead * (p.cache_read ?? p.input) +
+                t.cacheWrite * (p.cache_write ?? p.input) +
+                t.cacheWrite1h * 2 * p.input) /
+                1e6;
+    }
+    return { costUsd, unpriced };
+}

package/dist/setup/connect.js

@@ -0,0 +1,42 @@
+import { spawn } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { hostname } from "node:os";
+import { CliError, request } from "../client.js";
+// The name the approval page and Settings show for this machine.
+export const machineName = () => hostname()
+    .replace(/\.local$/, "")
+    .slice(0, 64);
+// The token is made here, like Settings' tokens; the server only ever sees its hash and prefix.
+export async function startConnect(cfg, clientName) {
+    const token = `brl_${randomBytes(32).toString("base64url")}`;
+    const body = { client_name: clientName, token_hash: createHash("sha256").update(token).digest("hex"), token_prefix: token.slice(0, 11) };
+    const { json } = await request(cfg, "POST", "/v1/connect", body, { auth: false });
+    return { ...json, token };
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export async function waitForApproval(cfg, id, interval, expiresIn) {
+    const deadline = Date.now() + expiresIn * 1000;
+    for (;;) {
+        await sleep(interval * 1000);
+        try {
+            const { json } = await request(cfg, "GET", `/v1/connect/${id}`, undefined, { auth: false, deadlineMs: 15_000 });
+            if (json.status !== "pending")
+                return json.status;
+        }
+        catch (err) {
+            // A network blip, a rate limit or a server error is no answer: the request stays pending until it expires. A 404 or
+            // another refusal ends the wait.
+            const unanswered = err instanceof CliError && (err.kind === "network" || err.status === 429 || (err.status ?? 0) >= 500);
+            if (!unanswered)
+                throw err;
+        }
+        if (Date.now() >= deadline)
+            return "expired";
+    }
+}
+// Best effort: when no browser opens, the printed URL is enough.
+export function openBrowser(url) {
+    const child = spawn(process.platform === "darwin" ? "open" : "xdg-open", [url], { detached: true, stdio: "ignore" });
+    child.on("error", () => { }); // a missing opener is reported here, not thrown
+    child.unref();
+}

package/dist/setup/hooks.js

@@ -0,0 +1,84 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+const entries = (tool, asyncStop) => {
+    const hooks = (extra = {}) => [{ type: "command", command: `berliner hook ${tool}`, ...extra }];
+    return {
+        // Claude Code runs Stop after every reply; async keeps the agent from waiting on it.
+        Stop: { hooks: hooks(asyncStop ? { async: true } : {}) },
+        PreCompact: { hooks: hooks() },
+        SessionEnd: { hooks: hooks() },
+        // Not async: what it prints is the reminder, which the tool adds to the agent's context.
+        SessionStart: { matcher: "compact|clear", hooks: hooks() },
+    };
+};
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const ours = (entry) => isObject(entry) &&
+    Array.isArray(entry.hooks) &&
+    entry.hooks.some((h) => isObject(h) && typeof h.command === "string" && h.command.startsWith("berliner hook "));
+// The file with our entries added to the events that lack one, or null when nothing is missing. "unreadable" when it
+// isn't a JSON object whose hooks we can add to: then it is the user's to fix, and is never rewritten.
+function merged(file, add) {
+    let text = null;
+    let json = {};
+    try {
+        text = readFileSync(file, "utf8");
+        json = JSON.parse(text);
+    }
+    catch (err) {
+        if (text !== null || err.code !== "ENOENT")
+            return "unreadable";
+    }
+    if (!isObject(json))
+        return "unreadable";
+    const hooks = json.hooks ?? {};
+    if (!isObject(hooks))
+        return "unreadable";
+    let changed = false;
+    for (const [event, entry] of Object.entries(add)) {
+        const list = hooks[event] ?? [];
+        if (!Array.isArray(list))
+            return "unreadable";
+        if (list.some(ours))
+            continue;
+        hooks[event] = [...list, entry];
+        changed = true;
+    }
+    if (!changed)
+        return null;
+    const indent = text?.match(/^[ \t]+(?=\S)/m)?.[0] ?? "  ";
+    return `${JSON.stringify({ ...json, hooks }, null, indent)}\n`;
+}
+function install(file, add) {
+    const text = merged(file, add);
+    if (text === "unreadable")
+        return text;
+    if (text === null)
+        return "present";
+    mkdirSync(dirname(file), { recursive: true });
+    // In place, so a settings file that is a symlink stays one.
+    writeFileSync(file, text);
+    return "added";
+}
+const describe = (text) => (text === "unreadable" ? "can't be read, left unchanged" : text === null ? "already installed" : "adds a hook");
+export const installClaudeHooks = (settingsPath) => install(settingsPath, entries("claude-code", true));
+export const describeClaudeHooks = (settingsPath) => describe(merged(settingsPath, entries("claude-code", true)));
+export const installCodexHooks = (hooksPath) => install(hooksPath, entries("codex", false));
+export const describeCodexHooks = (hooksPath) => describe(merged(hooksPath, entries("codex", false)));
+// dist/setup/hooks.js -> ../../opencode/berliner.js (the package's opencode/ directory).
+const plugin = () => readFileSync(new URL("../../opencode/berliner.js", import.meta.url), "utf8");
+const current = (pluginPath) => {
+    try {
+        return readFileSync(pluginPath, "utf8") === plugin();
+    }
+    catch {
+        return false;
+    }
+};
+export function installOpenCodePlugin(pluginPath) {
+    if (current(pluginPath))
+        return "present";
+    mkdirSync(dirname(pluginPath), { recursive: true });
+    writeFileSync(pluginPath, plugin());
+    return "added";
+}
+export const describeOpenCodePlugin = (pluginPath) => (current(pluginPath) ? "already installed" : "adds a hook");

package/dist/setup/targets.js

@@ -0,0 +1,41 @@
+import { accessSync, constants, existsSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+export const claudeDir = (env) => env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude");
+export const codexDir = (env) => env.CODEX_HOME || join(homedir(), ".codex");
+export const opencodeDir = (env) => join(env.XDG_CONFIG_HOME || join(homedir(), ".config"), "opencode");
+// The spec's table (docs/superpowers/specs/2026-10-20-onboarding-design.md, "Where each tool looks for skills").
+const TOOLS = [
+    { id: "claude-code", name: "Claude Code", bin: "claude", dir: claudeDir },
+    { id: "codex", name: "Codex", bin: "codex", dir: codexDir },
+    { id: "opencode", name: "OpenCode", bin: "opencode", dir: opencodeDir },
+];
+function isExecutable(file) {
+    try {
+        accessSync(file, constants.X_OK);
+        return statSync(file).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+export const onPath = (bin, env) => (env.PATH ?? "").split(":").some((dir) => dir !== "" && isExecutable(join(dir, bin)));
+export function detectTools(env) {
+    return TOOLS.map((t) => ({ id: t.id, name: t.name, found: onPath(t.bin, env) || existsSync(t.dir(env)) }));
+}
+const skillFile = (dir) => join(dir, "skills", "berliner", "SKILL.md");
+// One target per tool found. OpenCode reads ~/.claude/skills and ~/.agents/skills too, so it gets its own copy only when neither is written.
+export function skillTargets(tools, env) {
+    const found = (id) => tools.some((t) => t.id === id && t.found);
+    const targets = [];
+    if (found("claude-code"))
+        targets.push({ tool: "claude-code", path: skillFile(claudeDir(env)) });
+    if (found("codex"))
+        targets.push({ tool: "codex", path: skillFile(join(homedir(), ".agents")) });
+    if (found("opencode")) {
+        const read = [".claude", ".agents"].map((d) => skillFile(join(homedir(), d)));
+        const covering = targets.find((t) => read.includes(t.path));
+        targets.push({ tool: "opencode", path: covering?.path ?? skillFile(opencodeDir(env)) });
+    }
+    return targets.map((t) => ({ ...t, exists: existsSync(t.path) }));
+}

package/dist/upload.js

@@ -0,0 +1,94 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { open, stat } from "node:fs/promises";
+import path from "node:path";
+import { CliError, request } from "./client.js";
+const TYPES = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".mp4": "video/mp4",
+    ".webm": "video/webm",
+    ".mov": "video/quicktime",
+};
+// Evidence uploads are exempt from the 15 s report deadline (ruling R25).
+const LONG = { timeoutMs: 120_000, deadlineMs: 120_000 };
+export async function uploadEvidence(cfg, sessionId, files, budget = LONG) {
+    const result = { uploaded: 0, existing: 0, skipped: [] };
+    let unreachable = null;
+    for (const file of files) {
+        if (unreachable) {
+            result.skipped.push({ path: file.path, reason: unreachable });
+            continue;
+        }
+        try {
+            if (await uploadOne(cfg, sessionId, file, budget))
+                result.uploaded++;
+            else
+                result.existing++;
+        }
+        catch (err) {
+            // One bad file never fails the report.
+            const reason = err instanceof Error ? err.message : String(err);
+            result.skipped.push({ path: file.path, reason });
+            // The next file would wait out the same budget against the same server (anti-goal 1).
+            if (err instanceof CliError && err.kind === "network")
+                unreachable = reason;
+        }
+    }
+    return result;
+}
+// Resolves true when uploaded, false when the server already had the content.
+async function uploadOne(cfg, sessionId, file, budget) {
+    const contentType = TYPES[path.extname(file.path).toLowerCase()];
+    if (!contentType)
+        throw new Error("unsupported file type");
+    const size = await stat(file.path).then((s) => (s.isFile() ? s.size : 0), () => -1);
+    if (size < 0)
+        throw new Error("file not found");
+    if (size === 0)
+        throw new Error("file is empty");
+    const hash = createHash("sha256");
+    for await (const chunk of createReadStream(file.path))
+        hash.update(chunk);
+    const { json } = await request(cfg, "POST", `/v1/sessions/${encodeURIComponent(sessionId)}/evidence`, {
+        filename: path.basename(file.path),
+        content_type: contentType,
+        size_bytes: size,
+        sha256: hash.digest("hex"),
+        caption: file.caption,
+    }, budget);
+    if (json.status === "exists")
+        return false;
+    const base = `/v1/evidence/${json.evidence.id}`;
+    const handle = await open(file.path);
+    try {
+        const slice = async (start, length) => {
+            const buf = Buffer.alloc(length);
+            const { bytesRead } = await handle.read(buf, 0, length, start);
+            if (bytesRead !== length)
+                throw new Error("file changed while uploading");
+            return buf;
+        };
+        if (json.upload.mode === "single") {
+            await request(cfg, "PUT", `${base}/content`, await slice(0, size), budget);
+        }
+        else {
+            const parts = [];
+            const partSize = json.upload.part_size;
+            if (!Number.isInteger(partSize) || partSize < 1)
+                throw new Error("the server sent an invalid part size"); // 0 would loop forever
+            for (let start = 0, n = 1; start < size; start += partSize, n++) {
+                const res = await request(cfg, "PUT", `${base}/parts/${n}`, await slice(start, Math.min(partSize, size - start)), budget);
+                parts.push({ part_number: n, etag: res.json.etag });
+            }
+            await request(cfg, "POST", `${base}/complete`, { parts }, budget);
+        }
+    }
+    finally {
+        await handle.close();
+    }
+    return true;
+}

package/opencode/berliner.js

@@ -0,0 +1,124 @@
+// Berliner's OpenCode plugin, installed by `berliner setup` to ${XDG_CONFIG_HOME:-~/.config}/opencode/plugins/berliner.js.
+// It reports each top-level session to Berliner through `berliner hook opencode`, and must never throw into OpenCode or make it wait.
+//
+// Checked against OpenCode 1.18.30 (https://opencode.ai/docs/plugins/ and @opencode-ai/plugin 1.18.30's Hooks type):
+// - a plugin is an exported async function of { client, directory, ... } that returns its hooks;
+// - `event` receives every bus event; session.idle carries properties.sessionID;
+// - `shell.env` runs before the agent's shell tool (with sessionID) and before user terminals (without one);
+// - `experimental.session.compacting` runs before every compaction, manual (/compact) and automatic alike, and adds
+//   output.context to the summary prompt;
+// - client.session.get({ path: { id } }) returns { data } with the server's Session, which holds cost, tokens and model,
+//   so the messages are not needed;
+// - subagents run in child sessions (parentID set), each with its own cost and tokens, and
+//   client.session.children({ path: { id } }) returns { data } with a session's direct children.
+import { spawn } from "node:child_process";
+import { mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const REMINDER = "This session reports to Berliner: run `berliner report` with the task and PRs before your final message.";
+// The id names a file, so only the characters OpenCode's own ids use.
+const SAFE_ID = /^[\w-]+$/;
+// Bounds a walk up or down the session tree, which subagents keep shallow.
+const MAX_DEPTH = 10;
+
+const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : 0);
+const get = async (client, id) => (await client.session.get({ path: { id } }))?.data;
+
+// One agent session is one Berliner session: a subagent's child session belongs to the top-level session above it.
+async function topLevelId(client, id) {
+  let session = await get(client, id);
+  for (let i = 0; session?.parentID && i < MAX_DEPTH; i++) session = await get(client, session.parentID);
+  return session && !session.parentID ? session.id : null;
+}
+
+// The session with its subagents' cost and tokens added in, in the shape the CLI reads. OpenCode 1.18.30 keeps them apart:
+// a session's cost and tokens grow only from its own step-finish parts (packages/core/src/session/projector.ts:310-326,
+// applyUsage on the part's own sessionID, lines 89-109), and a live run with one task-tool subagent gave the parent 0.215
+// and the child 1.05.
+async function withChildren(client, session, depth = 0) {
+  const children = depth < MAX_DEPTH ? (await client.session.children({ path: { id: session.id } }))?.data : null;
+  if (!Array.isArray(children) || children.length === 0) return session;
+  const t = session.tokens;
+  let cost = num(session.cost);
+  const tokens = {
+    input: num(t?.input),
+    output: num(t?.output),
+    reasoning: num(t?.reasoning),
+    cache: { read: num(t?.cache?.read), write: num(t?.cache?.write) },
+  };
+  for (const c of await Promise.all(children.map((child) => withChildren(client, child, depth + 1)))) {
+    cost += num(c.cost);
+    tokens.input += num(c.tokens?.input);
+    tokens.output += num(c.tokens?.output);
+    tokens.reasoning += num(c.tokens?.reasoning);
+    tokens.cache.read += num(c.tokens?.cache?.read);
+    tokens.cache.write += num(c.tokens?.cache?.write);
+  }
+  return { ...session, cost, tokens };
+}
+
+// Saves a top-level session with its subagents' totals where `berliner report` run by the agent finds them: its shell can't
+// reach this client. Returns what it saved, or null for a child session, which the top-level session's totals count.
+async function save(client, sessionID) {
+  if (typeof sessionID !== "string" || !SAFE_ID.test(sessionID)) return null;
+  const found = await get(client, sessionID);
+  if (found?.id !== sessionID || found.parentID) return null;
+  // OpenCode moves time.updated only when a prompt arrives, so the session's last activity is now.
+  const session = { ...(await withChildren(client, found)), time: { ...found.time, updated: Date.now() } };
+  const dir = join(process.env.XDG_STATE_HOME || join(homedir(), ".local", "state"), "berliner", "opencode");
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const file = join(dir, `${sessionID}.json`);
+  // Renamed into place, so a reader never sees half of it.
+  writeFileSync(`${file}.${process.pid}`, JSON.stringify(session));
+  renameSync(`${file}.${process.pid}`, file);
+  return session;
+}
+
+async function report(client, event, sessionID) {
+  try {
+    const session = await save(client, sessionID);
+    if (!session) return;
+    // Detached and unreferenced: OpenCode never waits on it.
+    const child = spawn("berliner", ["hook", "opencode"], { detached: true, stdio: ["pipe", "ignore", "ignore"] });
+    child.on("error", () => {});
+    child.stdin.on("error", () => {});
+    child.stdin.end(JSON.stringify({ event, session }));
+    child.unref();
+  } catch {
+    // A report that can't be sent is skipped; the next idle sends the latest totals.
+  }
+}
+
+export const BerlinerPlugin = async ({ client }) => ({
+  "shell.env": async (input, output) => {
+    try {
+      if (!input?.sessionID) return;
+      output.env.OPENCODE_SESSION_ID = input.sessionID;
+      // A subagent's shell gets the top-level session, so a `berliner report` the agent runs there doesn't split it off.
+      const top = await topLevelId(client, input.sessionID);
+      if (!top) return;
+      output.env.OPENCODE_SESSION_ID = top;
+      // So that report finds the totals before the session's first idle. Not reported from here: that waits for idle.
+      await save(client, top);
+    } catch {
+      // Never fail the agent's shell.
+    }
+  },
+  event: async (input) => {
+    try {
+      if (input?.event?.type === "session.idle") void report(client, "idle", input.event.properties?.sessionID);
+    } catch {
+      // Never fail OpenCode's event bus.
+    }
+  },
+  "experimental.session.compacting": async (input, output) => {
+    try {
+      // The summary carries it, so the agent still reports the task and PRs after compaction.
+      output.context.push(REMINDER);
+    } catch {
+      // Never fail the compaction.
+    }
+    void report(client, "compacting", input?.sessionID);
+  },
+});

package/package.json

@@ -1,6 +1,30 @@
 {
   "name": "@paxnax/berliner",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Report coding-agent sessions to Berliner",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "berliner": "dist/index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "opencode",
+    "skill"
+  ],
+  "scripts": {
+    "build": "tsc -p .",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@types/node": "24.19.2",
+    "typescript": "7.0.2",
+    "vitest": "5.0.5"
+  }
+}