@raidiant/notifai 0.2.0 → 0.3.0

package/dist/config-schema.js

@@ -0,0 +1,274 @@
+/**
+ * What every configuration key means, in the reader's words.
+ *
+ * `config.ts` already documented all fourteen keys carefully — but in TypeScript
+ * comments, which is the one audience that never needed them. Someone running
+ * `notifai config show` saw `require_idle = true` and had no way to learn what
+ * it did short of reading the source, so this module is that knowledge moved to
+ * where it can be printed.
+ *
+ * It is the single source for `config show`, `config set`'s errors, `config
+ * explain`, the help footer, and the interactive settings screen. One
+ * description, rendered five ways, so the surfaces cannot disagree.
+ *
+ * `summary` is the one-line form that fits beside a value in a list.
+ * `detail` is the paragraph shown once the reader has asked for this key
+ * specifically — progressive disclosure, so a list of fourteen settings stays
+ * a list and not an essay.
+ */
+import { CLI_SOUNDS, INTERRUPTION_LEVELS } from '@raidiant/notifai-protocol';
+import { configBounds } from './config.js';
+export const CONFIG_GROUPS = [
+    {
+        id: 'questions',
+        title: 'Questions & presence',
+        blurb: 'When a question an agent registered is allowed to leave this terminal and reach your devices.',
+    },
+    {
+        id: 'delivery',
+        title: 'Delivery defaults',
+        blurb: 'What a notification looks and behaves like when a command does not say otherwise.',
+    },
+    {
+        id: 'project',
+        title: 'This project',
+        blurb: 'How work in this directory identifies itself, and the house rules agents read before notifying.',
+    },
+    {
+        id: 'connection',
+        title: 'Connection',
+        blurb: 'Which Notifai service this machine talks to. Most people never change this.',
+    },
+];
+const INFO = {
+    ask_notifications: {
+        label: 'Send questions to my devices',
+        group: 'questions',
+        kind: 'boolean',
+        summary: 'Whether a registered question may reach your phone and Mac at all',
+        detail: 'The master switch for question routing. When this is off, a question an agent registers with `notifai ask` stays in the terminal and never leaves this machine, whatever the presence settings say. Turn it off to stop being reached for a while without uninstalling the harness hooks.',
+        example: 'true',
+    },
+    require_idle: {
+        label: 'Only when I have stepped away',
+        group: 'questions',
+        kind: 'boolean',
+        summary: 'Whether sitting at this keyboard holds a question back',
+        detail: 'On (the default), a question waits while you are using this machine, because you are right there and a push would be redundant. Off means notify me anyway — `ask_grace_seconds` still runs, so the terminal is still offered the question first; it just no longer needs you to walk away before it may leave.\n\nThis is separate from `ask_notifications`, which switches routing off altogether: wanting to be reached while working is the opposite of not wanting to be reached.',
+        example: 'true',
+    },
+    away_after_seconds: {
+        label: 'Away after',
+        group: 'questions',
+        kind: 'integer',
+        unit: 's',
+        summary: 'Keyboard and mouse idle time before this machine counts as unattended',
+        detail: 'How long the keyboard and mouse must be quiet before you count as away. Only consulted while `require_idle` is on.\n\nWhere the operating system exposes no idle signal, silence since your last prompt is used instead, which is the conservative reading.',
+        example: '120',
+    },
+    ask_grace_seconds: {
+        label: 'Terminal-first grace',
+        group: 'questions',
+        kind: 'integer',
+        unit: 's',
+        summary: 'How long a question stays terminal-only before it may reach your devices',
+        detail: 'Measured from the moment the agent asked. The question appears in the terminal and a timer starts; only once it elapses may the question go to your devices.\n\nA timer and nothing more. It is honoured whether or not presence is consulted at all, because how long to wait and whether anyone is watching are separate questions, and answering one should not answer the other.',
+        example: '300',
+    },
+    hook_reply_timeout_seconds: {
+        label: 'Hook wait for an answer',
+        group: 'questions',
+        kind: 'integer',
+        unit: 's',
+        summary: 'How long the harness hook blocks waiting for your answer',
+        detail: 'After a question has gone out, the harness hook holds the agent for up to this long waiting for your answer before falling through to the harness\'s own prompt.\n\nThe ceiling exists because both Claude Code and Codex kill a command hook at 600 seconds. Grace plus this value plus the installer\'s headroom has to stay under that, or the hook is killed mid-wait — after you have already answered.',
+        example: '180',
+    },
+    sound: {
+        label: 'Sound',
+        group: 'delivery',
+        kind: 'enum',
+        choices: CLI_SOUNDS,
+        choiceHints: {
+            default: 'the standard notification tone',
+            done: 'the completion chime',
+            attention: 'used for questions that want an answer',
+            alert: 'the most insistent tone',
+            none: 'silent — arrives without a sound',
+        },
+        summary: 'Override the sound every notification uses',
+        detail: 'Normally the sound comes from what the notification is: progress updates are silent, completions get the done chime, questions get the attention tone. Setting this pins one sound for everything sent from here, overriding those profiles.\n\nA common use is `none`, to make a noisy project completely silent.',
+        unsetMeans: 'each notification uses the sound for its kind',
+    },
+    interruption_level: {
+        label: 'Interruption level',
+        group: 'delivery',
+        kind: 'enum',
+        choices: INTERRUPTION_LEVELS,
+        choiceHints: {
+            passive: 'no sound or wake — waits in the notification list',
+            active: 'wakes the screen and plays the sound',
+            time_sensitive: 'may break through Focus modes',
+        },
+        summary: 'Override how insistently notifications arrive',
+        detail: 'How hard a notification tries to reach you, in the operating system\'s terms. Like the sound, this is normally decided by what the notification is; setting it pins one level for everything.\n\n`time_sensitive` can pierce a Focus mode, so it is worth reserving for the cases that genuinely earn it.',
+        unsetMeans: 'each notification uses the level for its kind',
+    },
+    devices: {
+        label: 'Default devices',
+        group: 'delivery',
+        kind: 'list',
+        summary: 'Which of your devices receive by default',
+        detail: 'A comma-separated list of device ids. When set, notifications go only to these devices unless a command overrides it.\n\nRun `notifai devices` to see the ids and which of them can currently receive.',
+        unsetMeans: 'every device that can receive',
+        example: 'dev_abc123,dev_def456',
+    },
+    ttl_seconds: {
+        label: 'Delivery window',
+        group: 'delivery',
+        kind: 'integer',
+        unit: 's',
+        summary: 'How long the service keeps trying to deliver before giving up',
+        detail: 'A notification for a device that is off or offline is held for this long and delivered when the device reappears. After it lapses the notification is dropped rather than arriving stale.\n\nThe default of 86400 is one day.',
+        example: '86400',
+    },
+    wait_seconds: {
+        label: 'Wait for outcomes',
+        group: 'delivery',
+        kind: 'integer',
+        unit: 's',
+        summary: 'How long `send` waits to report what happened to a notification',
+        detail: 'After a notification is accepted, `notifai send` can wait for the delivery outcome so its exit code reflects what actually happened rather than only that the service took it.\n\nSet to 0 to return as soon as the service accepts, which is the fastest option and the one that tells you least.',
+        example: '10',
+    },
+    collapse_key: {
+        label: 'Collapse key',
+        group: 'delivery',
+        kind: 'string',
+        summary: 'Replace earlier notifications carrying the same key',
+        detail: 'Two notifications sharing a collapse key do not stack — the newer one replaces the older on the lock screen. This is how a status that changes repeatedly stays one line instead of becoming twenty.\n\nSetting it here applies one key to everything sent from here, which is usually too broad; most uses pass `--collapse-key` per send instead.',
+        unsetMeans: 'each notification stands on its own',
+        advanced: true,
+    },
+    project: {
+        label: 'Project id',
+        group: 'project',
+        kind: 'string',
+        summary: 'The name this project reports itself as',
+        detail: 'Stamped on every notification sent from this directory, and how the companion apps group and filter what arrives. Normally set once in `.notifai/config.toml` and committed, so everyone working on the repository reports the same name.',
+        unsetMeans: 'notifications arrive without a project',
+        example: 'my-app',
+    },
+    notify_criteria: {
+        label: 'House rules for agents',
+        group: 'project',
+        kind: 'string',
+        summary: 'Free text an agent reads before deciding whether to notify you',
+        detail: 'Your own guidance, in your own words, about what is worth a notification in this project — read by agents before they send. Something like "only tell me about failures and finished deploys; never per-file progress".\n\nIt is advice to the agent, not a filter the service enforces.',
+        unsetMeans: 'agents fall back to their default judgement',
+        example: 'Only failures and completed deploys',
+    },
+    base_url: {
+        label: 'Service URL',
+        group: 'connection',
+        kind: 'url',
+        summary: 'Which Notifai service this machine talks to',
+        detail: 'Points the CLI at a Notifai service. The default is the hosted service, and signing in stores the URL the credential belongs to, so this rarely needs setting by hand.\n\nChanging it does not move your credential: a URL that does not match the one you paired against will not authenticate.',
+        advanced: true,
+        example: 'https://notifai.fly.dev',
+    },
+};
+export function configInfo(key) {
+    return { key, ...INFO[key] };
+}
+/** Every key in its group, in the order a reader should meet them. */
+export function configKeysByGroup(group) {
+    return Object.keys(INFO)
+        .filter((key) => INFO[key].group === group)
+        .map((key) => configInfo(key));
+}
+/** Bounds rendered the way an error message wants them, or null. */
+export function boundsHint(key) {
+    const bounds = configBounds(key);
+    if (bounds === undefined)
+        return null;
+    const info = INFO[key];
+    const unit = info.unit ?? '';
+    return `${bounds.min}${unit}–${bounds.max}${unit}`;
+}
+/** What a `config set` caller may legally pass, phrased for an error message. */
+export function acceptedValues(key) {
+    const info = INFO[key];
+    switch (info.kind) {
+        case 'boolean':
+            return 'true or false';
+        case 'enum':
+            return (info.choices ?? []).join(', ');
+        case 'integer': {
+            const bounds = boundsHint(key);
+            return bounds === null ? 'a whole number' : `a whole number from ${bounds}`;
+        }
+        case 'list':
+            return 'a comma-separated list';
+        case 'url':
+            return 'a URL';
+        case 'string':
+            return 'any text';
+    }
+}
+/** How a resolved value should read in a list. */
+export function formatValue(key, value) {
+    const info = INFO[key];
+    if (value === null || value === undefined)
+        return info.unsetMeans ?? 'not set';
+    if (Array.isArray(value))
+        return value.length === 0 ? (info.unsetMeans ?? 'not set') : value.join(', ');
+    if (typeof value === 'boolean')
+        return value ? 'yes' : 'no';
+    if (typeof value === 'number' && info.unit !== undefined)
+        return formatDuration(value, info.unit);
+    return String(value);
+}
+/**
+ * Where a value came from, in words rather than in a tagged path.
+ *
+ * `global:/Users/you/.config/notifai/config.toml` answers "which file" but not
+ * "why is this the value" — and the second question is the one someone reading
+ * `config show` is actually asking. The path is still available for anyone
+ * about to edit the file; it is just no longer the whole answer.
+ */
+export function describeSource(source) {
+    if (source === 'default')
+        return { label: 'default', path: null };
+    if (source === 'flag')
+        return { label: 'this command', path: null };
+    const separator = source.indexOf(':');
+    if (separator === -1)
+        return { label: source, path: null };
+    const layer = source.slice(0, separator);
+    const filePath = source.slice(separator + 1);
+    const labels = {
+        session: 'this session',
+        'project-local': 'this project (personal)',
+        project: 'this project (shared)',
+        global: 'this machine',
+    };
+    return { label: labels[layer] ?? layer, path: filePath === '' ? null : filePath };
+}
+/** Seconds as something a person reads: `300s` is true, `5m` is legible. */
+export function formatDuration(value, unit) {
+    if (unit !== 's')
+        return `${value}${unit}`;
+    if (value === 0)
+        return '0s (immediately)';
+    if (value < 60)
+        return `${value}s`;
+    if (value % 86400 === 0)
+        return `${value / 86400}d`;
+    if (value % 3600 === 0)
+        return `${value / 3600}h`;
+    if (value % 60 === 0)
+        return `${value / 60}m`;
+    return `${Math.floor(value / 60)}m ${value % 60}s`;
+}
+//# sourceMappingURL=config-schema.js.map

package/dist/config-schema.js.map

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

package/dist/hooks.d.ts

@@ -32,19 +32,26 @@ export interface HookEnvelope {
 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 registered by `notifai ask`, in registration order, each
+     * awaiting escalation or its answer. A list, deliberately: registering a
+     * question never ends an earlier one. Superseding is reply semantics — a
+     * later reply corrects an earlier reply to the same question — never
+     * question semantics; the single-slot model silently discarded a live
+     * question the moment a second was registered (2026-08-09).
+     */
+    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.
+     * dead is not always a moment we can make one — the user's return to the
+     * terminal is observed by a bare hook, 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[];
     /** Tracks bounded Stop continuations so a follow-up ask is delivered once. */
@@ -250,18 +257,23 @@ export declare function handleStop(ctx: HookContext, envelope: HookEnvelope): Pr
  */
 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.
+ * More pending questions than this means an agent is looping, not asking.
+ * Related questions belong in one `ask --form` (the wire carries up to four
+ * questions per notification); four separate pushes is already a lot of lock
+ * screen.
+ */
+export declare const MAX_PENDING_QUESTIONS = 4;
+/**
+ * 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).
  *
- * 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.
+ * 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): void;
 /** Parses hook JSON from stdin, tolerating an empty or malformed body. */