@raidiant/notifai 7.0.1 → 8.0.0

package/dist/guidance-content.js

@@ -0,0 +1,175 @@
+/**
+ * The shipped notification-writing guidance: what agents follow when the user
+ * has not said otherwise.
+ *
+ * Each topic is a small Markdown document named for the moment an agent
+ * consults it. Users override a topic by placing a file with the same name in
+ * a guidance directory — resolution and layering live in `guidance.ts`, and
+ * the topics ship here as source rather than as packaged files so the packed
+ * CLI cannot lose them.
+ *
+ * The governing principle, stated once: the user hired the outcome, not the
+ * pipeline. Tests, coverage, review passes, hashes and exit codes are how the
+ * work got done; a notification carries what the work means — what is now
+ * finished, what went wrong, what needs them. A detail earns its place only
+ * when it changes what the user does next.
+ */
+const WHEN_TO_NOTIFY = `# When to notify
+
+Notify when something changed for the user:
+
+- Long-running work finished — succeeded or failed.
+- You are blocked on something only they can give: a key, an approval, a
+  decision.
+- You found something that needs their attention soon.
+
+Never notify for:
+
+- Routine progress: starting, still working, one more subtask done.
+- Anything they will see in the terminal within seconds.
+- A problem you hit and fixed yourself.
+
+One notification per event. When a status changes, replace your stale
+notification rather than stacking a new one.
+`;
+const TITLES = `# Titles
+
+The user hired the outcome, not the pipeline. A title says what the work means
+to them — what is now finished, what went wrong, what needs them — in about 40
+characters, understandable alone. Never put the kind or the project in it;
+both travel as their own fields.
+
+Good:
+
+- \`Users can now create accounts\` — the capability, not the process behind it
+- \`Password reset emails aren't sending\` — the failure as the user experiences it
+- \`Refund flow needs your Stripe key\` — what is stuck and what unblocks it
+- \`Found why checkout was flaky\` — the finding they were waiting on
+- \`3 orders didn't import and need review\` — a count that earns its place
+  because acting on it is theirs to do
+
+Bad:
+
+- \`All 42 tests passed\` — machinery; say what work is done
+- \`Adversarial review found 3 issues\` — process report; say what it means for
+  what ships
+- \`Migration 0007 failed\` — internal identifier; say what the user lost
+- \`Task complete\` / \`Build failed\` / \`Need input\` — no substance, and the
+  kind restated
+- \`Exit code 1\` — mechanics, not meaning
+`;
+const BODIES = `# Bodies
+
+The first sentence is what the lock screen shows — make it say what this means
+for the user. The rest is what changes for them and what is needed from them,
+never how many tests ran, how long a step took, or which internal stage
+produced it. Keep wording channel-neutral: no device names, no gestures.
+
+Work finished:
+
+> Account creation works end to end now: sign-up, email verification, and
+> login are live on staging.
+>
+> Next I'll start on password reset unless you want something else first.
+
+Work failed:
+
+> The new pricing page isn't live. The deploy failed and I rolled it back, so
+> the site still shows the old page — nothing is broken for users.
+>
+> The blocker is on my side and I'm fixing it; I'll retry and confirm when the
+> page is up. Nothing needed from you.
+
+Blocked:
+
+> The refund flow is built and working against the test environment. Going
+> live needs the Stripe key that only you can issue.
+>
+> That's the last open item — everything else is done.
+
+Bad bodies: a build report (\`42/42 green, coverage 87%, rebased onto main\`)
+where the news is "users can now create accounts"; the journey ("first I
+tried…") instead of the result; a log with the conclusion at the bottom; "see
+terminal for details".
+
+Add a summary line only when the body is long enough that its first line is
+not a fair summary of what is inside: one short line answering what the title
+raises, such as \`Rolled back cleanly; production is untouched\` over a long
+failure report.
+`;
+const QUESTIONS = `# Questions
+
+A question is answerable from the notification alone, in the user's terms, not
+the machinery's. One askable sentence; reasoning and stakes follow as context.
+Offer closed choices whose wording carries its own consequence.
+
+Good:
+
+- \`The schema change is ready. It touches live order data — deploy now or
+  wait for off-peak?\` with choices \`Deploy now\` / \`Wait for off-peak\`
+- \`The API key in .env.example is live. Revoke it now, or wait until the
+  replacement is provisioned?\` with \`Revoke now\` / \`Wait for the new key\`
+
+Bad:
+
+- \`What should I do?\` — nothing to answer without the terminal
+- \`Deploy to staging and notify the team?\` with \`Yes\` / \`No\` — two
+  decisions, one answer
+- \`Retry with --force-with-lease?\` — machinery; the real decision is
+  \`Overwrite the remote branch, or keep both versions?\`
+- Choices \`Option A\` / \`Option B\` — labels that point back into the body
+- \`Reply here with your choice\` — never name where the answer must arrive
+`;
+const ACKNOWLEDGEMENTS = `# Acknowledgements
+
+An acknowledgement names the concrete work the reply sets in motion — only
+work you will actually do, and nothing generic.
+
+Good:
+
+- \`Rolling out to staging now; I'll report the health checks.\`
+- \`Holding the deploy. I'll re-raise it once staging is green.\`
+- \`Shipping the fix; I'll confirm when password reset works again.\`
+
+Bad:
+
+- \`Acknowledged.\` / \`Got it!\` — a receipt that shows nothing was understood
+- \`You chose "Deploy now".\` — echoes the reply instead of naming the work
+- \`Deploying now, and I'll also refactor the retry logic.\` — promises work
+  the reply did not cause
+`;
+/**
+ * Topic order is reading order: decide first, then each thing an agent writes,
+ * in the order it writes them.
+ */
+export const SHIPPED_GUIDANCE = [
+    {
+        name: 'when-to-notify',
+        summary: 'What is worth a notification at all',
+        content: WHEN_TO_NOTIFY,
+    },
+    {
+        name: 'titles',
+        summary: 'What a title carries, with examples',
+        content: TITLES,
+    },
+    {
+        name: 'bodies',
+        summary: 'What a body and its summary line carry, with examples',
+        content: BODIES,
+    },
+    {
+        name: 'questions',
+        summary: 'How a question and its choices are worded',
+        content: QUESTIONS,
+    },
+    {
+        name: 'acknowledgements',
+        summary: 'How an acknowledgement is worded',
+        content: ACKNOWLEDGEMENTS,
+    },
+];
+export function shippedGuidanceTopic(name) {
+    return SHIPPED_GUIDANCE.find((topic) => topic.name === name);
+}
+//# sourceMappingURL=guidance-content.js.map

