@raidiant/notifai 0.3.0 → 0.5.0

package/dist/file-lock.js

@@ -0,0 +1,268 @@
+import { randomBytes } from 'node:crypto';
+import { chmodSync, closeSync, fstatSync, lstatSync, mkdirSync, openSync, readdirSync, renameSync, rmdirSync, unlinkSync, } from 'node:fs';
+import path from 'node:path';
+/**
+ * Serialize a short cross-process filesystem transaction.
+ *
+ * Each contender publishes all of its ownership in one unique filename. A
+ * two-phase bakery lock then orders live contenders by ticket and process
+ * identity. Because paths are never reused, recovering an entry left by a dead
+ * process cannot remove a later owner's entry; because process liveness, rather
+ * than age, decides recovery, a delayed holder is never mistaken for a dead one.
+ *
+ * Acquisition is deliberately bounded because both harness hooks and logging
+ * must fail open rather than hold an agent turn indefinitely.
+ */
+const FILE_LOCK_WAIT_MS = 1_000;
+const FILE_LOCK_POLL_MS = 5;
+const FILE_LOCK_TOKEN_BYTES = 12;
+const ENTRY_PATTERN = /^(choosing|ticket-(\d+))-(\d+)-([0-9a-f]+)$/;
+const lockSleep = new Int32Array(new SharedArrayBuffer(4));
+function parseEntry(name) {
+    const match = ENTRY_PATTERN.exec(name);
+    if (match === null)
+        return null;
+    const pid = Number(match[3]);
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return null;
+    const token = match[4];
+    if (match[1] === 'choosing')
+        return { kind: 'choosing', name, pid, token };
+    try {
+        const ticket = BigInt(match[2]);
+        if (ticket <= 0n)
+            return null;
+        return { kind: 'ticket', name, pid, token, ticket };
+    }
+    catch {
+        return null;
+    }
+}
+function processIsAlive(pid) {
+    if (pid === process.pid)
+        return true;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ESRCH')
+            return false;
+        // EPERM means the process exists but is owned by somebody else. Unknown
+        // failures are also treated as live: losing recovery is safer than allowing
+        // two holders into the transaction.
+        return true;
+    }
+}
+function currentUid() {
+    return typeof process.getuid === 'function' ? process.getuid() : undefined;
+}
+function assertOwnedDirectory(directory) {
+    const stat = lstatSync(directory);
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+        throw new Error(`${directory} is not a regular directory; refusing to use it as a file lock.`);
+    }
+    const uid = currentUid();
+    if (uid !== undefined && stat.uid !== uid) {
+        throw new Error(`${directory} is owned by uid ${stat.uid}, not the current user.`);
+    }
+    return { dev: stat.dev, ino: stat.ino };
+}
+function assertSameDirectory(directory, expected) {
+    const current = lstatSync(directory);
+    if (current.isSymbolicLink() ||
+        !current.isDirectory() ||
+        current.dev !== expected.dev ||
+        current.ino !== expected.ino) {
+        throw new Error(`${directory} changed while the file lock was active.`);
+    }
+}
+function sameIdentity(file, expected) {
+    try {
+        const current = lstatSync(file);
+        return current.dev === expected.dev && current.ino === expected.ino;
+    }
+    catch {
+        return false;
+    }
+}
+/** Live protocol entries, pruning only unique paths whose process is gone. */
+function liveEntries(directory, directoryIdentity, observe) {
+    assertSameDirectory(directory, directoryIdentity);
+    const live = [];
+    for (const name of readdirSync(directory)) {
+        const entry = parseEntry(name);
+        if (entry === null)
+            continue;
+        const entryPath = path.join(directory, name);
+        let stat;
+        try {
+            stat = lstatSync(entryPath);
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                continue;
+            throw err;
+        }
+        const uid = currentUid();
+        if (stat.isSymbolicLink() || !stat.isFile() || (uid !== undefined && stat.uid !== uid)) {
+            throw new Error(`${entryPath} is not a current-user-owned regular file-lock entry.`);
+        }
+        if (processIsAlive(entry.pid)) {
+            live.push(entry);
+            continue;
+        }
+        observe?.({ phase: 'stale-entry', entry: name });
+        try {
+            // Recheck the unique dead owner's inode so delayed recovery cannot reap
+            // a replacement published at the same path by external interference.
+            const current = lstatSync(entryPath);
+            if (current.dev === stat.dev && current.ino === stat.ino)
+                unlinkSync(entryPath);
+        }
+        catch {
+            // Another contender already recovered this exact dead owner's unique path.
+        }
+    }
+    return live;
+}
+function publishEmpty(file) {
+    const handle = openSync(file, 'wx', 0o600);
+    try {
+        const stat = fstatSync(handle);
+        return { dev: stat.dev, ino: stat.ino };
+    }
+    finally {
+        closeSync(handle);
+    }
+}
+function publishChoosing(directory, name, deadline, observe) {
+    const file = path.join(directory, name);
+    for (;;) {
+        try {
+            mkdirSync(directory, { recursive: true, mode: 0o700 });
+            const directoryIdentity = assertOwnedDirectory(directory);
+            chmodSync(directory, 0o700);
+            // Recover before registration so a delayed stale cleanup can only name an
+            // old owner's unique path, never this contender's future one.
+            liveEntries(directory, directoryIdentity, observe);
+            const fileIdentity = publishEmpty(file);
+            assertSameDirectory(directory, directoryIdentity);
+            return { file, fileIdentity, directoryIdentity };
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT')
+                throw err;
+            // The previous holder removed an empty rendezvous directory between our
+            // mkdir and publication. Recreate it; once our entry exists, no cooperating
+            // releaser can remove the non-empty directory underneath us.
+            if (Date.now() >= deadline) {
+                throw new Error(`timed out publishing file lock contender in ${directory}`);
+            }
+            Atomics.wait(lockSleep, 0, 0, FILE_LOCK_POLL_MS);
+        }
+    }
+}
+function comesBefore(entry, ticket, pid, token) {
+    if (entry.ticket !== ticket)
+        return entry.ticket < ticket;
+    if (entry.pid !== pid)
+        return entry.pid < pid;
+    return entry.token < token;
+}
+export function withFileLock(file, action, options = {}) {
+    const waitMs = options.waitMs ?? FILE_LOCK_WAIT_MS;
+    const deadline = Date.now() + waitMs;
+    const pid = process.pid;
+    const token = randomBytes(FILE_LOCK_TOKEN_BYTES).toString('hex');
+    const choosingName = `choosing-${pid}-${token}`;
+    let ownedPath = null;
+    let ownedIdentity = null;
+    let directoryIdentity = null;
+    let operationFailed = false;
+    try {
+        const published = publishChoosing(file, choosingName, deadline, options.observe);
+        ownedPath = published.file;
+        ownedIdentity = published.fileIdentity;
+        directoryIdentity = published.directoryIdentity;
+        options.observe?.({ phase: 'choosing-published', entry: choosingName });
+        let highest = 0n;
+        for (const entry of liveEntries(file, directoryIdentity, options.observe)) {
+            if (entry.kind === 'ticket' && entry.ticket > highest)
+                highest = entry.ticket;
+        }
+        const ticket = highest + 1n;
+        const ticketName = `ticket-${ticket}-${pid}-${token}`;
+        const ticketPath = path.join(file, ticketName);
+        // The rename is the doorway: observers see either a chooser or its complete
+        // ticket, never a gap in which a live contender has no published state.
+        renameSync(ownedPath, ticketPath);
+        ownedPath = ticketPath;
+        for (;;) {
+            const blockers = [];
+            for (const entry of liveEntries(file, directoryIdentity, options.observe)) {
+                if (entry.pid === pid && entry.token === token)
+                    continue;
+                if (entry.kind === 'choosing' || comesBefore(entry, ticket, pid, token)) {
+                    blockers.push(entry.name);
+                }
+            }
+            if (blockers.length === 0) {
+                assertSameDirectory(file, directoryIdentity);
+                return action();
+            }
+            options.observe?.({ phase: 'waiting', blockers });
+            if (Date.now() >= deadline)
+                throw new Error(`timed out waiting for file lock ${file}`);
+            Atomics.wait(lockSleep, 0, 0, FILE_LOCK_POLL_MS);
+        }
+    }
+    catch (err) {
+        operationFailed = true;
+        throw err;
+    }
+    finally {
+        let releaseChanged = false;
+        if (ownedPath !== null && ownedIdentity !== null) {
+            try {
+                if (sameIdentity(ownedPath, ownedIdentity))
+                    unlinkSync(ownedPath);
+                else
+                    releaseChanged = true;
+            }
+            catch {
+                // External cleanup cannot turn a release failure into a caller failure.
+            }
+        }
+        try {
+            if (directoryIdentity !== null)
+                assertSameDirectory(file, directoryIdentity);
+            rmdirSync(file);
+        }
+        catch {
+            // Another contender has published, or external cleanup already removed it.
+        }
+        if (releaseChanged && options.strictRelease === true && !operationFailed) {
+            throw new Error(`${ownedPath ?? file} changed while held; refusing to remove the replacement.`);
+        }
+    }
+}
+/**
+ * Serialize a read/merge/write transaction for one user-owned target file.
+ *
+ * This is the single installer-facing lock policy: the target's direct parent
+ * is a real current-user-owned directory, remains the same inode throughout,
+ * and the bakery rendezvous lives beside the target rather than inside it.
+ */
+export function withTargetFileLock(target, action, options = {}) {
+    const parent = path.dirname(target);
+    mkdirSync(parent, { recursive: true });
+    const parentIdentity = assertOwnedDirectory(parent);
+    const lockDirectory = path.join(parent, `.${path.basename(target)}.notifai.lock`);
+    return withFileLock(lockDirectory, () => {
+        assertSameDirectory(parent, parentIdentity);
+        return action();
+    }, { ...options, strictRelease: true });
+}
+//# sourceMappingURL=file-lock.js.map

