@raidiant/notifai 11.4.0-beta.2 → 11.4.0

package/dist/skill-source/notifai/references/writing-examples.md

@@ -0,0 +1,56 @@
+# Writing examples
+
+Examples for the shipped `titles`, `content`, and `acknowledgements` guidance.
+The effective guidance printed by `notifai guidance` always wins over them.
+
+## Titles
+
+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 rollout awaits provider recovery` — what is stuck, not machinery
+- `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
+
+## Content
+
+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, but the production rollout is waiting for the
+> payment provider to recover. I am monitoring it and will resume automatically.
+>
+> There is nothing for you to answer; I will confirm when it is live.
+
+## Acknowledgements
+
+- A note: `Switching the migration to staging; I'll rerun it there.`
+- An edit after irreversible work: `The email already went out with Monday;
+  sending a correction for Friday now.` — say what already happened; never
+  imply it was undone.

package/dist/wake-support.d.ts

@@ -1,8 +1,40 @@
 import type { DeliveryOutcome } from './hook-types.js';
 export declare function holdForNextTurn(reason: string): DeliveryOutcome;
+/** `log.reason` of a claimed write stopped at its boundary before any byte left. */
+export declare const WRITE_ABORTED_REASON = "write-aborted";
+export declare function abortedDelivery(): DeliveryOutcome;
+/**
+ * The last check before a claimed write's first byte: a connected socket asks
+ * `writable()`, and a connection still pending after `remainingMs()` is
+ * abandoned. Either way nothing is written.
+ */
+export interface WriteGuard {
+    writable(): boolean;
+    remainingMs(): number;
+}
+/** Thrown when a guarded write was stopped before any byte left. */
+export declare class WriteAbortedError extends Error {
+}
 export declare function cancelledDelivery(): DeliveryOutcome;
-/** Run one harness child and preserve its diagnostic stderr on failure. */
+/**
+ * Run one harness child and preserve its diagnostic stderr on failure.
+ *
+ * With `onSpawn` the child is started in its own process group (its pid is
+ * the group id) and reported at once, so a writer can journal the whole group
+ * that might still write if the writer itself dies. It is still awaited.
+ */
+/** A subprocess writer was stopped at its deadline; it may already have written. */
+export declare class WriteDeadlineError extends Error {
+}
+/**
+ * Run one harness command to completion. With `onSpawn` it runs in its own
+ * process group (reported as soon as it exists). With `signal`, an abort
+ * SIGKILLs that whole group — or the child, without one — and rejects with
+ * `WriteDeadlineError` at once: nothing the command started keeps running.
+ */
 export declare function runWakeCommand(command: string, args: readonly string[], options?: {
     cwd?: string;
     env?: NodeJS.ProcessEnv;
+    onSpawn?: (pgid: number) => void;
+    signal?: AbortSignal;
 }): Promise<string>;

package/dist/wake-support.js

@@ -6,6 +6,18 @@ export function holdForNextTurn(reason) {
         acknowledgement: 'held',
     };
 }