package/dist/guidance-content.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guidance-content.js","sourceRoot":"","sources":["../src/guidance-content.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAWH,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;;CAiBtB,CAAA;AAED,MAAM,MAAM,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;CAyBd,CAAA;AAED,MAAM,MAAM,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsCd,CAAA;AAED,MAAM,SAAS,GAAG;;;;;;;;;;;;;;;;;;;;;;CAsBjB,CAAA;AAED,MAAM,gBAAgB,GAAG;;;;;;;;;;;;;;;;;CAiBxB,CAAA;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAA6B;IACxD;QACE,IAAI,EAAE,gBAAgB;QACtB,OAAO,EAAE,qCAAqC;QAC9C,OAAO,EAAE,cAAc;KACxB;IACD;QACE,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,qCAAqC;QAC9C,OAAO,EAAE,MAAM;KAChB;IACD;QACE,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,uDAAuD;QAChE,OAAO,EAAE,MAAM;KAChB;IACD;QACE,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,2CAA2C;QACpD,OAAO,EAAE,SAAS;KACnB;IACD;QACE,IAAI,EAAE,kBAAkB;QACxB,OAAO,EAAE,kCAAkC;QAC3C,OAAO,EAAE,gBAAgB;KAC1B;CACF,CAAA;AAED,MAAM,UAAU,oBAAoB,CAAC,IAAY;IAC/C,OAAO,gBAAgB,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,CAAA;AAC9D,CAAC"}

