spexcode 0.6.2 → 0.6.6

package/README.md

@@ -94,11 +94,13 @@ workflow on its own.
 When you want the live board (the graph, sessions, evals), start the runtime:
 
 ```sh
+npm i -g @spexcode/spec-dashboard # install the optional UI package once
 spex serve       # this project's backend — prints its URL
 spex dashboard   # the machine's one gateway — every project behind one URL
 ```
 
-One `spex dashboard` per machine is enough: every project you serve shows up behind it, and its
+The dashboard is a separate package so writing-only installs do not carry frontend build output. One `spex dashboard`
+per machine is enough: every project you serve shows up behind it, and its
 `/projects` page manages them from the browser.
 [Getting started](https://spexcode.net/getting-started/) walks the rest of the setup.
 

package/bin/spex.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+// @@@ root release launcher ([[release-launcher]]) - the metapackage owns one command and delegates all
+// product behavior to the independently compiled CLI package.
+import '@spexcode/spec-cli/bin/spex.mjs'

package/node_modules/@spexcode/session-core/dist/delivery-queue.d.ts

@@ -0,0 +1,23 @@
+export type PendingMessage = {
+    mid: string;
+    text: string;
+    from: string | null;
+    dispatch?: {
+        operation: string;
+        requestDigest: string;
+    };
+};
+export declare function revokeSenderDelivery(id: string): void;
+export declare const senderDeliveryRevoked: (id: string) => boolean;
+export declare function pendingSnapshot(id: string): PendingMessage[];
+export declare function replacePendingWhileLocked(id: string, msgs: PendingMessage[]): void;
+export declare function revokePendingFromWhileLocked(id: string, sender: string): number;
+export declare function enqueue(id: string, msg: PendingMessage): void;
+export declare function ensurePendingWhileLocked(id: string, msg: PendingMessage): boolean;
+export declare const pendingMessages: (id: string) => PendingMessage[];
+export declare const owesDelivery: (id: string) => boolean;
+export declare function withDeliveryLocks<T>(rawIds: string[], body: () => Promise<T>, index?: number, ids?: string[]): Promise<T>;
+export declare function drain(id: string, insert: (msg: PendingMessage) => Promise<boolean>, timeoutMs?: number): Promise<{
+    delivered: number;
+    remaining: number;
+}>;

package/node_modules/@spexcode/session-core/dist/delivery-queue.js

@@ -0,0 +1,195 @@
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, writeSync } from 'node:fs';
+import { join } from 'node:path';
+import { runtimeRoot, sessionArtifactPath, sessionStoreDir } from '@spexcode/spec-core';
+import { sentDispatchReceipt, settleSentDispatch } from './session-timeline.js';
+const queuePath = (id) => sessionArtifactPath(id, 'pending.json');
+const revokedSenderRoot = () => join(runtimeRoot(), '.revoked-senders');
+const revokedSenderPath = (id) => join(revokedSenderRoot(), id);
+// @@@ its own lock, deliberately NOT the record lock - the drain holds this across the adapter insert, which
+// is what makes "claim" real: two processes draining the same session cannot both hand over one message. The
+// record lock could never span that call — a native turn runs lifecycle hooks that re-enter the record writer,
+// and holding it there deadlocks the adapter's own confirmation. Nothing in the delivery path takes this one,
+// so spanning the insert costs no contention. PID liveness reclaims a lock whose holder died mid-insert.
+const lockRoot = () => join(runtimeRoot(), '.delivery-locks');
+const lockPath = (id) => join(lockRoot(), `${id}.lock`);
+const pause = (ms) => new Promise((r) => setTimeout(r, ms));
+async function acquire(id, timeoutMs) {
+    mkdirSync(lockRoot(), { recursive: true });
+    const path = lockPath(id), deadline = Date.now() + timeoutMs;
+    for (;;) {
+        try {
+            const fd = openSync(path, 'wx');
+            writeSync(fd, String(process.pid));
+            closeSync(fd);
+            return () => { try {
+                unlinkSync(path);
+            }
+            catch { /* a liveness reclaim already removed it */ } };
+        }
+        catch (e) {
+            if (e.code !== 'EEXIST')
+                throw e;
+            let owner = 0;
+            try {
+                owner = Number(readFileSync(path, 'utf8').trim()) || 0;
+            }
+            catch { /* race with creator/releaser */ }
+            if (owner && owner !== process.pid) {
+                try {
+                    process.kill(owner, 0);
+                }
+                catch {
+                    try {
+                        unlinkSync(path);
+                    }
+                    catch { /* race */ }
+                    ;
+                    continue;
+                }
+            }
+            // A drain is never urgent enough to fight for: whoever holds the lock is delivering these same messages,
+            // and the retry sweep will come back. Declining is not a lost message.
+            if (Date.now() >= deadline)
+                return null;
+            await pause(25);
+        }
+    }
+}
+function read(id) {
+    try {
+        const raw = JSON.parse(readFileSync(queuePath(id), 'utf8'));
+        if (!Array.isArray(raw))
+            return [];
+        return raw.filter((m) => !!m && typeof m === 'object'
+            && typeof m.mid === 'string'
+            && typeof m.text === 'string'
+            && (m.dispatch === undefined
+                || (typeof m.dispatch?.operation === 'string'
+                    && typeof m.dispatch?.requestDigest === 'string')));
+    }
+    catch {
+        return [];
+    } // absent, empty, or unparseable all mean the honest thing: nothing owed
+}
+// Written whole and atomically; an empty queue is REMOVED rather than left as `[]`, so "is anything owed?" is
+// one existsSync on the sweep's hot path.
+function write(id, msgs) {
+    const path = queuePath(id);
+    if (!msgs.length) {
+        try {
+            unlinkSync(path);
+        }
+        catch { /* already gone */ }
+        ;
+        return;
+    }
+    mkdirSync(sessionStoreDir(id), { recursive: true });
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(msgs, null, 2) + '\n');
+    renameSync(tmp, path);
+}
+// A closed sender may have left debt in many other sessions' queues. The marker is deliberately outside its
+// own store (which close removes) and is checked under the sender's record lock by dispatch: a close cannot
+// return while an old process can still append, and a later sweep cannot hand over what it sees here.
+export function revokeSenderDelivery(id) {
+    mkdirSync(revokedSenderRoot(), { recursive: true });
+    writeFileSync(revokedSenderPath(id), `${id}\n`);
+}
+export const senderDeliveryRevoked = (id) => existsSync(revokedSenderPath(id));
+export function pendingSnapshot(id) { return read(id); }
+// These two writes require the target's delivery lock. They are the queue half of a larger transaction
+// (currently reparent), which must be able to restore the exact previous debt if a later record write fails.
+export function replacePendingWhileLocked(id, msgs) { write(id, msgs); }
+export function revokePendingFromWhileLocked(id, sender) {
+    const current = read(id);
+    const next = current.filter((msg) => msg.from !== sender);
+    write(id, next);
+    return current.length - next.length;
+}
+// The enqueue rides the timeline append ([[dispatch]]): the caller holds the session's RECORD lock across
+// both, and the record is written first, so delivery is never unrecorded. A keyed dispatch also carries its
+// exact delivery bytes in the timeline receipt, letting its retry restore a queue write lost to a crash.
+export function enqueue(id, msg) {
+    write(id, [...read(id), msg]);
+}
+// Caller holds this target's delivery lock. A retry may reach this after either side of the receipt->queue
+// crash boundary; exact mid identity makes reconstruction idempotent without inspecting message text.
+export function ensurePendingWhileLocked(id, msg) {
+    const current = read(id);
+    if (current.some((pending) => pending.mid === msg.mid))
+        return false;
+    write(id, [...current, msg]);
+    return true;
+}
+export const pendingMessages = (id) => read(id);
+export const owesDelivery = (id) => existsSync(queuePath(id));
+// Record transitions and queue mutations take locks in the same direction: record locks first, then these
+// target queue locks. A batch reparent needs all child queues held at once so its pointer/watch/debt change
+// either commits together or restores together.
+export async function withDeliveryLocks(rawIds, body, index = 0, ids = [...new Set(rawIds)].sort()) {
+    if (index >= ids.length)
+        return body();
+    const release = await acquire(ids[index], 30_000);
+    if (!release)
+        throw new Error(`delivery queue ${ids[index]}: timed out waiting for transaction lock`);
+    try {
+        return await withDeliveryLocks(ids, body, index + 1, ids);
+    }
+    finally {
+        release();
+    }
+}
+// Hand over what is owed, in order, exactly once. `insert` reports whether the adapter took the message: only
+// then is the entry dropped. A refusal ENDS the pass with that entry still queued and everything behind it
+// still behind it — order is a property of a conversation, so a message is never skipped to deliver a later
+// one. Returns how many were handed over and how many are still owed.
+export async function drain(id, insert, timeoutMs = 5_000) {
+    const release = await acquire(id, timeoutMs);
+    if (!release)
+        return { delivered: 0, remaining: read(id).length };
+    let delivered = 0;
+    try {
+        for (;;) {
+            const queued = read(id);
+            if (!queued.length)
+                return { delivered, remaining: 0 };
+            if (queued[0].from && senderDeliveryRevoked(queued[0].from)) {
+                // Closing a sender voids its undelivered output, not the recipient's immutable conversation history.
+                // Drop a revoked head and continue so it cannot permanently block the messages behind it.
+                write(id, read(id).filter((m) => m.mid !== queued[0].mid));
+                continue;
+            }
+            let ok = false;
+            try {
+                const head = queued[0];
+                if (head.dispatch) {
+                    const receipt = sentDispatchReceipt(id, head.dispatch.operation, head.dispatch.requestDigest);
+                    if (!receipt || receipt.mid !== head.mid || !receipt.delivery
+                        || receipt.delivery.text !== head.text || receipt.delivery.from !== head.from)
+                        return { delivered, remaining: queued.length };
+                    if (receipt.delivered)
+                        ok = true;
+                    else {
+                        ok = await insert(head);
+                        if (ok)
+                            settleSentDispatch(id, head.mid);
+                    }
+                }
+                else
+                    ok = await insert(head);
+            }
+            catch {
+                ok = false;
+            }
+            if (!ok)
+                return { delivered, remaining: queued.length };
+            // Re-read before removing: a send that landed while this pass ran appended to the tail, and rewriting a
+            // stale snapshot minus the head would silently drop it.
+            write(id, read(id).filter((m) => m.mid !== queued[0].mid));
+            delivered++;
+        }
+    }
+    finally {
+        release();
+    }
+}

