@50arms/platform-mcp 0.0.0-stage → 0.1.437

package/dist/session-key.js

@@ -0,0 +1,125 @@
+/**
+ * DX-4390 (PLAN-17 section 96) - the dashboard key a user approved for ONE agent session, kept on
+ * this machine so the session's MCP server and its event relay both authenticate with it.
+ *
+ * One file per dashboard and per session:
+ * `~/.config/danxbot/session-keys/<sha12(dashboard url)>/<session id>.json`, mode 0600. The key
+ * lapses on the dashboard after 24 hours without use (it slides on every authenticated call), so
+ * this file is a cache of a revocable, short-lived credential, not a standing secret: a 401 on it
+ * deletes it (`SessionAccess`), and files nothing has touched for a week are pruned on the next
+ * write (`pruneStaleSessionFiles`, shared with the session connection record). A live server
+ * rewrites its file at least hourly (`SessionAccess.guard`), so only an unused session's file
+ * ages out. The session id picks the file but never selects a key on the dashboard.
+ *
+ * Written write-then-rename, like the session connection record, so a relay reading
+ * concurrently sees the old file or the new one, never a torn one.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { writeFileDurable } from "./durable-write.js";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { assertSessionIdSegment, pruneStaleSessionFiles } from "./session-connection.js";
+/** One canonical shape (CLAUDE.md Core Principle 1): a file of any other version is refused. */
+export const SESSION_KEY_SCHEMA_VERSION = 1;
+const dashboardHash = (dashboardUrl) => createHash("sha256").update(dashboardUrl.replace(/\/+$/, "")).digest("hex").slice(0, 12);
+export function sessionKeyRoot(home = homedir()) {
+    return join(home, ".config", "danxbot", "session-keys");
+}
+export function sessionKeyDir(dashboardUrl, home = homedir()) {
+    return join(sessionKeyRoot(home), dashboardHash(dashboardUrl));
+}
+export function sessionKeyPath(dashboardUrl, sessionId, home = homedir()) {
+    assertSessionIdSegment(sessionId);
+    return join(sessionKeyDir(dashboardUrl, home), `${sessionId}.json`);
+}
+/** Store a freshly claimed key for this session; returns the file's path. */
+export function writeSessionKey(input, options = {}) {
+    const home = options.home ?? homedir();
+    const now = options.now ?? Date.now();
+    const file = sessionKeyPath(input.dashboardUrl, input.sessionId, home);
+    const dir = sessionKeyDir(input.dashboardUrl, home);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    pruneStaleSessionFiles(dir, now);
+    const record = {
+        schemaVersion: SESSION_KEY_SCHEMA_VERSION,
+        dashboardUrl: input.dashboardUrl.replace(/\/+$/, ""),
+        sessionId: input.sessionId,
+        apiKey: input.apiKey,
+        savedAt: new Date(now).toISOString(),
+    };
+    writeFileDurable(file, JSON.stringify(record), { mode: 0o600 });
+    return file;
+}
+/** Why a key file cannot be used, or `null`. */
+function invalidKeyReason(value) {
+    if (typeof value !== "object" || value === null)
+        return "it is not an object";
+    const r = value;
+    if (r.schemaVersion !== SESSION_KEY_SCHEMA_VERSION) {
+        return `schemaVersion is ${JSON.stringify(r.schemaVersion)}, not ${SESSION_KEY_SCHEMA_VERSION}`;
+    }
+    for (const field of ["dashboardUrl", "sessionId", "apiKey", "savedAt"]) {
+        if (typeof r[field] !== "string" || r[field] === "")
+            return `${field} is not a non-empty string`;
+    }
+    return null;
+}
+/** The thrown shape of an absent file, so a caller can tell "no key" from "a key I cannot read". */
+export class SessionKeyAbsentError extends Error {
+    constructor(path) {
+        super(`there is no session key at ${path}`);
+        this.name = "SessionKeyAbsentError";
+    }
+}
+/** A key file that is there but unreadable or of another shape. */
+export class SessionKeyUnusableError extends Error {
+    path;
+    constructor(path, why) {
+        super(`the session key file ${path} is unusable: ${why}`);
+        this.path = path;
+        this.name = "SessionKeyUnusableError";
+    }
+}
+/** The record in `path`. Absent and unusable are different errors: only the first means "never signed in". */
+function readSessionKeyRecord(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, "utf-8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            throw new SessionKeyAbsentError(path);
+        throw new SessionKeyUnusableError(path, err.message);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new SessionKeyUnusableError(path, `not JSON (${err.message})`);
+    }
+    const invalid = invalidKeyReason(parsed);
+    if (invalid !== null)
+        throw new SessionKeyUnusableError(path, invalid);
+    return parsed;
+}
+/** The key in `path`. */
+export function readSessionKeyFile(path) {
+    return readSessionKeyRecord(path).apiKey;
+}
+/** DX-6607 - every dashboard this session holds a key on, as its key files name them (the folder name is a hash of the URL, so only the file can say). A file that is there but unusable throws. */
+export function sessionKeyDashboards(sessionId, home = homedir()) {
+    assertSessionIdSegment(sessionId);
+    const root = sessionKeyRoot(home);
+    if (!existsSync(root))
+        return [];
+    return readdirSync(root).flatMap((dashboard) => {
+        const file = join(root, dashboard, `${sessionId}.json`);
+        return existsSync(file) ? [readSessionKeyRecord(file).dashboardUrl] : [];
+    });
+}
+/** Delete a key file (a revoked or lapsed key). Never throws for an absent file. */
+export function deleteSessionKey(path) {
+    rmSync(path, { force: true });
+}