package/dist/guidance.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Layered notification-writing guidance with provenance. Most specific wins,
+ * per topic, exactly the discipline config keys follow:
+ *
+ *   project-local > project > global > shipped default
+ *
+ * A topic is one Markdown file named `<topic>.md`. A user file replaces the
+ * shipped topic of the same name wholesale — their words outrank the default,
+ * not annotate it — and a file whose name matches no shipped topic is purely
+ * additive house rules. There is no session layer: an instruction given in
+ * conversation tunes the session by being followed, not persisted.
+ */
+export type GuidanceSource = `project-local:${string}` | `project:${string}` | `global:${string}` | 'default';
+export interface ResolvedGuidanceTopic {
+    name: string;
+    source: GuidanceSource;
+    /** One line for lists; user-authored topics describe themselves by content. */
+    summary: string;
+    content: string;
+}
+/**
+ * Topic names double as filenames, and the project layer arrives from a
+ * repository — untrusted input. Anything that does not match is not a topic,
+ * the same way `coerce` drops an unrecognised config value.
+ */
+export declare const GUIDANCE_TOPIC_PATTERN: RegExp;
+/**
+ * One topic is capped at the body limit. Guidance is read into agent context
+ * on every session, and a repository could otherwise feed it without bound.
+ */
+export declare const GUIDANCE_TOPIC_MAX_BYTES = 16000;
+export declare function globalGuidanceDir(env?: NodeJS.ProcessEnv): string;
+/** Walk up from cwd looking for `.notifai/guidance` (shared, committed). */
+export declare function findProjectGuidanceDir(startDir: string): string | null;
+/**
+ * Personal project guidance lives beside the personal project config file,
+ * under the user's config home rather than the repository:
+ * `$XDG_CONFIG_HOME/notifai/projects/<identity>/guidance`.
+ */
+export declare function personalProjectGuidanceDir(cwd: string, env?: NodeJS.ProcessEnv): string;
+/**
+ * Every effective topic, shipped reading order first, additive user topics
+ * after it in name order. Each carries the layer that supplied it.
+ */
+export declare function resolveGuidance(options: {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}): ResolvedGuidanceTopic[];

package/dist/guidance.js

