@raidiant/notifai 11.7.1 → 12.0.0-beta.13

package/dist/session-attendant.d.ts

@@ -1,143 +0,0 @@
-/**
- * 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;
-    /** Fresh in-process proof that a harness writer still targets this session. */
-    writer_ready?: 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;
-    /** Staged local input needs a fresh exchange rather than a quiet long-poll. */
-    localInputPending?: () => boolean;
-    /** Persist the local status `notifai doctor` reads. */
-    writeStatus(status: AttendantStatus): void;
-    /** Periodic housekeeping (e.g. keep markers younger than pruning). */
-    heartbeat?: () => void;
-    /** Harness-owned work that needs the fresh probe while attendance continues. */
-    onProbe?: (probe: HarnessProbe) => void;
-    /** Publish fresh writer evidence for ask admission. */
-    publishProbeStatus?: boolean;
-    /** 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;

package/dist/session-attendant.js

@@ -1,520 +0,0 @@
-import { ATTENDANCE_MAX_WAIT_SECONDS } from '@raidiant/notifai-protocol';
-import { ApiCallError } from './client.js';
-/** Local probe cadence. */
-export const ATTENDANT_PROBE_INTERVAL_MS = 2_000;
-/** Harness writes stop this long before the lease ends by the attendant's own clock. */
-export const ATTENDANT_WRITE_MARGIN_MS = 15_000;
-/** A wall-clock move this far from the monotonic clock means sleep or a clock jump. */
-export const ATTENDANT_CLOCK_JUMP_MS = 5_000;
-/** Best-effort bound on the final `ended` or `withdrawn` report. */
-export const ATTENDANT_FINAL_REPORT_MS = 3_000;
-/** How often an unsupported service is asked again. */
-export const ATTENDANT_UNSUPPORTED_RECHECK_MS = 30 * 60_000;
-/** How long to wait before asking again about a session the service does not know yet. */
-export const ATTENDANT_UNKNOWN_SESSION_RETRY_MS = 60_000;
-/** First pause before re-asking for a message that waits on something brief; doubles to the hold. */
-export const ATTENDANT_MESSAGE_RETRY_MS = 2_000;
-const MAX_NETWORK_BACKOFF_MS = 30_000;
-/** Runs one Session Attendant until its session ends or a gate fails. */
-export async function runSessionAttendant(options) {
-    const { clock, logger } = options;
-    const probeInterval = options.probeIntervalMs ?? ATTENDANT_PROBE_INTERVAL_MS;
-    const waitSeconds = Math.min(options.waitSeconds ?? ATTENDANCE_MAX_WAIT_SECONDS, ATTENDANCE_MAX_WAIT_SECONDS);
-    const stopping = new AbortController();
-    let incarnation = options.incarnation;
-    let generation = null;
-    let cursor;
-    /** Monotonic time after which the lease may have lapsed at the service. */
-    let leaseEndsAt = null;
-    let probe = options.probe();
-    let activity = probe.state === 'running' ? probe.activity : null;
-    let phase = 'dormant';
-    let phaseReason = null;
-    let networkStarted = false;
-    let exit = probe.state === 'ended' ? probe.reason : null;
-    let exchange = null;
-    let exchangeHeld = false;
-    let wake = null;
-    const setPhase = (next, reason = null) => {
-        if (next === phase && reason === phaseReason)
-            return;
-        phase = next;
-        phaseReason = reason;
-        logger.info('attendant.state', {
-            phase,
-            ...(reason === null ? {} : { reason }),
-            ...(generation === null ? {} : { generation }),
-        });
-        writeStatus();
-    };
-    const writeStatus = () => {
-        try {
-            options.writeStatus({
-                phase,
-                incarnation,
-                generation,
-                activity,
-                reason: phaseReason,
-                accepts_messages: options.acceptsMessages,
-                ...(options.publishProbeStatus ? { writer_ready: probe.state === 'running' } : {}),
-                updated_at: clock.wall(),
-            });
-        }
-        catch {
-            // Status is diagnostic; the attendant keeps attending without it.
-        }
-    };
-    const nudge = () => {
-        const resolve = wake;
-        wake = null;
-        resolve?.();
-    };
-    const abortExchange = () => {
-        exchange?.abort();
-    };
-    const stop = (reason) => {
-        if (exit === null)
-            exit = reason;
-        exchange?.abort();
-        stopping.abort();
-        nudge();
-    };
-    /** Bumped by every clock discontinuity; a lease granted in an older epoch is void. */
-    let epoch = 0;
-    let reacquireNow = false;
-    const loseLease = (reason) => {
-        if (leaseEndsAt !== null || generation !== null) {
-            logger.info('attendant.lease', { event: 'lost', reason, ...(generation === null ? {} : { generation }) });
-        }
-        leaseEndsAt = null;
-    };
-    let lastWall = clock.wall();
-    let lastMono = clock.monotonic();
-    /**
-     * Sleep pauses the monotonic clock while the service's lease keeps running;
-     * a wall-clock step says the same. Either way nothing may be written until
-     * a fresh exchange, sent after the jump, re-acquires.
-     */
-    const checkClock = () => {
-        const wall = clock.wall();
-        const mono = clock.monotonic();
-        const jump = Math.abs(wall - lastWall - (mono - lastMono));
-        lastWall = wall;
-        lastMono = mono;
-        if (jump > ATTENDANT_CLOCK_JUMP_MS) {
-            epoch += 1;
-            reacquireNow = true;
-            loseLease('clock-jump');
-            exchange?.abort();
-        }
-    };
-    /**
-     * Re-establish everything this attendant relies on, now: clock continuity,
-     * its claim, its incarnation, and fresh session evidence. Returns whether
-     * the session is running and this attendant may still act for it.
-     */
-    const refresh = () => {
-        if (exit !== null)
-            return false;
-        checkClock();
-        if (!options.claimHeld()) {
-            stop('claim-lost');
-            return false;
-        }
-        const recorded = options.incarnationNow();
-        if (recorded !== null && recorded !== incarnation) {
-            stop('superseded');
-            return false;
-        }
-        const previous = probe;
-        probe = options.probe();
-        if (probe.state === 'ended') {
-            stop(probe.reason);
-            return false;
-        }
-        if (probe.state === 'uncertain') {
-            if (previous.state !== 'uncertain') {
-                exchange?.abort();
-                if (networkStarted)
-                    setPhase('uncertain', probe.reason);
-            }
-            return false;
-        }
-        const changed = activity !== probe.activity;
-        activity = probe.activity;
-        if (changed) {
-            logger.info('attendant.state', { phase, activity, reason: 'activity-changed', generation });
-            writeStatus();
-        }
-        if (previous.state !== 'running' || changed) {
-            // A held exchange carries the old activity; cut it so the next one reports this.
-            exchange?.abort();
-            nudge();
-        }
-        return true;
-    };
-    const handle = {
-        mayWrite: () => {
-            if (!refresh())
-                return false;
-            const gate = options.gates();
-            if (!gate.ok) {
-                stop(`gate:${gate.reason}`);
-                return false;
-            }
-            return (generation !== null &&
-                leaseEndsAt !== null &&
-                clock.monotonic() < leaseEndsAt - ATTENDANT_WRITE_MARGIN_MS);
-        },
-        generation: () => generation,
-        incarnation: () => incarnation,
-    };
-    // -- local probe -------------------------------------------------------
-    let lastHeartbeat = lastMono;
-    const tick = () => {
-        refresh();
-        if (exit !== null)
-            return;
-        if (options.publishProbeStatus)
-            writeStatus();
-        try {
-            options.onProbe?.(probe);
-        }
-        catch (err) {
-            logger.error('attendant.state', {
-                phase, reason: 'probe-work-failed',
-                message: err instanceof Error ? err.message : String(err),
-            });
-        }
-        if (!networkStarted && options.notified())
-            nudge();
-        if (probe.state === 'running' && exchangeHeld && exchange !== null && options.localInputPending?.()) {
-            // A reply can arrive locally while attendance is holding for server notes.
-            // Refresh the lease and invoke the genuine resident writer on the next
-            // exchange, without waiting the server's entire quiet-poll interval.
-            reacquireNow = true;
-            exchange.abort();
-            nudge();
-        }
-        const mono = clock.monotonic();
-        if (mono - lastHeartbeat >= 60 * 60_000) {
-            lastHeartbeat = mono;
-            try {
-                options.heartbeat?.();
-            }
-            catch {
-                // Housekeeping only.
-            }
-        }
-    };
-    const probeLoop = (async () => {
-        while (!stopping.signal.aborted) {
-            await clock.sleep(probeInterval, stopping.signal).catch(() => undefined);
-            if (stopping.signal.aborted)
-                break;
-            tick();
-        }
-    })();
-    void options.signalled?.then(() => stop('signal'));
-    /** Wait until a probe tick changes something this loop waits on, or a stop. */
-    const nextChange = async () => {
-        if (stopping.signal.aborted)
-            return;
-        await new Promise((resolve) => {
-            wake = resolve;
-        });
-    };
-    const pause = async (ms) => {
-        await clock.sleep(ms, stopping.signal).catch(() => undefined);
-    };
-    writeStatus();
-    logger.info('attendant.start', { notified: options.notified(), probe: probe.state });
-    // -- exchange loop -----------------------------------------------------
-    let backoff = 1_000;
-    let rotated = false;
-    let serverChecked = false;
-    /** Consecutive `retry-soon` answers from message hand-off. */
-    let messageRetries = 0;
-    while (exit === null) {
-        if (!networkStarted) {
-            if (!options.notified()) {
-                await nextChange();
-                continue;
-            }
-            networkStarted = true;
-        }
-        // Fresh evidence before every exchange, not the last tick's.
-        if (!refresh()) {
-            if (exit !== null)
-                break;
-            if (probe.state === 'uncertain')
-                setPhase('uncertain', probe.reason);
-            await nextChange();
-            continue;
-        }
-        const gate = options.gates();
-        if (!gate.ok) {
-            stop(`gate:${gate.reason}`);
-            break;
-        }
-        const client = options.client();
-        if (client === null) {
-            stop('gate:not-paired');
-            break;
-        }
-        if (!serverChecked) {
-            // Discovery is an exchange like any other: a stop, an uncertain probe,
-            // or an activity change cuts it, and whatever it answers, every check
-            // above runs again before anything is sent.
-            const discovery = new AbortController();
-            exchange = discovery;
-            exchangeHeld = false;
-            let supported;
-            try {
-                supported = await abortable(options.serverSupportsAttendance(client), discovery.signal);
-            }
-            catch {
-                exchange = null;
-                if (exit !== null || discovery.signal.aborted)
-                    continue;
-                await pause(backoff);
-                backoff = Math.min(backoff * 2, MAX_NETWORK_BACKOFF_MS);
-                continue;
-            }
-            exchange = null;
-            if (!supported) {
-                setPhase('unsupported', 'service-has-no-session-attendance');
-                await pause(ATTENDANT_UNSUPPORTED_RECHECK_MS);
-                continue;
-            }
-            serverChecked = true;
-            continue;
-        }
-        if (generation === null)
-            setPhase('acquiring');
-        const body = {
-            incarnation,
-            ...(generation === null ? {} : { generation }),
-            state: 'running',
-            // Set by the successful refresh above.
-            activity: activity ?? 'idle',
-            accepts_messages: options.acceptsMessages,
-            ...(cursor === undefined ? {} : { message_cursor: cursor }),
-        };
-        const current = new AbortController();
-        exchange = current;
-        const sentAt = clock.monotonic();
-        const sentEpoch = epoch;
-        const hold = cursor !== undefined && !reacquireNow && messageRetries === 0;
-        exchangeHeld = hold;
-        reacquireNow = false;
-        let response;
-        try {
-            response = await client.attend(options.sessionId, body, {
-                waitSeconds: hold ? waitSeconds : 0,
-                signal: current.signal,
-            });
-        }
-        catch (err) {
-            exchange = null;
-            if (exit !== null)
-                break;
-            if (current.signal.aborted)
-                continue;
-            if (err instanceof ApiCallError) {
-                if (err.status === 401 || err.status === 403) {
-                    stop('unauthorized');
-                    break;
-                }
-                if (err.status === 404) {
-                    setPhase('acquiring', 'session-unknown-to-service');
-                    await pause(ATTENDANT_UNKNOWN_SESSION_RETRY_MS);
-                    continue;
-                }
-                if (err.status === 409 && err.code === 'feature_unavailable') {
-                    serverChecked = false;
-                    setPhase('unsupported', 'service-refused-session-attendance');
-                    await pause(ATTENDANT_UNSUPPORTED_RECHECK_MS);
-                    continue;
-                }
-            }
-            await pause(backoff);
-            backoff = Math.min(backoff * 2, MAX_NETWORK_BACKOFF_MS);
-            continue;
-        }
-        exchange = null;
-        backoff = 1_000;
-        if (exit !== null)
-            break;
-        if (response.status === 'attending') {
-            const acquired = generation !== response.generation;
-            if (acquired) {
-                logger.info('attendant.lease', { event: 'acquired', generation: response.generation });
-            }
-            generation = response.generation;
-            // A grant sent before a clock discontinuity says nothing about now.
-            leaseEndsAt = sentEpoch === epoch ? sentAt + response.lease_remaining_ms : null;
-            cursor = response.message_cursor;
-            rotated = false;
-            // The answer waiter claims under the generation this status names.
-            if (acquired)
-                writeStatus();
-            setPhase('attending');
-            let handedOff = 'done';
-            if (options.acceptsMessages && options.onMessages !== undefined) {
-                try {
-                    handedOff = await options.onMessages(response.messages, handle);
-                }
-                catch (err) {
-                    logger.error('attendant.state', {
-                        phase,
-                        reason: 'message-handoff-failed',
-                        message: err instanceof Error ? err.message : String(err),
-                    });
-                }
-            }
-            if (handedOff === 'retry-soon' && exit === null) {
-                // Ask again without holding the exchange, backing off to the ordinary
-                // hold so a message that keeps waiting cannot spin the attendant.
-                const pauseMs = ATTENDANT_MESSAGE_RETRY_MS * 2 ** Math.min(messageRetries, 4);
-                messageRetries += 1;
-                await pause(Math.min(pauseMs, waitSeconds * 1_000));
-            }
-            else {
-                messageRetries = 0;
-            }
-            continue;
-        }
-        if (response.status === 'owned') {
-            if (generation !== null)
-                loseLease('owned-by-another-incarnation');
-            generation = null;
-            cursor = undefined;
-            setPhase('waiting-for-lease');
-            await pause(Math.min(Math.max(response.retry_after_ms, 1_000), 120_000));
-            continue;
-        }
-        // withdrawn: the service holds no lease for this incarnation.
-        if (generation !== null) {
-            loseLease('withdrawn-by-service');
-            generation = null;
-            stop('withdrawn-by-service');
-            break;
-        }
-        // Refused while acquiring: this incarnation id already released its lease
-        // (a report made before a restart). A fresh id may acquire once.
-        const next = rotated ? null : options.rotateIncarnation(incarnation);
-        if (next === null) {
-            stop('withdrawn-by-service');
-            break;
-        }
-        logger.info('attendant.lease', { event: 'incarnation-rotated' });
-        incarnation = next;
-        rotated = true;
-        cursor = undefined;
-    }
-    // -- end -----------------------------------------------------------------
-    stopping.abort();
-    abortExchange();
-    await probeLoop;
-    const reason = exit ?? 'signal';
-    let reported = null;
-    const final = finalReport(reason);
-    if (networkStarted && final !== null && (final === 'ended' || generation !== null)) {
-        const client = safeClient(options);
-        if (client !== null) {
-            reported = final;
-            const bound = new AbortController();
-            const timer = setTimeout(() => bound.abort(), ATTENDANT_FINAL_REPORT_MS);
-            try {
-                await client.attend(options.sessionId, {
-                    incarnation,
-                    ...(generation === null ? {} : { generation }),
-                    state: final,
-                }, { waitSeconds: 0, signal: bound.signal });
-            }
-            catch {
-                // Without the report the lease lapses and presence reads out of reach.
-            }
-            finally {
-                clearTimeout(timer);
-            }
-        }
-    }
-    leaseEndsAt = null;
-    phase = 'exited';
-    phaseReason = reason;
-    writeStatus();
-    logger.info('attendant.exit', {
-        reason,
-        ...(reported === null ? {} : { reported }),
-        ...(generation === null ? {} : { generation }),
-    });
-    return { reason, reported };
-}
-/** Which final state a way of ending reports, if any. */
-function finalReport(reason) {
-    switch (reason) {
-        case 'harness-gone':
-        case 'session-replaced':
-        case 'session-end-hook':
-        case 'signal':
-            return 'ended';
-        case 'superseded':
-            // A newer start of the same session attends now; ending would end it.
-            return 'withdrawn';
-        case 'withdrawn-by-service':
-        case 'unauthorized':
-        case 'claim-lost':
-            // Another attendant may hold this incarnation's lease now; any report
-            // from here could release it.
-            return null;
-        default:
-            return reason.startsWith('gate:') && reason !== 'gate:not-paired' ? 'withdrawn' : null;
-    }
-}
-function safeClient(options) {
-    try {
-        return options.client();
-    }
-    catch {
-        return null;
-    }
-}
-/** Rejects when `signal` aborts, so an awaited call cannot outlive a stop. */
-function abortable(work, signal) {
-    if (signal.aborted)
-        return Promise.reject(new Error('aborted'));
-    return new Promise((resolve, reject) => {
-        const onAbort = () => reject(new Error('aborted'));
-        signal.addEventListener('abort', onAbort, { once: true });
-        work.then((value) => {
-            signal.removeEventListener('abort', onAbort);
-            resolve(value);
-        }, (err) => {
-            signal.removeEventListener('abort', onAbort);
-            reject(err);
-        });
-    });
-}
-/** Production clocks: `performance.now()` pauses with the machine; `Date.now()` does not. */
-export const systemAttendantClock = {
-    monotonic: () => performance.now(),
-    wall: () => Date.now(),
-    sleep: (milliseconds, signal) => new Promise((resolve, reject) => {
-        if (signal.aborted) {
-            reject(signal.reason);
-            return;
-        }
-        const timer = setTimeout(() => {
-            signal.removeEventListener('abort', onAbort);
-            resolve();
-        }, milliseconds);
-        const onAbort = () => {
-            clearTimeout(timer);
-            reject(signal.reason);
-        };
-        signal.addEventListener('abort', onAbort, { once: true });
-    }),
-};
-//# sourceMappingURL=session-attendant.js.map