package/dist/session-options.js

@@ -0,0 +1,60 @@
+/**
+ * DX-2862 / DX-4233 - how `restart_notice` (`restart-notice.ts`, this file's only caller) learns which dashboard to call and
+ * as whom when it asks about an earlier session. It reads the connection record that session's own MCP server wrote when it
+ * connected a plan (`session-connection.ts`), resolves the credential the record names through the same resolver the server
+ * used, and refuses unless it fingerprints identically. The in-process relay behind `plan_events_wait` needs none of this: it
+ * lives inside the server that holds the credential.
+ */
+import { homedir } from "node:os";
+import { credentialFingerprint, describeCredentialSource, readCredential } from "./credential.js";
+import { readSessionConnection } from "./session-connection.js";
+import { fixForStop } from "./stop-fixes.js";
+export const SESSION_ID_HEADER = "x-danx-session-id";
+/** DX-5033 / DX-5076 - marks a request as this process's own background work (not the agent acting): the dashboard ends no agent pause on it. */
+export const PLUGIN_BACKGROUND_HEADER = "x-danx-plugin-background";
+/** A start this process cannot make, named the way the session will be told about it. */
+export class SessionStartError extends Error {
+    // `ListenStopReason`, not `string`: a start-time failure is always one of `no_connection_record` / `credential_unavailable`
+    // / `credential_mismatch` (there is no stream yet).
+    reason;
+    fix;
+    constructor(reason, detail, fix) {
+        super(detail);
+        this.name = "SessionStartError";
+        this.reason = reason;
+        this.fix = fix;
+    }
+}
+/**
+ * The session's connection, as its own MCP server recorded it, and the proof that this process holds the SAME credential that
+ * server does. Never falls back to an ambient env credential: that fallback is precisely DX-2862.
+ */
+export function resolveDashboardAuth(sessionId, env, options = {}) {
+    const home = options.home ?? homedir();
+    let record;
+    try {
+        record = readSessionConnection(sessionId, { home });
+    }
+    catch (err) {
+        throw new SessionStartError("no_connection_record", err.message, fixForStop("no_connection_record"));
+    }
+    if (record === null) {
+        throw new SessionStartError("no_connection_record", `session ${sessionId} has no dashboard connection record — no platform MCP server has connected it to a plan`, fixForStop("no_connection_record"));
+    }
+    let token;
+    try {
+        token = readCredential(record.source, env);
+    }
+    catch (err) {
+        const credentialError = err;
+        throw new SessionStartError("credential_unavailable", `the credential this session's platform MCP server declared cannot be resolved here: ${credentialError.message}`, 
+        // CredentialError.fix is a required string, never absent — no fallback needed.
+        credentialError.fix);
+    }
+    const fingerprint = credentialFingerprint(token);
+    if (fingerprint !== record.fingerprint) {
+        throw new SessionStartError("credential_mismatch", `${describeCredentialSource(record.source)} now yields credential ${fingerprint}, but this session's ` +
+            `platform MCP server is using ${record.fingerprint} — a lookup would authenticate as somebody else`, fixForStop("credential_mismatch"));
+    }
+    return { dashboardUrl: record.dashboardUrl.replace(/\/+$/, ""), token, sessionId };
+}