package/node_modules/@spexcode/session-core/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { acceptMessage, MessageKeyConflict, type AcceptMessageOptions, type MessageIdempotency, type PreparedMessage } from './message.js';
+export { drain, owesDelivery, pendingMessages, type PendingMessage } from './delivery-queue.js';
+export { publishRuntimeSessionState, readRuntimeSession, registerRuntimeSession, runtimeSessionChildren, RuntimeSessionConflict, type RuntimeSessionRecord, type RuntimeSessionRegistration, type RuntimeSessionState, } from './runtime-session.js';
+export { advanceFollow, followedSessions, followCursor, readCursors, unreadSince, type Cursors } from './session-cursors.js';
+export { currentHumanTurn, lastHumanSendVia, recordStatus, timelineEvents, timelineStamp, timelineTail, type SessionTurn, type TimelineEvent, } from './session-timeline.js';

package/node_modules/@spexcode/session-core/dist/index.js

@@ -0,0 +1,5 @@
+export { acceptMessage, MessageKeyConflict } from './message.js';
+export { drain, owesDelivery, pendingMessages } from './delivery-queue.js';
+export { publishRuntimeSessionState, readRuntimeSession, registerRuntimeSession, runtimeSessionChildren, RuntimeSessionConflict, } from './runtime-session.js';
+export { advanceFollow, followedSessions, followCursor, readCursors, unreadSince } from './session-cursors.js';
+export { currentHumanTurn, lastHumanSendVia, recordStatus, timelineEvents, timelineStamp, timelineTail, } from './session-timeline.js';

