@raidiant/notifai 1.1.0 → 2.0.0

package/dist/hooks.d.ts

@@ -76,6 +76,17 @@ export interface SessionState {
      * reaches the harness replays it instead of erasing it.
      */
     accepted?: AcceptedAnswerDelivery;
+    /**
+     * Required Agent Acknowledgements that the resumed agent still owes. This is
+     * separate from answer delivery: the answer journal may settle as soon as a
+     * harness accepts the continuation, while this obligation must survive until
+     * the service confirms the agent-authored follow-up exists.
+     */
+    acknowledgement_due?: AcknowledgementDue[];
+}
+export interface AcknowledgementDue {
+    request_id: string;
+    recorded_at: number;
 }
 interface AcceptedAnswerDelivery {
     answers: AnsweredPending[];
@@ -288,7 +299,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' | 'delivery-limit' | 'notifications-off' | 'claimed-elsewhere' | 'no-devices' | 'proceeding';
+export type GateReason = 'no-session' | 'no-question' | 'answered' | 'already-asked' | 'continuation-repeat' | 'continuation-limit' | 'delivery-limit' | 'acknowledgement-required' | 'notifications-off' | 'claimed-elsewhere' | 'no-devices' | 'proceeding';
 export type HookHarness = Harness;
 /**
  * Everything retirement needs. Narrower than a HookContext on purpose:
@@ -331,7 +342,10 @@ interface AnsweredPending {
     pending: PendingQuestion;
     reply: ReplyView;
     replies: ReplyView[];
+    /** Immutable server snapshot for this request, known after a replies/close response. */
+    agent_acknowledgement_required?: boolean | undefined;
 }