package/dist/session-stats.js

@@ -0,0 +1,235 @@
+/**
+ * DX-2954 — an operator session's live stats, collected by the relay and sent
+ * in its DX-2952 heartbeat.
+ *
+ * Workers and operator sessions report the same stats the same way (epic
+ * DX-2958), so this module owns NO counting or cursor logic of its own: it runs
+ * the ONE collector from the shared package (`DispatchUsage`, the shared ledger
+ * counter + transcript cursors + running-set queue), fed by the ONE transcript
+ * tailer (`SessionLogWatcher`) and the ONE transcript-side running-set producer
+ * (`createActivityObserver`) — the exact trio the worker runs in
+ * `attach-monitoring-stack.ts`. The server side is the ONE writer too:
+ * `POST /api/plan-sessions/me/heartbeat` applies the `stats` field through the
+ * same `applyStatsInTx` the worker's `/stats` route uses.
+ *
+ * ## Process start: the first heartbeat's answer, never the mint (round 22)
+ *
+ * A restarted session's relay (a resume or a restarted MCP server) may fail its mint and
+ * still heartbeat (DX-2952), so the heartbeat is the one call that always
+ * answers. Until this process holds that answer it sends ONLY its connection
+ * state: no ledger entries, no cursors — the transcript is not even opened. The
+ * answer's `sourceCursors` are where each source resumes (start-order rule 1: an
+ * operator dispatch is one per session id, so its own stored `acked` is the
+ * whole answer; a source with none starts at 0 — rule 3, so a session connected
+ * mid-way, or a fork, has its full transcript counted). There is no predecessor
+ * and never an end-of-file skip for an operator session.
+ *
+ * An in-process re-mint (lease expiry, a refused ticket, transient backoff)
+ * never reaches this module: it lives for the whole process, so its in-memory
+ * state is untouched by anything the mint loop does.
+ *
+ * ## The one path that leaves the machine
+ *
+ * `transcriptPath` comes from the Claude Code hook input `transcript_path` (the
+ * plugin hands it to this process as {@link TRANSCRIPT_PATH_ENV}). It is sent
+ * once, in the first stats-bearing heartbeat, and recorded on the dispatch's
+ * `jsonl_path`; the strict stats parser refuses every other path field.
+ */
+import { basename, dirname, isAbsolute } from "node:path";
+import { DispatchUsage, SessionLogWatcher, createActivityObserver, readGitHead, } from "@50arms/session-telemetry";
+/**
+ * DX-4233 - the one rule for a transcript path, wherever it comes from (the `transcript_path` argument of
+ * `plan_events_wait`): an absolute `.jsonl` path, or a loud refusal naming `source`.
+ */
+export function checkedTranscriptPath(path, source) {
+    if (!isAbsolute(path) || !path.endsWith(".jsonl")) {
+        throw new Error(`${source} must be an absolute path to a session .jsonl transcript (got "${path}")`);
+    }
+    return path;
+}
+const realWatcher = (options) => new SessionLogWatcher(options);
+/** The collector's dispatch-id argument; the heartbeat is addressed by session, not dispatch. */
+const OPERATOR_DISPATCH_REF = "operator-session";
+/**
+ * DX-3962 - the relay's collector. `"operator-bridge"` (the telemetry package's published mode value, kept under its old name) is the ONE mode that credits a sub-agent's replies to the card
+ * it claimed (from its own transcript's pickup); a worker builds its collector with attribution off.
+ */
+function newCollector() {
+    return new DispatchUsage("operator-bridge");
+}
+export class OperatorSessionStats {
+    transcriptPath;
+    makeWatcher;
+    usage = newCollector();
+    watcher = null;
+    stopped = false;
+    /** DX-6367: the last landed answer said the dashboard accepts `statsHeld`. */
+    dashboardAcceptsStatsHeld = false;
+    constructor(transcriptPath, makeWatcher = realWatcher) {
+        this.transcriptPath = transcriptPath;
+        this.makeWatcher = makeWatcher;
+    }
+    /** Whether this process holds the stored stats (and is therefore collecting). */
+    collecting() {
+        return this.watcher !== null;
+    }
+    /**
+     * One heartbeat tick. Before the process holds the stored stats: a plain
+     * connection-state heartbeat, whose answer starts collection. After: the
+     * collector's flush, carried by the heartbeat (a flush with nothing new
+     * sends one plain heartbeat instead, so an idle session still heartbeats).
+     * Returns whether a heartbeat landed, for the relay's silent-failure count.
+     */
+    async tick(rawSend) {
+        const send = this.tracked(rawSend);
+        if (this.watcher === null) {
+            const answer = await send(undefined);
+            if (answer.stats !== null)
+                this.begin(answer.stats);
+            return answer.landed;
+        }
+        const { carried, landed, planless } = await this.flushVia(send);
+        if (planless) {
+            // DX-4892: re-queueing would resend this batch on every tick for as long as the session stays planless. Drop the collector instead:
+            // the plain heartbeats that follow start collection again from the stored cursors once an answer carries stats (the session is bound).
+            this.watcher?.stop();
+            this.watcher = null;
+            this.usage = newCollector();
+            return landed;
+        }
+        if (carried)
+            return landed;
+        // DX-6367: while collecting, this process holds the stored stats, so the plain heartbeat asks for none.
+        return (await send(undefined, this.dashboardAcceptsStatsHeld)).landed;
+    }
+    /** `send`, remembering whether the dashboard accepts `statsHeld`. */
+    tracked(send) {
+        return async (stats, statsHeld) => {
+            const answer = await send(stats, statsHeld);
+            if (answer.landed)
+                this.dashboardAcceptsStatsHeld = answer.acceptsStatsHeld;
+            return answer;
+        };
+    }
+    /** One collector flush carried by `send`; a refused or unlanded batch throws inside the collector, which re-queues it. */
+    async flushVia(send) {
+        const outcome = { carried: false, landed: true, planless: false };
+        const flushed = await this.usage.flush({
+            applyStats: async (_dispatchId, payload) => {
+                outcome.carried = true;
+                const answer = await send(payload);
+                if (!answer.landed) {
+                    outcome.landed = false;
+                    throw new Error("stats heartbeat did not reach the dashboard");
+                }
+                if (answer.statsNotStored === "no_plan") {
+                    outcome.planless = true;
+                    throw new Error("stats heartbeat refused: the session is on no plan, so the dashboard stores no stats for it");
+                }
+                if (answer.stats === null) {
+                    throw new Error(`stats heartbeat answered HTTP ${answer.status} without stats`);
+                }
+                return answer.stats;
+            },
+        }, OPERATOR_DISPATCH_REF);
+        return { ...outcome, outcome: flushed };
+    }
+    /**
+     * Stop tailing. Idempotent; a stopped collector never starts again.
+     *
+     * DX-5415: a sub-agent's final report is held until its end signal is read, and confirmed only by a LATER poll (DX-5413), so a bare
+     * `watcher.stop()` lost any final still held or whose signal was read in the last poll. A collecting watcher is therefore settled first:
+     * `drainFinal()`, then one flush carried by `send`, and only then stopped. The bound only stops WAITING: when it fires, `stop` returns
+     * and stops the watcher, but the drain and the flush already under way keep running to their own end (each dashboard request is
+     * bounded by its own request timeout), so shutdown never hangs and a cut-off settle can still land late. A drain that throws, a flush
+     * that fails or is refused, or a settle cut off costs only what it had not yet delivered, said on stderr.
+     */
+    async stop(send, bound) {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        const watcher = this.watcher;
+        if (watcher === null)
+            return;
+        const cutOff = new Promise((resolve) => {
+            if (bound.aborted)
+                resolve("cut");
+            else
+                bound.addEventListener("abort", () => resolve("cut"), { once: true });
+        });
+        try {
+            const settled = (async () => {
+                await watcher.drainFinal();
+                // DX-5415: a failed or refused flush re-queues nothing for a collector that is stopping, so it says what it costs.
+                const flushed = (await this.flushVia(send)).outcome;
+                if (flushed !== "ok")
+                    process.stderr.write(`operator session stats: the final flush was ${flushed}; held sub-agent finals may be lost
+`);
+                return "settled";
+            })();
+            settled.catch(() => undefined); // a cut-off settle's late failure is already reported by the race below
+            if ((await Promise.race([settled, cutOff])) === "cut") {
+                process.stderr.write("operator session stats: the final settle was cut off by its bound; held sub-agent finals may be lost\n");
+            }
+        }
+        catch (err) {
+            process.stderr.write(`operator session stats: final settle failed: ${err instanceof Error ? err.message : String(err)}\n`);
+        }
+        finally {
+            watcher.stop();
+        }
+    }
+    begin(stored) {
+        // `this.watcher !== null`: the relay fires `tick` without awaiting it, so
+        // two ticks can both be waiting on a pre-collection heartbeat. The first
+        // answer starts collection; a second must not start (and leak) another
+        // tailer over the same transcript.
+        if (this.transcriptPath === null || this.stopped || this.watcher !== null)
+            return;
+        const path = this.transcriptPath;
+        const activities = createActivityObserver({
+            recordActivities: (changes) => this.usage.recordActivities(changes),
+            // DX-5333: each sub-agent's brief, follow-ups and reports, the problems it raised, and the commit it started from.
+            recordMessages: (messages) => this.usage.recordMessages(messages),
+            recordProblemLinks: (links) => this.usage.recordProblemLinks(links),
+            readHeadSha: readGitHead,
+        });
+        const watcher = this.makeWatcher({
+            cwd: dirname(path),
+            sessionDir: dirname(path),
+            sessionId: basename(path, ".jsonl"),
+            startCursors: stored.sourceCursors,
+            onCursorPastEof: (info) => this.usage.recordPastEof(info),
+            onSourceDiscovered: (info) => activities.onSourceDiscovered(info),
+            onPollComplete: () => activities.onPollComplete(),
+        });
+        this.usage.attachCursors(() => watcher.cursorState(), stored.sourceCursors);
+        this.usage.setTranscriptPath(path);
+        // Replays are credited (the ledger is idempotent) and marked so the
+        // collector's own estimate never counts them twice; the relay has no
+        // side-effecting transcript subscriber to skip them for.
+        watcher.onUsageLine((raw, meta) => this.usage.observeRawLine(raw, meta));
+        // DX-4498 — the raw line feed: the brief and Claude Code's task notifications are not entries.
+        watcher.onUsageLine(activities.onLine);
+        this.watcher = watcher;
+        void watcher
+            .start()
+            .then(async () => {
+            // The watcher's discovery gives up after a bounded wait when the
+            // transcript file does not exist yet (Claude Code may create it lazily,
+            // on the session's first turn). Collecting "forever" from a watcher that
+            // adopted no file would read nothing, so drop it: the next heartbeat's
+            // answer starts collection again from the stored cursors.
+            if (this.watcher !== watcher || this.stopped)
+                return;
+            if ((await watcher.resolveSessionFileNow()) !== null)
+                return;
+            watcher.stop();
+            this.watcher = null;
+            this.usage = newCollector();
+        })
+            .catch((err) => {
+            process.stderr.write(`operator session stats: transcript watcher failed: ${err.message}\n`);
+        });
+    }
+}