@raidiant/notifai 9.2.2 → 10.0.0

package/dist/hooks.d.ts

@@ -2,7 +2,7 @@ import type { LifecycleEndState, MediaItemT, NotificationDraftT, QuestionT, Repl
 import { type ApiClient } from './client.js';
 import { type CliConfig } from './config.js';
 import type { Logger } from './logging.js';
-import { type DeliveryRoute, type Harness } from './harnesses.js';
+import { type DeliveryRoute, type HookInstallableHarness } from './harnesses.js';
 /**
  * Harness hook handlers.
  *
@@ -12,12 +12,11 @@ import { type DeliveryRoute, type Harness } from './harnesses.js';
  * proven exact-session continuation fail closed at question admission.
  *
  * 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.
+ * old turn-end route held the terminal briefly and made keyboard presence an
+ * input to whether it waited. The current policy is explicit instead: Claude
+ * Code owns the complete answer window out of band, while Codex owns it by
+ * holding the asking turn. Neither infers notification preference from
+ * keystrokes.
  */
 /** Fields we read from harness hook JSON. Everything else is passed through. */
 export interface HookEnvelope {
@@ -127,6 +126,11 @@ interface AcceptedAnswerDelivery {
      * passes through.
      */
     delivery_attempts?: number;
+    /**
+     * Linearization point between delivery and SessionEnd. Once recorded, the
+     * route began first; before it, SessionEnd cancellation wins.
+     */
+    delivery_committed_at?: number;
     /** Turns this answer has been held without being handed to the agent. */
     held_deliveries?: number;
 }
@@ -185,15 +189,13 @@ export interface PendingQuestion {
     collapse_key?: string;
     /** Exact fanout of the live question; routing config may change afterwards. */
     device_ids?: string[];
-    /** Absolute end of the server reply window and its local continuation owner. */
+    /** Absolute end of the server reply window. */
     reply_deadline_at?: number;
     /**
-     * When this Stop owner stops listening for a direct wake. Distinct from
-     * `reply_deadline_at`: the server may still accept an answer for a day after
-     * this owner has returned. A later Stop that treats the reply window as a
-     * fresh waiter ceiling monopolizes the claim and skips newly registered
-     * questions. Absent on state written before this field existed — treated as
-     * already spent, because that is the shape a degraded waiter left behind.
+     * Absolute process-owner deadline. It begins before submission and includes
+     * startup headroom, so it must be later than `reply_deadline_at`. Absent on
+     * state written before ownership was persisted — treated as already spent
+     * instead of inventing a fresh multi-day claim.
      */
     owner_deadline_at?: number;
     /** Frozen before the first network byte, so an ambiguous submit is replayable. */
@@ -207,51 +209,17 @@ interface PendingSubmissionIntent {
     draft: NotificationDraftT;
     owner_deadline_at: number;
 }
-/**
- * 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.
- *
- * 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 const WAITER_CEILING_SECONDS = 480;
-/**
- * The same wall clock where the waiter runs in the background instead of
- * inside a held turn.
- *
- * On a host that holds its turn, 480 s is a real cost to the person sitting in
- * front of it, and the number above is right. On Claude Code the Stop hook
- * returns at once and the waiter is detached, so the same 480 s buys nothing
- * and costs a direct wake: an answer arriving at minute nine had to wait for
- * the session's next turn even though nothing was blocked.
- *
- * This sits under `CLAUDE_ASYNC_STOP_TIMEOUT_SECONDS` (3600) with headroom,
- * because that declaration's kill is silent, and under the reply window the
- * question was pushed with. Past it the journal still delivers at the next
- * turn — the ceiling decides how long a *direct* wake stays possible, never
- * whether the answer survives.
- */
-export declare const DETACHED_WAITER_CEILING_SECONDS = 3300;
-/** The waiter's wall clock, which depends on whether a turn is held open for it. */
-export declare function waiterCeilingSeconds(detached: boolean): number;
 /**
  * The wire contract's shortest reply window. A question submitted with less
  * than this is rejected outright, and accepting one would in any case let the
  * server go on taking an answer after the waiter that owns it has returned.
  */
 export declare const MIN_REPLY_WINDOW_SECONDS = 60;
-/**
- * HTTP budget reserved for the waiter's final reply fetch and close fence.
- * Taken from the owner deadline rather than added after it, so the hook does
- * not block past its ceiling. A near-zero remainder used to produce a
- * misleading 0s timeout and an unproven retirement.
- */
-export declare const FINALIZATION_NETWORK_BUDGET_SECONDS = 3;
 export interface HookOutcome {
     /** Written to stdout verbatim — the harness parses this as output. */
     stdout?: string;
+    /** Commit a blocking continuation immediately before the harness stdout write. */
+    commitStdout?: () => boolean;
     /** Whether stdout takes over the turn, rather than adding prompt context. */
     decided?: boolean;
     /** Diagnostics; harnesses surface hook stderr in the transcript. */
@@ -266,6 +234,12 @@ export interface ContinuationEvent {
     remaining: number;
     request_ids: string[];
     journal_recorded_at: number;
+    /**
+     * Must be called immediately before the route's irreversible harness write.
+     * It atomically orders that write against SessionEnd; false means cancellation
+     * won and the route must hand nothing over.
+     */
+    commitDelivery(): boolean;
 }
 /**
  * How much a route's own return proves about where the answer ended up.
@@ -292,6 +266,8 @@ export type DeliveryAcknowledgement = 'delivered' | 'stdout' | 'held';
 /** What a route returns: the hook's outcome plus what the attempt proved. */
 export interface DeliveryOutcome {
     stdout?: string;
+    /** Deferred SessionEnd fence for a blocking stdout continuation. */
+    commitStdout?: () => boolean;
     notes?: string[];
     log?: Record<string, unknown>;
     acknowledgement: DeliveryAcknowledgement;
@@ -330,7 +306,7 @@ export declare function confirmCursorStopActivation(sessionId: string, env: Node
 /** A fresh/cleared Cursor lifecycle makes its next Stop the fallback owner again. */
 export declare function resetCursorStopActivation(sessionId: string, env: NodeJS.ProcessEnv): void;
 export declare function pruneAbandonedSessions(env: NodeJS.ProcessEnv, now?: number, maxAgeMs?: number): number;
-export declare function claimQuestionPush(sessionId: string, env: NodeJS.ProcessEnv, now?: number, beforeStaleReplace?: () => void): boolean;
+export declare function claimQuestionPush(sessionId: string, env: NodeJS.ProcessEnv, now?: number, beforeStaleReplace?: () => void, ownerDeadlineAt?: number): boolean;
 export declare function releaseQuestionPush(sessionId: string, env: NodeJS.ProcessEnv): void;
 export interface ProjectSessionPointer {
     sessionId: string;
@@ -397,7 +373,7 @@ export declare const GATE_REASONS: readonly ["no-session", "no-question", "answe
  * emitted once; documenting them taught agents to filter for silence.
  */
 export type GateReason = (typeof GATE_REASONS)[number];
-export type HookHarness = Harness;
+export type HookHarness = HookInstallableHarness;
 /**
  * Everything retirement needs. Narrower than a HookContext on purpose:
  * `notifai ask` supersedes the previous question and it is a plain command with