@@ -0,0 +1,118 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+import { globalConfigDir, personalProjectIdentity } from './config.js';
+import { SHIPPED_GUIDANCE } from './guidance-content.js';
+/**
+ * Topic names double as filenames, and the project layer arrives from a
+ * repository — untrusted input. Anything that does not match is not a topic,
+ * the same way `coerce` drops an unrecognised config value.
+ */
+export const GUIDANCE_TOPIC_PATTERN = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+/**
+ * One topic is capped at the body limit. Guidance is read into agent context
+ * on every session, and a repository could otherwise feed it without bound.
+ */
+export const GUIDANCE_TOPIC_MAX_BYTES = 16_000;
+export function globalGuidanceDir(env = process.env) {
+    return path.join(globalConfigDir(env), 'guidance');
+}
+/** Walk up from cwd looking for `.notifai/guidance` (shared, committed). */
+export function findProjectGuidanceDir(startDir) {
+    let dir = path.resolve(startDir);
+    for (;;) {
+        const candidate = path.join(dir, '.notifai', 'guidance');
+        if (existsSync(candidate))
+            return candidate;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/**
+ * Personal project guidance lives beside the personal project config file,
+ * under the user's config home rather than the repository:
+ * `$XDG_CONFIG_HOME/notifai/projects/<identity>/guidance`.
+ */
+export function personalProjectGuidanceDir(cwd, env = process.env) {
+    return path.join(globalConfigDir(env), 'projects', personalProjectIdentity(cwd), 'guidance');
+}
+function topicsInDir(dir) {
+    const topics = new Map();
+    if (!existsSync(dir))
+        return topics;
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return topics;
+    }
+    for (const entry of entries.sort()) {
+        if (!entry.endsWith('.md'))
+            continue;
+        const name = entry.slice(0, -'.md'.length);
+        if (!GUIDANCE_TOPIC_PATTERN.test(name))
+            continue;
+        topics.set(name, path.join(dir, entry));
+    }
+    return topics;
+}
+function readTopicFile(filePath) {
+    let content;
+    try {
+        content = readFileSync(filePath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    if (content.trim() === '')
+        return null;
+    if (content.length > GUIDANCE_TOPIC_MAX_BYTES) {
+        return `${content.slice(0, GUIDANCE_TOPIC_MAX_BYTES)}\n\n[Truncated: this guidance file exceeds ${GUIDANCE_TOPIC_MAX_BYTES} bytes.]\n`;
+    }
+    return content;
+}
+/**
+ * Every effective topic, shipped reading order first, additive user topics
+ * after it in name order. Each carries the layer that supplied it.
+ */
+export function resolveGuidance(options) {
+    const env = options.env ?? process.env;
+    const cwd = options.cwd ?? process.cwd();
+    // Ascending precedence: a later layer overwrites an earlier one per topic.
+    const layers = [
+        { dir: globalGuidanceDir(env), label: 'global' },
+        { dir: findProjectGuidanceDir(cwd), label: 'project' },
+        { dir: personalProjectGuidanceDir(cwd, env), label: 'project-local' },
+    ];
+    const winners = new Map();
+    for (const layer of layers) {
+        if (layer.dir === null)
+            continue;
+        for (const [name, filePath] of topicsInDir(layer.dir)) {
+            const content = readTopicFile(filePath);
+            if (content === null)
+                continue;
+            winners.set(name, { source: `${layer.label}:${filePath}`, content });
+        }
+    }
+    const resolved = SHIPPED_GUIDANCE.map((topic) => {
+        const override = winners.get(topic.name);
+        winners.delete(topic.name);
+        return override === undefined
+            ? { name: topic.name, source: 'default', summary: topic.summary, content: topic.content }
+            : { name: topic.name, source: override.source, summary: topic.summary, content: override.content };
+    });
+    for (const name of [...winners.keys()].sort()) {
+        const extra = winners.get(name);
+        resolved.push({
+            name,
+            source: extra.source,
+            summary: 'User-added guidance',
+            content: extra.content,
+        });
+    }
+    return resolved;
+}
+//# sourceMappingURL=guidance.js.map

package/dist/guidance.js.map

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

package/dist/hooks.js

@@ -331,8 +331,9 @@ function claimPath(sessionId, env) {
 /**
  * A question is stored so a later hook can push it, and it reaches us from a
  * shell command, so its size is whatever the agent typed. The push itself is
- * bounded by the 4096-byte APNs envelope; this bounds what sits on disk in the
- * meantime, and keeps one runaway agent from writing megabytes per session.
+ * bounded by the current 4096-byte push-provider envelopes; this bounds what
+ * sits on disk in the meantime, and keeps one runaway agent from writing
+ * megabytes per session.
  */
 const MAX_STORED_QUESTION_CHARS = 2000;
 function storedProjectSessionPointer(candidate) {
@@ -623,15 +624,14 @@ function permanentReplyFailureNote(failures) {
     const details = [...failures].map(([requestId, failure]) => `${requestId}: ${failure}`).join('; ');
     return `reply polling stopped after a permanent server rejection (${details}); the affected question will be retired before its continuation owner exits`;
 }
-/**
- * Healthy companion devices that implement replies. Both the iOS app and the
- * macOS app register reply categories and submit answers directly.
- */
+/** Healthy Companion devices that advertise the current answer job. */
 async function answerableDevices(ctx) {
     const configured = ctx.config.devices.value;
     const { devices } = await ctx.client.listDevices();
     return devices
-        .filter((device) => (device.platform === 'ios' || device.platform === 'macos') &&
+        .filter((device) => (device.platform === 'ios' ||
+        device.platform === 'macos' ||
+        device.platform === 'android') &&
         device.registration_healthy &&
         device.capabilities?.includes('answer') === true &&
         device.derived_status !== 'must_update')