+export declare function clearAcknowledgementObligation(sessionId: string, env: NodeJS.ProcessEnv, requestId: string): boolean;
 /**
  * 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

package/dist/hooks.js

@@ -541,7 +541,7 @@ async function answerableDevices(ctx) {
     return devices
         .filter((device) => (device.platform === 'ios' || device.platform === 'macos') &&
         device.registration_healthy &&
-        device.reply_protocol_version === 1)
+        device.reply_protocol_version === 2)
         .filter((device) => configured === null || configured.includes(device.device_id))
         .map((device) => device.device_id);
 }
@@ -814,7 +814,14 @@ async function finalizePendings(ctx, pending) {
 function finalizedAnswer(finalized) {
     const replies = finalized.response?.replies ?? [];
     const reply = replies.at(-1);
-    return reply === undefined ? null : { pending: finalized.pending, reply, replies };
+    return reply === undefined
+        ? null
+        : {
+            pending: finalized.pending,
+            reply,
+            replies,
+            agent_acknowledgement_required: finalized.response?.agent_acknowledgement_required,
+        };
 }
 /** Persist and surface one answer without letting the two representations drift. */
 function reportAnswer(ctx, notes, answered, late) {
@@ -902,12 +909,35 @@ function answerContext(answered) {
  * tied to the question that asked it, with a truthful note about anything
  * still waiting.
  */
+function acknowledgementCommand(requestId) {
+    return `notifai acknowledge ${requestId} --text <text>`;
+}
+function acknowledgementContext(answered) {
+    const due = answered.filter((entry) => entry.agent_acknowledgement_required === true && entry.pending.request_id !== undefined);
+    if (due.length === 0) {
+        return ' Agent Acknowledgement is not required for the answered request(s).';
+    }
+    if (due.length === 1) {
+        const requestId = due[0].pending.request_id;
+        return (` Agent Acknowledgement is required for request ${requestId}. Immediately, before doing the resumed work or ending this turn, run ` +
+            `\`${acknowledgementCommand(requestId)}\` with non-empty text saying what concrete work you will do because of the reply; a bare acknowledgement is insufficient.`);
+    }
+    const commands = due
+        .map((entry) => {
+        const requestId = entry.pending.request_id;
+        return `- ${requestId}: \`${acknowledgementCommand(requestId)}\``;
+    })
+        .join('\n');
+    return (` Agent Acknowledgement is required for ${due.length} requests. Immediately, before doing the resumed work or ending this turn, run every command below with non-empty text saying what concrete work you will do because of that reply; a bare acknowledgement is insufficient:\n` +
+        commands);
+}
 function answersContext(answered, remaining) {
     const tail = remaining > 0
         ? ` (${remaining} more registered question${remaining === 1 ? ' is' : 's are'} still waiting for an answer.)`
         : '';
+    const guidance = acknowledgementContext(answered);
     if (answered.length === 1) {
-        return answerContext(answered[0]) + tail;
+        return answerContext(answered[0]) + tail + guidance;
     }
     const lines = answered.map(({ pending, replies }) => {
         const latest = replies.at(-1);
@@ -918,7 +948,7 @@ function answersContext(answered, remaining) {
         const identity = ids.length === 0 ? '' : `question_id${ids.length === 1 ? '' : 's'} ${ids.join(', ')}: `;
         return `- ${identity}${JSON.stringify(pending.question)} → ${answer}`;
     });
-    return `Notifai — the user answered ${answered.length} questions:\n${lines.join('\n')}${tail}`;
+    return `Notifai — the user answered ${answered.length} questions:\n${lines.join('\n')}${tail}${guidance}`;
 }
 function stopAnswerOutput(context) {
     return JSON.stringify({
@@ -940,6 +970,15 @@ function stageAcceptedAnswers(ctx, sessionId, answered, remaining) {
     };
     updateSessionState(sessionId, ctx.env, (current) => {
         const pendingRemaining = pendingList(current).filter((entry) => !answered.some(({ pending }) => isSamePending(entry, pending)));
+        const acknowledgementDue = [...(current.acknowledgement_due ?? [])];
+        for (const answer of answered) {
+            const requestId = answer.pending.request_id;
+            if (answer.agent_acknowledgement_required === true &&
+                requestId !== undefined &&
+                !acknowledgementDue.some((entry) => entry.request_id === requestId)) {
+                acknowledgementDue.push({ request_id: requestId, recorded_at: accepted.recorded_at });
+            }
+        }
         const next = {
             ...current,
             accepted,
@@ -948,6 +987,10 @@ function stageAcceptedAnswers(ctx, sessionId, answered, remaining) {
             next.pending = pendingRemaining;
         else
             delete next.pending;
+        if (acknowledgementDue.length > 0)
+            next.acknowledgement_due = acknowledgementDue;
+        else
+            delete next.acknowledgement_due;
         return next;
     });
     return accepted;
@@ -956,6 +999,58 @@ function stageAcceptedAnswers(ctx, sessionId, answered, remaining) {
 function amendAcceptedAnswers(ctx, sessionId, amend) {
     updateSessionState(sessionId, ctx.env, (current) => current.accepted === undefined ? current : { ...current, accepted: amend(current.accepted) });
 }
+export function clearAcknowledgementObligation(sessionId, env, requestId) {
+    let cleared = false;
+    updateSessionState(sessionId, env, (current) => {
+        const due = current.acknowledgement_due ?? [];
+        const remaining = due.filter((entry) => entry.request_id !== requestId);
+        cleared = remaining.length !== due.length;
+        if (!cleared)
+            return current;
+        const next = { ...current };
+        if (remaining.length > 0)
+            next.acknowledgement_due = remaining;
+        else
+            delete next.acknowledgement_due;
+        return next;
+    });
+    return cleared;
+}
+function acknowledgementBlockContext(due) {
+    const commands = due
+        .map((entry) => `- ${entry.request_id}: \`${acknowledgementCommand(entry.request_id)}\``)
+        .join('\n');
+    return (`Notifai — required Agent Acknowledgement${due.length === 1 ? '' : 's'} still missing for request${due.length === 1 ? '' : 's'} ${due.map((entry) => entry.request_id).join(', ')}. ` +
+        `Before doing more resumed work or ending this turn, run ${due.length === 1 ? 'this command' : 'every command'} with non-empty text saying what concrete work you will do because of the reply; a bare acknowledgement is insufficient:\n${commands}`);
+}
+async function reconcileAcknowledgementObligations(ctx, sessionId, due) {
+    const unresolved = [];
+    for (const obligation of due) {
+        try {
+            const snapshot = await ctx.client.agentAcknowledgement(obligation.request_id, {
+                waitSeconds: 0,
+            });
+            if (snapshot.agent_acknowledgement_required === false ||
+                snapshot.agent_acknowledgement !== null) {
+                clearAcknowledgementObligation(sessionId, ctx.env, obligation.request_id);
+            }
+            else {
+                unresolved.push(obligation);
+            }
+        }
+        catch (err) {
+            unresolved.push(obligation);
+            ctx.log?.error('hook.gate', {
+                verdict: 'held',
+                reason: 'acknowledgement-required',
+                stage: 'reconcile-failed',
+                request_id: obligation.request_id,
+                message: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    return unresolved;
+}
 /**
  * Retire the answered questions and close the journal.
  *
@@ -1050,7 +1145,13 @@ export async function handleUserPromptSubmit(ctx, envelope) {
             if (response === null) {
                 notes.push(`could not confirm the close fence for ${entry.pending.request_id}; preserving the durable answer already observed`);
             }
-            return { ...entry, replies, reply: replies.at(-1) };
+            return {
+                ...entry,
+                replies,
+                reply: replies.at(-1),
+                agent_acknowledgement_required: response?.agent_acknowledgement_required ??
+                    entry.agent_acknowledgement_required,
+            };
         });
         if (answered.length > 0) {
             stageAcceptedAnswers(ctx, sessionId, lateAnswers, 0);
@@ -1164,6 +1265,23 @@ export async function runEscalationWaiter(ctx, options) {
         let state = readSessionState(sessionId, ctx.env);
         if (state.accepted !== undefined) {
             const accepted = state.accepted;
+            if (envelope.stop_hook_active === true && pendingList(state).length > 0) {
+                const due = await reconcileAcknowledgementObligations(ctx, sessionId, state.acknowledgement_due ?? []);
+                if (due.length > 0) {
+                    gate(ctx, 'held', 'acknowledgement-required', {
+                        request_ids: due.map((entry) => entry.request_id),
+                    });
+                    return {
+                        stdout: stopAnswerOutput(acknowledgementBlockContext(due)),
+                        notes,
+                        log: {
+                            stage: 'acknowledgement-required',
+                            request_ids: due.map((entry) => entry.request_id),
+                        },
+                    };
+                }
+                state = readSessionState(sessionId, ctx.env);
+            }
             // Acknowledgement is per route, because routes end in different places.
             //
             // A blocking continuation ends at this process's stdout, which the
@@ -1184,6 +1302,39 @@ export async function runEscalationWaiter(ctx, options) {
             settleAcceptedAnswers(ctx, sessionId, accepted);
             settledAnswerThisPass = true;
             state = readSessionState(sessionId, ctx.env);
+            const currentAcceptedIds = new Set(accepted.answers.flatMap(({ pending }) => pending.request_id === undefined ? [] : [pending.request_id]));
+            const due = await reconcileAcknowledgementObligations(ctx, sessionId, (state.acknowledgement_due ?? []).filter((entry) => currentAcceptedIds.has(entry.request_id)));
+            if (due.length > 0) {
+                gate(ctx, 'held', 'acknowledgement-required', {
+                    request_ids: due.map((entry) => entry.request_id),
+                });
+                return {
+                    stdout: stopAnswerOutput(acknowledgementBlockContext(due)),
+                    notes,
+                    log: {
+                        stage: 'acknowledgement-required',
+                        request_ids: due.map((entry) => entry.request_id),
+                    },
+                };
+            }
+            state = readSessionState(sessionId, ctx.env);
+        }
+        if (state.accepted === undefined && (state.acknowledgement_due?.length ?? 0) > 0) {
+            const due = await reconcileAcknowledgementObligations(ctx, sessionId, state.acknowledgement_due);
+            if (due.length > 0) {
+                gate(ctx, 'held', 'acknowledgement-required', {
+                    request_ids: due.map((entry) => entry.request_id),
+                });
+                return {
+                    stdout: stopAnswerOutput(acknowledgementBlockContext(due)),
+                    notes,
+                    log: {
+                        stage: 'acknowledgement-required',
+                        request_ids: due.map((entry) => entry.request_id),
+                    },
+                };
+            }
+            state = readSessionState(sessionId, ctx.env);
         }
         const pending = pendingList(state);
         if (pending.length === 0) {
@@ -1332,7 +1483,13 @@ async function handleClaimedStop(ctx, envelope, sessionId, state, pending, notes
                 if (response === null) {
                     notes.push(`could not confirm the close fence for ${entry.pending.request_id}; delivering the durable answer already observed`);
                 }
-                return { ...entry, replies, reply: replies.at(-1) };
+                return {
+                    ...entry,
+                    replies,
+                    reply: replies.at(-1),
+                    agent_acknowledgement_required: response?.agent_acknowledgement_required ??
+                        entry.agent_acknowledgement_required,
+                };
             });
             const accepted = stageAcceptedAnswers(ctx, sessionId, authoritative, pending.length - authoritative.length - permanentlyRejected.length);
             for (const answer of authoritative)
@@ -1666,7 +1823,12 @@ async function escalate(ctx, envelope, sessionId, unasked, alreadyLive, notes, h
         // unreachable, never discard the durable reply already observed.
         const finalReplies = finalized.response?.replies ?? [];
         const authoritative = finalReplies.length > 0 ? finalReplies : replies;
-        answered.push({ pending: entry, reply: authoritative.at(-1), replies: authoritative });
+        answered.push({
+            pending: entry,
+            reply: authoritative.at(-1),
+            replies: authoritative,
+            agent_acknowledgement_required: finalized.response?.agent_acknowledgement_required,
+        });
         if (finalized.response === null) {
             notes.push(`could not confirm the close fence for ${entry.request_id}; delivering the durable answer already observed`);
         }
@@ -1717,8 +1879,13 @@ export function handleSessionEnd(env, envelope, now = Date.now()) {
         orphanRetirements(env, orphans, label !== undefined && label !== '' ? label : sessionId, now);
         notes.push(`queued ${orphans.length} question${orphans.length > 1 ? 's' : ''} for retirement on the next hook`);
     }
-    if (state.accepted !== undefined) {
-        const preserved = { accepted: state.accepted };
+    if (state.accepted !== undefined || (state.acknowledgement_due?.length ?? 0) > 0) {
+        const preserved = {};
+        if (state.accepted !== undefined)
+            preserved.accepted = state.accepted;
+        if (state.acknowledgement_due !== undefined && state.acknowledgement_due.length > 0) {
+            preserved.acknowledgement_due = state.acknowledgement_due;
+        }
         if (state.last_prompt_at !== undefined)
             preserved.last_prompt_at = state.last_prompt_at;
         if (state.last_stop_at !== undefined)
@@ -1726,13 +1893,16 @@ export function handleSessionEnd(env, envelope, now = Date.now()) {
         if (state.continuation !== undefined)
             preserved.continuation = state.continuation;
         writeSessionState(sessionId, env, preserved);
-        notes.push('preserved an accepted device answer for this exact session to resume');
+        notes.push(state.accepted !== undefined
+            ? 'preserved an accepted device answer for this exact session to resume'
+            : 'preserved required Agent Acknowledgement obligations for this exact session');
         return {
             notes,
             log: {
-                outcome: 'answer-preserved',
+                outcome: state.accepted !== undefined ? 'answer-preserved' : 'acknowledgement-preserved',
                 queued_retirements: orphans.length,
-                accepted_answers: state.accepted.answers.length,
+                accepted_answers: state.accepted?.answers.length ?? 0,
+                acknowledgement_due: state.acknowledgement_due?.length ?? 0,
             },
         };
     }