+/** `log.reason` of a claimed write stopped at its boundary before any byte left. */
+export const WRITE_ABORTED_REASON = 'write-aborted';
+export function abortedDelivery() {
+    return {
+        notes: ['the claim lapsed before the write started; nothing was handed over'],
+        log: { route: 'hold-for-next-turn', stage: 'queued', reason: WRITE_ABORTED_REASON },
+        acknowledgement: 'held',
+    };
+}
+/** Thrown when a guarded write was stopped before any byte left. */
+export class WriteAbortedError extends Error {
+}
 export function cancelledDelivery() {
     return {
         notes: ['the Agent Session ended before answer delivery; stopping this observer'],
@@ -13,25 +25,70 @@ export function cancelledDelivery() {
         acknowledgement: 'held',
     };
 }
-/** Run one harness child and preserve its diagnostic stderr on failure. */
+/**
+ * Run one harness child and preserve its diagnostic stderr on failure.
+ *
+ * With `onSpawn` the child is started in its own process group (its pid is
+ * the group id) and reported at once, so a writer can journal the whole group
+ * that might still write if the writer itself dies. It is still awaited.
+ */
+/** A subprocess writer was stopped at its deadline; it may already have written. */
+export class WriteDeadlineError extends Error {
+}
+/**
+ * Run one harness command to completion. With `onSpawn` it runs in its own
+ * process group (reported as soon as it exists). With `signal`, an abort
+ * SIGKILLs that whole group — or the child, without one — and rejects with
+ * `WriteDeadlineError` at once: nothing the command started keeps running.
+ */
 export function runWakeCommand(command, args, options = {}) {
     return new Promise((resolve, reject) => {
+        const signal = options.signal;
+        if (signal?.aborted === true) {
+            reject(new WriteDeadlineError(`${command} ${args[0] ?? ''} was not started: its deadline had passed`));
+            return;
+        }
+        const grouped = options.onSpawn !== undefined;
         const child = spawn(command, [...args], {
             ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
             ...(options.env === undefined ? {} : { env: options.env }),
+            ...(grouped ? { detached: true } : {}),
             stdio: ['ignore', 'pipe', 'pipe'],
         });
+        let settled = false;
+        const settle = (finish) => {
+            if (settled)
+                return;
+            settled = true;
+            signal?.removeEventListener('abort', onAbort);
+            finish();
+        };
+        const onAbort = () => {
+            try {
+                if (child.pid !== undefined)
+                    process.kill(grouped ? -child.pid : child.pid, 'SIGKILL');
+            }
+            catch {
+                // Already gone.
+            }
+            settle(() => reject(new WriteDeadlineError(`${command} ${args[0] ?? ''} was stopped at its deadline and may have written`)));
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+        if (options.onSpawn !== undefined && child.pid !== undefined)
+            options.onSpawn(child.pid);
         const stdout = [];
         const stderr = [];
         child.stdout?.on('data', (chunk) => stdout.push(Buffer.from(chunk)));
         child.stderr?.on('data', (chunk) => stderr.push(Buffer.from(chunk)));
-        child.once('error', reject);
-        child.once('exit', (code, signal) => {
-            if (code === 0) {
-                resolve(Buffer.concat(stdout).toString());
-                return;
-            }
-            reject(new Error(`${command} ${args[0] ?? ''} exited ${code === null ? `on ${String(signal)}` : String(code)}: ${Buffer.concat(stderr).toString().trim()}`));
+        child.once('error', (err) => settle(() => reject(err)));
+        child.once('exit', (code, exitSignal) => {
+            settle(() => {
+                if (code === 0) {
+                    resolve(Buffer.concat(stdout).toString());
+                    return;
+                }
+                reject(new Error(`${command} ${args[0] ?? ''} exited ${code === null ? `on ${String(exitSignal)}` : String(code)}: ${Buffer.concat(stderr).toString().trim()}`));
+            });
         });
     });
 }

package/dist/wake-support.js.map

@@ -1 +1 @@
-{"version":3,"file":"wake-support.js","sourceRoot":"","sources":["../src/wake-support.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAA;AAG1C,MAAM,UAAU,eAAe,CAAC,MAAc;IAC5C,OAAO;QACL,KAAK,EAAE,CAAC,kDAAkD,MAAM,EAAE,CAAC;QACnE,GAAG,EAAE,EAAE,KAAK,EAAE,oBAAoB,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE;QAC7D,eAAe,EAAE,MAAM;KACxB,CAAA;AACH,CAAC;AAED,MAAM,UAAU,iBAAiB;IAC/B,OAAO;QACL,KAAK,EAAE,CAAC,wEAAwE,CAAC;QACjF,GAAG,EAAE,EAAE,KAAK,EAAE,oBAAoB,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,eAAe,EAAE;QAC9E,eAAe,EAAE,MAAM;KACxB,CAAA;AACH,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,cAAc,CAC5B,OAAe,EACf,IAAuB,EACvB,UAAqD,EAAE;IAEvD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE;YACtC,GAAG,CAAC,OAAO,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC;YAC1D,GAAG,CAAC,OAAO,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC;YAC1D,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC;SAClC,CAAC,CAAA;QACF,MAAM,MAAM,GAAa,EAAE,CAAA;QAC3B,MAAM,MAAM,GAAa,EAAE,CAAA;QAC3B,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,KAAsB,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;QACrF,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,KAAsB,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;QACrF,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;QAC3B,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE;YAClC,IAAI,IAAI,KAAK,CAAC,EAAE,CAAC;gBACf,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAA;gBACzC,OAAM;YACR,CAAC;YACD,MAAM,CACJ,IAAI,KAAK,CACP,GAAG,OAAO,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,WAAW,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,EAAE,CAC1I,CACF,CAAA;QACH,CAAC,CAAC,CAAA;IACJ,CAAC,CAAC,CAAA;AACJ,CAAC"}
+{"version":3,"file":"wake-support.js","sourceRoot":"","sources":["../src/wake-support.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raidiant/notifai",
-  "version": "11.4.0-beta.2",
+  "version": "11.4.0",
   "type": "module",
   "description": "Send native device notifications from agents and local programs",
   "bin": {
@@ -12,7 +12,7 @@
   ],
   "dependencies": {
     "@clack/prompts": "^1.7.0",
-    "@raidiant/notifai-protocol": "8.0.3",
+    "@raidiant/notifai-protocol": "8.1.0",
     "commander": "^14.0.0",
     "picocolors": "^1.1.1",
     "smol-toml": "^1.4.0"