@raidiant/notifai 8.0.0 → 9.0.0

package/dist/hooks.js

@@ -74,6 +74,13 @@ export function waiterCeilingSeconds(detached) {
  * server go on taking an answer after the waiter that owns it has returned.
  */
 export 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 const FINALIZATION_NETWORK_BUDGET_SECONDS = 3;
 /**
  * The terminal-first wait: the question sits in the terminal for
  * `ask_grace_seconds` from when it was sent, and only then reaches companion
@@ -140,6 +147,81 @@ function updateSessionState(sessionId, env, update) {
         return next;
     });
 }
+/** Record a lifecycle activation so the first-prompt compatibility path stays silent. */
+export function markSessionActivation(sessionId, env, now, ownerPid) {
+    updateSessionState(sessionId, env, (current) => ({
+        ...current,
+        activation_context_emitted_at: now,
+        activation_context_owner_pid: ownerPid,
+    }));
+}
+/**
+ * Atomically own first-prompt activation only when no lifecycle hook did.
+ *
+ * Some managed hosts preserve UserPromptSubmit while regenerating away newer
+ * SessionStart definitions. This is a compatibility seam, not the primary
+ * lifecycle: one session gets at most one model-visible activation from it.
+ */
+export function claimPromptActivation(sessionId, env, now, ownerPid) {
+    let claimed = false;
+    updateSessionState(sessionId, env, (current) => {
+        if (current.activation_context_emitted_at !== undefined &&
+            current.activation_context_owner_pid === ownerPid) {
+            return current;
+        }
+        claimed = true;
+        return {
+            ...current,
+            activation_context_emitted_at: now,
+            activation_context_owner_pid: ownerPid,
+        };
+    });
+    return claimed;
+}
+/** 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.
  *
@@ -527,7 +609,6 @@ async function prepareQuestionSubmission(ctx, options) {
     const build = buildDraft(ctx.config, {
         title: options.title,
         body: options.body,
-        event: options.event,
         lifecycle: { tier: 'needs_you' },
         ...(options.project !== undefined ? { project: options.project } : {}),
         ...(options.media !== undefined ? { media: options.media } : {}),
@@ -573,6 +654,9 @@ async function waitForAnyReply(ctx, requestIds, timeoutSeconds) {
     let degraded = false;
     let firstPoll = true;
     const permanentFailures = new Map();
+    if (timeoutSeconds <= 0 || deadline <= ctx.now()) {
+        return { byRequest: new Map(), degraded: false, permanentFailures };
+    }
     for (;;) {
         const remainingMs = Math.max(0, deadline - ctx.now());
         if (!firstPoll && remainingMs === 0) {
@@ -657,45 +741,20 @@ async function closeQuietly(ctx, requestId) {
     await finalizeReplies(ctx, requestId);
 }
 /**
- * Retire the question on every device it reached. A state change is not news
- * (D-B): the retirement rides as a background state sync — no alert, no
- * sound — carrying the shared collapse key so the companion removes the
- * delivered question and marks it done. If the app cannot run, the stale
- * question simply waits until next open, which beats a tombstone banner
- * announcing what the user just did.
+ * Close the reply window so the server can mint the retirement push. Client
+ * submissions cannot carry `question_retired`; that event is reserved for
+ * server-origin state syncs.
  */
-async function retire(ctx, collapseKey, title, body, endState, retiresRequestId, devices, project, source) {
-    const build = buildDraft(ctx.config, {
-        title,
-        body,
-        event: 'question_retired',
-        lifecycle: { tier: 'done', state: endState, retires_request_id: retiresRequestId },
-        ...(project !== undefined ? { project } : {}),
-        ...(devices !== undefined && devices.length > 0 ? { device: devices } : {}),
-        collapseKey,
-        level: 'passive',
-    }, source === undefined ? {} : { source });
-    if (!build.ok)
-        return false;
-    try {
-        await ctx.client.submit({ idempotency_key: `retire-${randomBytes(12).toString('base64url')}`, draft: build.draft }, 0);
-        return true;
-    }
-    catch {
-        // Same reasoning as closeQuietly: the window is already closed server-side.
-        return false;
-    }
+async function proveRetirement(ctx, requestId) {
+    const response = await finalizeReplies(ctx, requestId);
+    const proven = response !== null;
+    ctx.log?.info('hook.retirement', {
+        request_id: requestId,
+        attempted: true,
+        proven,
+    });
+    return proven;
 }
-/**
- * The title a retirement carries. It is never rendered as a banner — the push
- * is `content-available` only — but it is what a companion with no matching
- * history entry has to fall back on, and it is what shows in server-side logs.
- */
-const RETIREMENT_TITLES = {
-    answered: 'Answered',
-    answered_elsewhere: 'Answered in the terminal',
-    expired: 'Question expired',
-};
 /**
  * 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.
@@ -749,11 +808,36 @@ function retiringQuestion(pending, state, cwd) {
         state,
     };
 }
-function retirementDeviceIds(entry) {
-    if (!Array.isArray(entry.device_ids) || entry.device_ids.length === 0) {
-        throw new Error(`retirement for ${entry.request_id} is missing its device identifiers; refusing to re-resolve routing`);
-    }
-    return entry.device_ids;
+const SHORT_CONFIRMATIONS = new Set(['done', 'yes', 'y', 'no', 'n', 'ok', 'okay']);
+function normalizePrompt(value) {
+    return value.trim().replace(/\s+/g, ' ').toLowerCase();
+}
+function pendingChoiceLabels(pending) {
+    const fromQuestions = (pending.questions ?? []).flatMap((question) => (question.choices ?? []).flatMap((choice) => [choice.label, choice.id]));
+    return fromQuestions.map(normalizePrompt).filter((label) => label.length > 0);
+}
+function pendingHasMatchingChoice(pending, normalizedPrompt) {
+    return pendingChoiceLabels(pending).includes(normalizedPrompt);
+}
+/**
+ * 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 function pendingAnsweredByPrompt(prompt, pending) {
+    const normalized = normalizePrompt(prompt ?? '');
+    if (normalized.length === 0 || pending.length === 0)
+        return [];
+    const labelled = pending.filter((entry) => pendingHasMatchingChoice(entry, normalized));
+    if (labelled.length === 1)
+        return labelled;
+    if (labelled.length > 1)
+        return [];
+    if (pending.length === 1 && SHORT_CONFIRMATIONS.has(normalized))
+        return [...pending];
+    return [];
 }
 /**
  * Send every parked retirement, and forget the ones that landed. A failure
@@ -766,9 +850,8 @@ export async function drainRetirements(ctx, sessionId, env) {
         return [];
     const retired = [];
     for (const entry of queue) {
-        await closeQuietly(ctx, entry.request_id);
-        const sent = await retire(ctx, entry.collapse_key, RETIREMENT_TITLES[entry.state], entry.question, entry.state, entry.request_id, retirementDeviceIds(entry), entry.project, entry.source);
-        if (sent) {
+        const proven = await proveRetirement(ctx, entry.request_id);
+        if (proven) {
             retired.push(entry.request_id);
             // Persist each success before touching the next entry. A later corrupt
             // record or interrupted process must not resurrect work already done.
@@ -837,9 +920,8 @@ export async function drainOrphanRetirements(ctx, env, now) {
             updateOrphanQueue(env, (current) => current.filter((candidate) => candidate.request_id !== entry.request_id));
             continue;
         }
-        await closeQuietly(ctx, entry.request_id);
-        const sent = await retire(ctx, entry.collapse_key, RETIREMENT_TITLES[entry.state], entry.question, entry.state, entry.request_id, retirementDeviceIds(entry), entry.project, entry.source);
-        if (sent) {
+        const proven = await proveRetirement(ctx, entry.request_id);
+        if (proven) {
             done.push(entry.request_id);
             updateOrphanQueue(env, (current) => current.filter((candidate) => candidate.request_id !== entry.request_id));
         }
@@ -893,10 +975,15 @@ async function pollPendingReply(ctx, pending, timeoutSeconds) {
 }
 /** Close several windows concurrently without confusing failure with silence. */
 async function finalizePendings(ctx, pending) {
-    return Promise.all(pending.map(async (entry) => ({
-        pending: entry,
-        response: await finalizeReplies(ctx, entry.request_id),
-    })));
+    return Promise.all(pending.map(async (entry) => {
+        const response = await finalizeReplies(ctx, entry.request_id);
+        ctx.log?.info('hook.retirement', {
+            request_id: entry.request_id,
+            attempted: true,
+            proven: response !== null,
+        });
+        return { pending: entry, response };
+    }));
 }
 /** Convert a fenced final reply set into the exact answer handed to the model. */
 function finalizedAnswer(finalized) {
@@ -920,7 +1007,7 @@ function reportAnswer(ctx, notes, answered, late) {
         ...(late ? { late: true } : {}),
         request_id: answered.pending.request_id,
         device: answered.reply.device_name,
-        text: answered.reply.text,
+        text_chars: answered.reply.text.length,
     });
     notes.push(`${late ? 'late ' : ''}answer from ${answered.reply.device_name}: ${answered.reply.text}`);
 }
@@ -964,7 +1051,7 @@ function isSamePending(a, b) {
 function isTerminalDraftRejection(err) {
     return err.status === 422 || (err.status === 400 && err.code === 'invalid_request');
 }
-function dropPendingQuestion(sessionId, env, entry) {
+export function dropPendingQuestion(sessionId, env, entry) {
     updateSessionState(sessionId, env, (current) => {
         const pending = pendingList(current).filter((candidate) => !isSamePending(candidate, entry));
         const next = { ...current };
@@ -975,6 +1062,28 @@ function dropPendingQuestion(sessionId, env, entry) {
         return next;
     });
 }
+/**
+ * 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 function withdrawUnpushedQuestions(sessionId, env) {
+    let withdrawn = [];
+    updateSessionState(sessionId, env, (current) => {
+        const pending = pendingList(current);
+        withdrawn = pending.filter((entry) => entry.request_id === undefined);
+        if (withdrawn.length === 0)
+            return current;
+        const remaining = pending.filter((entry) => entry.request_id !== undefined);
+        const next = { ...current };
+        if (remaining.length > 0)
+            next.pending = remaining;
+        else
+            delete next.pending;
+        return next;
+    });
+    return withdrawn;
+}
 function clearFrozenSubmission(sessionId, env, entry) {
     updateSessionState(sessionId, env, (current) => {
         const list = pendingList(current);
@@ -1308,10 +1417,9 @@ async function retirePendings(ctx, envelope, sessionId, entries, state) {
 // UserPromptSubmit — the user is at the keyboard
 // ---------------------------------------------------------------------------
 /**
- * Records presence and retires anything still asking on companion devices. This is the
- * "answered in the terminal" case from the original design: we cannot tell
- * whether the new prompt answers the question, but we do not need to — the
- * user being here is what makes the notification noise.
+ * 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 async function handleUserPromptSubmit(ctx, envelope) {
     const notes = [];
@@ -1365,24 +1473,41 @@ export async function handleUserPromptSubmit(ctx, envelope) {
         if (permanentFailure !== null)
             notes.push(permanentFailure);
     }
+    const matched = pendingAnsweredByPrompt(envelope.prompt, pendingList(state));
+    for (const entry of matched) {
+        ctx.log?.info('hook.retirement', {
+            request_id: entry.request_id,
+            question_id: entry.question_id,
+            reason: 'prompt-matched',
+            attempted: entry.request_id !== undefined,
+            proven: false,
+        });
+    }
     // Park before dropping `pending`. If the process dies between these writes,
     // the next hook sees both copies and dedupes them; the old order could die in
     // the gap after erasing the only request/collapse/device identifiers.
     updateSessionState(sessionId, ctx.env, (current) => {
         const retiring = [...(current.retiring ?? [])];
-        const unasked = pendingList(current).filter((entry) => entry.request_id === undefined);
-        for (const entry of pendingList(current).filter((entry) => entry.request_id !== undefined)) {
+        const matchedNow = pendingAnsweredByPrompt(envelope.prompt, pendingList(current));
+        const unmatched = pendingList(current).filter((entry) => !matchedNow.some((item) => isSamePending(item, entry)));
+        for (const entry of matchedNow.filter((item) => item.request_id !== undefined)) {
             const retirement = retiringQuestion(entry, 'answered_elsewhere', envelope.cwd);
             if (retirement !== null &&
                 !retiring.some((parked) => parked.request_id === retirement.request_id)) {
                 retiring.push(retirement);
             }
         }
+        const unasked = unmatched.filter((entry) => entry.request_id === undefined);
+        const stillLive = unmatched.filter((entry) => entry.request_id !== undefined);
+        const remaining = [...stillLive, ...unasked];
         // Start from the whole document so fields introduced by a newer CLI remain
         // attached while this older writer applies the prompt transition it knows.
-        const next = { ...current, last_prompt_at: ctx.now() };
-        if (unasked.length > 0)
-            next.pending = unasked;
+        const next = {
+            ...current,
+            last_prompt_at: ctx.now(),
+        };
+        if (remaining.length > 0)
+            next.pending = remaining;
         else
             delete next.pending;
         if (retiring.length > 0)
@@ -1661,6 +1786,10 @@ async function deliverAcceptedAnswers(ctx, sessionId, route, accepted, notes, cw
         outcome.log = delivered.log;
     return outcome;
 }
+/** True while this Stop owner is still allowed a direct-wake wait. */
+function ownerLeaseActive(entry, now) {
+    return entry.owner_deadline_at !== undefined && entry.owner_deadline_at > now;
+}
 /** The complete per-session Stop decision, after this process owns the claim. */
 async function handleClaimedStop(ctx, envelope, sessionId, state, pending, notes, hardDeadlineAt, route, continuingFromAnswer) {
     const live = pending.filter((entry) => entry.request_id !== undefined);
@@ -1715,18 +1844,34 @@ async function handleClaimedStop(ctx, envelope, sessionId, state, pending, notes
             return deliverAcceptedAnswers(ctx, sessionId, route, accepted, notes, envelope.cwd);
         }
         const recoverableLive = live.filter((entry) => !permanentFailures.has(entry.request_id));
-        liveToEscalate = recoverableLive;
+        // A spent owner has already used its waiter ceiling. Passing those
+        // questions back into `escalate` starts a fresh ceiling, holds the
+        // per-session claim for another 3300s, and is why a later `ask` never
+        // reached a device after a degraded waiter (the next Stop never ran, or
+        // ran as claimed-elsewhere). Late answers still ride the short poll above
+        // and every later turn. Independent questions whose lease is still running
+        // keep their successor wait.
+        const stillOwned = recoverableLive.filter((entry) => ownerLeaseActive(entry, ctx.now()));
+        liveToEscalate = stillOwned;
         if (unasked.length === 0) {
             if (recoverableLive.length === 0)
                 return { notes };
-            // A previous answer may have resumed the model while independent
-            // questions remain. The next Stop is their successor owner: keep waiting
-            // to the original absolute deadline instead of polling for four seconds
-            // and abandoning them.
-            return await escalate(ctx, envelope, sessionId, [], recoverableLive, notes, hardDeadlineAt, route);
+            if (stillOwned.length === 0) {
+                const requestIdSummary = summarizeRequestIds(recoverableLive);
+                ctx.log?.info('hook.answer', {
+                    answered: false,
+                    stage: 'queued',
+                    request_ids: requestIdSummary.ids,
+                    owner_spent: true,
+                });
+                notes.push(`${recoverableLive.length} question${recoverableLive.length === 1 ? ' is' : 's are'} still answerable; the previous waiter already used its ceiling, so a later turn will collect a late answer rather than waiting again`);
+                return { notes };
+            }
+            return await escalate(ctx, envelope, sessionId, [], stillOwned, notes, hardDeadlineAt, route);
         }
         // Questions registered after the earlier push still owe the user their
-        // notification; fall through and escalate just those.
+        // notification; fall through and escalate just those, plus any live
+        // question whose owner lease is still running.
     }
     // A Stop answer may immediately produce a legitimate follow-up question.
     // Allow that new generation, but never re-run an old pending question and
@@ -1830,7 +1975,6 @@ async function escalate(ctx, envelope, sessionId, unasked, alreadyLive, notes, h
                 ...(entry.media !== undefined ? { media: entry.media } : {}),
                 ...(entry.project !== undefined ? { project: entry.project } : {}),
                 ...(eventSource !== undefined ? { source: eventSource } : {}),
-                event: 'agent_question',
                 windowSeconds: replyWindowSeconds,
                 ownerDeadlineAt,
             });
@@ -1909,7 +2053,6 @@ async function escalate(ctx, envelope, sessionId, unasked, alreadyLive, notes, h
                         ...(entry.media !== undefined ? { media: entry.media } : {}),
                         ...(entry.project !== undefined ? { project: entry.project } : {}),
                         ...(eventSource !== undefined ? { source: eventSource } : {}),
-                        event: 'agent_question',
                         windowSeconds: replyWindowSeconds,
                         ownerDeadlineAt,
                     });
@@ -1976,7 +2119,7 @@ async function escalate(ctx, envelope, sessionId, unasked, alreadyLive, notes, h
                 request_id: intent.request_id,
                 devices: intent.device_ids.length,
                 questions: questions.length,
-                text: questions[0].text,
+                text_chars: questions[0].text.length,
             });
         }
         const committedReplyDeadline = receipt?.reply_expires_at === null || receipt?.reply_expires_at === undefined
