@raidiant/notifai 0.4.0 → 0.5.1

package/dist/hooks.d.ts

@@ -2,7 +2,7 @@ import type { LifecycleEndState, NotificationDraftT, QuestionT, ReplyView } from
 import { type ApiClient } from './client.js';
 import { type CliConfig } from './config.js';
 import type { Logger } from './logging.js';
-import { type Harness } from './harnesses.js';
+import { type DeliveryRoute, type Harness } from './harnesses.js';
 /**
  * Harness hook handlers.
  *
@@ -11,10 +11,13 @@ import { type Harness } from './harnesses.js';
  * and Codex can continue directly from a turn-end answer. Harnesses without a
  * proven exact-session continuation fail closed at question admission.
  *
- * The load-bearing constraint is that these hooks are synchronous: while one
- * blocks, the harness cannot show its own prompt either. So a hook may only
- * take over when the user is demonstrably absent. Present user, or no evidence
- * either way, means exit immediately and let the terminal do its job.
+ * Where the user is standing no longer decides anything here. It used to: the
+ * turn-end hook held the terminal for as long as it waited, so waiting was
+ * only defensible while the person was demonstrably not at the keyboard. On
+ * Claude Code the handler now returns instantly and the waiter runs out of
+ * band, and nothing is monopolised in the first place — so the question is
+ * simply whether the user wants to be reached, which they answer once in
+ * configuration rather than implicitly with every keystroke.
  */
 /** Fields we read from harness hook JSON. Everything else is passed through. */
 export interface HookEnvelope {
@@ -57,16 +60,20 @@ export interface SessionState {
      * costs nothing and a missed one costs a stale notification for ever.
      */
     retiring?: RetiringQuestion[];
-    /** Tracks bounded Stop continuations so a follow-up ask is delivered once. */
+    /**
+     * Tracks bounded Stop continuations so a follow-up ask is delivered once.
+     * `count` is how many answer generations have run consecutively without the
+     * user taking a turn themselves; their next prompt starts it over.
+     */
     continuation?: {
         answered_at: number;
         count: number;
     };
     /**
-     * A phone answer durably captured but not yet acknowledged by a successor
-     * hook. It stays here until the next Stop proves the harness processed the
-     * continuation; a crash before stdout therefore replays instead of erasing
-     * the user's answer.
+     * A phone answer durably captured but not yet acknowledged. It stays here
+     * until a delivery is acknowledged — by the route's own write, or by the
+     * successor Stop of a blocking continuation — so a crash before the answer
+     * reaches the harness replays it instead of erasing it.
      */
     accepted?: AcceptedAnswerDelivery;
 }
@@ -74,7 +81,20 @@ interface AcceptedAnswerDelivery {
     answers: AnsweredPending[];
     remaining: number;
     recorded_at: number;
-    continuation_count?: number;
+    /**
+     * Epoch ms when a route's own write handed this answer to the harness, with
+     * the route that performed it. Recorded so that "this answer was delivered"
+     * is a fact on the journal rather than something inferred from a harness flag
+     * that only one route ever sets.
+     */
+    delivered_at?: number;
+    delivered_route?: string;
+    /**
+     * How many times this answer has been handed to any route. The route-agnostic
+     * loop backstop: bounded by `MAX_CONTINUATION_COUNT` in one place every route
+     * passes through.
+     */
+    delivery_attempts?: number;
 }
 /** A delivered question awaiting its retirement push. */
 export interface RetiringQuestion {
@@ -139,33 +159,16 @@ interface PendingSubmissionIntent {
     draft: NotificationDraftT;
     owner_deadline_at: number;
 }
-export type GraceOutcome = 
-/** The window elapsed with the user still gone; escalate. */
-'absent'
-/** The user touched the machine; the terminal is theirs. */
- | 'user-returned'
-/** No idle source, so waiting would hold a terminal we cannot monitor. */
- | 'no-signal';
 /**
- * The terminal-first wait: the question sits in the terminal for
- * `ask_grace_seconds` from when it was sent, and only then reaches companion
- * devices.
- *
- * Holding a blocking Stop hook open is normally hostile — while it blocks, the
- * harness cannot show its prompt either, so a user wanting to answer locally is
- * locked out. What makes it safe is that the wait is abandoned the moment the
- * user touches the keyboard or mouse. The block therefore only ever persists
- * while they are demonstrably not using the machine, which costs them nothing.
+ * The waiter's whole wall clock: the terminal-first timer, submission, and the
+ * wait for an answer, from the moment the turn-end hook starts.
  *
- * That safety depends entirely on the idle signal, so with no idle source this
- * refuses to wait at all rather than holding a terminal it cannot monitor.
- *
- * With `require_idle` off the whole calculus changes: the user has said they
- * want the question to reach them whether or not they are at the keyboard, so
- * there is nothing to watch for and this becomes what its name always claimed —
- * a plain timer. It then works on machines with no idle source too.
+ * One plain ceiling, deliberately not a budget carved into reserves. The
+ * reserves existed to fit every phase inside a *held* turn; on Claude Code the
+ * turn is not held any more, and on a host that still holds one the useful
+ * question is only how long that host is willing to wait in total.
  */
-export declare function awaitGrace(ctx: HookContext, askedAt: number): Promise<GraceOutcome>;
+export declare const WAITER_CEILING_SECONDS = 480;
 export interface HookOutcome {
     /** Written to stdout verbatim — the harness parses this as the decision. */
     stdout?: string;
@@ -174,6 +177,54 @@ export interface HookOutcome {
     /** Structured lifecycle detail that belongs on hook.end without user text. */
     log?: Record<string, unknown>;
 }
+/** An accepted continuation ready for whichever host owns the last meter. */
+export interface ContinuationEvent {
+    context: string;
+    answers: number;
+    remaining: number;
+    request_ids: string[];
+    journal_recorded_at: number;
+}
+/**
+ * How much a route's own return proves about where the answer ended up.
+ *
+ * Acknowledgement belongs to the delivery, not to the harness envelope: routes
+ * end in different places, so no single field on a hook payload can speak for
+ * all of them. `stop_hook_active` is the harness confirming that a *blocking
+ * continuation* was admitted; it stays false for ever on a route that starts a
+ * brand-new turn instead of continuing this one, so a journal keyed to it alone
+ * never settles and every later turn-end redelivers the same answer.
+ *
+ * - `delivered` — the route completed a write to the harness itself (an inbox
+ *   socket, a cold resume). Delivery is not consumption: the write proves the
+ *   harness accepted the message, never that the model acted on it. But nothing
+ *   later will ever prove more, and redelivering an answer without end is
+ *   strictly worse than settling on the write, so the journal settles here.
+ * - `stdout` — the answer is this process's stdout, which the harness reads only
+ *   after this process exits. Nothing this process can write is proof, so the
+ *   journal waits for the successor Stop's `stop_hook_active`, and a crash
+ *   before stdout replays the answer instead of losing it.
+ * - `held` — the route handed nothing over; the journal replays the answer.
+ */
+export type DeliveryAcknowledgement = 'delivered' | 'stdout' | 'held';
+/** What a route returns: the hook's outcome plus what the attempt proved. */
+export interface DeliveryOutcome {
+    stdout?: string;
+    notes?: string[];
+    log?: Record<string, unknown>;
+    acknowledgement: DeliveryAcknowledgement;
+}
+/** Host adapter injected into the waiter; no route is implemented by the waiter. */
+export interface EscalationDeliveryRoute {
+    kind: Exclude<DeliveryRoute, 'unsupported'>;
+    deliver(event: ContinuationEvent): Promise<DeliveryOutcome>;
+}
+export interface EscalationWaiterOptions {
+    sessionId: string;
+    envelope: HookEnvelope;
+    route: EscalationDeliveryRoute;
+    processDeadlineAt?: number;
+}
 export declare function readSessionState(sessionId: string, env: NodeJS.ProcessEnv): SessionState;
 export declare function writeSessionState(sessionId: string, env: NodeJS.ProcessEnv, state: SessionState): void;
 export declare function clearSessionState(sessionId: string, env: NodeJS.ProcessEnv): void;
@@ -192,42 +243,25 @@ export interface ProjectSessionPointer {
  * into state nothing is watching.
  */
 export declare function readProjectSession(cwd: string, env: NodeJS.ProcessEnv, now: number, maxAgeMs?: number): string | null;
-export declare function readProjectSessionPointer(cwd: string, env: NodeJS.ProcessEnv, now: number, maxAgeMs?: number): ProjectSessionPointer | null;
-export declare function readMatchingProjectSessionPointer(cwd: string, env: NodeJS.ProcessEnv, now: number, sessionId: string, harness: HookHarness, maxAgeMs?: number): ProjectSessionPointer | null;
+/** A live pointer keeps when it was last written, so callers can rank by it. */
+export interface LiveProjectSessionPointer extends ProjectSessionPointer {
+    updatedAt: number;
+}
 /**
- * Absent means the user is not at this machine's keyboard.
- *
- * OS idle time answers that directly, so where it exists it decides alone.
- * Silence since the user's last prompt is only ever a proxy for it, and a poor
- * one — it is wrong in both directions:
- *
- *   - Too long: it counts the agent's own turn, so a user watching a build was
- *     read as absent and had the question pushed at them.
- *   - Too short: a session that has just been spawned always has a fresh
- *     prompt, so its FIRST question could never escalate however long its
- *     owner had been gone. That is the "kick off some agents and
- *     walk away" case this feature mainly exists for, and requiring both
- *     signals to agree is what broke it.
- *
- * The proxy therefore survives only as the fallback for machines with no idle
- * source. There, never having seen a prompt is not evidence of absence — it is
- * a missing `UserPromptSubmit` hook — so it resolves to "present".
- *
- * Answering from a companion device does not make the user present; only touching this
- * machine does. Answering on a device is evidence of being away from it.
+ * Every session that has fired a hook in this directory recently, newest first.
  *
- * All of which only matters if presence is being consulted at all. With
- * `require_idle` off the user has said their whereabouts are not a
- * precondition, so this stops guessing and answers yes.
+ * This is the only local record of which harness sessions are actually alive
+ * here, which makes it the tiebreaker when the environment alone cannot say
+ * which harness owns the current shell.
  */
-export declare function isUserAway(state: SessionState, config: CliConfig, now: number, idleSeconds: number | null): boolean;
+export declare function readLiveProjectSessionPointers(cwd: string, env: NodeJS.ProcessEnv, now: number, maxAgeMs?: number): LiveProjectSessionPointer[];
+export declare function readProjectSessionPointer(cwd: string, env: NodeJS.ProcessEnv, now: number, maxAgeMs?: number): ProjectSessionPointer | null;
+export declare function readMatchingProjectSessionPointer(cwd: string, env: NodeJS.ProcessEnv, now: number, sessionId: string, harness: HookHarness, maxAgeMs?: number): ProjectSessionPointer | null;
 export interface HookContext {
     client: ApiClient;
     config: CliConfig;
     env: NodeJS.ProcessEnv;
     now: () => number;
-    /** Seconds since the last keyboard/mouse event, or null if unknowable. */
-    idleSeconds: () => number | null;
     /** Injected so tests advance a virtual clock instead of sleeping. */
     sleep: (milliseconds: number) => Promise<void>;
     /** Bounded wait for the first reply; injected so tests do not sleep. */
@@ -254,7 +288,7 @@ export interface HookContext {
  * the user sees in the terminal — but it is free to be rewritten, and a log a
  * filter cannot rely on is a log nobody filters.
  */
-export type GateReason = 'no-session' | 'no-question' | 'answered' | 'already-asked' | 'continuation-repeat' | 'continuation-limit' | 'notifications-off' | 'user-present' | 'claimed-elsewhere' | 'user-returned' | 'no-devices' | 'proceeding';
+export type GateReason = 'no-session' | 'no-question' | 'answered' | 'already-asked' | 'continuation-repeat' | 'continuation-limit' | 'delivery-limit' | 'notifications-off' | 'claimed-elsewhere' | 'no-devices' | 'proceeding';
 export type HookHarness = Harness;
 /**
  * Everything retirement needs. Narrower than a HookContext on purpose:
@@ -283,6 +317,15 @@ export declare function orphanRetirements(env: NodeJS.ProcessEnv, entries: Retir
  * next holder of a client; entries past the TTL are dropped as already dead.
  */
 export declare function drainOrphanRetirements(ctx: RetireDeps, env: NodeJS.ProcessEnv, now: number): Promise<string[]>;
+/**
+ * The one bound on answer deliveries, for every route.
+ *
+ * It caps two things that both used to be able to run away: how many times a
+ * single accepted answer may be handed to a route before the journal gives up
+ * on it, and how many answer-driven continuation generations one chain may
+ * produce.
+ */
+export declare const MAX_CONTINUATION_COUNT = 3;
 /** One answered registered question, with everything the agent needs to read it. */
 interface AnsweredPending {
     pending: PendingQuestion;
@@ -301,7 +344,18 @@ export declare function handleUserPromptSubmit(ctx: HookContext, envelope: HookE
  * `notifai ask`. Guessing from the last assistant message was the alternative
  * and it is not worth it: a false positive here hijacks the terminal.
  */
-export declare function handleStop(ctx: HookContext, envelope: HookEnvelope, processDeadlineAt?: number): Promise<HookOutcome>;
+export declare function handleStop(ctx: HookContext, envelope: HookEnvelope, processDeadlineAt?: number, route?: EscalationDeliveryRoute): Promise<HookOutcome>;
+/**
+ * Own one registered question pipeline from its terminal-first timer through
+ * its final delivery or retirement. Hosts differ only in the injected route.
+ */
+export declare function runEscalationWaiter(ctx: HookContext, options: EscalationWaiterOptions): Promise<HookOutcome>;
+/**
+ * The blocking Stop hook's own last meter: the answer becomes this process's
+ * stdout, and the harness admits it as a new user turn. Exported because a
+ * host adapter that has other routes still falls back to this one.
+ */
+export declare function hookContinuationRoute(): EscalationDeliveryRoute;
 /**
  * Claude Code gives SessionEnd hooks a 1.5-second shared budget and Codex 1
  * second, so this cannot make a network call. It drops the local marker — but