package/node_modules/@spexcode/session-core/dist/internal.d.ts

@@ -0,0 +1,3 @@
+export { enqueue, ensurePendingWhileLocked, pendingSnapshot, replacePendingWhileLocked, revokePendingFromWhileLocked, revokeSenderDelivery, senderDeliveryRevoked, withDeliveryLocks, } from './delivery-queue.js';
+export { appendSent, sentDispatchReceipt, settleSentDispatch, type SentDispatchReceipt, type SentDispatchState, } from './session-timeline.js';
+export { trySessionRecordLockSync, withSessionRecordLock, withSessionRecordLocks, withSessionRecordLockSync, } from './record-lock.js';

package/node_modules/@spexcode/session-core/dist/internal.js

@@ -0,0 +1,3 @@
+export { enqueue, ensurePendingWhileLocked, pendingSnapshot, replacePendingWhileLocked, revokePendingFromWhileLocked, revokeSenderDelivery, senderDeliveryRevoked, withDeliveryLocks, } from './delivery-queue.js';
+export { appendSent, sentDispatchReceipt, settleSentDispatch, } from './session-timeline.js';
+export { trySessionRecordLockSync, withSessionRecordLock, withSessionRecordLocks, withSessionRecordLockSync, } from './record-lock.js';

package/node_modules/@spexcode/session-core/dist/message.d.ts

