@raidiant/notifai 10.1.7 → 11.0.2

package/dist/hook-events.js

@@ -0,0 +1,22 @@
+/** Canonical lifecycle event vocabulary shared by installation and execution. */
+import {} from './harnesses.js';
+// ---------------------------------------------------------------------------
+// hook / ask / close — harness integration
+// ---------------------------------------------------------------------------
+export const HOOK_EVENTS = [
+    'session-start',
+    'subagent-start',
+    'activation-stop',
+    'user-prompt-submit',
+    'stop',
+    'session-end',
+];
+/** Lifecycle handlers one installed harness must carry in this CLI build. */
+export function requiredHookEvents(harness) {
+    if (harness === 'opencode' || harness === 'openclaw')
+        return [];
+    return harness === 'cursor'
+        ? ['session-start', 'activation-stop', 'user-prompt-submit', 'stop', 'session-end']
+        : ['session-start', 'subagent-start', 'user-prompt-submit', 'stop', 'session-end'];
+}
+//# sourceMappingURL=hook-events.js.map

package/dist/hook-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-events.js","sourceRoot":"","sources":["../src/hook-events.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,OAAO,EAA+B,MAAM,gBAAgB,CAAA;AAE5D,8EAA8E;AAC9E,2CAA2C;AAC3C,8EAA8E;AAE9E,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,eAAe;IACf,gBAAgB;IAChB,iBAAiB;IACjB,oBAAoB;IACpB,MAAM;IACN,aAAa;CACL,CAAA;AAIV,6EAA6E;AAC7E,MAAM,UAAU,kBAAkB,CAAC,OAA+B;IAChE,IAAI,OAAO,KAAK,UAAU,IAAI,OAAO,KAAK,UAAU;QAAE,OAAO,EAAE,CAAA;IAC/D,OAAO,OAAO,KAAK,QAAQ;QACzB,CAAC,CAAC,CAAC,eAAe,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,EAAE,aAAa,CAAC;QACnF,CAAC,CAAC,CAAC,eAAe,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,EAAE,aAAa,CAAC,CAAA;AACtF,CAAC"}

package/dist/hook-gates.d.ts

@@ -0,0 +1,7 @@
+/** Structured gate decisions shared by lifecycle and acknowledgement handling. */
+import type { HookContext } from './hook-types.js';
+/** Runtime vocabulary for every recorded question gate. */
+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"];
+export type GateReason = (typeof GATE_REASONS)[number];
+/** Record one gate decision using a stable reason agents can filter on. */
+export declare function gate(ctx: HookContext, verdict: 'held' | 'proceeding', reason: GateReason, data?: Record<string, unknown>): void;

package/dist/hook-gates.js

@@ -0,0 +1,21 @@
+/** Runtime vocabulary for every recorded question gate. */
+export const GATE_REASONS = [
+    'no-session',
+    'no-question',
+    'answered',
+    'continuation-repeat',
+    'continuation-limit',
+    'delivery-limit',
+    'acknowledgement-required',
+    'acknowledgement-abandoned',
+    'harness-cannot-continue',
+    'notifications-off',
+    'claimed-elsewhere',
+    'elapsed',
+    'proceeding',
+];
+/** Record one gate decision using a stable reason agents can filter on. */
+export function gate(ctx, verdict, reason, data = {}) {
+    ctx.log?.info('hook.gate', { verdict, reason, stage: 'queued', ...data });
+}
+//# sourceMappingURL=hook-gates.js.map

package/dist/hook-gates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-gates.js","sourceRoot":"","sources":["../src/hook-gates.ts"],"names":[],"mappings":"AAGA,2DAA2D;AAC3D,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,YAAY;IACZ,aAAa;IACb,UAAU;IACV,qBAAqB;IACrB,oBAAoB;IACpB,gBAAgB;IAChB,0BAA0B;IAC1B,2BAA2B;IAC3B,yBAAyB;IACzB,mBAAmB;IACnB,mBAAmB;IACnB,SAAS;IACT,YAAY;CACJ,CAAA;AAIV,2EAA2E;AAC3E,MAAM,UAAU,IAAI,CAClB,GAAgB,EAChB,OAA8B,EAC9B,MAAkB,EAClB,OAAgC,EAAE;IAElC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,WAAW,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,CAAC,CAAA;AAC3E,CAAC"}

package/dist/hook-lifecycle.d.ts

@@ -0,0 +1,93 @@
+import type { EscalationDeliveryRoute, EscalationWaiterOptions, HookContext, HookEnvelope, HookOutcome, PendingQuestion } from './hook-types.js';
+/**
+ * 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;
+/**
+ * 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;
+/**
+ * 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;