@raidiant/notifai 10.1.7 → 11.0.1

package/dist/hook-session-state.js

@@ -0,0 +1,249 @@
+/** Durable per-Agent-Session state, activation bookkeeping, and pruning. */
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import path from 'node:path';
+import { atomicWriteFileSync } from './atomic-file.js';
+import { sanitizeSessionId, sessionConfigPath, stateDir } from './config.js';
+import { withFileLock } from './file-lock.js';
+export function sessionStatePath(sessionId, env) {
+    return path.join(stateDir(env), 'sessions', `${sanitizeSessionId(sessionId)}.json`);
+}
+/**
+ * Durable cancellation for observers that can outlive the harness process.
+ *
+ * Absence of session state is not enough: SessionEnd deliberately deletes it,
+ * and an in-flight submit/fence could otherwise recreate it afterwards. The
+ * marker shares the session-state lock, giving every racing writer one total
+ * order: either its state lands before SessionEnd and is cleaned up there, or
+ * it observes this marker and must not write or deliver into the ended session.
+ */
+function sessionEndMarkerPath(sessionId, env) {
+    return path.join(stateDir(env), 'sessions', `${sanitizeSessionId(sessionId)}.ended`);
+}
+export function sessionHasEnded(sessionId, env) {
+    return existsSync(sessionEndMarkerPath(sessionId, env));
+}
+export function markSessionEnded(sessionId, env, now) {
+    const stateFile = sessionStatePath(sessionId, env);
+    withFileLock(`${stateFile}.lock`, () => {
+        atomicWriteFileSync(sessionEndMarkerPath(sessionId, env), `${now}\n`);
+    });
+}
+function clearSessionEndMarker(sessionId, env) {
+    const stateFile = sessionStatePath(sessionId, env);
+    withFileLock(`${stateFile}.lock`, () => {
+        rmSync(sessionEndMarkerPath(sessionId, env), { force: true });
+    });
+}
+export function readSessionState(sessionId, env) {
+    const file = sessionStatePath(sessionId, env);
+    if (!existsSync(file))
+        return {};
+    try {
+        const parsed = JSON.parse(readFileSync(file, 'utf8'));
+        if (typeof parsed !== 'object' || parsed === null)
+            return {};
+        const state = { ...parsed };
+        delete state.session_id;
+        return state;
+    }
+    catch {
+        // A corrupt marker must not wedge the harness; treat it as "no evidence",
+        // which fails closed onto ordinary terminal behaviour.
+        return {};
+    }
+}
+/**
+ * Resolve a stable question or request id to the one exact session that owns it.
+ *
+ * This deliberately searches lifecycle state, not checkout pointers: question
+ * identity is global on this machine, while a linked worktree is only where a
+ * command happened to run. Ambiguous or corrupt matches fail closed.
+ */
+export function findOwningSession(id, env) {
+    const directory = path.join(stateDir(env), 'sessions');
+    if (!existsSync(directory))
+        return { sessionId: null, ambiguous: false };
+    const matches = [];
+    for (const name of readdirSync(directory)) {
+        if (!name.endsWith('.json'))
+            continue;
+        let persisted = null;
+        try {
+            const parsed = JSON.parse(readFileSync(path.join(directory, name), 'utf8'));
+            if (typeof parsed === 'object' && parsed !== null) {
+                persisted = parsed;
+            }
+        }
+        catch {
+            // Corrupt lifecycle state is not identity evidence.
+        }
+        if (persisted === null || typeof persisted.session_id !== 'string')
+            continue;
+        const sessionId = persisted.session_id;
+        const state = persisted;
+        const pendingMatch = pendingList(state).some((entry) => entry.question_id === id || entry.request_id === id);
+        const retiringMatch = (state.retiring ?? []).some((entry) => entry.question_id === id || entry.request_id === id);
+        const historyMatch = (state.question_history ?? []).some((entry) => entry.question_id === id || entry.request_id === id);
+        const acknowledgementMatch = (state.acknowledgement_due ?? []).some((entry) => entry.request_id === id);
+        const acceptedMatch = state.accepted?.answers.some(({ pending }) => pending.question_id === id || pending.request_id === id) ?? false;
+        if (pendingMatch || retiringMatch || historyMatch || acknowledgementMatch || acceptedMatch) {
+            matches.push(sessionId);
+            if (matches.length > 1)
+                return { sessionId: null, ambiguous: true };
+        }
+    }
+    return { sessionId: matches[0] ?? null, ambiguous: false };
+}
+export function writeSessionState(sessionId, env, state) {
+    const file = sessionStatePath(sessionId, env);
+    withFileLock(`${file}.lock`, () => writeSessionStateUnlocked(file, sessionId, state));
+}
+export function clearSessionState(sessionId, env) {
+    const file = sessionStatePath(sessionId, env);
+    withFileLock(`${file}.lock`, () => {
+        rmSync(file, { force: true });
+        // The session override lives in a sibling file; leaving it behind meant a
+        // later session reusing the id silently inherited `ask_notifications = false`.
+        rmSync(sessionConfigPath(sessionId, env), { force: true });
+    });
+}
+export function writeSessionStateUnlocked(file, sessionId, state) {
+    atomicWriteFileSync(file, `${JSON.stringify({ ...state, session_id: sessionId }, null, 2)}\n`);
+}
+export function updateSessionState(sessionId, env, update) {
+    const file = sessionStatePath(sessionId, env);
+    return withFileLock(`${file}.lock`, () => {
+        const current = readSessionState(sessionId, env);
+        // SessionEnd and every asynchronous writer share this lock. Once the
+        // durable marker exists, no observer may recreate state for that session.
+        if (sessionHasEnded(sessionId, env))
+            return current;
+        const next = update(current);
+        writeSessionStateUnlocked(file, sessionId, next);
+        return next;
+    });
+}
+/** Record the current installation when an owner session starts. */
+export function recordSessionStart(sessionId, env, harness, cwd, codexStopDefinitionFingerprint) {
+    // Harnesses may reuse a session id only by explicitly starting that session
+    // again. That lifecycle edge is the sole authority for clearing cancellation.
+    clearSessionEndMarker(sessionId, env);
+    updateSessionState(sessionId, env, (current) => {
+        const next = {
+            ...current,
+            ...(harness === undefined ? {} : { harness }),
+            ...(cwd === undefined
+                ? {}
+                : { activation_cwd: harness === 'codex' ? cwd : current.activation_cwd ?? cwd }),
+        };
+        // A Codex SessionStart materializes one new runtime generation. Absence of
+        // singular proof must replace prior proof too; retaining it would let a
+        // resumed session borrow the definition loaded by an earlier runtime.
+        if (harness === 'codex') {
+            delete next.codex_stop_definition_fingerprint;
+            if (codexStopDefinitionFingerprint !== undefined) {
+                next.codex_stop_definition_fingerprint = codexStopDefinitionFingerprint;
+            }
+        }
+        return next;
+    });
+}
+/** Atomically claim Cursor's first-Stop activation fallback once per conversation. */
+export function claimCursorStopActivation(sessionId, env, now) {
+    const claimGuardMs = 30_000;
+    let claimed = false;
+    updateSessionState(sessionId, env, (current) => {
+        if (current.cursor_activation_confirmed_at !== undefined)
+            return current;
+        if (current.cursor_activation_claimed_at !== undefined &&
+            now - current.cursor_activation_claimed_at < claimGuardMs) {
+            return current;
+        }
+        claimed = true;
+        return { ...current, cursor_activation_claimed_at: now };
+    });
+    return claimed;
+}
+/** Cursor's loop_count proves the previous Stop follow-up reached the host. */
+export function confirmCursorStopActivation(sessionId, env, now) {
+    let owned = false;
+    updateSessionState(sessionId, env, (current) => {
+        if (current.cursor_activation_confirmed_at !== undefined) {
+            owned = true;
+            return current;
+        }
+        if (current.cursor_activation_claimed_at === undefined)
+            return current;
+        owned = true;
+        return { ...current, cursor_activation_confirmed_at: now };
+    });
+    return owned;
+}
+/** A fresh/cleared Cursor lifecycle makes its next Stop the fallback owner again. */
+export function resetCursorStopActivation(sessionId, env) {
+    updateSessionState(sessionId, env, (current) => {
+        if (current.cursor_activation_claimed_at === undefined &&
+            current.cursor_activation_confirmed_at === undefined) {
+            return current;
+        }
+        const next = { ...current };
+        delete next.cursor_activation_claimed_at;
+        delete next.cursor_activation_confirmed_at;
+        return next;
+    });
+}
+/**
+ * Session state a crashed harness left behind.
+ *
+ * `SessionEnd` removes session state and leaves a short-lived cancellation
+ * marker; a harness that crashes or is killed never reaches it. At roughly a
+ * hundred sessions a day that is tens of thousands of files a year, none of
+ * which anything reads.
+ *
+ * Opportunistic rather than scheduled: hooks are the only thing that runs, so
+ * a hook is where this has to live. It is rate-limited by its own stamp file
+ * so the common case costs one `stat`, not a directory walk — a Stop hook is
+ * on the critical path of every turn.
+ */
+const SESSION_PRUNE_AFTER_MS = 7 * 24 * 3600 * 1000;
+const SESSION_PRUNE_INTERVAL_MS = 24 * 3600 * 1000;
+export function pruneAbandonedSessions(env, now = Date.now(), maxAgeMs = SESSION_PRUNE_AFTER_MS) {
+    const directory = path.join(stateDir(env), 'sessions');
+    const stamp = path.join(stateDir(env), 'last-prune');
+    try {
+        if (existsSync(stamp) && now - statSync(stamp).mtimeMs < SESSION_PRUNE_INTERVAL_MS)
+            return 0;
+        mkdirSync(path.dirname(stamp), { recursive: true });
+        writeFileSync(stamp, '', { mode: 0o600 });
+        if (!existsSync(directory))
+            return 0;
+        let removed = 0;
+        for (const name of readdirSync(directory)) {
+            const file = path.join(directory, name);
+            try {
+                const age = now - statSync(file).mtimeMs;
+                // A negative age means the clock moved, not that the file is old.
+                // Deleting live session state on an NTP correction would lose a
+                // question already on the user's phone.
+                if (age <= maxAgeMs)
+                    continue;
+                rmSync(file, { force: true });
+                removed += 1;
+            }
+            catch {
+                // A file that vanished under us, or one we may not read. Neither is
+                // worth failing a hook for, and the next pass will see it again.
+            }
+        }
+        return removed;
+    }
+    catch {
+        // Housekeeping must never be the reason a turn fails.
+        return 0;
+    }
+}
+/** The registered-question queue. Anything but the current shape reads as empty. */
+export function pendingList(state) {
+    return Array.isArray(state.pending) ? state.pending : [];
+}
+//# sourceMappingURL=hook-session-state.js.map

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

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