package/dist/file-lock.js.map

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

package/dist/harnesses.d.ts

@@ -0,0 +1,28 @@
+/** Every harness Notifai ships. This is the sole source of the harness union. */
+export declare const HARNESSES: readonly ["claude-code", "codex", "cursor", "opencode"];
+export type Harness = (typeof HARNESSES)[number];
+/** One canonical wall-clock budget shared by config, hooks, and installers. */
+export declare const HOOK_TIMING: Readonly<{
+    totalSeconds: 480;
+    finalizationReserveSeconds: 45;
+    submissionReserveSeconds: 40;
+    minimumReplySeconds: 60;
+    schedulingSlackSeconds: 1;
+    stdoutReserveSeconds: 5;
+    hostHeadroomSeconds: 60;
+    maxGraceSeconds: 334;
+}>;
+export type StopContinuation = 'decision-block' | 'followup-message' | 'unsupported';
+export interface HarnessCapability {
+    /** How an answer is admitted to another turn in the already-open session. */
+    stopContinuation: StopContinuation;
+    /** Whether delivery remains native after the turn-end event has returned. */
+    dormantWake: 'unsupported' | 'native-session-prompt';
+    /** Concise, honest readiness text for doctor and installation guidance. */
+    deliveryContract: string;
+}
+/**
+ * Exhaustive runtime contract. Adding a harness without deciding every
+ * continuation joint is a type error, not a silently degraded notification.
+ */
+export declare const HARNESS_CAPABILITIES: Record<Harness, HarnessCapability>;

