@paxnax/berliner 0.0.0-stage → 0.1.0

package/dist/args.js

@@ -0,0 +1,42 @@
+import { parseArgs } from "node:util";
+const config = {
+    options: {
+        "session-id": { type: "string" },
+        title: { type: "string" },
+        repo: { type: "string" },
+        cost: { type: "string" },
+        model: { type: "string" },
+        plan: { type: "string" },
+        task: { type: "string" },
+        "task-url": { type: "string" },
+        project: { type: "string" },
+        "started-at": { type: "string" },
+        "ended-at": { type: "string" },
+        commits: { type: "string" },
+        coverage: { type: "string" },
+        pr: { type: "string", multiple: true },
+        evidence: { type: "string", multiple: true },
+        json: { type: "boolean" },
+        strict: { type: "boolean" },
+        help: { type: "boolean" },
+        yes: { type: "boolean" },
+        ci: { type: "string" },
+        merge: { type: "string" },
+        since: { type: "string" },
+        from: { type: "string" },
+        to: { type: "string" },
+        limit: { type: "string" },
+    },
+    allowPositionals: true,
+};
+export function parse(argv) {
+    try {
+        const { values, positionals } = parseArgs({ ...config, args: argv });
+        return { command: positionals[0], positionals: positionals.slice(1), values, error: null };
+    }
+    catch (err) {
+        // Parse again leniently so the caller still knows the command and --strict, which decide the exit code.
+        const { values, positionals } = parseArgs({ ...config, args: argv, strict: false });
+        return { command: positionals[0], positionals: [], values: { strict: values.strict === true }, error: err.message };
+    }
+}

package/dist/client.js

