agent-andon 0.1.0

package/dist/commands/serve.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseServeArgs = parseServeArgs;
+exports.serve = serve;
+/** `andon serve [--demo] [--port N] [--host H] [--token T]` */
+const server_1 = require("../server");
+const demo_1 = require("../demo");
+const net_1 = require("../net");
+function parseServeArgs(argv) {
+    const args = {
+        port: Number(process.env.ANDON_PORT) || 8787,
+        host: process.env.ANDON_HOST || "0.0.0.0",
+        demo: false,
+        token: process.env.ANDON_TOKEN || undefined,
+    };
+    // Consume the value after a flag, erroring if it's missing or is itself a flag.
+    const takeValue = (argv, i, flag) => {
+        const v = argv[i + 1];
+        if (v === undefined || v.startsWith("-")) {
+            throw new Error(`${flag} needs a value`);
+        }
+        return v;
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--demo")
+            args.demo = true;
+        else if (a === "--port")
+            args.port = Number(takeValue(argv, i++, "--port"));
+        else if (a === "--host")
+            args.host = takeValue(argv, i++, "--host");
+        else if (a === "--token")
+            args.token = takeValue(argv, i++, "--token");
+        else if (a?.startsWith("--port="))
+            args.port = Number(a.split("=")[1]);
+        else if (a?.startsWith("--token="))
+            args.token = a.split("=")[1];
+        else if (a?.startsWith("--host="))
+            args.host = a.split("=")[1];
+    }
+    return args;
+}
+function serve(argv) {
+    let args;
+    try {
+        args = parseServeArgs(argv);
+    }
+    catch (e) {
+        console.error(`✗ ${e.message}`);
+        process.exit(2);
+        return;
+    }
+    if (!Number.isFinite(args.port) || args.port <= 0) {
+        console.error(`✗ invalid port: ${args.port}`);
+        process.exit(1);
+    }
+    const { server, store } = (0, server_1.createServer)({
+        port: args.port,
+        host: args.host,
+        token: args.token,
+    });
+    if (args.demo)
+        (0, demo_1.startDemo)(store);
+    server.on("error", (err) => {
+        if (err.code === "EADDRINUSE") {
+            console.error(`\n  ✗ Port ${args.port} is already in use.\n` +
+                `    Another Andon server may be running, or pick a free port:\n` +
+                `      andon serve --port 8788\n`);
+        }
+        else {
+            console.error(`\n  ✗ Server error: ${err.message}\n`);
+        }
+        process.exit(1);
+    });
+    server.listen(args.port, args.host, () => {
+        const url = `http://${(0, net_1.lanIp)()}:${args.port}`;
+        const tokenSuffix = args.token ? `?token=${args.token}` : "";
+        console.log("\n  🚦 Agent Andon is live");
+        console.log("  ──────────────────────────────────────────");
+        console.log(`  This Mac:   http://127.0.0.1:${args.port}${tokenSuffix}`);
+        console.log(`  iPad:       ${url}${tokenSuffix}`);
+        console.log("              (iPad must be on the same Wi-Fi)");
+        if (args.token)
+            console.log("  🔒 token auth enabled");
+        if (args.demo)
+            console.log("  [demo] injecting fake agents, cycling every 3s");
+        console.log("  Ctrl-C to stop\n");
+    });
+    const shutdown = () => {
+        console.log("\n  stopped.");
+        server.close(() => process.exit(0));
+        setTimeout(() => process.exit(0), 500).unref();
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+}

package/dist/commands/shared.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The tile title. `ANDON_LABEL` (set per-terminal) wins so you can name a run
+ * "backend refactor" instead of leaning on the directory basename.
+ */
+export declare function labelFor(cwd: string, fallback: string): string;
+/**
+ * Session id rules, shared by `post` and `notify` so the same project shows as
+ * ONE tile across "working/done/gone":
+ *   ANDON_SESSION (injected by the codex wrapper, unique per launch)  ->
+ *   else codex falls back to cwd, other agents to the agent name.
+ */
+export declare function sessionId(agent: string, cwd: string): string;

package/dist/commands/shared.js

@@ -0,0 +1,60 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.labelFor = labelFor;
+exports.sessionId = sessionId;
+/** Tiny helpers shared by the client-side commands. */
+const path = __importStar(require("path"));
+/**
+ * The tile title. `ANDON_LABEL` (set per-terminal) wins so you can name a run
+ * "backend refactor" instead of leaning on the directory basename.
+ */
+function labelFor(cwd, fallback) {
+    const env = process.env.ANDON_LABEL;
+    if (env && env.trim())
+        return env.trim();
+    const base = path.basename(cwd.replace(/\/+$/, ""));
+    return base || fallback;
+}
+/**
+ * Session id rules, shared by `post` and `notify` so the same project shows as
+ * ONE tile across "working/done/gone":
+ *   ANDON_SESSION (injected by the codex wrapper, unique per launch)  ->
+ *   else codex falls back to cwd, other agents to the agent name.
+ */
+function sessionId(agent, cwd) {
+    return (process.env.ANDON_SESSION ||
+        (agent === "codex" ? cwd : agent));
+}

package/dist/demo.d.ts

@@ -0,0 +1,3 @@
+/** Injects two fake agents that cycle states, for verifying the board first. */
+import type { SessionStore } from "./store";
+export declare function startDemo(store: SessionStore): NodeJS.Timeout;

package/dist/demo.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startDemo = startDemo;
+function startDemo(store) {
+    const seq = [
+        ["claude", "/Users/you/dev/checkout-api",
+            ["working", "working", "waiting", "working", "done", "done"]],
+        ["codex", "/Users/you/dev/landing-page",
+            ["working", "working", "working", "error", "working", "done"]],
+    ];
+    const msgs = {
+        waiting: "needs permission: Bash(git push origin main)",
+        error: "command failed: exit 1 — tsc: 3 errors",
+    };
+    let i = 0;
+    const tick = () => {
+        for (const [agent, cwd, states] of seq) {
+            const st = states[i % states.length];
+            store.apply({
+                agent,
+                id: cwd,
+                state: st,
+                title: cwd.split("/").pop() || agent,
+                message: msgs[st] ?? "",
+            });
+        }
+        i++;
+    };
+    tick(); // seed immediately
+    const t = setInterval(tick, 3000);
+    t.unref?.();
+    return t;
+}

package/dist/net.d.ts

@@ -0,0 +1,7 @@
+/** Default base URL hooks post to; override with AGENT_STATUS_URL. */
+export declare function serverBase(): string;
+/**
+ * Best-effort LAN IP for the "open this on your iPad" URL. Prefers a private
+ * (RFC1918) IPv4, skips loopback / link-local / virtual where possible.
+ */
+export declare function lanIp(): string;

package/dist/net.js

@@ -0,0 +1,64 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serverBase = serverBase;
+exports.lanIp = lanIp;
+/** Small networking helpers shared by the server and CLI. */
+const os = __importStar(require("os"));
+/** Default base URL hooks post to; override with AGENT_STATUS_URL. */
+function serverBase() {
+    return (process.env.AGENT_STATUS_URL || "http://127.0.0.1:8787").replace(/\/+$/, "");
+}
+/**
+ * Best-effort LAN IP for the "open this on your iPad" URL. Prefers a private
+ * (RFC1918) IPv4, skips loopback / link-local / virtual where possible.
+ */
+function lanIp() {
+    const nis = os.networkInterfaces();
+    const candidates = [];
+    for (const name of Object.keys(nis)) {
+        for (const ni of nis[name] ?? []) {
+            if (ni.family !== "IPv4" || ni.internal)
+                continue;
+            if (ni.address.startsWith("169.254."))
+                continue; // link-local
+            candidates.push(ni.address);
+        }
+    }
+    const isPrivate = (a) => a.startsWith("192.168.") ||
+        a.startsWith("10.") ||
+        /^172\.(1[6-9]|2\d|3[01])\./.test(a);
+    return candidates.find(isPrivate) ?? candidates[0] ?? "127.0.0.1";
+}

package/dist/server.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The Agent Andon board server.
+ *
+ *   GET  /                    full-screen dashboard (served from assets/)
+ *   GET  /state               JSON snapshot the iPad polls every second
+ *   GET  /healthz             liveness + session count
+ *   GET  /manifest.webmanifest, /favicon.svg   PWA polish
+ *   POST /event               a hook / the CLI pushes one status event
+ *
+ * Hardening over the prototype: request-body size cap, guarded body read,
+ * optional shared-token auth (ANDON_TOKEN), no CORS (the board is same-origin),
+ * and a same-origin guard that blocks cross-origin POST /event (CSRF).
+ */
+import * as http from "http";
+import { SessionStore } from "./store";
+export interface ServerOptions {
+    port: number;
+    host: string;
+    /** When set, /state and /event require ?token=… or an x-andon-token header. */
+    token?: string;
+    /** Inject a store (tests); a fresh one is created otherwise. */
+    store?: SessionStore;
+}
+export interface AndonServer {
+    server: http.Server;
+    store: SessionStore;
+}
+export declare function createServer(opts: ServerOptions): AndonServer;

package/dist/server.js

@@ -0,0 +1,181 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createServer = createServer;
+/**
+ * The Agent Andon board server.
+ *
+ *   GET  /                    full-screen dashboard (served from assets/)
+ *   GET  /state               JSON snapshot the iPad polls every second
+ *   GET  /healthz             liveness + session count
+ *   GET  /manifest.webmanifest, /favicon.svg   PWA polish
+ *   POST /event               a hook / the CLI pushes one status event
+ *
+ * Hardening over the prototype: request-body size cap, guarded body read,
+ * optional shared-token auth (ANDON_TOKEN), no CORS (the board is same-origin),
+ * and a same-origin guard that blocks cross-origin POST /event (CSRF).
+ */
+const http = __importStar(require("http"));
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const store_1 = require("./store");
+const assets_1 = require("./assets");
+/** Reject event bodies larger than this (plenty for a status line). */
+const MAX_BODY = 64 * 1024;
+/** dist/server.js -> ../assets/dashboard.html (also correct once installed). */
+const DASHBOARD_PATH = path.join(__dirname, "..", "assets", "dashboard.html");
+function createServer(opts) {
+    const store = opts.store ?? new store_1.SessionStore();
+    const sweeper = setInterval(() => store.sweep(), 30_000);
+    sweeper.unref?.();
+    let dashboard = null;
+    try {
+        dashboard = fs.readFileSync(DASHBOARD_PATH);
+    }
+    catch {
+        dashboard = null;
+    }
+    // Accept the token either as ?token=… (the dashboard reads it from its own
+    // URL) or as an x-andon-token header (hooks/CLI use this, keeping the secret
+    // out of URLs and access logs).
+    const authorized = (url, req) => {
+        if (!opts.token)
+            return true;
+        return (url.searchParams.get("token") === opts.token ||
+            req.headers["x-andon-token"] === opts.token);
+    };
+    // CSRF guard: reject cross-origin browser writes. The board is same-origin
+    // with the server, and CLI/hooks (curl, Node http) send no Origin header —
+    // both pass. Only a request from a *different* web origin is blocked.
+    const sameOriginOrNone = (req) => {
+        const origin = req.headers.origin;
+        if (!origin)
+            return true;
+        try {
+            return new URL(origin).host === req.headers.host;
+        }
+        catch {
+            return false;
+        }
+    };
+    const server = http.createServer((req, res) => {
+        const send = (code, body, ctype = "application/json") => {
+            const buf = typeof body === "string" ? Buffer.from(body, "utf8") : body;
+            // No CORS headers: the board is same-origin with the server, so it needs
+            // none, and withholding them stops any other website from reading /state.
+            res.writeHead(code, {
+                "Content-Type": ctype,
+                "Content-Length": buf.length,
+                "Cache-Control": "no-store",
+            });
+            res.end(buf);
+        };
+        const url = new URL(req.url || "/", "http://localhost");
+        const p = url.pathname;
+        if (req.method === "OPTIONS") {
+            // No CORS is offered (same-origin board only); answer preflights plainly.
+            res.writeHead(204, { Allow: "GET, POST, OPTIONS" });
+            res.end();
+            return;
+        }
+        if (req.method === "GET") {
+            if (p === "/" || p === "/index.html") {
+                if (dashboard)
+                    send(200, dashboard, "text/html; charset=utf-8");
+                else
+                    send(500, "dashboard.html is missing from the package assets/.", "text/plain; charset=utf-8");
+            }
+            else if (p === "/state") {
+                if (!authorized(url, req))
+                    return send(401, JSON.stringify({ error: "unauthorized" }));
+                send(200, JSON.stringify(store.snapshot()));
+            }
+            else if (p === "/healthz") {
+                send(200, JSON.stringify({ ok: true, sessions: store.size }));
+            }
+            else if (p === "/manifest.webmanifest") {
+                send(200, JSON.stringify(assets_1.MANIFEST), "application/manifest+json");
+            }
+            else if (p === "/favicon.svg") {
+                send(200, assets_1.FAVICON_SVG, "image/svg+xml");
+            }
+            else {
+                send(404, JSON.stringify({ error: "not found" }));
+            }
+            return;
+        }
+        if (req.method === "POST" && p === "/event") {
+            if (!sameOriginOrNone(req))
+                return send(403, JSON.stringify({ error: "cross-origin forbidden" }));
+            if (!authorized(url, req))
+                return send(401, JSON.stringify({ error: "unauthorized" }));
+            const chunks = [];
+            let size = 0;
+            let aborted = false;
+            req.on("data", (c) => {
+                size += c.length;
+                if (size > MAX_BODY && !aborted) {
+                    aborted = true;
+                    send(413, JSON.stringify({ error: "payload too large" }));
+                    req.destroy();
+                }
+                else if (!aborted) {
+                    chunks.push(c);
+                }
+            });
+            req.on("end", () => {
+                if (aborted || res.writableEnded)
+                    return;
+                let ev;
+                try {
+                    ev = JSON.parse(Buffer.concat(chunks).toString("utf8") || "{}");
+                }
+                catch {
+                    return send(400, JSON.stringify({ error: "bad json" }));
+                }
+                const r = store.apply(ev);
+                send(r.ok ? 200 : 400, JSON.stringify(r));
+            });
+            req.on("error", () => {
+                if (!res.writableEnded)
+                    send(400, JSON.stringify({ error: "read error" }));
+            });
+            return;
+        }
+        send(404, JSON.stringify({ error: "not found" }));
+    });
+    server.on("close", () => clearInterval(sweeper));
+    return { server, store };
+}

package/dist/store.d.ts

@@ -0,0 +1,30 @@
+/**
+ * In-memory session store. Pure logic, no I/O — so it is trivially testable.
+ *
+ * Concurrency note: Node runs this single-threaded, so unlike the Python
+ * prototype no lock is needed. Each HTTP callback runs to completion.
+ */
+import { type AndonEvent, type Snapshot } from "./types";
+/** Any session untouched for this long is swept (a process died without cleanup). */
+export declare const HARD_TTL_SEC: number;
+/** Hard cap so a misbehaving/abusive client can't grow the board unbounded. */
+export declare const MAX_SESSIONS = 200;
+export interface ApplyResult {
+    ok: boolean;
+    error?: string;
+    removed?: boolean;
+}
+export declare class SessionStore {
+    private readonly now;
+    private readonly maxSessions;
+    private readonly ttlSec;
+    private sessions;
+    constructor(now?: () => number, maxSessions?: number, ttlSec?: number);
+    /** Create / update / delete one session from a single event. */
+    apply(ev: AndonEvent): ApplyResult;
+    /** Snapshot, sorted by priority then most-recent — exactly what the board renders. */
+    snapshot(): Snapshot;
+    /** Drop sessions older than the TTL. Returns how many were removed. */
+    sweep(): number;
+    get size(): number;
+}

package/dist/store.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionStore = exports.MAX_SESSIONS = exports.HARD_TTL_SEC = void 0;
+/**
+ * In-memory session store. Pure logic, no I/O — so it is trivially testable.
+ *
+ * Concurrency note: Node runs this single-threaded, so unlike the Python
+ * prototype no lock is needed. Each HTTP callback runs to completion.
+ */
+const types_1 = require("./types");
+/** Any session untouched for this long is swept (a process died without cleanup). */
+exports.HARD_TTL_SEC = 6 * 3600;
+/** Hard cap so a misbehaving/abusive client can't grow the board unbounded. */
+exports.MAX_SESSIONS = 200;
+class SessionStore {
+    now;
+    maxSessions;
+    ttlSec;
+    sessions = new Map();
+    constructor(now = () => Date.now() / 1000, maxSessions = exports.MAX_SESSIONS, ttlSec = exports.HARD_TTL_SEC) {
+        this.now = now;
+        this.maxSessions = maxSessions;
+        this.ttlSec = ttlSec;
+    }
+    /** Create / update / delete one session from a single event. */
+    apply(ev) {
+        const sid = String(ev.id ?? ev.agent ?? "agent").trim();
+        if (!sid)
+            return { ok: false, error: "missing id" };
+        const state = (ev.state ?? "").trim();
+        if (state === "gone") {
+            const existed = this.sessions.delete(sid);
+            return { ok: true, removed: existed };
+        }
+        if (!types_1.VALID_STATES.has(state)) {
+            return { ok: false, error: `invalid state: ${JSON.stringify(ev.state)}` };
+        }
+        if (!this.sessions.has(sid) && this.sessions.size >= this.maxSessions) {
+            return { ok: false, error: "session limit reached" };
+        }
+        const prev = this.sessions.get(sid);
+        const agent = ev.agent || prev?.agent || "agent";
+        this.sessions.set(sid, {
+            id: sid,
+            agent,
+            state: state,
+            title: ev.title || prev?.title || agent,
+            message: ev.message != null ? String(ev.message) : prev?.message ?? "",
+            updated_at: this.now(),
+        });
+        return { ok: true };
+    }
+    /** Snapshot, sorted by priority then most-recent — exactly what the board renders. */
+    snapshot() {
+        const items = [...this.sessions.values()].map((s) => ({ ...s }));
+        items.sort((a, b) => (types_1.PRIORITY[a.state] ?? 9) - (types_1.PRIORITY[b.state] ?? 9) ||
+            b.updated_at - a.updated_at);
+        return { server_time: this.now(), sessions: items };
+    }
+    /** Drop sessions older than the TTL. Returns how many were removed. */
+    sweep() {
+        const cutoff = this.now() - this.ttlSec;
+        let removed = 0;
+        for (const [id, s] of this.sessions) {
+            if (s.updated_at < cutoff) {
+                this.sessions.delete(id);
+                removed++;
+            }
+        }
+        return removed;
+    }
+    get size() {
+        return this.sessions.size;
+    }
+}
+exports.SessionStore = SessionStore;

package/dist/types.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Shared types and the single source of truth for state priority.
+ *
+ * The status palette IS the message: green/amber/red/blue each own a meaning,
+ * and the iPad edge glows the most-urgent ("dominant") one on the board.
+ */
+/** A live agent status. */
+export type State = "working" | "waiting" | "done" | "error" | "idle";
+/** What a client may send. `gone` is a command: remove this session's tile. */
+export type EventState = State | "gone";
+/** Raw event posted to POST /event by a hook or the CLI. Intentionally loose. */
+export interface AndonEvent {
+    agent?: string;
+    id?: string;
+    state?: string;
+    title?: string;
+    message?: string;
+}
+/** A normalized, stored session — one tile on the board. */
+export interface Session {
+    id: string;
+    agent: string;
+    state: State;
+    title: string;
+    message: string;
+    /** epoch seconds */
+    updated_at: number;
+}
+/** The payload the dashboard polls from GET /state. */
+export interface Snapshot {
+    server_time: number;
+    sessions: Session[];
+}
+/**
+ * Lower number = "more in need of your attention". The board border takes the
+ * lowest (most urgent) state present. Mirrored verbatim in the dashboard JS.
+ */
+export declare const PRIORITY: Record<string, number>;
+/** States a tile can hold (excludes the `gone` delete-command). */
+export declare const VALID_STATES: ReadonlySet<string>;

package/dist/types.js

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * Shared types and the single source of truth for state priority.
+ *
+ * The status palette IS the message: green/amber/red/blue each own a meaning,
+ * and the iPad edge glows the most-urgent ("dominant") one on the board.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VALID_STATES = exports.PRIORITY = void 0;
+/**
+ * Lower number = "more in need of your attention". The board border takes the
+ * lowest (most urgent) state present. Mirrored verbatim in the dashboard JS.
+ */
+exports.PRIORITY = {
+    error: 0,
+    waiting: 1,
+    done: 2,
+    working: 3,
+    idle: 4,
+};
+/** States a tile can hold (excludes the `gone` delete-command). */
+exports.VALID_STATES = new Set([
+    "error",
+    "waiting",
+    "done",
+    "working",
+    "idle",
+]);