package/dist/harnesses.js

@@ -0,0 +1,40 @@
+/** Every harness Notifai ships. This is the sole source of the harness union. */
+export const HARNESSES = ['claude-code', 'codex', 'cursor', 'opencode'];
+/** One canonical wall-clock budget shared by config, hooks, and installers. */
+export const HOOK_TIMING = Object.freeze({
+    totalSeconds: 480,
+    finalizationReserveSeconds: 45,
+    submissionReserveSeconds: 40,
+    minimumReplySeconds: 60,
+    schedulingSlackSeconds: 1,
+    stdoutReserveSeconds: 5,
+    hostHeadroomSeconds: 60,
+    maxGraceSeconds: 334,
+});
+/**
+ * Exhaustive runtime contract. Adding a harness without deciding every
+ * continuation joint is a type error, not a silently degraded notification.
+ */
+export const HARNESS_CAPABILITIES = {
+    'claude-code': {
+        stopContinuation: 'decision-block',
+        dormantWake: 'unsupported',
+        deliveryContract: 'live Stop continuation; no automatic wake after its bounded wait returns',
+    },
+    codex: {
+        stopContinuation: 'decision-block',
+        dormantWake: 'unsupported',
+        deliveryContract: 'live Stop continuation; no automatic wake after its bounded wait returns',
+    },
+    cursor: {
+        stopContinuation: 'unsupported',
+        dormantWake: 'unsupported',
+        deliveryContract: 'the hook can return a live follow-up, but the invoking shell exposes no exact conversation id; asynchronous ask is unsupported',
+    },
+    opencode: {
+        stopContinuation: 'unsupported',
+        dormantWake: 'unsupported',
+        deliveryContract: 'no proven answer continuation after session.idle; use a blocking reply command',
+    },
+};
+//# sourceMappingURL=harnesses.js.map