@@ -0,0 +1,65 @@
+export class CliError extends Error {
+    kind;
+    status;
+    details;
+    constructor(message, kind, status, details) {
+        super(message);
+        this.kind = kind;
+        this.status = status;
+        this.details = details;
+    }
+}
+export async function request(cfg, method, path, body, opts = {}) {
+    if (!cfg.token)
+        throw new CliError("BERLINER_TOKEN is not set", "usage");
+    const { timeoutMs = 10_000, retries = 3, deadlineMs = 15_000 } = opts;
+    // One budget for all attempts, so a hung server can't hold the agent's pipeline for long (anti-goal 1).
+    const deadline = Date.now() + deadlineMs;
+    const raw = body instanceof Uint8Array;
+    for (let attempt = 0;; attempt++) {
+        // 500 ms, 1 s, 2 s, ... A retry whose backoff would end at or after the deadline is not attempted.
+        const backoffMs = 500 * 2 ** attempt;
+        const canRetry = () => attempt < retries && Date.now() + backoffMs < deadline;
+        let res;
+        try {
+            res = await fetch(cfg.url.replace(/\/+$/, "") + path, {
+                method,
+                headers: {
+                    Authorization: `Bearer ${cfg.token}`,
+                    ...(body === undefined ? {} : { "Content-Type": raw ? "application/octet-stream" : "application/json" }),
+                },
+                // A Uint8Array is sent as-is (evidence bytes); fetch sets its Content-Length.
+                body: body === undefined ? undefined : raw ? body : JSON.stringify(body),
+                signal: AbortSignal.timeout(Math.max(1, Math.min(timeoutMs, deadline - Date.now()))),
+            });
+        }
+        catch (err) {
+            if (!canRetry())
+                throw new CliError(`could not reach ${cfg.url} (${reason(err)})`, "network");
+            await sleep(backoffMs);
+            continue;
+        }
+        if ((res.status === 429 || res.status >= 500) && canRetry()) {
+            await res.body?.cancel();
+            await sleep(backoffMs);
+            continue;
+        }
+        const json = (await res.json().catch(() => null));
+        if (!res.ok)
+            throw new CliError(errorMessage(method, path, res.status, json), "http", res.status, json?.error?.details);
+        return { status: res.status, json };
+    }
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function reason(err) {
+    const e = err;
+    return e.cause?.code ?? e.cause?.message ?? e.message;
+}
+// Validation errors list the failing fields, so an agent can correct its flags.
+function errorMessage(method, path, status, json) {
+    const error = json?.error;
+    if (typeof error?.message !== "string")
+        return `${method} ${path} returned HTTP ${status}`;
+    const fields = Object.entries(error.details?.fieldErrors ?? {}).map(([field, msgs]) => `${field}: ${[msgs].flat().join(", ")}`);
+    return [error.message, ...fields].join("; ");
+}

package/dist/commands/body.js

@@ -0,0 +1,108 @@
+import { CliError, request } from "../client.js";
+import { warn } from "../output.js";
+// Shared by report (PUT) and update (PATCH): unset flags are undefined and drop out of the JSON.
+export function sessionBody(values) {
+    return {
+        title: values.title,
+        repository: values.repo,
+        cost_usd: number(values, "cost"),
+        model: values.model,
+        plan: values.plan,
+        task_id: values.task,
+        task_url: values["task-url"],
+        project: values.project,
+        started_at: values["started-at"],
+        ended_at: values["ended-at"],
+        commits: number(values, "commits"),
+        coverage: number(values, "coverage"),
+        prs: values.pr?.map(parsePr),
+    };
+}
+function number(values, flag) {
+    const raw = values[flag];
+    if (raw === undefined)
+        return undefined;
+    const n = Number(raw);
+    if (raw.trim() === "" || !Number.isFinite(n))
+        throw new CliError(`--${flag} must be a number, got "${raw}"`, "usage");
+    return n;
+}
+// <url>[,merge=<state>][,ci=<state>]. A malformed suffix is recorded as `problem`, not thrown, so prefilterPrs
+// can drop that one entry instead of the command aborting and the session being lost.
+function parsePr(spec) {
+    const [url, ...parts] = spec.split(",");
+    const pr = { url };
+    for (const part of parts) {
+        const m = /^(merge|ci)=(.+)$/.exec(part);
+        if (m)
+            pr[m[1] === "merge" ? "merge_state" : "ci_state"] = m[2];
+        else
+            pr.problem ??= `expected <url>[,merge=<state>][,ci=<state>], got ",${part}"`;
+    }
+    return pr;
+}
+// Mirrors the server's rules (parsePrUrl and the prs schema in app/src/worker), so bad entries never cost the session.
+const PR_URL = /^https?:\/\/github\.com\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+\/pull\/(\d+)(?:[/?#].*)?$/i;
+export const isPrUrl = (url) => {
+    const n = Number(PR_URL.exec(url)?.[1]);
+    return n >= 1 && n <= 2147483647;
+};
+const MERGE_STATES = ["open", "merged", "closed"];
+const CI_STATES = ["pending", "running", "passed", "failed", "none"];
+const MAX_PRS = 50;
+// Fields whose absence still leaves a trustworthy session; the rest are required (anti-goal 2).
+const optional = ["task_id", "task_url", "project", "started_at", "ended_at", "commits", "coverage", "prs"];
+// R49: drop the --pr entries the server would reject, so they never cost the session.
+function prefilterPrs(body) {
+    if (!body.prs)
+        return { body, dropped: [] };
+    const dropped = [];
+    const drop = (url, why) => {
+        dropped.push({ field: "prs", reason: `${url}: ${why}` });
+        return false;
+    };
+    let valid = 0;
+    const kept = body.prs.filter((p) => {
+        if (p.problem)
+            return drop(p.url, p.problem);
+        if (!isPrUrl(p.url))
+            return drop(p.url, "Not a GitHub pull request URL");
+        if (p.merge_state !== undefined && !MERGE_STATES.includes(p.merge_state))
+            return drop(p.url, `merge must be ${MERGE_STATES.join(", ")}`);
+        if (p.ci_state !== undefined && !CI_STATES.includes(p.ci_state))
+            return drop(p.url, `ci must be ${CI_STATES.join(", ")}`);
+        // The cap counts valid entries only, so a bad entry never displaces a good one.
+        if (++valid > MAX_PRS)
+            return drop(p.url, `more than ${MAX_PRS} PRs`);
+        return true;
+    });
+    // Nothing left: omit prs rather than send [], which could clear PRs already saved.
+    return { body: { ...body, prs: kept.length ? kept : undefined }, dropped };
+}
+// R46/R49: one invalid optional value must not lose the session. Bad PRs are filtered first; on a 422 naming
+// only optional fields, drop them and retry once. Anything else is thrown as before. Warnings are printed
+// only once the save succeeded, so a failed save never claims fields were dropped.
+export async function saveSession(cfg, method, path, input) {
+    const first = prefilterPrs(input);
+    const dropped = first.dropped;
+    const finish = (res) => {
+        for (const d of dropped)
+            warn(`${d.field}: ${d.reason}`);
+        return { ...res, dropped };
+    };
+    try {
+        return finish(await request(cfg, method, path, first.body));
+    }
+    catch (err) {
+        const fieldErrors = err instanceof CliError && err.status === 422 ? err.details?.fieldErrors : undefined;
+        const names = Object.keys(fieldErrors ?? {});
+        if (!fieldErrors || !names.length || !names.every((n) => optional.includes(n)))
+            throw err;
+        const retry = { ...first.body };
+        for (const field of names) {
+            delete retry[field];
+            dropped.push({ field, reason: field === "prs" ? `all PRs dropped: ${[fieldErrors[field]].flat().join(", ")}` : [fieldErrors[field]].flat().join(", ") });
+        }
+        return finish(await request(cfg, method, path, retry));
+    }
+}

package/dist/commands/delete.js

@@ -0,0 +1,35 @@
+import { createInterface } from "node:readline/promises";
+import { CliError, request } from "../client.js";
+export async function del(cfg, values, positionals) {
+    if (positionals.length !== 1)
+        throw new CliError("usage: berliner delete <session-id> [--evidence <id>] [--yes]", "usage");
+    const id = positionals[0];
+    const evidenceId = values.evidence?.[0];
+    if (evidenceId) {
+        // Evidence ids are global, so the session named on the command line must actually hold this one.
+        const { json } = await request(cfg, "GET", `/v1/sessions/${encodeURIComponent(id)}`);
+        if (!json.session.evidence.some((e) => String(e.id) === evidenceId)) {
+            throw new CliError(`evidence ${evidenceId} is not part of session ${id}`, "usage");
+        }
+    }
+    const question = evidenceId ? `Delete evidence ${evidenceId} of session ${id}? [y/N] ` : `Delete session ${id} and its evidence? [y/N] `;
+    if (!values.yes) {
+        if (!process.stdin.isTTY)
+            throw new CliError("refusing to delete without confirmation; pass --yes to delete without a prompt", "usage");
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        const answer = await rl.question(question);
+        rl.close();
+        if (!/^y(es)?$/i.test(answer.trim())) {
+            console.log("Cancelled.");
+            return;
+        }
+    }
+    if (evidenceId) {
+        await request(cfg, "DELETE", `/v1/evidence/${encodeURIComponent(evidenceId)}`);
+        console.log(`Deleted evidence ${evidenceId}.`);
+    }
+    else {
+        await request(cfg, "DELETE", `/v1/sessions/${encodeURIComponent(id)}`);
+        console.log(`Deleted session ${id}.`);
+    }
+}

package/dist/commands/query.js

@@ -0,0 +1,25 @@
+import { CliError } from "../client.js";
+// Filters shared by `sessions` and `summary`, mapped to the API's query string.
+export function filterQuery(values, extra = {}) {
+    const q = new URLSearchParams();
+    const set = (k, v) => v !== undefined && q.set(k, v);
+    set("repository", values.repo);
+    set("model", values.model);
+    set("project", values.project);
+    set("ci", values.ci);
+    set("merge", values.merge);
+    if (values.since !== undefined) {
+        const m = /^(\d+)d$/.exec(values.since);
+        if (!m)
+            throw new CliError(`--since must look like 30d, got "${values.since}"`, "usage");
+        const to = new Date();
+        q.set("to", to.toISOString());
+        q.set("from", new Date(to.getTime() - Number(m[1]) * 864e5).toISOString());
+    }
+    set("from", values.from);
+    set("to", values.to);
+    q.set("tz", Intl.DateTimeFormat().resolvedOptions().timeZone);
+    for (const [k, v] of Object.entries(extra))
+        set(k, v);
+    return `?${q}`;
+}

package/dist/commands/report.js

@@ -0,0 +1,40 @@
+import { CliError } from "../client.js";
+import { print, warn } from "../output.js";
+import { uploadEvidence } from "../upload.js";
+import { saveSession, sessionBody } from "./body.js";
+const required = ["session-id", "title", "repo", "cost", "model", "plan"];
+export async function report(cfg, values, positionals) {
+    // Usually an unquoted value with spaces, e.g. --title Fix the bug.
+    if (positionals.length)
+        throw new CliError(`unexpected argument "${positionals[0]}"; quote values that contain spaces`, "usage");
+    const missing = required.filter((flag) => values[flag] === undefined);
+    if (missing.length)
+        throw new CliError(`missing required flag(s): ${missing.map((f) => `--${f}`).join(", ")}`, "usage");
+    const body = sessionBody(values);
+    const id = values["session-id"];
+    const { json: saved, dropped } = await saveSession(cfg, "PUT", `/v1/sessions/${encodeURIComponent(id)}`, body);
+    const json = dropped.length ? { ...saved, dropped } : saved;
+    const { created, session } = json;
+    const text = `Saved session ${session.id} (${created ? "created" : "updated"}). ${session.pr_count} PR(s) linked.`;
+    const json_ = values.json === true;
+    // Human mode prints the session line before uploads start; --json waits so stdout is one document.
+    if (!json_)
+        print({ data: json, text }, false);
+    if (!values.evidence?.length) {
+        if (json_)
+            print({ data: json, text }, true);
+        return;
+    }
+    const result = await uploadEvidence(cfg, id, values.evidence.map(parseEvidence));
+    if (json_)
+        print({ data: { ...json, evidence: result }, text }, true);
+    else
+        console.log(`Evidence: ${result.uploaded} uploaded, ${result.existing} already uploaded, ${result.skipped.length} skipped.`);
+    for (const s of result.skipped)
+        warn(`${s.path}: ${s.reason}`);
+}
+// <path>[::<caption>]
+function parseEvidence(spec) {
+    const i = spec.indexOf("::");
+    return i < 0 ? { path: spec } : { path: spec.slice(0, i), caption: spec.slice(i + 2) || undefined };
+}

package/dist/commands/session.js

@@ -0,0 +1,33 @@
+import { CliError, request } from "../client.js";
+import { mergeLabel, print } from "../output.js";
+export async function session(cfg, values, positionals) {
+    if (positionals.length !== 1)
+        throw new CliError("usage: berliner session <session-id> [--json]", "usage");
+    const { json } = await request(cfg, "GET", `/v1/sessions/${encodeURIComponent(positionals[0])}`);
+    const s = json.session;
+    const fields = [
+        ["Session", s.id],
+        ["Title", s.title],
+        ["Repository", s.repository],
+        ["Task", [s.task_id, s.task_url].filter(Boolean).join(" ")],
+        ["Project", s.project],
+        ["Estimated cost", `$${s.cost_usd.toFixed(2)}`],
+        ["Model", s.model],
+        ["Plan", s.plan],
+        ["Started", s.started_at],
+        ["Ended", s.ended_at],
+        ["Duration (s)", s.duration_seconds],
+        ["Commits", s.commits],
+        ["Coverage", s.coverage],
+        ["CI", s.ci],
+        ["Merge", mergeLabel(s)],
+    ];
+    const lines = fields.filter(([, v]) => v !== null && v !== undefined && v !== "").map(([k, v]) => `${k}: ${v}`);
+    lines.push(`Pull requests: ${s.prs.length || "none"}`);
+    for (const p of s.prs)
+        lines.push(`  ${p.url}  merge=${p.merge_state} ci=${p.ci_state}${p.tracked ? "" : " (not tracked)"}`);
+    lines.push(`Evidence: ${s.evidence.length || "none"}`);
+    for (const e of s.evidence)
+        lines.push(`  #${e.id} ${e.kind} ${e.filename}${e.caption ? ` - ${e.caption}` : ""}${e.status === "ready" ? "" : ` (${e.status})`}`);
+    print({ data: json, text: lines.join("\n") }, values.json === true);
+}

package/dist/commands/sessions.js

@@ -0,0 +1,17 @@
+import { request } from "../client.js";
+import { mergeLabel, print } from "../output.js";
+import { filterQuery } from "./query.js";
+const usd = (n) => `$${n.toFixed(2)}`;
+export async function sessions(cfg, values) {
+    const { json } = await request(cfg, "GET", `/v1/sessions${filterQuery(values, { limit: values.limit })}`);
+    const rows = [["TASK", "TITLE", "REPO", "COST (est.)", "PRS", "CI", "MERGE"]];
+    for (const s of json.sessions)
+        rows.push([s.task_id ?? s.id, s.title, s.repository, usd(s.cost_usd), String(s.pr_count), s.ci, mergeLabel(s)]);
+    const widths = rows[0].map((_, i) => Math.max(...rows.map((r) => r[i].length)));
+    const lines = rows.map((r) => r
+        .map((c, i) => c.padEnd(widths[i]))
+        .join("  ")
+        .trimEnd());
+    const text = json.sessions.length ? `${lines.join("\n")}\n${json.sessions.length} of ${json.total} session(s).` : "No sessions.";
+    print({ data: json, text }, values.json === true);
+}

package/dist/commands/skill.js

@@ -0,0 +1,5 @@
+import { readFileSync } from "node:fs";
+// dist/commands/skill.js -> ../../skill/SKILL.md (the package's skill/ directory).
+export function skill() {
+    process.stdout.write(readFileSync(new URL("../../skill/SKILL.md", import.meta.url), "utf8"));
+}

package/dist/commands/summary.js

@@ -0,0 +1,15 @@
+import { request } from "../client.js";
+import { print } from "../output.js";
+import { filterQuery } from "./query.js";
+export async function summary(cfg, values) {
+    const { json } = await request(cfg, "GET", `/v1/summary${filterQuery(values)}`);
+    const s = json.summary;
+    const text = [
+        `Estimated spend: $${s.spend_usd.toFixed(2)}`,
+        `Sessions: ${s.sessions}`,
+        `PRs merged: ${s.prs_merged} of ${s.prs_opened} opened`,
+        `Cost per merged PR: ${s.cost_per_merged_pr === null ? "n/a" : `$${s.cost_per_merged_pr.toFixed(2)}`}`,
+        `Commits: ${s.commits}`,
+    ].join("\n");
+    print({ data: json, text }, values.json === true);
+}

package/dist/commands/update.js

@@ -0,0 +1,12 @@
+import { CliError } from "../client.js";
+import { print } from "../output.js";
+import { saveSession, sessionBody } from "./body.js";
+export async function update(cfg, values, positionals) {
+    if (positionals.length !== 1)
+        throw new CliError("usage: berliner update <session-id> [flags]; quote values that contain spaces", "usage");
+    if (values.evidence?.length)
+        throw new CliError("update does not upload evidence; use report --evidence", "usage");
+    const { json: saved, dropped } = await saveSession(cfg, "PATCH", `/v1/sessions/${encodeURIComponent(positionals[0])}`, sessionBody(values));
+    const json = dropped.length ? { ...saved, dropped } : saved;
+    print({ data: json, text: `Updated session ${json.session.id}. ${json.session.pr_count} PR(s) linked.` }, values.json === true);
+}

package/dist/config.js

@@ -0,0 +1,4 @@
+export const DEFAULT_URL = "https://berliner.app";
+export function readConfig(env) {
+    return { url: env.BERLINER_URL || DEFAULT_URL, token: env.BERLINER_TOKEN || null };
+}

package/dist/index.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+import { parse } from "./args.js";
+import { CliError } from "./client.js";
+import { del } from "./commands/delete.js";
+import { report } from "./commands/report.js";
+import { session } from "./commands/session.js";
+import { sessions } from "./commands/sessions.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:
+  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]
+  update <session-id>   same flags as report, all optional
+  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
+
+Environment: BERLINER_TOKEN, BERLINER_URL`;
+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(["report", "update", "sessions", "session", "summary", "delete", "skill"]);
+const cfg = () => readConfig(process.env);
+try {
+    if (args.values.help)
+        console.log(usage);
+    else if (args.error)
+        throw new CliError(args.error, "usage");
+    else if (args.command === "report")
+        await report(cfg(), args.values, args.positionals);
+    else if (args.command === "update")
+        await update(cfg(), args.values, args.positionals);
+    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,10 @@
+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);

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/package.json

@@ -1,6 +1,29 @@
 {
   "name": "@paxnax/berliner",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Report coding-agent sessions to Berliner",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "berliner": "dist/index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "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"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: berliner
+description: Use at the end of an autonomous coding session, and again whenever its PRs or results change, to report cost, model, plan, PRs, commits, test coverage and screenshots or videos to Berliner with the berliner CLI.
+---
+
+# Reporting to Berliner
+
+Berliner records what an autonomous session cost and produced. You report with one command, `berliner report`.
+
+## When to report
+
+- Once, at the end of the session.
+- Again with the **same `--session-id`** if anything changes afterwards (a PR is opened or merged, CI finishes, you add evidence). The new values replace the old ones, PR URLs are added to the list, and evidence already uploaded is skipped. It never double-counts.
+
+## Required values and where each comes from
+
+| Flag | Source |
+|---|---|
+| `--session-id` | Your harness's session ID if it exposes one, otherwise generate a UUID at the start of the session and reuse it for every report. |
+| `--title` | One short line describing the work. |
+| `--repo` | `owner/name`, from `git remote get-url origin`. |
+| `--cost` | Estimated USD. Your harness's reported session cost if it shows one, otherwise estimate from token usage at the model's API prices. |
+| `--model` | The primary model ID you ran on. |
+| `--plan` | One of `free`, `pro`, `max_x5`, `max_x20`, `team`, `enterprise`, `api`. |
+
+## Optional values
+
+- `--commits <n>`: `git rev-list --count <base>..HEAD`
+- `--coverage <percent>`: from the test run's coverage summary.
+- `--pr <url>[,merge=<open|merged|closed>][,ci=<pending|running|passed|failed|none>]`: repeat per PR. URL from `gh pr view --json url`.
+- `--evidence <path>[::caption]`: repeat per screenshot or video.
+- `--task <id>`, `--task-url <url>`, `--project <name>`, `--started-at <ISO>`, `--ended-at <ISO>`.
+
+Quote any value that contains spaces.
+
+## Environment
+
+`BERLINER_TOKEN` must be set (an API token from the Settings page at https://berliner.app). `BERLINER_URL` overrides the server address.
+
+## Timeouts
+
+The session is saved first, then evidence is uploaded. Allow at least 10 minutes for the command when attaching videos.
+
+## Reading the output
+
+- Success prints what was saved, then an evidence line such as `Evidence: 1 uploaded, 0 already uploaded, 0 skipped.`
+- A line starting `berliner:` on stderr is a warning: the report may be incomplete (server unreachable, a file skipped). The command still exits 0, so it never fails your work (`--strict` makes failures exit 1). Re-run the same command; it is safe to repeat.
+- `--json` prints the saved session as JSON, plus an `evidence` field with `uploaded`, `existing` and `skipped` results when `--evidence` was given.
+- To change a field later without resending everything, use `berliner update <session-id> --commits 5`.
+
+## Example
+
+```sh
+berliner report \
+  --session-id 3f1c2a9e-7b64-4d0a-9a51-2c8f0e6d1b77 \
+  --title "Fix recurring event off-by-one" \
+  --repo octo/app \
+  --cost 4.20 \
+  --model claude-opus-5-5 \
+  --plan max_x20 \
+  --task TEC-5521 \
+  --commits 3 \
+  --coverage 87.5 \
+  --pr "https://github.com/octo/app/pull/42,ci=running" \
+  --evidence "./shots/after.png::Calendar after the fix"
+```

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.