spexcode 0.6.7 → 0.6.8

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

@@ -1,326 +0,0 @@
-import { createHash, randomUUID } from 'node:crypto';
-import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { isSessionLifecycle, isSessionProposal, listSessionIds, readRecordEntry, sessionArtifactPath, sessionRecordPath, sessionStoreDir, } from '@spexcode/spec-core';
-import { enqueue, ensurePendingWhileLocked, withDeliveryLocks } from './delivery-queue.js';
-import { withSessionRecordLocks } from './record-lock.js';
-import { appendSent, recordStatus, sentDispatchReceipt } from './session-timeline.js';
-export class RuntimeSessionConflict extends Error {
-    code = 'runtime_session_conflict';
-    constructor(message) {
-        super(message);
-        this.name = 'RuntimeSessionConflict';
-    }
-}
-const digest = (value) => createHash('sha256').update(value).digest('hex');
-const watchPath = (target) => sessionArtifactPath(target, 'watchers.json');
-const RUNTIME_NOTIFICATION_KIND = 'spex.runtime-state.v1';
-function scalar(value, field) {
-    const normalized = value.trim();
-    if (!normalized)
-        throw new RuntimeSessionConflict(`${field} must be a non-empty string`);
-    return normalized;
-}
-function metadata(value) {
-    if (!value)
-        return {};
-    const entries = Object.entries(value).map(([rawKey, rawValue]) => {
-        const key = scalar(rawKey, 'runtimeMetadata key');
-        if (typeof rawValue !== 'string')
-            throw new RuntimeSessionConflict(`runtimeMetadata.${key} must be a string`);
-        return [key, rawValue];
-    }).sort(([left], [right]) => left.localeCompare(right));
-    if (new Set(entries.map(([key]) => key)).size !== entries.length)
-        throw new RuntimeSessionConflict('runtimeMetadata keys must be unique after normalization');
-    return Object.fromEntries(entries);
-}
-function metadataKey(value) {
-    return JSON.stringify(metadata(value));
-}
-function readRaw(id) {
-    const entry = readRecordEntry(id);
-    if (entry.kind === 'absent')
-        return null;
-    if (entry.kind === 'corrupt')
-        throw new RuntimeSessionConflict(`session ${id} record is corrupt: ${entry.error}`);
-    return entry.raw;
-}
-function runtimeRecord(raw) {
-    const runtimeOwner = raw.runtime_owner?.trim();
-    if (!runtimeOwner)
-        throw new RuntimeSessionConflict(`session ${raw.session_id} is not owned by an external runtime`);
-    if (!isSessionLifecycle(raw.status))
-        throw new RuntimeSessionConflict(`session ${raw.session_id} has invalid lifecycle ${JSON.stringify(raw.status)}`);
-    if (!(raw.proposal == null || raw.proposal === '' || isSessionProposal(raw.proposal)))
-        throw new RuntimeSessionConflict(`session ${raw.session_id} has invalid proposal ${JSON.stringify(raw.proposal)}`);
-    return {
-        sessionId: raw.session_id,
-        runtimeOwner,
-        runtimeState: raw.runtime_state?.trim() || null,
-        revision: raw.runtime_revision?.trim() || null,
-        worktreePath: raw.worktree_path,
-        branch: raw.branch || null,
-        parentSessionId: raw.parent || null,
-        title: raw.title || null,
-        node: raw.node || null,
-        runtimeMetadata: metadata(raw.runtime_metadata),
-        lifecycle: raw.status,
-        proposal: isSessionProposal(raw.proposal) ? raw.proposal : null,
-        note: raw.note || null,
-        createdAt: Number(raw.createdAt) || 0,
-    };
-}
-function writeRaw(raw) {
-    const dir = sessionStoreDir(raw.session_id);
-    mkdirSync(dir, { recursive: true });
-    const path = sessionRecordPath(raw.session_id);
-    const tmp = join(dir, `.session.json.${process.pid}.${randomUUID()}.tmp`);
-    writeFileSync(tmp, JSON.stringify(raw, null, 2) + '\n');
-    renameSync(tmp, path);
-}
-function readWatches(target) {
-    let parsed;
-    try {
-        parsed = JSON.parse(readFileSync(watchPath(target), 'utf8'));
-    }
-    catch (error) {
-        if (error.code === 'ENOENT')
-            return [];
-        throw new RuntimeSessionConflict(`session ${target} watch record is unreadable: ${error instanceof Error ? error.message : String(error)}`);
-    }
-    if (!Array.isArray(parsed))
-        throw new RuntimeSessionConflict(`session ${target} watch record is not an array`);
-    return parsed.map((candidate, index) => {
-        if (!candidate || typeof candidate !== 'object')
-            throw new RuntimeSessionConflict(`session ${target} watch row ${index} is invalid`);
-        const row = candidate;
-        if (typeof row.watcher !== 'string' || typeof row.createdAt !== 'string' || !Array.isArray(row.sources)
-            || row.sources.some((source) => source !== 'manual' && source !== 'parent')
-            || (row.snapshotPending !== undefined && typeof row.snapshotPending !== 'string'))
-            throw new RuntimeSessionConflict(`session ${target} watch row ${index} is invalid`);
-        return row;
-    });
-}
-function writeWatches(target, entries) {
-    const dir = sessionStoreDir(target);
-    mkdirSync(dir, { recursive: true });
-    const path = watchPath(target);
-    const tmp = join(dir, `.watchers.json.${process.pid}.${randomUUID()}.tmp`);
-    writeFileSync(tmp, JSON.stringify(entries, null, 2) + '\n');
-    renameSync(tmp, path);
-}
-function registrationRaw(input) {
-    const sessionId = scalar(input.sessionId, 'sessionId');
-    const runtimeOwner = scalar(input.runtimeOwner, 'runtimeOwner');
-    return {
-        session_id: sessionId,
-        governed: false,
-        worktree_path: scalar(input.worktreePath, 'worktreePath'),
-        branch: input.branch ?? '',
-        node: input.node?.trim() || '',
-        title: input.title?.trim() || '',
-        name: '',
-        parent: input.parentSessionId?.trim() || '',
-        status: 'active',
-        proposal: '',
-        merges: 0,
-        note: '',
-        sortkey: null,
-        createdAt: input.createdAt ?? Date.now(),
-        harness: runtimeOwner,
-        harness_session_id: sessionId,
-        stopped: false,
-        archived: false,
-        cold_proof: '',
-        adapter_recovery: '',
-        launcher: '',
-        launch_cmd: '',
-        create_request_id: '',
-        create_payload_hash: '',
-        runtime_owner: runtimeOwner,
-        runtime_state: 'registered',
-        runtime_revision: '',
-        runtime_metadata: metadata(input.runtimeMetadata),
-        launch_readiness_pending: '',
-    };
-}
-function sameRegistration(raw, input) {
-    return raw.runtime_owner === input.runtimeOwner.trim()
-        && raw.worktree_path === input.worktreePath.trim()
-        && (raw.branch || null) === (input.branch || null)
-        && (raw.parent || null) === (input.parentSessionId?.trim() || null)
-        && metadataKey(raw.runtime_metadata) === metadataKey(input.runtimeMetadata);
-}
-export async function registerRuntimeSession(input) {
-    const id = scalar(input.sessionId, 'sessionId');
-    const parent = input.parentSessionId?.trim() || null;
-    return withSessionRecordLocks([id, ...(parent ? [parent] : [])], async () => {
-        if (parent) {
-            const parentRaw = readRaw(parent);
-            if (!parentRaw)
-                throw new RuntimeSessionConflict(`parent runtime session ${parent} is not registered`);
-            if (parentRaw.runtime_owner !== input.runtimeOwner.trim())
-                throw new RuntimeSessionConflict(`parent runtime session ${parent} belongs to another runtime`);
-        }
-        const existing = readRaw(id);
-        if (existing) {
-            if (!sameRegistration(existing, input))
-                throw new RuntimeSessionConflict(`session ${id} is already registered with different runtime coordinates`);
-            return { replayed: true };
-        }
-        writeRaw(registrationRaw(input));
-        if (parent)
-            writeWatches(id, [{
-                    watcher: parent,
-                    createdAt: new Date().toISOString(),
-                    sources: ['parent'],
-                    snapshotPending: randomUUID(),
-                }]);
-        return { replayed: false };
-    });
-}
-function stateMessage(record) {
-    const proposal = record.lifecycle === 'awaiting' && record.proposal ? `/${record.proposal}` : '';
-    const note = record.note ? ` — ${record.note}` : '';
-    return `[spex watch] ${record.sessionId} is ${record.runtimeState ?? record.lifecycle}${proposal}${note}`;
-}
-function notificationAttributes(record) {
-    if (!record.revision || !record.runtimeState)
-        throw new RuntimeSessionConflict(`runtime session ${record.sessionId} has no publishable state revision`);
-    return {
-        kind: RUNTIME_NOTIFICATION_KIND,
-        runtimeOwner: record.runtimeOwner,
-        runtimeState: record.runtimeState,
-        revision: record.revision,
-        lifecycle: record.lifecycle,
-        proposal: record.proposal ?? '',
-        note: record.note ?? '',
-    };
-}
-function pendingFor(receipt, mid) {
-    return {
-        mid,
-        text: receipt.delivery.text,
-        from: receipt.delivery.from,
-        ...(receipt.delivery.attributes ? { attributes: receipt.delivery.attributes } : {}),
-        dispatch: { operation: receipt.operation, requestDigest: receipt.requestDigest },
-    };
-}
-export function runtimeSessionNotification(parentSessionId, message) {
-    const parent = scalar(parentSessionId, 'parentSessionId');
-    const child = message.from?.trim();
-    const attributes = message.attributes;
-    if (!child || !attributes || attributes.kind !== RUNTIME_NOTIFICATION_KIND)
-        return null;
-    const record = readRuntimeSession(child);
-    if (!record || record.parentSessionId !== parent || record.runtimeOwner !== attributes.runtimeOwner)
-        return null;
-    if (!attributes.revision || !attributes.runtimeState || !isSessionLifecycle(attributes.lifecycle))
-        return null;
-    if (attributes.proposal && !isSessionProposal(attributes.proposal))
-        return null;
-    return {
-        childSessionId: child,
-        runtimeOwner: attributes.runtimeOwner,
-        runtimeState: attributes.runtimeState,
-        revision: attributes.revision,
-        lifecycle: attributes.lifecycle,
-        proposal: isSessionProposal(attributes.proposal) ? attributes.proposal : null,
-        note: attributes.note || null,
-        runtimeMetadata: record.runtimeMetadata,
-    };
-}
-export async function publishRuntimeSessionState(input) {
-    const id = scalar(input.sessionId, 'sessionId');
-    const owner = scalar(input.runtimeOwner, 'runtimeOwner');
-    const revision = scalar(input.revision, 'revision');
-    const runtimeState = scalar(input.runtimeState, 'runtimeState');
-    const initial = readRaw(id);
-    if (!initial)
-        throw new RuntimeSessionConflict(`runtime session ${id} is not registered`);
-    const watchers = readWatches(id).map((entry) => entry.watcher);
-    return withSessionRecordLocks([id, ...watchers], async () => withDeliveryLocks(watchers, async () => {
-        const raw = readRaw(id);
-        if (!raw)
-            throw new RuntimeSessionConflict(`runtime session ${id} disappeared during publication`);
-        if (raw.runtime_owner !== owner)
-            throw new RuntimeSessionConflict(`runtime session ${id} belongs to ${raw.runtime_owner || 'no external runtime'}, not ${owner}`);
-        const proposal = input.proposal ?? null;
-        const note = input.note ?? null;
-        const sameRevision = raw.runtime_revision === revision;
-        const sameState = raw.runtime_state === runtimeState && raw.status === input.lifecycle
-            && (raw.proposal || null) === proposal && (raw.note || null) === note;
-        if (sameRevision && !sameState)
-            throw new RuntimeSessionConflict(`runtime revision ${revision} for session ${id} is already bound to another state`);
-        const candidate = runtimeRecord({
-            ...raw,
-            status: input.lifecycle,
-            proposal: proposal ?? '',
-            note: note ?? '',
-            runtime_state: runtimeState,
-            runtime_revision: revision,
-        });
-        const message = stateMessage(candidate);
-        const attributes = notificationAttributes(candidate);
-        const historical = watchers.map((watcher) => {
-            const operation = `runtime-state:${id}`;
-            const requestDigest = digest(`${id}\0${watcher}\0${revision}`);
-            const payloadHash = digest(`${operation}\0${requestDigest}\0${message}\0${JSON.stringify(attributes)}`);
-            const prior = sentDispatchReceipt(watcher, operation, requestDigest);
-            if (prior && prior.payloadHash !== payloadHash)
-                throw new RuntimeSessionConflict(`runtime revision ${revision} notification is already bound to different bytes`);
-            return { watcher, operation, requestDigest, payloadHash, prior };
-        });
-        const historicalReplay = !sameRevision && historical.length > 0 && historical.every(({ prior }) => prior);
-        const replayed = sameRevision || historicalReplay;
-        if (!sameRevision) {
-            if (!historicalReplay) {
-                writeRaw({
-                    ...raw,
-                    status: input.lifecycle,
-                    proposal: proposal ?? '',
-                    note: note ?? '',
-                    runtime_state: runtimeState,
-                    runtime_revision: revision,
-                });
-                recordStatus(id, input.lifecycle, proposal, note);
-            }
-        }
-        const notified = [];
-        for (const { watcher, operation, requestDigest, payloadHash, prior } of historical) {
-            const receipt = {
-                operation,
-                requestDigest,
-                payloadHash,
-                delivery: { text: message, from: id, attributes },
-            };
-            if (prior) {
-                if (!prior.delivered)
-                    ensurePendingWhileLocked(watcher, pendingFor(receipt, prior.mid));
-            }
-            else {
-                const { mid } = appendSent(watcher, message, id, undefined, receipt);
-                enqueue(watcher, pendingFor(receipt, mid));
-            }
-            notified.push(watcher);
-        }
-        const entries = readWatches(id);
-        if (entries.some((entry) => entry.snapshotPending)) {
-            writeWatches(id, entries.map(({ snapshotPending: _pending, ...entry }) => entry));
-        }
-        return { notified, replayed };
-    }));
-}
-export function readRuntimeSession(sessionId) {
-    const raw = readRaw(scalar(sessionId, 'sessionId'));
-    return raw?.runtime_owner ? runtimeRecord(raw) : null;
-}
-export function runtimeSessionChildren(parentSessionId, runtimeOwner) {
-    const parent = scalar(parentSessionId, 'parentSessionId');
-    return listSessionIds().flatMap((id) => {
-        const record = readRuntimeSession(id);
-        if (!record || record.parentSessionId !== parent || (runtimeOwner && record.runtimeOwner !== runtimeOwner))
-            return [];
-        return [record];
-    }).sort((left, right) => left.createdAt - right.createdAt || left.sessionId.localeCompare(right.sessionId));
-}

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