package/dist/harnesses.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"harnesses.js","sourceRoot":"","sources":["../src/harnesses.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,aAAa,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,CAAU,CAAA;AAIhF,+EAA+E;AAC/E,MAAM,CAAC,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC;IACvC,YAAY,EAAE,GAAG;IACjB,0BAA0B,EAAE,EAAE;IAC9B,wBAAwB,EAAE,EAAE;IAC5B,mBAAmB,EAAE,EAAE;IACvB,sBAAsB,EAAE,CAAC;IACzB,oBAAoB,EAAE,CAAC;IACvB,mBAAmB,EAAE,EAAE;IACvB,eAAe,EAAE,GAAG;CACrB,CAAC,CAAA;AAgBF;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAuC;IACtE,aAAa,EAAE;QACb,gBAAgB,EAAE,gBAAgB;QAClC,WAAW,EAAE,aAAa;QAC1B,gBAAgB,EAAE,0EAA0E;KAC7F;IACD,KAAK,EAAE;QACL,gBAAgB,EAAE,gBAAgB;QAClC,WAAW,EAAE,aAAa;QAC1B,gBAAgB,EAAE,0EAA0E;KAC7F;IACD,MAAM,EAAE;QACN,gBAAgB,EAAE,aAAa;QAC/B,WAAW,EAAE,aAAa;QAC1B,gBAAgB,EACd,gIAAgI;KACnI;IACD,QAAQ,EAAE;QACR,gBAAgB,EAAE,aAAa;QAC/B,WAAW,EAAE,aAAa;QAC1B,gBAAgB,EACd,gFAAgF;KACnF;CACF,CAAA"}

package/dist/hook-adapter.d.ts

@@ -0,0 +1,27 @@
+export interface HookAdapterTarget {
+    execPath: string;
+    scriptPath: string;
+}
+export interface HookAdapterInspection {
+    path: string;
+    target: HookAdapterTarget | null;
+    problems: string[];
+}
+/**
+ * One user-level identity for every harness and every project/global install.
+ *
+ * The pathname is deliberately outside XDG configuration/state routing. XDG
+ * overrides routinely differ between shells, package managers, and harness
+ * processes; allowing one to select this path would put mutable environment
+ * back into every trusted definition. Only the user's home boundary selects
+ * it; CLI, Node, package-manager, checkout, and preference paths stay behind
+ * it and may change without changing hook identity.
+ */
+export declare function hookAdapterPath(homeDir?: string): string;
+/** Install or repair the stable adapter and atomically retarget its implementation. */
+export declare function installHookAdapter(target: HookAdapterTarget, homeDir?: string): {
+    path: string;
+    changed: boolean;
+};
+/** Inspect the shared adapter without executing either it or its registered CLI. */
+export declare function inspectHookAdapter(homeDir?: string): HookAdapterInspection;

package/dist/hook-adapter.js

