@raidiant/notifai 0.1.0

package/dist/credentials.js

@@ -0,0 +1,94 @@
+import { execFileSync } from 'node:child_process';
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { globalConfigDir } from './config.js';
+const SERVICE = 'io.notifai.cli';
+/** macOS Keychain via the `security` CLI — no native addons (proposal concern). */
+export class KeychainStore {
+    load() {
+        try {
+            const raw = execFileSync('security', ['find-generic-password', '-s', SERVICE, '-a', 'machine', '-w'], { stdio: ['ignore', 'pipe', 'ignore'] })
+                .toString()
+                .trim();
+            return JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    save(credential) {
+        execFileSync('security', [
+            'add-generic-password',
+            '-U',
+            '-s',
+            SERVICE,
+            '-a',
+            'machine',
+            '-w',
+            JSON.stringify(credential),
+        ], { stdio: 'ignore' });
+    }
+    clear() {
+        try {
+            execFileSync('security', ['delete-generic-password', '-s', SERVICE, '-a', 'machine'], {
+                stdio: 'ignore',
+            });
+        }
+        catch {
+            // nothing stored
+        }
+    }
+    describe() {
+        return `macOS Keychain (${SERVICE})`;
+    }
+}
+/** 0600 file fallback for hosts without a keychain. */
+export class FileStore {
+    env;
+    constructor(env = process.env) {
+        this.env = env;
+    }
+    filePath() {
+        return path.join(globalConfigDir(this.env), 'credentials.json');
+    }
+    load() {
+        const file = this.filePath();
+        if (!existsSync(file))
+            return null;
+        try {
+            return JSON.parse(readFileSync(file, 'utf8'));
+        }
+        catch {
+            return null;
+        }
+    }
+    save(credential) {
+        const file = this.filePath();
+        mkdirSync(path.dirname(file), { recursive: true });
+        writeFileSync(file, `${JSON.stringify(credential, null, 2)}\n`, { mode: 0o600 });
+        chmodSync(file, 0o600);
+    }
+    clear() {
+        rmSync(this.filePath(), { force: true });
+    }
+    describe() {
+        return this.filePath();
+    }
+}
+function keychainAvailable() {
+    if (process.platform !== 'darwin')
+        return false;
+    try {
+        execFileSync('security', ['help'], { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function defaultCredentialStore(env = process.env) {
+    if (env['NOTIFAI_CREDENTIALS'] === 'file')
+        return new FileStore(env);
+    return keychainAvailable() ? new KeychainStore() : new FileStore(env);
+}
+//# sourceMappingURL=credentials.js.map

package/dist/credentials.js.map

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

package/dist/hooks.d.ts

@@ -0,0 +1,250 @@
+import type { LifecycleEndState, ReplyView } from '@raidiant/notifai-protocol';
+import type { ApiClient } from './client.js';
+import { type CliConfig } from './config.js';
+/**
+ * Harness hook handlers.
+ *
+ * Claude Code, Codex and OpenCode all expose the same three joints: a blocking
+ * pre-approval hook that returns a decision, a turn-end hook, and a hook that
+ * fires when the user submits a prompt. That is enough to answer a blocked
+ * agent from the phone without the agent cooperating at all — no question
+ * detection, no pending state in a context window that compaction will eat.
+ *
+ * The load-bearing constraint is that these hooks are synchronous: while one
+ * blocks, the harness cannot show its own prompt either. So a hook may only
+ * take over when the user is demonstrably absent. Present user, or no evidence
+ * either way, means exit immediately and let the terminal do its job.
+ */
+/** Fields we read from harness hook JSON. Everything else is passed through. */
+export interface HookEnvelope {
+    session_id?: string;
+    cwd?: string;
+    hook_event_name?: string;
+    /** Set by the harness when this Stop follows a previous Stop continuation. */
+    stop_hook_active?: boolean;
+    /** Cursor's stable per-conversation identifier. */
+    conversation_id?: string;
+    /** Cursor's project roots; the first is the hook's configuration root. */
+    workspace_roots?: string[];
+    /** Cursor increments this after each stop-hook automatic follow-up. */
+    loop_count?: number;
+}
+export interface SessionState {
+    /** Epoch ms of the user's last prompt in this session — our presence signal. */
+    last_prompt_at?: number;
+    /** Question registered by `notifai ask`, awaiting the turn to end. */
+    pending?: PendingQuestion;
+    /**
+     * Questions that have been delivered to the user's devices and are now dead,
+     * but whose retirement has not been confirmed yet.
+     *
+     * A retirement needs a network call and the moment we learn a question is
+     * dead is not always a moment we can make one — `notifai ask` supersedes the
+     * previous question from a bare shell command, and the machine may be
+     * offline. Dropping the ids there is how a delivered question becomes
+     * permanently unretirable, so they are parked here instead and every later
+     * hook with a client drains them. Retirement is idempotent, so a duplicate
+     * attempt costs nothing and a missed one costs a stale notification for ever.
+     */
+    retiring?: RetiringQuestion[];
+}
+/** A delivered question awaiting its retirement push. */
+export interface RetiringQuestion {
+    request_id: string;
+    collapse_key: string;
+    /** Shown if the companion has no history entry to correlate against. */
+    question: string;
+    state: LifecycleEndState;
+}
+/**
+ * A retirement that outlived its session.
+ *
+ * Per-session parking assumes some later hook in the SAME session will hold a
+ * client, and `SessionEnd` is exactly where that assumption breaks: it may not
+ * touch the network, and no hook for that session ever fires again. Deleting
+ * the state there lost the only copy of the delivered question's ids, so the
+ * phone kept an answerable question nobody was listening to. These entries are
+ * moved to a machine-global queue instead, drained by whichever session's hook
+ * next holds a client.
+ */
+export interface OrphanRetirement extends RetiringQuestion {
+    /** Label of the session that asked, so the retirement sync matches its badge. */
+    session?: string;
+    /** Epoch ms when the entry was orphaned; entries beyond the TTL are dropped. */
+    enqueued_at: number;
+}
+export interface PendingQuestion {
+    question: 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
+     * while it kept working has already served its wait in the terminal.
+     */
+    asked_at?: number;
+    /**
+     * Canonical answer labels, already split and validated by `notifai ask`.
+     * Stored as a list rather than a comma-joined string so a label containing a
+     * comma survives the round trip.
+     */
+    choices?: string[];
+    /** Set once the question has actually been pushed, so it can be retired. */
+    request_id?: string;
+    collapse_key?: string;
+}
+export type GraceOutcome = 
+/** The window elapsed with the user still gone; escalate. */
+'absent'
+/** The user touched the machine; the terminal is theirs. */
+ | 'user-returned'
+/** No idle source, so waiting would hold a terminal we cannot monitor. */
+ | 'no-signal';
+/**
+ * The terminal-first wait: the question sits in the terminal for
+ * `ask_grace_seconds` from when it was sent, and only then reaches companion
+ * devices.
+ *
+ * Holding a blocking Stop hook open is normally hostile — while it blocks, the
+ * harness cannot show its prompt either, so a user wanting to answer locally is
+ * locked out. What makes it safe is that the wait is abandoned the moment the
+ * user touches the keyboard or mouse. The block therefore only ever persists
+ * while they are demonstrably not using the machine, which costs them nothing.
+ *
+ * That safety depends entirely on the idle signal, so with no idle source this
+ * refuses to wait at all rather than holding a terminal it cannot monitor.
+ *
+ * With `require_idle` off the whole calculus changes: the user has said they
+ * want the question to reach them whether or not they are at the keyboard, so
+ * there is nothing to watch for and this becomes what its name always claimed —
+ * a plain timer. It then works on machines with no idle source too.
+ */
+export declare function awaitGrace(ctx: HookContext, askedAt: number): Promise<GraceOutcome>;
+export interface HookOutcome {
+    /** Written to stdout verbatim — the harness parses this as the decision. */
+    stdout?: string;
+    /** Diagnostics; harnesses surface hook stderr in the transcript. */
+    notes: string[];
+}
+export declare function readSessionState(sessionId: string, env: NodeJS.ProcessEnv): SessionState;
+export declare function writeSessionState(sessionId: string, env: NodeJS.ProcessEnv, state: SessionState): void;
+export declare function clearSessionState(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): boolean;
+export declare function releaseQuestionPush(sessionId: string, env: NodeJS.ProcessEnv): void;
+/** Records which session is working in a directory, for `notifai ask`. */
+export declare function writeProjectSession(cwd: string, env: NodeJS.ProcessEnv, sessionId: string, now: number): 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;
+/**
+ * Absent means the user is not at this machine's keyboard.
+ *
+ * OS idle time answers that directly, so where it exists it decides alone.
+ * Silence since the user's last prompt is only ever a proxy for it, and a poor
+ * one — it is wrong in both directions:
+ *
+ *   - Too long: it counts the agent's own turn, so a user watching a build was
+ *     read as absent and had the question pushed at them.
+ *   - Too short: a session that has just been spawned always has a fresh
+ *     prompt, so its FIRST question could never escalate however long its
+ *     owner had been gone. That is the "kick off some agents and
+ *     walk away" case this feature mainly exists for, and requiring both
+ *     signals to agree is what broke it.
+ *
+ * The proxy therefore survives only as the fallback for machines with no idle
+ * source. There, never having seen a prompt is not evidence of absence — it is
+ * a missing `UserPromptSubmit` hook — so it resolves to "present".
+ *
+ * Answering from a companion device does not make the user present; only touching this
+ * machine does. Answering on a device is evidence of being away from it.
+ *
+ * All of which only matters if presence is being consulted at all. With
+ * `require_idle` off the user has said their whereabouts are not a
+ * precondition, so this stops guessing and answers yes.
+ */
+export declare function isUserAway(state: SessionState, config: CliConfig, now: number, idleSeconds: number | null): boolean;
+export interface HookContext {
+    client: ApiClient;
+    config: CliConfig;
+    env: NodeJS.ProcessEnv;
+    now: () => number;
+    /** Seconds since the last keyboard/mouse event, or null if unknowable. */
+    idleSeconds: () => number | null;
+    /** Injected so tests advance a virtual clock instead of sleeping. */
+    sleep: (milliseconds: number) => Promise<void>;
+    /** Bounded wait for the first reply; injected so tests do not sleep. */
+    waitForFirstReply: (requestId: string, timeoutSeconds: number) => Promise<{
+        replies: ReplyView[];
+        timedOut: boolean;
+        degraded?: boolean;
+    }>;
+}
+/**
+ * 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'>;
+/**
+ * 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;
+/**
+ * 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, session?: string | undefined): Promise<string[]>;
+/** Move retirements into the global queue; deduped so a retry costs nothing. */
+export declare function orphanRetirements(env: NodeJS.ProcessEnv, entries: RetiringQuestion[], session: string | undefined, 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[]>;
+/**
+ * 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.
+ */
+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): Promise<HookOutcome>;
+/**
+ * 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;
+/**
+ * One session holds one live question, so registering a second one ends the
+ * first.
+ *
+ * This used to replace `pending` wholesale, which silently discarded the
+ * `request_id` and `collapse_key` of a question already delivered to the user's
+ * devices. Nothing else knows those ids, so the notification became
+ * unretirable — it sat on the lock screen for ever asking a question no answer
+ * could reach. That is where the stale pile-up came from.
+ *
+ * Supersession is keyed on the session, not the project: several agents may be
+ * running in one project at once, and one agent's new question killing another
+ * agent's live one would be worse than the staleness this fixes.
+ */
+export declare function registerQuestion(sessionId: string, env: NodeJS.ProcessEnv, question: PendingQuestion, now?: number): void;
+/** 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;