package/dist/{hooks.d.ts → hook-types.d.ts}

@@ -1,8 +1,9 @@
+/** Value-free contracts shared across hook state and lifecycle modules. */
 import type { LifecycleEndState, MediaItemT, NotificationDraftT, QuestionT, ReplyView, SourceContextT } from '@raidiant/notifai-protocol';
 import { type ApiClient } from './client.js';
 import { type CliConfig } from './config.js';
-import type { Logger } from './logging.js';
 import { type DeliveryRoute, type HookInstallableHarness } from './harnesses.js';
+import type { Logger } from './logging.js';
 /**
  * Harness hook handlers.
  *
@@ -117,7 +118,7 @@ export interface AcknowledgementDue {
      */
     text_required?: boolean;
 }
-interface AcceptedAnswerDelivery {
+export interface AcceptedAnswerDelivery {
     answers: AnsweredPending[];
     remaining: number;
     recorded_at: number;
@@ -172,11 +173,22 @@ export interface OrphanRetirement extends RetiringQuestion {
     /** Epoch ms when the entry was orphaned; entries beyond the TTL are dropped. */
     enqueued_at: number;
 }
+/** A fully prepared question submission whose ownership deadline is fixed. */
+export interface PendingSubmissionIntent {
+    request_id: string;
+    idempotency_key: string;
+    collapse_key: string;
+    device_ids: string[];
+    draft: NotificationDraftT;
+    owner_deadline_at: number;
+}
 export interface PendingQuestion {
     /** Stable local identity across racing state writers and submit recovery. */
     question_id?: string;
     /** One-line summary: the single question's text, or the set's first. */
     question: string;
+    /** Purpose-written plain text for native banners and notification lists. */
+    summary: string;
     /**
      * Epoch ms when `notifai ask` registered this. The grace window runs from
      * here, not from the turn's end: a question the agent asked five minutes ago
@@ -188,7 +200,7 @@ export interface PendingQuestion {
      * texts, choices, multi flags. What actually rides the push.
      */
     questions?: QuestionT[];
-    /** Canonical Markdown body composed when the question was registered. */
+    /** Optional standalone Markdown Body composed when the question was registered. */
     body?: string;
     /** Final ordered media collection; uploads complete before registration. */
     media?: MediaItemT[];
@@ -213,7 +225,7 @@ export interface PendingQuestion {
     submission?: PendingSubmissionIntent;
 }
 export type QuestionDeliveryState = 'local' | 'frozen' | 'live' | 'answered' | 'withdrawn' | 'retired';
-type QuestionTerminalState = Extract<QuestionDeliveryState, 'answered' | 'withdrawn' | 'retired'>;
+export type QuestionTerminalState = Extract<QuestionDeliveryState, 'answered' | 'withdrawn' | 'retired'>;
 export interface QuestionHistoryEntry {
     question_id: string;
     state: QuestionTerminalState;
@@ -222,36 +234,6 @@ export interface QuestionHistoryEntry {
     /** Reserved idempotent identity that was never locally promoted. */
     frozen_request_id?: string;
 }
-export interface QuestionStateView {
-    question_id: string;
-    state: QuestionDeliveryState;
-    /** Null means a frozen submission may or may not have crossed the service boundary. */
-    submitted: boolean | null;
-    request_id: string | null;
-    frozen_request_id: string | null;
-}
-export type QuestionStateLookup = {
-    found: true;
-    session_id: string;
-    question: QuestionStateView;
-} | {
-    found: false;
-    ambiguous: boolean;
-};
-interface PendingSubmissionIntent {
-    request_id: string;
-    idempotency_key: string;
-    collapse_key: string;
-    device_ids: string[];
-    draft: NotificationDraftT;
-    owner_deadline_at: 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;
 export interface HookOutcome {
     /** Written to stdout verbatim — the harness parses this as output. */
     stdout?: string;
@@ -324,57 +306,6 @@ export interface EscalationWaiterOptions {
     /** Stop owns diagnostics; a pre-Stop recovery owner must not impersonate it. */
     recordStop?: boolean;
 }
-export declare function readSessionState(sessionId: string, env: NodeJS.ProcessEnv): SessionState;
-/**
- * Resolve a stable question or request id to the one exact session that owns it.
- *
- * This deliberately searches lifecycle state, not checkout pointers: question
- * identity is global on this machine, while a linked worktree is only where a
- * command happened to run. Ambiguous or corrupt matches fail closed.
- */
-export declare function findOwningSession(id: string, env: NodeJS.ProcessEnv): {
-    sessionId: string | null;
-    ambiguous: boolean;
-};
-export declare function writeSessionState(sessionId: string, env: NodeJS.ProcessEnv, state: SessionState): void;
-export declare function clearSessionState(sessionId: string, env: NodeJS.ProcessEnv): void;
-/** Record the current installation when an owner session starts. */
-export declare function recordSessionStart(sessionId: string, env: NodeJS.ProcessEnv, harness?: HookHarness, cwd?: string, codexStopDefinitionFingerprint?: string): void;
-/** Atomically claim Cursor's first-Stop activation fallback once per conversation. */
-export declare function claimCursorStopActivation(sessionId: string, env: NodeJS.ProcessEnv, now: number): boolean;
-/** Cursor's loop_count proves the previous Stop follow-up reached the host. */
-export declare function confirmCursorStopActivation(sessionId: string, env: NodeJS.ProcessEnv, now: number): boolean;
-/** 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, ownerDeadlineAt?: number): boolean;
-export declare function releaseQuestionPush(sessionId: string, env: NodeJS.ProcessEnv): void;
-export interface ProjectSessionPointer {
-    sessionId: string;
-    harness: HookHarness;
-}
-/** Records every live session working in a directory, for `notifai ask`. */
-export declare function writeProjectSession(cwd: string, env: NodeJS.ProcessEnv, sessionId: string, now: number, harness: HookHarness): void;
-/**
- * Resolves the session working in `cwd`. Stale pointers are ignored rather than
- * trusted: an id left by a session that ended days ago would send the question
- * into state nothing is watching.
- */
-export declare function readProjectSession(cwd: string, env: NodeJS.ProcessEnv, now: number, maxAgeMs?: number): string | null;
-/** A live pointer keeps when it was last written, so callers can rank by it. */
-export interface LiveProjectSessionPointer extends ProjectSessionPointer {
-    updatedAt: number;
-}
-/**
- * Every session that has fired a hook in this directory recently, newest first.
- *
- * 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 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;
@@ -397,84 +328,9 @@ export interface HookContext {
      */
     log?: Logger;
 }
-/**
- * Record one gate decision.
- *
- * `verdict` is what happened to the question and `reason` is the closed-set
- * name of the rule that decided it, so an agent can ask "why was it held" with
- * a filter rather than by matching on prose. The prose still exists — it is what
- * 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 declare const GATE_REASONS: readonly ["no-session", "no-question", "answered", "continuation-repeat", "continuation-limit", "delivery-limit", "acknowledgement-required", "acknowledgement-abandoned", "harness-cannot-continue", "notifications-off", "claimed-elsewhere", "elapsed", "proceeding"];
-/**
- * A runtime list rather than a bare type, so the guidance that tells agents to
- * filter on these can be tested against the set the code can actually emit.
- * `already-asked` and `no-devices` were declared here for a long time and never
- * emitted once; documenting them taught agents to filter for silence.
- */
-export type GateReason = (typeof GATE_REASONS)[number];
 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
- * no hook payload, no idle probe and nothing to sleep for.
- */
-export type RetireDeps = Pick<HookContext, 'client' | 'config'> & Pick<Partial<HookContext>, 'log'>;
-/**
- * Park a delivered question for retirement. Called at the moment we learn it is
- * dead, which is frequently not a moment we can reach the network.
- *
- * Nothing is parked for a question that never reached a device: with no
- * request_id there is nothing on any device to retire.
- */
-export declare function parkForRetirement(sessionId: string, env: NodeJS.ProcessEnv, pending: PendingQuestion, state: LifecycleEndState): void;
-/**
- * Which outstanding questions this prompt plausibly answers.
- *
- * A unique closed-choice match is enough. A short confirmation such as "done"
- * matches only when exactly one question is outstanding. Long unrelated
- * prompts leave every question open for the reply window.
- */
-export declare function pendingAnsweredByPrompt(prompt: string | undefined, pending: readonly PendingQuestion[]): PendingQuestion[];
-/**
- * Send every parked retirement, and forget the ones that landed. A failure
- * leaves the entry in place for the next hook rather than losing it, which is
- * the whole reason the queue exists.
- */
-export declare function drainRetirements(ctx: RetireDeps, sessionId: string, env: NodeJS.ProcessEnv): Promise<string[]>;
-/** Move retirements into the global queue; deduped so a retry costs nothing. */
-export declare function orphanRetirements(env: NodeJS.ProcessEnv, entries: RetiringQuestion[], now: number): void;
-/**
- * Retire everything a dead session left behind. Failures stay queued for the
- * 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;
-/**
- * How many turns an answer may be *held* before it is settled unread.
- *
- * A hold is not a delivery: the route reported that it handed nothing over, so
- * the agent has not seen the answer and the wake-loop the continuation cap
- * exists to stop has not happened. Counting holds against that cap meant three
- * turns where a liveness probe could not reach a busy session were enough to
- * discard an answer the user had already given.
- *
- * It still has to end. A route that can never deliver would otherwise retry
- * every turn for the life of the session, so holds get their own, far looser
- * bound — loose because each one costs nothing and the answer is still wanted.
- */
-export declare const MAX_HELD_DELIVERIES = 20;
 /** One answered registered question, with everything the agent needs to read it. */
-interface AnsweredPending {
+export interface AnsweredPending {
     pending: PendingQuestion;
     reply: ReplyView;
     replies: ReplyView[];
@@ -483,78 +339,3 @@ interface AnsweredPending {
     /** Whether that acknowledgement must carry text; the account's snapshot. */
     agent_acknowledgement_text_required?: boolean | undefined;
 }
-/** Read one stable local question identity without minting or submitting anything. */
-export declare function inspectQuestionState(questionId: string, env: NodeJS.ProcessEnv): QuestionStateLookup;
-export declare function dropPendingQuestion(sessionId: string, env: NodeJS.ProcessEnv, entry: PendingQuestion, terminalState?: QuestionTerminalState): void;
-/**
- * Drop registrations that never reached a device, so a later Stop cannot push
- * them. A retirement push would be noise: there is nothing on any device to
- * withdraw. Returns the withdrawn entries in registration order.
- */
-export declare function withdrawUnpushedQuestions(sessionId: string, env: NodeJS.ProcessEnv): PendingQuestion[];
-export declare function clearAcknowledgementObligation(sessionId: string, env: NodeJS.ProcessEnv, requestId: string): boolean;
-/**
- * Records presence. Retires a live question only when this prompt plausibly
- * answers it. Typing in the terminal is not by itself a resolution: the User
- * may be answering a different question on a device.
- */
-export declare function handleUserPromptSubmit(ctx: HookContext, envelope: HookEnvelope): Promise<HookOutcome>;
-/**
- * Only engages for a question the agent explicitly registered with
- * `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, route?: EscalationDeliveryRoute, recordStop?: boolean): 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
- * first moves anything still live on the user's devices into the global
- * retirement queue, because this file was the only record of those ids and no
- * hook for this session will ever run again. A question whose
- * agent just exited can receive no answer, so it is orphaned as `expired`.
- */
-export declare function handleSessionEnd(env: NodeJS.ProcessEnv, envelope: HookEnvelope, now?: number): HookOutcome;
-/**
- * Registrations still waiting for their first push. More than this in one turn
- * means an agent is looping, not asking, and related questions belong in one
- * `ask --form` instead.
- *
- * Deliberately counts only unasked entries. A question already on the user's
- * devices is waiting on a person, not on the agent, and an answer stays
- * accepted for a day — so counting live questions here would have turned a
- * patient user into a reason the agent could no longer ask anything.
- */
-export declare const MAX_PENDING_QUESTIONS = 4;
-/**
- * Everything this session has open at once, asked or not. The lock screen is
- * the shared resource being protected here, not the agent's turn.
- */
-export declare const MAX_LIVE_QUESTIONS = 10;
-/**
- * A session may hold several registered questions at once: a new `ask` never
- * ends an earlier one. Each reaches the user as its own notification and is
- * answerable independently. Superseding is reply semantics — a later reply
- * corrects an earlier reply to the same question (that correction model lives
- * server-side) — never question semantics: the old single-slot model silently
- * discarded a question the moment a second was registered, and the user was
- * pointed at a notification that never existed (2026-08-09).
- *
- * The queue is keyed on the session, not the project: several agents may be
- * running in one project at once, and their questions must never interfere.
- */
-export declare function registerQuestion(sessionId: string, env: NodeJS.ProcessEnv, question: PendingQuestion, now?: number): string;
-/** Parses hook JSON from stdin, tolerating an empty or malformed body. */
-export declare function parseHookInput(raw: string): HookEnvelope;
-export declare function resolveHookConfig(cwd: string, env: NodeJS.ProcessEnv, sessionId: string | undefined): CliConfig;
-export {};

package/dist/hook-types.js

@@ -0,0 +1,4 @@
+import {} from './client.js';
+import {} from './config.js';
+import {} from './harnesses.js';
+//# sourceMappingURL=hook-types.js.map

package/dist/hook-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-types.js","sourceRoot":"","sources":["../src/hook-types.ts"],"names":[],"mappings":"AASA,OAAO,EAAkB,MAAM,aAAa,CAAA;AAC5C,OAAO,EAAkB,MAAM,aAAa,CAAA;AAC5C,OAAO,EAAmD,MAAM,gBAAgB,CAAA"}