@@ -0,0 +1,22 @@
+import { type SentDispatchReceipt } from './session-timeline.js';
+export type MessageIdempotency = SentDispatchReceipt;
+export type PreparedMessage = {
+    text: string;
+    replyVia?: 'note';
+};
+export type AcceptMessageOptions = {
+    target: string;
+    text: string;
+    from?: string;
+    idempotency?: MessageIdempotency;
+    validate?: () => Promise<void>;
+    prepare: () => Promise<PreparedMessage>;
+};
+export declare class MessageKeyConflict extends Error {
+    readonly code = "dispatch_key_reused";
+    constructor(operation: string);
+}
+export declare function acceptMessage(options: AcceptMessageOptions): Promise<{
+    mid: string;
+    replayed: boolean;
+}>;

package/node_modules/@spexcode/session-core/dist/message.js

@@ -0,0 +1,52 @@
+import { ensurePendingWhileLocked, enqueue, senderDeliveryRevoked, withDeliveryLocks } from './delivery-queue.js';
+import { appendSent, sentDispatchReceipt } from './session-timeline.js';
+import { withSessionRecordLocks } from './record-lock.js';
+export class MessageKeyConflict extends Error {
+    code = 'dispatch_key_reused';
+    constructor(operation) {
+        super(`idempotency key is already bound to another ${operation} payload`);
+        this.name = 'MessageKeyConflict';
+    }
+}
+const keyedPending = (receipt, mid, delivery) => ({
+    mid,
+    text: delivery.text,
+    from: delivery.from,
+    dispatch: { operation: receipt.operation, requestDigest: receipt.requestDigest },
+});
+// The durable acceptance boundary. Product validation and prompt composition run while the record fence is
+// held, but the package alone owns append + debt publication and keyed crash recovery.
+export async function acceptMessage(options) {
+    const from = options.from ?? null;
+    let result = null;
+    await withSessionRecordLocks([options.target, ...(from ? [from] : [])], async () => {
+        if (from && senderDeliveryRevoked(from))
+            throw new Error(`sender session ${from} is closed; prompt NOT delivered`);
+        await options.validate?.();
+        const accept = async () => {
+            if (options.idempotency) {
+                const prior = sentDispatchReceipt(options.target, options.idempotency.operation, options.idempotency.requestDigest);
+                if (prior) {
+                    if (prior.payloadHash !== options.idempotency.payloadHash)
+                        throw new MessageKeyConflict(options.idempotency.operation);
+                    if (prior.delivery && !prior.delivered)
+                        ensurePendingWhileLocked(options.target, keyedPending(options.idempotency, prior.mid, prior.delivery));
+                    result = { mid: prior.mid, replayed: true };
+                    return;
+                }
+            }
+            const prepared = await options.prepare();
+            const receipt = options.idempotency
+                ? { ...options.idempotency, delivery: { text: prepared.text, from } }
+                : undefined;
+            const { mid } = appendSent(options.target, options.text, from, prepared.replyVia, receipt);
+            enqueue(options.target, receipt ? keyedPending(receipt, mid, receipt.delivery) : { mid, text: prepared.text, from });
+            result = { mid, replayed: false };
+        };
+        if (options.idempotency)
+            await withDeliveryLocks([options.target], accept);
+        else
+            await accept();
+    });
+    return result;
+}