@@ -1,14 +0,0 @@
-import type { TimelineEvent } from './session-timeline.js';
-export type Cursors = {
-    version: 1;
-    follows: Record<string, number>;
-};
-export declare function readCursors(id: string): Cursors;
-export declare const followCursor: (id: string, target: string) => number | null;
-export declare function advanceFollow(id: string, target: string, to: number): void;
-export declare const followedSessions: (id: string) => string[];
-export declare function unreadSince(events: TimelineEvent[], from: number): {
-    events: TimelineEvent[];
-    at: number[];
-    next: number;
-};

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

@@ -1,82 +0,0 @@
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { sessionArtifactPath, sessionStoreDir } from '@spexcode/spec-core';
-const cursorsPath = (id) => sessionArtifactPath(id, 'cursors.json');
-const at = (v) => (typeof v === 'number' && Number.isFinite(v) && v > 0 ? Math.floor(v) : 0);
-// Never throws: a missing, empty, or unparseable file reads as "nothing consumed", because re-showing a
-// message is the honest recovery for a lost position and skipping one is not. Followed entries whose target
-// store dir is gone are dropped here — expiry is this read, and the next write persists it.
-export function readCursors(id) {
-    let raw = null;
-    try {
-        raw = JSON.parse(readFileSync(cursorsPath(id), 'utf8'));
-    }
-    catch { /* no cursors yet */ }
-    const follows = {};
-    const stored = raw?.follows;
-    if (stored && typeof stored === 'object') {
-        for (const [target, pos] of Object.entries(stored)) {
-            if (!target || !existsSync(sessionStoreDir(target)))
-                continue;
-            follows[target] = at(pos);
-        }
-    }
-    return { version: 1, follows };
-}
-// Written whole and atomically, one field per line — the same shape as the session record, so a position stays
-// readable by an exact whole-line match where a value regex would not be.
-function writeCursors(id, cursors) {
-    const dir = sessionStoreDir(id);
-    mkdirSync(dir, { recursive: true });
-    const tmp = join(dir, `.cursors.json.${process.pid}.tmp`);
-    writeFileSync(tmp, JSON.stringify(cursors, null, 2) + '\n');
-    renameSync(tmp, cursorsPath(id));
-}
-export const followCursor = (id, target) => {
-    const stored = readCursors(id).follows[target];
-    return stored === undefined ? null : stored;
-};
-// Start or advance a follow. Following IS this entry existing, so the first call registers the relationship.
-// Monotonic: a stale read can leave a position too low (an event read twice), never too high (one lost).
-export function advanceFollow(id, target, to) {
-    const cursors = readCursors(id);
-    const stored = cursors.follows[target];
-    if (stored !== undefined && to <= stored)
-        return;
-    writeCursors(id, { ...cursors, follows: { ...cursors.follows, [target]: Math.max(0, Math.floor(to)) } });
-}
-export const followedSessions = (id) => Object.keys(readCursors(id).follows);
-const sameStatus = (a, b) => a.kind === 'status' && b.kind === 'status' && a.status === b.status
-    && (a.proposal ?? null) === (b.proposal ?? null) && (a.note ?? null) === (b.note ?? null);
-// @@@ edges, not lines - what a reader has not yet seen, with repeated status lines dropped. X→X IS NOT A
-// TRANSITION: the log is append-only and already holds runs of identical status lines from before the
-// timeline observer was deleted (every stray `spex serve` process ran an fs.watch over the same store and
-// re-recorded each real move, so ONE transition landed as up to 6 lines within ~200ms). Those bytes are
-// history and stay. Any consumer that decides "did it move?" must therefore compare VALUES, never adjacency,
-// and must compare against the last status the reader ALREADY saw — otherwise a duplicate straddling the
-// cursor boundary reads as a fresh move on the very next tick. `next` is where the cursor goes after consuming
-// the WHOLE slice: the full length, because a dropped duplicate is still consumed. `at[i]` is the absolute
-// index of `events[i]`, which is what lets a reader that STOPS on one event ([[session-follow]]'s take-one
-// wait) advance to exactly `at[i] + 1` and leave the lines behind it unread for the next reader.
-export function unreadSince(events, from) {
-    const start = Math.min(Math.max(0, Math.floor(from)), events.length);
-    let prev = null;
-    for (let i = start - 1; i >= 0; i--)
-        if (events[i].kind === 'status') {
-            prev = events[i];
-            break;
-        }
-    const out = [];
-    const at = [];
-    for (let i = start; i < events.length; i++) {
-        const e = events[i];
-        if (e.kind === 'status') {
-            if (prev && sameStatus(prev, e))
-                continue;
-            prev = e;
-        }
-        out.push(e);
-        at.push(i);
-    }
-    return { events: out, at, next: events.length };
-}

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