@@ -0,0 +1,188 @@
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, statSync, } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { atomicWriteFileSync } from './atomic-file.js';
+import { withTargetFileLock } from './file-lock.js';
+const ADAPTER_MARKER = '# notifai managed hook adapter';
+const ADAPTER_VERSION = 1;
+/**
+ * One user-level identity for every harness and every project/global install.
+ *
+ * The pathname is deliberately outside XDG configuration/state routing. XDG
+ * overrides routinely differ between shells, package managers, and harness
+ * processes; allowing one to select this path would put mutable environment
+ * back into every trusted definition. Only the user's home boundary selects
+ * it; CLI, Node, package-manager, checkout, and preference paths stay behind
+ * it and may change without changing hook identity.
+ */
+export function hookAdapterPath(homeDir = os.userInfo().homedir) {
+    return path.join(homeDir, '.notifai', 'bin', 'hook-adapter');
+}
+/** Install or repair the stable adapter and atomically retarget its implementation. */
+export function installHookAdapter(target, homeDir) {
+    assertUsableTarget(target);
+    const file = hookAdapterPath(homeDir);
+    ensureManagedDirectories(homeDir ?? os.userInfo().homedir);
+    const source = hookAdapterSource(target);
+    return withTargetFileLock(file, () => {
+        const existing = existsSync(file) ? readSafeManagedFile(file) : null;
+        const changed = existing === null || existing.contents !== source || (existing.mode & 0o777) !== 0o700;
+        if (changed) {
+            atomicWriteFileSync(file, source, {
+                mode: 0o700,
+                preserveMode: false,
+                requireCurrentUserOwner: true,
+            });
+        }
+        return { path: file, changed };
+    });
+}
+function assertUsableTarget(target) {
+    let exec;
+    try {
+        exec = statSync(target.execPath);
+    }
+    catch {
+        throw new Error(`Hook adapter runtime ${target.execPath} does not exist.`);
+    }
+    if (!exec.isFile() || (exec.mode & 0o111) === 0) {
+        throw new Error(`Hook adapter runtime ${target.execPath} is not executable.`);
+    }
+    try {
+        if (!statSync(target.scriptPath).isFile()) {
+            throw new Error(`Hook adapter CLI ${target.scriptPath} is not a regular file.`);
+        }
+    }
+    catch (err) {
+        if (err instanceof Error && err.message.startsWith('Hook adapter CLI '))
+            throw err;
+        throw new Error(`Hook adapter CLI ${target.scriptPath} does not exist.`);
+    }
+}
+/** Inspect the shared adapter without executing either it or its registered CLI. */
+export function inspectHookAdapter(homeDir) {
+    const file = hookAdapterPath(homeDir);
+    if (!existsSync(file)) {
+        return { path: file, target: null, problems: [`${file} is missing; rerun \`notifai hooks install\``] };
+    }
+    let stat;
+    try {
+        stat = lstatSync(file);
+    }
+    catch (err) {
+        return { path: file, target: null, problems: [String(err)] };
+    }
+    if (stat.isSymbolicLink() || !stat.isFile()) {
+        return {
+            path: file,
+            target: null,
+            problems: [`${file} is not a regular file; refusing the adapter`],
+        };
+    }
+    const problems = [];
+    const uid = typeof process.getuid === 'function' ? process.getuid() : undefined;
+    if (uid !== undefined && stat.uid !== uid) {
+        problems.push(`${file} is owned by uid ${stat.uid}, not the current user`);
+    }
+    if ((stat.mode & 0o077) !== 0 || (stat.mode & 0o700) !== 0o700) {
+        problems.push(`${file} permissions are ${(stat.mode & 0o777).toString(8)}, expected 700`);
+    }
+    const contents = readFileSync(file, 'utf8');
+    if (!contents.startsWith(`#!/bin/sh\n${ADAPTER_MARKER}\n`)) {
+        problems.push(`${file} has no managed adapter marker`);
+    }
+    const version = Number(/^# adapter-version: (\d+)$/m.exec(contents)?.[1] ?? Number.NaN);
+    if (version !== ADAPTER_VERSION)
+        problems.push(`${file} uses obsolete adapter version ${version}`);
+    const target = parseTarget(contents);
+    if (target === null) {
+        problems.push(`${file} has malformed target metadata`);
+    }
+    else {
+        try {
+            const exec = statSync(target.execPath);
+            if (!exec.isFile() || (exec.mode & 0o111) === 0) {
+                problems.push(`registered runtime ${target.execPath} is not executable`);
+            }
+        }
+        catch {
+            problems.push(`registered runtime ${target.execPath} is missing`);
+        }
+        try {
+            if (!statSync(target.scriptPath).isFile()) {
+                problems.push(`registered CLI ${target.scriptPath} is not a regular file`);
+            }
+        }
+        catch {
+            problems.push(`registered CLI ${target.scriptPath} is missing`);
+        }
+    }
+    return { path: file, target, problems };
+}
+function hookAdapterSource(target) {
+    return `#!/bin/sh
+${ADAPTER_MARKER}
+# adapter-version: ${ADAPTER_VERSION}
+# target-exec-json: ${JSON.stringify(target.execPath)}
+# target-script-json: ${JSON.stringify(target.scriptPath)}
+set -eu
+
+registered_exec=${quote(target.execPath)}
+registered_script=${quote(target.scriptPath)}
+
+if [ -x "$registered_exec" ] && [ -f "$registered_script" ]; then
+  exec "$registered_exec" "$registered_script" "$@"
+fi
+
+printf '%s\n' 'Notifai hook adapter target is stale; run notifai hooks install.' >&2
+exit 127
+`;
+}
+function parseTarget(contents) {
+    const exec = /^# target-exec-json: (.+)$/m.exec(contents)?.[1];
+    const script = /^# target-script-json: (.+)$/m.exec(contents)?.[1];
+    if (exec === undefined || script === undefined)
+        return null;
+    try {
+        const execPath = JSON.parse(exec);
+        const scriptPath = JSON.parse(script);
+        return typeof execPath === 'string' && typeof scriptPath === 'string'
+            ? { execPath, scriptPath }
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+function quote(value) {
+    return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+function ensureManagedDirectories(homeDir) {
+    if (!existsSync(homeDir))
+        mkdirSync(homeDir, { recursive: true, mode: 0o700 });
+    for (const dir of [path.join(homeDir, '.notifai'), path.join(homeDir, '.notifai', 'bin')]) {
+        if (!existsSync(dir))
+            mkdirSync(dir, { mode: 0o700 });
+        const stat = lstatSync(dir);
+        if (stat.isSymbolicLink() || !stat.isDirectory()) {
+            throw new Error(`${dir} is not a regular directory; refusing to install the hook adapter.`);
+        }
+        const uid = typeof process.getuid === 'function' ? process.getuid() : undefined;
+        if (uid !== undefined && stat.uid !== uid) {
+            throw new Error(`${dir} is owned by uid ${stat.uid}, not the current user.`);
+        }
+        chmodSync(dir, 0o700);
+    }
+}
+function readSafeManagedFile(file) {
+    const stat = lstatSync(file);
+    if (stat.isSymbolicLink() || !stat.isFile()) {
+        throw new Error(`${file} is not a regular file; refusing to replace it.`);
+    }
+    const uid = typeof process.getuid === 'function' ? process.getuid() : undefined;
+    if (uid !== undefined && stat.uid !== uid) {
+        throw new Error(`${file} is owned by uid ${stat.uid}, not the current user.`);
+    }
+    return { contents: readFileSync(file, 'utf8'), mode: stat.mode };
+}
+//# sourceMappingURL=hook-adapter.js.map

package/dist/hook-adapter.js.map

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

package/dist/hook-input.d.ts

@@ -0,0 +1,10 @@
+import type { Readable } from 'node:stream';
+/**
+ * Read one harness-hook envelope without letting a stuck pipe hold the prompt.
+ *
+ * A timeout or stream error before any bytes arrive rejects, so the hook can
+ * record that its input was unavailable. Once bytes exist they are more useful
+ * than the transport failure: complete JSON can still run, while partial or
+ * capped JSON reaches the hook's malformed/truncated diagnostic.
+ */
+export declare function readStdinWithTimeout(input?: Readable, timeoutMs?: number, maxBytes?: number): Promise<string>;

package/dist/hook-input.js

@@ -0,0 +1,64 @@
+const TRUNCATED_INPUT_SUFFIX = '\n[notifai: hook input truncated]\n';
+/**
+ * Read one harness-hook envelope without letting a stuck pipe hold the prompt.
+ *
+ * A timeout or stream error before any bytes arrive rejects, so the hook can
+ * record that its input was unavailable. Once bytes exist they are more useful
+ * than the transport failure: complete JSON can still run, while partial or
+ * capped JSON reaches the hook's malformed/truncated diagnostic.
+ */
+export function readStdinWithTimeout(input = process.stdin, timeoutMs = 2_000, maxBytes = 1_000_000) {
+    if (input.isTTY === true)
+        return Promise.resolve('');
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let total = 0;
+        let settled = false;
+        const cleanup = () => {
+            clearTimeout(timer);
+            input.off('data', onData);
+            input.off('end', onEnd);
+            input.off('error', onError);
+            input.destroy();
+        };
+        const finishBuffered = () => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            resolve(Buffer.concat(chunks).toString('utf8'));
+        };
+        const failEmpty = (err) => {
+            if (settled)
+                return;
+            if (chunks.length > 0)
+                return finishBuffered();
+            settled = true;
+            cleanup();
+            reject(err);
+        };
+        const onData = (chunk) => {
+            const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            const remaining = Math.max(0, maxBytes - total);
+            if (bytes.length <= remaining) {
+                chunks.push(bytes);
+                total += bytes.length;
+                return;
+            }
+            if (remaining > 0) {
+                chunks.push(bytes.subarray(0, remaining));
+                total += remaining;
+            }
+            chunks.push(Buffer.from(TRUNCATED_INPUT_SUFFIX));
+            finishBuffered();
+        };
+        const onEnd = () => finishBuffered();
+        const onError = (err) => failEmpty(err);
+        const timer = setTimeout(() => failEmpty(new Error(`timed out waiting ${timeoutMs}ms for hook input`)), timeoutMs);
+        timer.unref?.();
+        input.on('data', onData);
+        input.once('end', onEnd);
+        input.once('error', onError);
+    });
+}
+//# sourceMappingURL=hook-input.js.map