package/node_modules/@spexcode/session-core/dist/record-lock.d.ts

@@ -0,0 +1,7 @@
+export declare class SessionRecordLockTimeout extends Error {
+    constructor(id: string);
+}
+export declare function withSessionRecordLock<T>(id: string, body: () => Promise<T>, signal?: AbortSignal): Promise<T>;
+export declare function withSessionRecordLockSync<T>(id: string, body: () => T): T;
+export declare function trySessionRecordLockSync(id: string): (() => void) | null;
+export declare function withSessionRecordLocks<T>(rawIds: string[], body: () => Promise<T>, index?: number, ids?: string[]): Promise<T>;

package/node_modules/@spexcode/session-core/dist/record-lock.js

@@ -0,0 +1,152 @@
+import { closeSync, mkdirSync, openSync, readFileSync, unlinkSync, writeSync } from 'node:fs';
+import { join } from 'node:path';
+import { runtimeRoot } from '@spexcode/spec-core';
+const lockRoot = () => join(runtimeRoot(), '.session-locks');
+const lockPath = (id) => join(lockRoot(), `${id}.lock`);
+const syncPause = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+export class SessionRecordLockTimeout extends Error {
+    constructor(id) {
+        super(`session ${id}: lifecycle transition lock timed out; refusing a stale write`);
+        this.name = 'SessionRecordLockTimeout';
+    }
+}
+function acquireSync(id, timeoutMs = 30_000) {
+    mkdirSync(lockRoot(), { recursive: true });
+    const path = lockPath(id), deadline = Date.now() + timeoutMs;
+    for (;;) {
+        try {
+            const fd = openSync(path, 'wx');
+            writeSync(fd, String(process.pid));
+            closeSync(fd);
+            return () => { try {
+                unlinkSync(path);
+            }
+            catch { /* another recovery already removed it */ } };
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            let owner = 0;
+            try {
+                owner = Number(readFileSync(path, 'utf8').trim()) || 0;
+            }
+            catch { /* race */ }
+            if (owner && owner !== process.pid) {
+                try {
+                    process.kill(owner, 0);
+                }
+                catch {
+                    try {
+                        unlinkSync(path);
+                    }
+                    catch { /* race */ }
+                    ;
+                    continue;
+                }
+            }
+            if (Date.now() >= deadline)
+                throw new SessionRecordLockTimeout(id);
+            syncPause(10);
+        }
+    }
+}
+const aborted = (signal) => signal.reason instanceof Error
+    ? signal.reason
+    : Object.assign(new Error('The operation was aborted'), { name: 'AbortError', code: 'ABORT_ERR' });
+async function pause(signal) {
+    if (!signal) {
+        await new Promise((resolve) => setTimeout(resolve, 10));
+        return;
+    }
+    if (signal.aborted)
+        throw aborted(signal);
+    await new Promise((resolve, reject) => {
+        const timer = setTimeout(done, 10);
+        const abort = () => { clearTimeout(timer); signal.removeEventListener('abort', abort); reject(aborted(signal)); };
+        function done() { signal.removeEventListener('abort', abort); resolve(); }
+        signal.addEventListener('abort', abort, { once: true });
+    });
+}
+async function acquire(id, timeoutMs = 30_000, signal) {
+    mkdirSync(lockRoot(), { recursive: true });
+    const path = lockPath(id), deadline = Date.now() + timeoutMs;
+    for (;;) {
+        if (signal?.aborted)
+            throw aborted(signal);
+        try {
+            const fd = openSync(path, 'wx');
+            writeSync(fd, String(process.pid));
+            closeSync(fd);
+            return () => { try {
+                unlinkSync(path);
+            }
+            catch { /* another recovery already removed it */ } };
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            let owner = 0;
+            try {
+                owner = Number(readFileSync(path, 'utf8').trim()) || 0;
+            }
+            catch { /* race */ }
+            if (owner && owner !== process.pid) {
+                try {
+                    process.kill(owner, 0);
+                }
+                catch {
+                    try {
+                        unlinkSync(path);
+                    }
+                    catch { /* race */ }
+                    ;
+                    continue;
+                }
+            }
+            if (Date.now() >= deadline)
+                throw new SessionRecordLockTimeout(id);
+            await pause(signal);
+        }
+    }
+}
+export async function withSessionRecordLock(id, body, signal) {
+    const release = await acquire(id, 30_000, signal);
+    try {
+        return await body();
+    }
+    finally {
+        release();
+    }
+}
+export function withSessionRecordLockSync(id, body) {
+    const release = acquireSync(id);
+    try {
+        return body();
+    }
+    finally {
+        release();
+    }
+}
+export function trySessionRecordLockSync(id) {
+    mkdirSync(lockRoot(), { recursive: true });
+    const path = lockPath(id);
+    try {
+        const fd = openSync(path, 'wx');
+        writeSync(fd, String(process.pid));
+        closeSync(fd);
+        return () => { try {
+            unlinkSync(path);
+        }
+        catch { /* another recovery already removed it */ } };
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            return null;
+        throw error;
+    }
+}
+export async function withSessionRecordLocks(rawIds, body, index = 0, ids = [...new Set(rawIds)].sort()) {
+    if (index >= ids.length)
+        return body();
+    return withSessionRecordLock(ids[index], () => withSessionRecordLocks(ids, body, index + 1, ids));
+}