@@ -1,47 +0,0 @@
-import type { SessionLifecycle, SessionProposal } from '@spexcode/spec-core';
-export type TimelineEvent = {
-    ts: string;
-    kind: 'status';
-    status: SessionLifecycle;
-    proposal: SessionProposal | null;
-    note: string | null;
-    display?: string;
-} | {
-    ts: string;
-    kind: 'sent';
-    mid: string;
-    text: string;
-    from: string | null;
-    replyVia?: 'note';
-};
-export type SentDispatchReceipt = {
-    operation: string;
-    requestDigest: string;
-    payloadHash: string;
-    delivery?: {
-        text: string;
-        from: string | null;
-        attributes?: Record<string, string>;
-    };
-};
-export declare function recordStatus(id: string, status: SessionLifecycle, proposal: SessionProposal | null, note: string | null): void;
-export declare function appendSent(id: string, text: string, from: string | null, replyVia?: 'note', dispatchReceipt?: SentDispatchReceipt): {
-    mid: string;
-};
-export type SentDispatchState = {
-    mid: string;
-    payloadHash: string;
-    delivery: SentDispatchReceipt['delivery'] | null;
-    delivered: boolean;
-};
-export declare function sentDispatchReceipt(id: string, operation: SentDispatchReceipt['operation'], requestDigest: string): SentDispatchState | null;
-export declare function settleSentDispatch(id: string, mid: string): void;
-export declare function timelineEvents(id: string): TimelineEvent[];
-export declare function timelineStamp(id: string): string | null;
-export declare function lastHumanSendVia(id: string): 'note' | null;
-export type SessionTurn = Readonly<{
-    token: string;
-    acceptedAt: string;
-}>;
-export declare function currentHumanTurn(id: string): SessionTurn | null;
-export declare function timelineTail(id: string, limit?: number): TimelineEvent[];