@pentoshi/clai 3.11.7 → 3.11.9

package/dist/interactive-session/recovery-journal.js

@@ -0,0 +1,167 @@
+/**
+ * Crash-recovery journal for live interactive sessions.
+ *
+ * Interactive sessions are never reattachable: this file exists only so a crash
+ * cannot leave an orphaned process tree behind. It therefore stores cleanup
+ * evidence and nothing else — no command, cwd, input, environment, or output.
+ */
+import { createHash, randomUUID } from "node:crypto";
+import { mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+import { getDataDir } from "../store/paths.js";
+import { processIdentityTracker, } from "../os/process-identity.js";
+import { terminateProcessTree, } from "../os/process-tree.js";
+const JOURNAL_FILE = "registry-v1.json";
+const JOURNAL_PREFIX = "registry-v1-";
+const SCHEMA_VERSION = 1;
+const DEFAULT_DIRECTORY = join(getDataDir(), "interactive-sessions");
+export function hashOwner(ownerId) {
+    return createHash("sha256").update(ownerId).digest("hex").slice(0, 16);
+}
+const defaultProcessDeps = {
+    compareIdentity: (pid, identity) => processIdentityTracker.compare(pid, identity),
+    terminateTree: terminateProcessTree,
+};
+export class RecoveryJournal {
+    directory;
+    path;
+    process;
+    sharedDirectory;
+    manager;
+    records = new Map();
+    constructor(directory = DEFAULT_DIRECTORY, processDeps = {}) {
+        this.directory = directory;
+        this.sharedDirectory = directory === DEFAULT_DIRECTORY;
+        this.manager = this.sharedDirectory
+            ? {
+                pid: process.pid,
+                identity: processIdentityTracker.capture(process.pid, {
+                    refresh: true,
+                }),
+            }
+            : undefined;
+        this.path = this.sharedDirectory
+            ? join(this.directory, `${JOURNAL_PREFIX}${process.pid}-${randomUUID()}.json`)
+            : join(this.directory, JOURNAL_FILE);
+        this.process = { ...defaultProcessDeps, ...processDeps };
+    }
+    upsert(record) {
+        this.records.set(record.id, record);
+        this.persist();
+    }
+    upsertDurable(record) {
+        this.records.set(record.id, record);
+        return this.persist();
+    }
+    remove(id) {
+        if (!this.records.delete(id))
+            return;
+        this.persist();
+    }
+    load() {
+        return this.readPersisted(this.path)?.sessions ?? [];
+    }
+    reconcile() {
+        const results = [];
+        for (const path of this.reconciliationPaths()) {
+            const persisted = this.readPersisted(path);
+            if (!persisted)
+                continue;
+            if (persisted.manager) {
+                const managerState = this.process.compareIdentity(persisted.manager.pid, persisted.manager.identity);
+                if (managerState === "match" || managerState === "unknown")
+                    continue;
+            }
+            const retained = [];
+            for (const record of persisted.sessions) {
+                const outcome = this.reconcileOne(record);
+                results.push({ id: record.id, outcome });
+                if (outcome === "unverified")
+                    retained.push(record);
+            }
+            this.writePersisted(path, persisted.manager, retained);
+        }
+        this.records = new Map(this.load().map((record) => [record.id, record]));
+        return results;
+    }
+    reconciliationPaths() {
+        if (!this.sharedDirectory)
+            return [this.path];
+        try {
+            return readdirSync(this.directory, { withFileTypes: true })
+                .filter((entry) => entry.isFile() &&
+                (entry.name === JOURNAL_FILE ||
+                    (entry.name.startsWith(JOURNAL_PREFIX) &&
+                        entry.name.endsWith(".json"))))
+                .map((entry) => join(this.directory, entry.name));
+        }
+        catch {
+            return [];
+        }
+    }
+    readPersisted(path) {
+        try {
+            const parsed = JSON.parse(readFileSync(path, "utf8"));
+            if (parsed?.schemaVersion !== SCHEMA_VERSION ||
+                !Array.isArray(parsed.sessions)) {
+                return undefined;
+            }
+            return parsed;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    reconcileOne(record) {
+        if (!record.launchConfirmed || !record.pid)
+            return "unverified";
+        const comparison = this.process.compareIdentity(record.pid, record.identity);
+        if (comparison === "gone")
+            return "gone";
+        if (comparison === "mismatch")
+            return "identity-mismatch";
+        if (comparison === "unknown")
+            return "unverified";
+        const outcome = this.process.terminateTree(record.pid, {
+            signal: "SIGKILL",
+            ...(record.processGroupId !== undefined
+                ? { processGroupId: record.processGroupId }
+                : {}),
+        });
+        if (outcome === "failed")
+            return "unverified";
+        return outcome === "gone" ? "gone" : "terminated";
+    }
+    persist() {
+        return this.writePersisted(this.path, this.manager, [...this.records.values()]);
+    }
+    writePersisted(path, manager, sessions) {
+        try {
+            if (sessions.length === 0) {
+                rmSync(path, { force: true });
+                return true;
+            }
+            mkdirSync(this.directory, { recursive: true, mode: 0o700 });
+            const payload = {
+                schemaVersion: SCHEMA_VERSION,
+                ...(manager ? { manager } : {}),
+                sessions,
+            };
+            const temp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+            writeFileSync(temp, `${JSON.stringify(payload)}\n`, { mode: 0o600 });
+            renameSync(temp, path);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    clear() {
+        this.records.clear();
+        try {
+            rmSync(this.path, { force: true });
+        }
+        catch { }
+    }
+}
+//# sourceMappingURL=recovery-journal.js.map

package/dist/interactive-session/recovery-journal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery-journal.js","sourceRoot":"","sources":["../../src/interactive-session/recovery-journal.ts"],"names":[],"mappings":"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"}

package/dist/interactive-session/registry.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Owner-scoped registry for interactive sessions.
+ *
+ * Records carry no command, input, environment value, prompt, or output — only
+ * opaque identity, state, cursors, and outcome metadata. Interactive records are
+ * intentionally separate from `JobManager` records: the two domains have
+ * different ownership, policy, and cleanup contracts.
+ */
+import { type InteractiveSessionRecord, type ProcessOutcome, type SessionState, type SessionSummary, type TerminationReason } from "./types.js";
+export declare function canTransition(from: SessionState, to: SessionState): boolean;
+export declare class SessionRegistry {
+    private readonly records;
+    private readonly byOwner;
+    /** Process-lifetime issued ids: never reused, even after removal. */
+    private readonly issuedIds;
+    private readonly ownerLocks;
+    private readonly fencedOwners;
+    /**
+     * Serialize id issuance and live-slot reservation for one owner so two
+     * concurrent starts cannot both pass the live limit.
+     */
+    withOwnerLock<T>(ownerId: string, fn: () => Promise<T> | T): Promise<T>;
+    mintId(): string;
+    liveCount(ownerId: string): number;
+    insert(record: InteractiveSessionRecord): void;
+    /**
+     * Owner mismatch is indistinguishable from a missing id: callers must not be
+     * able to use this lookup as an existence oracle for another conversation.
+     */
+    get(ownerId: string, id: string): InteractiveSessionRecord | undefined;
+    /** Unscoped access for cleanup/lifecycle paths that already own the record. */
+    getUnscoped(id: string): InteractiveSessionRecord | undefined;
+    liveRecords(ownerId: string): InteractiveSessionRecord[];
+    allLiveRecords(): InteractiveSessionRecord[];
+    owners(): string[];
+    /** Live first, then descending start time, capped for model consumption. */
+    list(ownerId: string): SessionSummary[];
+    /**
+     * Compare-and-transition. Returns false when the transition is not allowed,
+     * which is how a late exit observation loses to a committed terminal state.
+     */
+    transition(record: InteractiveSessionRecord, to: SessionState, patch?: {
+        terminationReason?: TerminationReason | undefined;
+        processOutcome?: ProcessOutcome | undefined;
+        cleanupVerified?: boolean | undefined;
+        now?: number | undefined;
+    }): boolean;
+    /** Add outcome facts without replacing a chosen terminal state. */
+    enrich(record: InteractiveSessionRecord, patch: {
+        terminationReason?: TerminationReason | undefined;
+        processOutcome?: ProcessOutcome | undefined;
+        cleanupVerified?: boolean | undefined;
+    }): void;
+    /** Fence an owner before its id is rebound so no new operation can enter. */
+    fenceOwner(ownerId: string): void;
+    unfenceOwner(ownerId: string): void;
+    isFenced(ownerId: string): boolean;
+    private pruneTerminal;
+}

package/dist/interactive-session/registry.js

@@ -0,0 +1,170 @@
+/**
+ * Owner-scoped registry for interactive sessions.
+ *
+ * Records carry no command, input, environment value, prompt, or output — only
+ * opaque identity, state, cursors, and outcome metadata. Interactive records are
+ * intentionally separate from `JobManager` records: the two domains have
+ * different ownership, policy, and cleanup contracts.
+ */
+import { randomUUID } from "node:crypto";
+import { MAX_LIST_SUMMARIES } from "./config.js";
+import { AsyncMutex } from "./runtime.js";
+import { isTerminalState, toSummary, } from "./types.js";
+const SESSION_ID_PREFIX = "its_";
+/** Terminal summaries retained per owner; live records are never evicted. */
+const MAX_TERMINAL_RECORDS_PER_OWNER = MAX_LIST_SUMMARIES;
+const ALLOWED_TRANSITIONS = {
+    starting: ["running", "exited", "failed"],
+    running: ["closing", "exited", "failed"],
+    closing: ["closed", "exited", "failed"],
+    exited: [],
+    failed: [],
+    closed: [],
+};
+export function canTransition(from, to) {
+    return ALLOWED_TRANSITIONS[from].includes(to);
+}
+export class SessionRegistry {
+    records = new Map();
+    byOwner = new Map();
+    /** Process-lifetime issued ids: never reused, even after removal. */
+    issuedIds = new Set();
+    ownerLocks = new Map();
+    fencedOwners = new Set();
+    /**
+     * Serialize id issuance and live-slot reservation for one owner so two
+     * concurrent starts cannot both pass the live limit.
+     */
+    withOwnerLock(ownerId, fn) {
+        let lock = this.ownerLocks.get(ownerId);
+        if (!lock) {
+            lock = new AsyncMutex();
+            this.ownerLocks.set(ownerId, lock);
+        }
+        return lock.run(fn);
+    }
+    mintId() {
+        for (;;) {
+            const candidate = `${SESSION_ID_PREFIX}${randomUUID()}`;
+            if (this.issuedIds.has(candidate))
+                continue;
+            this.issuedIds.add(candidate);
+            return candidate;
+        }
+    }
+    liveCount(ownerId) {
+        let count = 0;
+        for (const id of this.byOwner.get(ownerId) ?? []) {
+            const record = this.records.get(id);
+            if (record && !isTerminalState(record.state))
+                count += 1;
+        }
+        return count;
+    }
+    insert(record) {
+        this.records.set(record.id, record);
+        let owned = this.byOwner.get(record.ownerId);
+        if (!owned) {
+            owned = new Set();
+            this.byOwner.set(record.ownerId, owned);
+        }
+        owned.add(record.id);
+    }
+    /**
+     * Owner mismatch is indistinguishable from a missing id: callers must not be
+     * able to use this lookup as an existence oracle for another conversation.
+     */
+    get(ownerId, id) {
+        const record = this.records.get(id);
+        return record && record.ownerId === ownerId ? record : undefined;
+    }
+    /** Unscoped access for cleanup/lifecycle paths that already own the record. */
+    getUnscoped(id) {
+        return this.records.get(id);
+    }
+    liveRecords(ownerId) {
+        return [...(this.byOwner.get(ownerId) ?? [])]
+            .map((id) => this.records.get(id))
+            .filter((record) => record !== undefined && !isTerminalState(record.state));
+    }
+    allLiveRecords() {
+        return [...this.records.values()].filter((record) => !isTerminalState(record.state));
+    }
+    owners() {
+        return [...this.byOwner.keys()];
+    }
+    /** Live first, then descending start time, capped for model consumption. */
+    list(ownerId) {
+        const records = [...(this.byOwner.get(ownerId) ?? [])]
+            .map((id) => this.records.get(id))
+            .filter((record) => record !== undefined);
+        records.sort((a, b) => {
+            const aLive = isTerminalState(a.state) ? 1 : 0;
+            const bLive = isTerminalState(b.state) ? 1 : 0;
+            if (aLive !== bLive)
+                return aLive - bLive;
+            return b.startedAt - a.startedAt;
+        });
+        return records.slice(0, MAX_LIST_SUMMARIES).map(toSummary);
+    }
+    /**
+     * Compare-and-transition. Returns false when the transition is not allowed,
+     * which is how a late exit observation loses to a committed terminal state.
+     */
+    transition(record, to, patch = {}) {
+        if (!canTransition(record.state, to)) {
+            // A terminal record may still be enriched with late outcome metadata.
+            if (isTerminalState(record.state))
+                this.enrich(record, patch);
+            return false;
+        }
+        record.state = to;
+        if (isTerminalState(to)) {
+            record.endedAt = patch.now ?? record.endedAt ?? Date.now();
+            if (patch.terminationReason)
+                record.terminationReason = patch.terminationReason;
+            if (patch.processOutcome)
+                record.processOutcome = patch.processOutcome;
+            if (patch.cleanupVerified !== undefined) {
+                record.cleanupVerified = patch.cleanupVerified;
+            }
+            this.pruneTerminal(record.ownerId);
+        }
+        else {
+            this.enrich(record, patch);
+        }
+        return true;
+    }
+    /** Add outcome facts without replacing a chosen terminal state. */
+    enrich(record, patch) {
+        record.terminationReason ??= patch.terminationReason;
+        record.processOutcome ??= patch.processOutcome;
+        if (record.cleanupVerified === undefined && patch.cleanupVerified !== undefined) {
+            record.cleanupVerified = patch.cleanupVerified;
+        }
+    }
+    /** Fence an owner before its id is rebound so no new operation can enter. */
+    fenceOwner(ownerId) {
+        this.fencedOwners.add(ownerId);
+    }
+    unfenceOwner(ownerId) {
+        this.fencedOwners.delete(ownerId);
+    }
+    isFenced(ownerId) {
+        return this.fencedOwners.has(ownerId);
+    }
+    pruneTerminal(ownerId) {
+        const owned = this.byOwner.get(ownerId);
+        if (!owned)
+            return;
+        const terminal = [...owned]
+            .map((id) => this.records.get(id))
+            .filter((record) => record !== undefined && isTerminalState(record.state))
+            .sort((a, b) => (b.endedAt ?? b.startedAt) - (a.endedAt ?? a.startedAt));
+        for (const record of terminal.slice(MAX_TERMINAL_RECORDS_PER_OWNER)) {
+            this.records.delete(record.id);
+            owned.delete(record.id);
+        }
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/interactive-session/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/interactive-session/registry.ts"],"names":[],"mappings":"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"}

package/dist/interactive-session/runtime.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Per-session concurrency primitives.
+ *
+ * The locking model is deliberately fine-grained: one owner-level mutex guards
+ * id issuance and live-slot reservation, one mutation mutex per session guards
+ * state/input/resize decisions, and output ingestion never takes either lock so
+ * a chatty child cannot block Close.
+ */
+/** Monotonic time source. Wall time is only used for receipts, never deadlines. */
+export interface Clock {
+    now(): number;
+    setTimeout(handler: () => void, ms: number): TimerHandle;
+    clearTimeout(handle: TimerHandle): void;
+}
+export type TimerHandle = {
+    readonly id: unknown;
+};
+export declare const systemClock: Clock;
+export declare class AsyncMutex {
+    private tail;
+    /** Serialize `fn`; rejections do not poison the queue. */
+    run<T>(fn: () => Promise<T> | T): Promise<T>;
+}
+/**
+ * Single-winner terminal work. Every later caller joins the first promise, so
+ * cleanup executes exactly once no matter how many triggers race.
+ */
+export declare class FinalizeOnce<T> {
+    private promise;
+    private winnerReason;
+    get started(): boolean;
+    /** The reason that won the race, useful for choosing a terminal state. */
+    get reason(): string | undefined;
+    run(reason: string, fn: () => Promise<T>): Promise<T>;
+    join(): Promise<T> | undefined;
+}
+export type Unsubscribe = () => void;
+/** Version-counter subscription used by blocking reads and send gathering. */
+export declare class Notifier {
+    private version;
+    private readonly listeners;
+    get current(): number;
+    bump(): void;
+    subscribe(listener: (version: number) => void): Unsubscribe;
+    clear(): void;
+}
+export interface SessionTimers {
+    idle?: TimerHandle | undefined;
+    lifetime?: TimerHandle | undefined;
+}
+/** Idle resets on activity; lifetime is fixed from confirmed launch. */
+export declare class TimerSet {
+    private readonly clock;
+    private readonly onExpire;
+    private readonly timers;
+    constructor(clock: Clock, onExpire: (reason: "idle-timeout" | "lifetime-timeout") => void);
+    armIdle(ms: number | undefined): void;
+    armLifetime(ms: number | undefined): void;
+    clearAll(): void;
+}
+/** Resolve/reject handle for one in-flight wait, removable on cancel. */
+export interface Waiter {
+    cancel(): void;
+}
+export declare class WaiterSet {
+    private readonly waiters;
+    add(waiter: Waiter): Unsubscribe;
+    cancelAll(): void;
+    get size(): number;
+}
+/**
+ * One accepted input action. Immutable once queued: the payload is never
+ * rewritten, and delivery is attempted exactly once.
+ */
+export interface QueuedInputAction {
+    readonly sequence: number;
+    readonly queuedBytes: number;
+    /** Cursor captured when the action was accepted, used as the default page start. */
+    readonly cursorAtAcceptance: number;
+    readonly deliver: () => Promise<InputDeliveryOutcome>;
+    readonly settle: (outcome: InputDeliveryOutcome) => void;
+}
+export interface InputDeliveryOutcome {
+    readonly status: "delivered" | "not-delivered" | "unknown";
+    readonly deliveredBytes: number;
+    readonly cause?: unknown;
+}
+/**
+ * FIFO writer lane. Accepted actions are written strictly in ascending sequence
+ * order by a single drain loop, so concurrent sends can never interleave bytes
+ * or reorder commands.
+ */
+export declare class OrderedInputQueue {
+    private readonly queue;
+    private draining;
+    private nextSequence;
+    private queuedBytes;
+    get depth(): number;
+    get pendingBytes(): number;
+    peekSequence(): number;
+    /** Reserve a sequence number and queued-byte budget for one action. */
+    reserve(bytes: number): number;
+    enqueue(action: QueuedInputAction): void;
+    private drain;
+    /** Reject every undelivered entry, e.g. after process exit or close. */
+    rejectAll(outcome: InputDeliveryOutcome): void;
+}