package/node_modules/@spexcode/session-core/dist/runtime-session.d.ts

@@ -0,0 +1,50 @@
+import { type SessionLifecycle, type SessionProposal } from '@spexcode/spec-core';
+export type RuntimeSessionRegistration = {
+    sessionId: string;
+    runtimeOwner: string;
+    worktreePath: string;
+    branch: string | null;
+    parentSessionId?: string | null;
+    title?: string | null;
+    node?: string | null;
+    runtimeMetadata?: Record<string, string>;
+    createdAt?: number;
+};
+export type RuntimeSessionState = {
+    sessionId: string;
+    runtimeOwner: string;
+    revision: string;
+    runtimeState: string;
+    lifecycle: SessionLifecycle;
+    proposal?: SessionProposal | null;
+    note?: string | null;
+};
+export type RuntimeSessionRecord = {
+    sessionId: string;
+    runtimeOwner: string;
+    runtimeState: string | null;
+    revision: string | null;
+    worktreePath: string;
+    branch: string | null;
+    parentSessionId: string | null;
+    title: string | null;
+    node: string | null;
+    runtimeMetadata: Record<string, string>;
+    lifecycle: SessionLifecycle;
+    proposal: SessionProposal | null;
+    note: string | null;
+    createdAt: number;
+};
+export declare class RuntimeSessionConflict extends Error {
+    readonly code = "runtime_session_conflict";
+    constructor(message: string);
+}
+export declare function registerRuntimeSession(input: RuntimeSessionRegistration): Promise<{
+    replayed: boolean;
+}>;
+export declare function publishRuntimeSessionState(input: RuntimeSessionState): Promise<{
+    notified: string[];
+    replayed: boolean;
+}>;
+export declare function readRuntimeSession(sessionId: string): RuntimeSessionRecord | null;
+export declare function runtimeSessionChildren(parentSessionId: string, runtimeOwner?: string): RuntimeSessionRecord[];