@@ -1995,14 +2138,14 @@ async function escalate(ctx, envelope, sessionId, unasked, alreadyLive, notes, h
             // stale about eight minutes later and retired, so the answer given over
             // lunch met a closed question.
             //
-            // Both consumers of this field already clamp to the owner's own ceiling
-            // (`Math.min(hardDeadlineAt, …)` when deriving the ceiling, and
-            // `Math.min(ceilingAt, …)` when deriving the wait), so recording the
-            // real expiry here lengthens what the user gets without lengthening what
-            // this process waits.
+            // The reply window is how long the server accepts an answer. This
+            // process still clamps its own wait to `hardDeadlineAt`. Recording the
+            // owner lease separately is what stops the *next* Stop from treating
+            // the remaining window as a fresh waiter ceiling.
             reply_deadline_at: Number.isFinite(committedReplyDeadline)
                 ? committedReplyDeadline
                 : intent.owner_deadline_at,
+            owner_deadline_at: intent.owner_deadline_at,
         };
         if (intent.draft.source === undefined)
             delete live.source;
@@ -2065,7 +2208,8 @@ async function escalate(ctx, envelope, sessionId, unasked, alreadyLive, notes, h
         return { notes };
     // Phase two: one wait across everything live, old and new alike.
     const ownerDeadline = Math.min(ceilingAt, Math.max(...waitingOn.map((entry) => entry.reply_deadline_at)));
-    const timeoutSeconds = Math.max(0, Math.ceil((ownerDeadline - ctx.now()) / 1000));
+    const waitUntil = ownerDeadline - FINALIZATION_NETWORK_BUDGET_SECONDS * 1000;
+    const timeoutSeconds = Math.max(0, Math.ceil((waitUntil - ctx.now()) / 1000));
     const waited = await waitForAnyReply(ctx, waitingOn.map((entry) => entry.request_id), timeoutSeconds);
     const permanentFailure = permanentReplyFailureNote(waited.permanentFailures);
     if (permanentFailure !== null)
@@ -2087,7 +2231,7 @@ async function escalate(ctx, envelope, sessionId, unasked, alreadyLive, notes, h
         // ends still retires its questions — that is what the session-end hook is
         // for, and it is the honest place for it.
         const expired = waitingOn.filter((entry) => entry.reply_deadline_at === undefined ||
-            entry.reply_deadline_at <= ctx.now() ||
+            entry.reply_deadline_at <= ownerDeadline ||
             // A permanent rejection is the server saying this question can never be
             // answered, whatever its window says. Leaving it open would strand a
             // dead question on the user's devices.
@@ -2126,9 +2270,9 @@ async function escalate(ctx, envelope, sessionId, unasked, alreadyLive, notes, h
             permanent_failures: waited.permanentFailures.size,
             waited_seconds: timeoutSeconds,
         });
-        if (waited.permanentFailures.size === 0) {
+        if (waited.permanentFailures.size === 0 && confirmedSilent.length > 0) {
             notes.push(waited.degraded
-                ? 'could not reach the server before the owner deadline; the question was retired so no answer can be lost later'
+                ? 'could not reach the server before the owner deadline; expired questions were retired so no answer can be lost later'
                 : 'no answer in time; the question expired with its continuation owner');
         }
         return { notes };
@@ -2260,6 +2404,7 @@ export const MAX_LIVE_QUESTIONS = 10;
  */
 export function registerQuestion(sessionId, env, question, now = Date.now()) {
     let full = null;
+    const questionId = question.question_id ?? `q_${randomBytes(12).toString('base64url')}`;
     updateSessionState(sessionId, env, (state) => {
         const pending = pendingList(state);
         const unasked = pending.filter((entry) => entry.request_id === undefined);
@@ -2276,9 +2421,9 @@ export function registerQuestion(sessionId, env, question, now = Date.now()) {
             pending: [
                 ...pending,
                 {
-                    question_id: `q_${randomBytes(12).toString('base64url')}`,
                     asked_at: now,
                     ...question,
+                    question_id: questionId,
                     question: question.question.slice(0, MAX_STORED_QUESTION_CHARS),
                 },
             ],
@@ -2290,8 +2435,9 @@ export function registerQuestion(sessionId, env, question, now = Date.now()) {
     }
     if (full === 'live') {
         throw new Error(`${MAX_LIVE_QUESTIONS} questions from this session are already open. ` +
-            'Retire the ones you no longer need with `notifai close <request_id>` before asking another.');
+            'Retire the ones you no longer need with `notifai close <question_id>` or `notifai close --pending` before asking another.');
     }
+    return questionId;
 }
 /** Parses hook JSON from stdin, tolerating an empty or malformed body. */
 export function parseHookInput(raw) {