@raidiant/notifai 11.4.0-beta.2 → 11.4.0

package/dist/session-attendant-state.js

@@ -0,0 +1,175 @@
+/** Local files of the Session Attendant: its exclusive claim and its readable status. */
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { atomicWriteFileSync } from './atomic-file.js';
+import { sanitizeSessionId, stateDir } from './config.js';
+import { withFileLock } from './file-lock.js';
+import { claimHolderMayRun, readClaimFile } from './hook-question-lock.js';
+/** One live attendant per Agent Session: PID + process start time + incarnation. */
+export function attendantClaimPath(sessionId, env) {
+    return path.join(stateDir(env), 'sessions', `${sanitizeSessionId(sessionId)}.attendant`);
+}
+export function attendantStatusPath(sessionId, env) {
+    return path.join(stateDir(env), 'sessions', `${sanitizeSessionId(sessionId)}.attendance.json`);
+}
+export function writeAttendantStatus(sessionId, env, status) {
+    atomicWriteFileSync(attendantStatusPath(sessionId, env), `${JSON.stringify({ session_id: sessionId, pid: process.pid, ...status })}\n`);
+}
+const PHASES = new Set([
+    'dormant',
+    'unsupported',
+    'acquiring',
+    'attending',
+    'waiting-for-lease',
+    'uncertain',
+    'exited',
+]);
+/**
+ * Every attendant status on this machine, newest first. An attendant whose
+ * process is gone without writing `exited` is reported as not alive.
+ */
+export function listAttendantReports(env) {
+    const directory = path.join(stateDir(env), 'sessions');
+    if (!existsSync(directory))
+        return [];
+    const reports = [];
+    for (const name of readdirSync(directory)) {
+        if (!name.endsWith('.attendance.json'))
+            continue;
+        try {
+            const parsed = JSON.parse(readFileSync(path.join(directory, name), 'utf8'));
+            const sessionId = parsed['session_id'];
+            const phase = parsed['phase'];
+            if (typeof sessionId !== 'string' || typeof phase !== 'string' || !PHASES.has(phase))
+                continue;
+            const claim = readClaimFile(attendantClaimPath(sessionId, env));
+            const alive = phase !== 'exited' && claim !== null && claim['pid'] === parsed['pid'] && claimHolderMayRun(claim);
+            reports.push({
+                session_id: sessionId,
+                phase: phase,
+                alive,
+                generation: typeof parsed['generation'] === 'number' ? parsed['generation'] : null,
+                activity: typeof parsed['activity'] === 'string' ? parsed['activity'] : null,
+                reason: typeof parsed['reason'] === 'string' ? parsed['reason'] : null,
+                accepts_messages: parsed['accepts_messages'] === true,
+                updated_at: typeof parsed['updated_at'] === 'number' ? parsed['updated_at'] : 0,
+            });
+        }
+        catch {
+            // A half-written or foreign file is not an attendant.
+        }
+    }
+    return reports.sort((a, b) => b.updated_at - a.updated_at);
+}
+/**
+ * The lease a writer beside the attendant (the answer waiter) may claim under:
+ * the generation the live attendant of this session holds right now, or null.
+ * The service still decides; a stale read is refused as `generation_fenced`.
+ */
+export function readAttendantLease(sessionId, env) {
+    try {
+        const status = JSON.parse(readFileSync(attendantStatusPath(sessionId, env), 'utf8'));
+        const generation = status['generation'];
+        const incarnation = status['incarnation'];
+        if (status['phase'] !== 'attending' ||
+            typeof generation !== 'number' ||
+            !Number.isInteger(generation) ||
+            generation < 1 ||
+            typeof incarnation !== 'string') {
+            return null;
+        }
+        const claim = readClaimFile(attendantClaimPath(sessionId, env));
+        if (claim === null || claim['pid'] !== status['pid'] || !claimHolderMayRun(claim))
+            return null;
+        return { incarnation, generation };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The lease a live attendant of this session holds in any phase short of
+ * exiting, for the one writer that ends it on the attendant's behalf: Codex's
+ * SessionEnd, after which Codex kills the attendant before it can report.
+ */
+export function readAttendantHeldLease(sessionId, env) {
+    try {
+        const status = JSON.parse(readFileSync(attendantStatusPath(sessionId, env), 'utf8'));
+        const generation = status['generation'];
+        const incarnation = status['incarnation'];
+        if (status['phase'] === 'exited' ||
+            typeof generation !== 'number' ||
+            !Number.isInteger(generation) ||
+            generation < 1 ||
+            typeof incarnation !== 'string') {
+            return null;
+        }
+        const claim = readClaimFile(attendantClaimPath(sessionId, env));
+        if (claim === null || claim['pid'] !== status['pid'] || !claimHolderMayRun(claim))
+            return null;
+        return { incarnation, generation };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * A thread's own turn boundaries, for a harness that publishes no activity of
+ * its own (Codex), scoped to one session incarnation (its stable start key).
+ *
+ * Starts are recorded by the synchronous prompt hook, which Codex runs before
+ * each turn and one turn at a time, so recorded starts keep the thread's own
+ * order. Ends come from asynchronous hooks (Stop, Interrupt) that may run late
+ * or before the start they close, so they are matched by turn id. A start of a
+ * turn already seen — started or ended — is stale and never replaces the
+ * current turn. The thread is working while its current turn has no end.
+ */
+export function turnActivityPath(sessionId, env) {
+    return path.join(stateDir(env), 'sessions', `${sanitizeSessionId(sessionId)}.turns.json`);
+}
+/** Turn ids kept to recognise a late hook; a late hook trails its turn by seconds. */
+const TURNS_KEPT = 32;
+function readTurns(file) {
+    const ids = (value) => Array.isArray(value) ? value.filter((turn) => typeof turn === 'string') : [];
+    try {
+        const parsed = JSON.parse(readFileSync(file, 'utf8'));
+        return {
+            key: typeof parsed['key'] === 'string' ? parsed['key'] : null,
+            current: typeof parsed['current'] === 'string' ? parsed['current'] : null,
+            started: ids(parsed['started']),
+            ended: ids(parsed['ended']),
+        };
+    }
+    catch {
+        return { key: null, current: null, started: [], ended: [] };
+    }
+}
+function updateTurns(sessionId, env, update) {
+    const file = turnActivityPath(sessionId, env);
+    withFileLock(`${file}.lock`, () => {
+        const next = update(readTurns(file));
+        atomicWriteFileSync(file, `${JSON.stringify({ session_id: sessionId, ...next })}\n`);
+    }, 
+    // The prompt hook runs in front of the User's turn; activity is only a hint.
+    { waitMs: 500 });
+}
+const keep = (ids, id) => [...ids.filter((turn) => turn !== id), id].slice(-TURNS_KEPT);
+/** A turn of incarnation `key` started. Ignored when that turn was already seen. */
+export function recordTurnStart(sessionId, env, key, turnId) {
+    updateTurns(sessionId, env, (record) => {
+        const same = record.key === key ? record : { key, current: null, started: [], ended: record.ended };
+        if (same.started.includes(turnId) || same.ended.includes(turnId))
+            return same;
+        return { ...same, current: turnId, started: keep(same.started, turnId) };
+    });
+}
+/** A turn ended (or was interrupted), whenever its hook got to run. */
+export function recordTurnEnd(sessionId, env, turnId) {
+    updateTurns(sessionId, env, (record) => ({ ...record, ended: keep(record.ended, turnId) }));
+}
+/** Working while incarnation `key`'s current turn has no recorded end. */
+export function readTurnActivity(sessionId, env, key) {
+    const { key: recorded, current, ended } = readTurns(turnActivityPath(sessionId, env));
+    return recorded === key && current !== null && !ended.includes(current) ? 'working' : 'idle';
+}
+//# sourceMappingURL=session-attendant-state.js.map

package/dist/session-attendant-state.js.map

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

package/dist/session-attendant.d.ts

@@ -0,0 +1,135 @@
+/**
+ * The Session Attendant: one long-lived CLI process per Agent Session.
+ *
+ * It starts as that session's own asynchronous hook child, proves the harness
+ * process alive every two seconds by local evidence only, and holds the
+ * session's Session Presence lease with the service. It is resident from its
+ * start but makes no network call until the session had a Notification
+ * Request accepted, so sessions that never notified are never reported.
+ *
+ * Nothing ends it from outside. Claude Code neither signals nor waits for a
+ * resident async hook on `/exit` or when the harness is killed, so the local
+ * probe is the one universal end signal; SessionEnd's marker is a fast path,
+ * and a SIGTERM (terminal close) is treated as "ending, report once".
+ *
+ * Local only: PIDs, process start times, descriptor paths, and harness homes
+ * never leave this machine. The service sees an opaque incarnation id.
+ */
+import type { AttendanceMessage, SessionActivity } from '@raidiant/notifai-protocol';
+import { type ApiClient } from './client.js';
+import type { Logger } from './logging.js';
+/** Local probe cadence. */
+export declare const ATTENDANT_PROBE_INTERVAL_MS = 2000;
+/** Harness writes stop this long before the lease ends by the attendant's own clock. */
+export declare const ATTENDANT_WRITE_MARGIN_MS = 15000;
+/** A wall-clock move this far from the monotonic clock means sleep or a clock jump. */
+export declare const ATTENDANT_CLOCK_JUMP_MS = 5000;
+/** Best-effort bound on the final `ended` or `withdrawn` report. */
+export declare const ATTENDANT_FINAL_REPORT_MS = 3000;
+/** How often an unsupported service is asked again. */
+export declare const ATTENDANT_UNSUPPORTED_RECHECK_MS: number;
+/** How long to wait before asking again about a session the service does not know yet. */
+export declare const ATTENDANT_UNKNOWN_SESSION_RETRY_MS = 60000;
+/** First pause before re-asking for a message that waits on something brief; doubles to the hold. */
+export declare const ATTENDANT_MESSAGE_RETRY_MS = 2000;
+export type HarnessProbe = {
+    state: 'running';
+    activity: SessionActivity;
+}
+/** Evidence is missing or ambiguous: no renewal, no deliveries, never `running`. */
+ | {
+    state: 'uncertain';
+    reason: string;
+} | {
+    state: 'ended';
+    reason: 'harness-gone' | 'session-replaced' | 'session-end-hook';
+};
+export type GateResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+export type AttendantPhase = 
+/** Resident, no network: the session has not notified yet. */
+'dormant'
+/** The service does not offer Session Attendance; resident without reporting. */
+ | 'unsupported' | 'acquiring' | 'attending'
+/** Another incarnation holds the lease. */
+ | 'waiting-for-lease' | 'uncertain' | 'exited';
+export type AttendantExitReason = 'harness-gone' | 'session-replaced' | 'session-end-hook' | 'signal' | 'superseded' | 'claim-lost' | 'withdrawn-by-service' | 'unauthorized' | `gate:${string}`;
+export interface AttendantStatus {
+    phase: AttendantPhase;
+    incarnation: string;
+    generation: number | null;
+    activity: SessionActivity | null;
+    reason: string | null;
+    /** Whether this attendant hands Session Messages in, so the service accepts notes. */
+    accepts_messages: boolean;
+    updated_at: number;
+}
+export interface AttendantClock {
+    /** Monotonic milliseconds; never moves with the wall clock. */
+    monotonic(): number;
+    wall(): number;
+    sleep(milliseconds: number, signal: AbortSignal): Promise<void>;
+}
+export interface SessionAttendantOptions {
+    sessionId: string;
+    /** The opaque incarnation this attendant serves; see `incarnationNow`. */
+    incarnation: string;
+    /** The incarnation currently recorded for the session, read fresh each probe. */
+    incarnationNow(): string | null;
+    /** Replace a refused incarnation id; null when the record moved on. */
+    rotateIncarnation(expected: string): string | null;
+    probe(): HarnessProbe;
+    /** Whether this attendant still holds its exclusive local claim. */
+    claimHeld(): boolean;
+    /** Whether this session had a Notification Request accepted on this machine. */
+    notified(): boolean;
+    /** Project Enablement and the installed CLI/hook contract. */
+    gates(): GateResult;
+    /** Authenticated client, or null when this machine is not paired. */
+    client(): ApiClient | null;
+    /** Whether the service advertises Session Attendance. */
+    serverSupportsAttendance(client: ApiClient): Promise<boolean>;
+    /** Whether this attendant can hand Session Messages into the session. */
+    acceptsMessages: boolean;
+    /**
+     * Hands claimable Session Messages into the session. `retry-soon` asks for
+     * the next exchange without holding it open: a message is waiting on
+     * something that resolves in seconds.
+     */
+    onMessages?: (messages: AttendanceMessage[], attendant: AttendantHandle) => Promise<'done' | 'retry-soon'>;
+    clock: AttendantClock;
+    logger: Logger;
+    /** Persist the local status `notifai doctor` reads. */
+    writeStatus(status: AttendantStatus): void;
+    /** Periodic housekeeping (e.g. keep markers younger than pruning). */
+    heartbeat?: () => void;
+    /** Resolves when a termination signal arrived. */
+    signalled?: Promise<void>;
+    probeIntervalMs?: number;
+    waitSeconds?: number;
+}
+/** What a harness writer asks before each write. */
+export interface AttendantHandle {
+    /**
+     * True only while, right now: this attendant still owns its claim and
+     * incarnation, fresh local evidence shows the session running, every gate
+     * passes, no clock discontinuity happened since the lease was granted, and
+     * the lease cannot lapse before the write ends by the monotonic clock.
+     */
+    mayWrite(): boolean;
+    generation(): number | null;
+    incarnation(): string;
+}
+export interface AttendantResult {
+    reason: AttendantExitReason;
+    /** Whether a final report was attempted. */
+    reported: 'ended' | 'withdrawn' | null;
+}
+/** Runs one Session Attendant until its session ends or a gate fails. */
+export declare function runSessionAttendant(options: SessionAttendantOptions): Promise<AttendantResult>;
+/** Production clocks: `performance.now()` pauses with the machine; `Date.now()` does not. */
+export declare const systemAttendantClock: AttendantClock;