@abaigram/abai-stub 0.0.0-stage → 0.2.0

package/dist/wire/descriptor.d.ts

@@ -0,0 +1,38 @@
+/** Discovery record a program with a wire endpoint writes next to its socket. */
+export interface WireDescriptor {
+    pid: number;
+    socket: string;
+    cwd: string;
+    /** The program's name; "unknown" when a foreign descriptor has none. */
+    name: string;
+    mode: string;
+    /** ISO timestamp. */
+    startedAt: string;
+}
+/** Longest socket path accepted (macOS sun_path is 104 bytes including the NUL). */
+export declare const MAX_SOCKET_PATH_BYTES = 103;
+/** Path of the descriptor file for a pid. */
+export declare function descriptorPath(runDir: string, pid: number): string;
+/** Default Unix socket path for a pid. */
+export declare function defaultSocketPath(runDir: string, pid: number): string;
+/** Throw when a socket path exceeds MAX_SOCKET_PATH_BYTES. */
+export declare function assertSocketPathLength(socketPath: string): void;
+/** Create the run dir with mode 0o700 (tightening an existing one) and return it. */
+export declare function ensureRunDir(runDir: string): string;
+/** True when the path exists and is a Unix socket. */
+export declare function isSocketFile(path: string): boolean;
+/** True when a process with this pid exists (including ones we may not signal). */
+export declare function isPidAlive(pid: number): boolean;
+/** Atomically write a descriptor file (mode 0o600) via a temp file and rename. */
+export declare function writeDescriptor(runDir: string, descriptor: WireDescriptor): void;
+/**
+ * Read all valid descriptors in filename order; a missing dir yields []. A
+ * descriptor needs a numeric `pid` and a string `socket`; extra fields (a
+ * foreign program's) are kept, and a missing `name` reads as "unknown".
+ */
+export declare function readDescriptors(runDir: string): WireDescriptor[];
+/** Remove a descriptor file; a missing file is not an error. */
+export declare function removeDescriptor(runDir: string, pid: number): void;
+/** Delete descriptors (and their sockets) of dead processes; return the live descriptors. */
+export declare function pruneDescriptors(runDir: string): WireDescriptor[];
+//# sourceMappingURL=descriptor.d.ts.map

package/dist/wire/descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"descriptor.d.ts","sourceRoot":"","sources":["../../src/wire/descriptor.ts"],"names":[],"mappings":"AAeA,iFAAiF;AACjF,MAAM,WAAW,cAAc;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,qBAAqB;IACrB,SAAS,EAAE,MAAM,CAAC;CAClB;AAED,oFAAoF;AACpF,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC,6CAA6C;AAC7C,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAElE;AAED,0CAA0C;AAC1C,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAErE;AAED,8DAA8D;AAC9D,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAK/D;AAED,qFAAqF;AACrF,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAInD;AAED,sDAAsD;AACtD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAMlD;AAED,mFAAmF;AACnF,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAS/C;AAED,kFAAkF;AAClF,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,cAAc,GAAG,IAAI,CAchF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,EAAE,CA6BhE;AAED,gEAAgE;AAChE,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAOlE;AAED,6FAA6F;AAC7F,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,EAAE,CAuBjE","sourcesContent":["// Discovery records for the wire endpoint: a program writes one next to its\n// socket in a run directory, and a client finds the program through it.\nimport { Buffer } from \"node:buffer\";\nimport {\n\tchmodSync,\n\tlstatSync,\n\tmkdirSync,\n\treaddirSync,\n\treadFileSync,\n\trenameSync,\n\tunlinkSync,\n\twriteFileSync,\n} from \"node:fs\";\nimport { join } from \"node:path\";\n\n/** Discovery record a program with a wire endpoint writes next to its socket. */\nexport interface WireDescriptor {\n\tpid: number;\n\tsocket: string;\n\tcwd: string;\n\t/** The program's name; \"unknown\" when a foreign descriptor has none. */\n\tname: string;\n\tmode: string;\n\t/** ISO timestamp. */\n\tstartedAt: string;\n}\n\n/** Longest socket path accepted (macOS sun_path is 104 bytes including the NUL). */\nexport const MAX_SOCKET_PATH_BYTES = 103;\n\n/** Path of the descriptor file for a pid. */\nexport function descriptorPath(runDir: string, pid: number): string {\n\treturn join(runDir, `${pid}.json`);\n}\n\n/** Default Unix socket path for a pid. */\nexport function defaultSocketPath(runDir: string, pid: number): string {\n\treturn join(runDir, `${pid}.sock`);\n}\n\n/** Throw when a socket path exceeds MAX_SOCKET_PATH_BYTES. */\nexport function assertSocketPathLength(socketPath: string): void {\n\tconst bytes = Buffer.byteLength(socketPath);\n\tif (bytes > MAX_SOCKET_PATH_BYTES) {\n\t\tthrow new Error(`socket path is too long (${bytes} bytes, max ${MAX_SOCKET_PATH_BYTES}): ${socketPath}`);\n\t}\n}\n\n/** Create the run dir with mode 0o700 (tightening an existing one) and return it. */\nexport function ensureRunDir(runDir: string): string {\n\tmkdirSync(runDir, { recursive: true, mode: 0o700 });\n\tchmodSync(runDir, 0o700);\n\treturn runDir;\n}\n\n/** True when the path exists and is a Unix socket. */\nexport function isSocketFile(path: string): boolean {\n\ttry {\n\t\treturn lstatSync(path).isSocket();\n\t} catch {\n\t\treturn false;\n\t}\n}\n\n/** True when a process with this pid exists (including ones we may not signal). */\nexport function isPidAlive(pid: number): boolean {\n\ttry {\n\t\tprocess.kill(pid, 0);\n\t\treturn true;\n\t} catch (error) {\n\t\tconst code = (error as NodeJS.ErrnoException).code;\n\t\tif (code === \"EPERM\") return true;\n\t\treturn false;\n\t}\n}\n\n/** Atomically write a descriptor file (mode 0o600) via a temp file and rename. */\nexport function writeDescriptor(runDir: string, descriptor: WireDescriptor): void {\n\tconst target = descriptorPath(runDir, descriptor.pid);\n\tconst tmp = `${target}.${process.pid}.tmp`;\n\ttry {\n\t\twriteFileSync(tmp, `${JSON.stringify(descriptor)}\\n`, { mode: 0o600 });\n\t\trenameSync(tmp, target);\n\t} catch (error) {\n\t\ttry {\n\t\t\tunlinkSync(tmp);\n\t\t} catch {\n\t\t\t// ignore\n\t\t}\n\t\tthrow error;\n\t}\n}\n\n/**\n * Read all valid descriptors in filename order; a missing dir yields []. A\n * descriptor needs a numeric `pid` and a string `socket`; extra fields (a\n * foreign program's) are kept, and a missing `name` reads as \"unknown\".\n */\nexport function readDescriptors(runDir: string): WireDescriptor[] {\n\tlet names: string[];\n\ttry {\n\t\tnames = readdirSync(runDir);\n\t} catch (error) {\n\t\tif ((error as NodeJS.ErrnoException).code === \"ENOENT\") return [];\n\t\tthrow error;\n\t}\n\tconst result: WireDescriptor[] = [];\n\tfor (const name of names.filter((n) => n.endsWith(\".json\")).sort()) {\n\t\tlet parsed: unknown;\n\t\ttry {\n\t\t\tparsed = JSON.parse(readFileSync(join(runDir, name), \"utf8\"));\n\t\t} catch {\n\t\t\tcontinue;\n\t\t}\n\t\tif (\n\t\t\ttypeof parsed !== \"object\" ||\n\t\t\tparsed === null ||\n\t\t\ttypeof (parsed as { pid?: unknown }).pid !== \"number\" ||\n\t\t\ttypeof (parsed as { socket?: unknown }).socket !== \"string\"\n\t\t) {\n\t\t\tcontinue;\n\t\t}\n\t\tconst record = parsed as WireDescriptor;\n\t\tif (typeof record.name !== \"string\") record.name = \"unknown\";\n\t\tresult.push(record);\n\t}\n\treturn result;\n}\n\n/** Remove a descriptor file; a missing file is not an error. */\nexport function removeDescriptor(runDir: string, pid: number): void {\n\ttry {\n\t\tunlinkSync(descriptorPath(runDir, pid));\n\t} catch (error) {\n\t\tif ((error as NodeJS.ErrnoException).code === \"ENOENT\") return;\n\t\tthrow error;\n\t}\n}\n\n/** Delete descriptors (and their sockets) of dead processes; return the live descriptors. */\nexport function pruneDescriptors(runDir: string): WireDescriptor[] {\n\tconst live: WireDescriptor[] = [];\n\tfor (const descriptor of readDescriptors(runDir)) {\n\t\tif (isPidAlive(descriptor.pid)) {\n\t\t\tlive.push(descriptor);\n\t\t\tcontinue;\n\t\t}\n\t\ttry {\n\t\t\tunlinkSync(descriptorPath(runDir, descriptor.pid));\n\t\t} catch {\n\t\t\t// ignore\n\t\t}\n\t\t// Only a default-path socket is known to belong to the dead pid. An explicit\n\t\t// path may have been reclaimed by a live process since, so prune never touches it.\n\t\tif (descriptor.socket === defaultSocketPath(runDir, descriptor.pid) && isSocketFile(descriptor.socket)) {\n\t\t\ttry {\n\t\t\t\tunlinkSync(descriptor.socket);\n\t\t\t} catch {\n\t\t\t\t// ignore\n\t\t\t}\n\t\t}\n\t}\n\treturn live;\n}\n"]}

package/dist/wire/descriptor.js

@@ -0,0 +1,144 @@
+// Discovery records for the wire endpoint: a program writes one next to its
+// socket in a run directory, and a client finds the program through it.
+import { Buffer } from "node:buffer";
+import { chmodSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+/** Longest socket path accepted (macOS sun_path is 104 bytes including the NUL). */
+export const MAX_SOCKET_PATH_BYTES = 103;
+/** Path of the descriptor file for a pid. */
+export function descriptorPath(runDir, pid) {
+    return join(runDir, `${pid}.json`);
+}
+/** Default Unix socket path for a pid. */
+export function defaultSocketPath(runDir, pid) {
+    return join(runDir, `${pid}.sock`);
+}
+/** Throw when a socket path exceeds MAX_SOCKET_PATH_BYTES. */
+export function assertSocketPathLength(socketPath) {
+    const bytes = Buffer.byteLength(socketPath);
+    if (bytes > MAX_SOCKET_PATH_BYTES) {
+        throw new Error(`socket path is too long (${bytes} bytes, max ${MAX_SOCKET_PATH_BYTES}): ${socketPath}`);
+    }
+}
+/** Create the run dir with mode 0o700 (tightening an existing one) and return it. */
+export function ensureRunDir(runDir) {
+    mkdirSync(runDir, { recursive: true, mode: 0o700 });
+    chmodSync(runDir, 0o700);
+    return runDir;
+}
+/** True when the path exists and is a Unix socket. */
+export function isSocketFile(path) {
+    try {
+        return lstatSync(path).isSocket();
+    }
+    catch {
+        return false;
+    }
+}
+/** True when a process with this pid exists (including ones we may not signal). */
+export function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "EPERM")
+            return true;
+        return false;
+    }
+}
+/** Atomically write a descriptor file (mode 0o600) via a temp file and rename. */
+export function writeDescriptor(runDir, descriptor) {
+    const target = descriptorPath(runDir, descriptor.pid);
+    const tmp = `${target}.${process.pid}.tmp`;
+    try {
+        writeFileSync(tmp, `${JSON.stringify(descriptor)}\n`, { mode: 0o600 });
+        renameSync(tmp, target);
+    }
+    catch (error) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch {
+            // ignore
+        }
+        throw error;
+    }
+}
+/**
+ * Read all valid descriptors in filename order; a missing dir yields []. A
+ * descriptor needs a numeric `pid` and a string `socket`; extra fields (a
+ * foreign program's) are kept, and a missing `name` reads as "unknown".
+ */
+export function readDescriptors(runDir) {
+    let names;
+    try {
+        names = readdirSync(runDir);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    const result = [];
+    for (const name of names.filter((n) => n.endsWith(".json")).sort()) {
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(join(runDir, name), "utf8"));
+        }
+        catch {
+            continue;
+        }
+        if (typeof parsed !== "object" ||
+            parsed === null ||
+            typeof parsed.pid !== "number" ||
+            typeof parsed.socket !== "string") {
+            continue;
+        }
+        const record = parsed;
+        if (typeof record.name !== "string")
+            record.name = "unknown";
+        result.push(record);
+    }
+    return result;
+}
+/** Remove a descriptor file; a missing file is not an error. */
+export function removeDescriptor(runDir, pid) {
+    try {
+        unlinkSync(descriptorPath(runDir, pid));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return;
+        throw error;
+    }
+}
+/** Delete descriptors (and their sockets) of dead processes; return the live descriptors. */
+export function pruneDescriptors(runDir) {
+    const live = [];
+    for (const descriptor of readDescriptors(runDir)) {
+        if (isPidAlive(descriptor.pid)) {
+            live.push(descriptor);
+            continue;
+        }
+        try {
+            unlinkSync(descriptorPath(runDir, descriptor.pid));
+        }
+        catch {
+            // ignore
+        }
+        // Only a default-path socket is known to belong to the dead pid. An explicit
+        // path may have been reclaimed by a live process since, so prune never touches it.
+        if (descriptor.socket === defaultSocketPath(runDir, descriptor.pid) && isSocketFile(descriptor.socket)) {
+            try {
+                unlinkSync(descriptor.socket);
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
+    return live;
+}
+//# sourceMappingURL=descriptor.js.map

package/dist/wire/descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"descriptor.js","sourceRoot":"","sources":["../../src/wire/descriptor.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,wEAAwE;AACxE,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EACN,SAAS,EACT,SAAS,EACT,SAAS,EACT,WAAW,EACX,YAAY,EACZ,UAAU,EACV,UAAU,EACV,aAAa,GACb,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAcjC,oFAAoF;AACpF,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAEzC,6CAA6C;AAC7C,MAAM,UAAU,cAAc,CAAC,MAAc,EAAE,GAAW,EAAU;IACnE,OAAO,IAAI,CAAC,MAAM,EAAE,GAAG,GAAG,OAAO,CAAC,CAAC;AAAA,CACnC;AAED,0CAA0C;AAC1C,MAAM,UAAU,iBAAiB,CAAC,MAAc,EAAE,GAAW,EAAU;IACtE,OAAO,IAAI,CAAC,MAAM,EAAE,GAAG,GAAG,OAAO,CAAC,CAAC;AAAA,CACnC;AAED,8DAA8D;AAC9D,MAAM,UAAU,sBAAsB,CAAC,UAAkB,EAAQ;IAChE,MAAM,KAAK,GAAG,MAAM,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;IAC5C,IAAI,KAAK,GAAG,qBAAqB,EAAE,CAAC;QACnC,MAAM,IAAI,KAAK,CAAC,4BAA4B,KAAK,eAAe,qBAAqB,MAAM,UAAU,EAAE,CAAC,CAAC;IAC1G,CAAC;AAAA,CACD;AAED,qFAAqF;AACrF,MAAM,UAAU,YAAY,CAAC,MAAc,EAAU;IACpD,SAAS,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACpD,SAAS,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACzB,OAAO,MAAM,CAAC;AAAA,CACd;AAED,sDAAsD;AACtD,MAAM,UAAU,YAAY,CAAC,IAAY,EAAW;IACnD,IAAI,CAAC;QACJ,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC;IACnC,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,KAAK,CAAC;IACd,CAAC;AAAA,CACD;AAED,mFAAmF;AACnF,MAAM,UAAU,UAAU,CAAC,GAAW,EAAW;IAChD,IAAI,CAAC;QACJ,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC;IACb,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,MAAM,IAAI,GAAI,KAA+B,CAAC,IAAI,CAAC;QACnD,IAAI,IAAI,KAAK,OAAO;YAAE,OAAO,IAAI,CAAC;QAClC,OAAO,KAAK,CAAC;IACd,CAAC;AAAA,CACD;AAED,kFAAkF;AAClF,MAAM,UAAU,eAAe,CAAC,MAAc,EAAE,UAA0B,EAAQ;IACjF,MAAM,MAAM,GAAG,cAAc,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC;IACtD,MAAM,GAAG,GAAG,GAAG,MAAM,IAAI,OAAO,CAAC,GAAG,MAAM,CAAC;IAC3C,IAAI,CAAC;QACJ,aAAa,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QACvE,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IACzB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,IAAI,CAAC;YACJ,UAAU,CAAC,GAAG,CAAC,CAAC;QACjB,CAAC;QAAC,MAAM,CAAC;YACR,SAAS;QACV,CAAC;QACD,MAAM,KAAK,CAAC;IACb,CAAC;AAAA,CACD;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,MAAc,EAAoB;IACjE,IAAI,KAAe,CAAC;IACpB,IAAI,CAAC;QACJ,KAAK,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;IAC7B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,EAAE,CAAC;QAClE,MAAM,KAAK,CAAC;IACb,CAAC;IACD,MAAM,MAAM,GAAqB,EAAE,CAAC;IACpC,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QACpE,IAAI,MAAe,CAAC;QACpB,IAAI,CAAC;YACJ,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;QAC/D,CAAC;QAAC,MAAM,CAAC;YACR,SAAS;QACV,CAAC;QACD,IACC,OAAO,MAAM,KAAK,QAAQ;YAC1B,MAAM,KAAK,IAAI;YACf,OAAQ,MAA4B,CAAC,GAAG,KAAK,QAAQ;YACrD,OAAQ,MAA+B,CAAC,MAAM,KAAK,QAAQ,EAC1D,CAAC;YACF,SAAS;QACV,CAAC;QACD,MAAM,MAAM,GAAG,MAAwB,CAAC;QACxC,IAAI,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ;YAAE,MAAM,CAAC,IAAI,GAAG,SAAS,CAAC;QAC7D,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACrB,CAAC;IACD,OAAO,MAAM,CAAC;AAAA,CACd;AAED,gEAAgE;AAChE,MAAM,UAAU,gBAAgB,CAAC,MAAc,EAAE,GAAW,EAAQ;IACnE,IAAI,CAAC;QACJ,UAAU,CAAC,cAAc,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;IACzC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO;QAC/D,MAAM,KAAK,CAAC;IACb,CAAC;AAAA,CACD;AAED,6FAA6F;AAC7F,MAAM,UAAU,gBAAgB,CAAC,MAAc,EAAoB;IAClE,MAAM,IAAI,GAAqB,EAAE,CAAC;IAClC,KAAK,MAAM,UAAU,IAAI,eAAe,CAAC,MAAM,CAAC,EAAE,CAAC;QAClD,IAAI,UAAU,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YAChC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YACtB,SAAS;QACV,CAAC;QACD,IAAI,CAAC;YACJ,UAAU,CAAC,cAAc,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC;QACpD,CAAC;QAAC,MAAM,CAAC;YACR,SAAS;QACV,CAAC;QACD,6EAA6E;QAC7E,mFAAmF;QACnF,IAAI,UAAU,CAAC,MAAM,KAAK,iBAAiB,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,CAAC,IAAI,YAAY,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YACxG,IAAI,CAAC;gBACJ,UAAU,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;YAC/B,CAAC;YAAC,MAAM,CAAC;gBACR,SAAS;YACV,CAAC;QACF,CAAC;IACF,CAAC;IACD,OAAO,IAAI,CAAC;AAAA,CACZ","sourcesContent":["// Discovery records for the wire endpoint: a program writes one next to its\n// socket in a run directory, and a client finds the program through it.\nimport { Buffer } from \"node:buffer\";\nimport {\n\tchmodSync,\n\tlstatSync,\n\tmkdirSync,\n\treaddirSync,\n\treadFileSync,\n\trenameSync,\n\tunlinkSync,\n\twriteFileSync,\n} from \"node:fs\";\nimport { join } from \"node:path\";\n\n/** Discovery record a program with a wire endpoint writes next to its socket. */\nexport interface WireDescriptor {\n\tpid: number;\n\tsocket: string;\n\tcwd: string;\n\t/** The program's name; \"unknown\" when a foreign descriptor has none. */\n\tname: string;\n\tmode: string;\n\t/** ISO timestamp. */\n\tstartedAt: string;\n}\n\n/** Longest socket path accepted (macOS sun_path is 104 bytes including the NUL). */\nexport const MAX_SOCKET_PATH_BYTES = 103;\n\n/** Path of the descriptor file for a pid. */\nexport function descriptorPath(runDir: string, pid: number): string {\n\treturn join(runDir, `${pid}.json`);\n}\n\n/** Default Unix socket path for a pid. */\nexport function defaultSocketPath(runDir: string, pid: number): string {\n\treturn join(runDir, `${pid}.sock`);\n}\n\n/** Throw when a socket path exceeds MAX_SOCKET_PATH_BYTES. */\nexport function assertSocketPathLength(socketPath: string): void {\n\tconst bytes = Buffer.byteLength(socketPath);\n\tif (bytes > MAX_SOCKET_PATH_BYTES) {\n\t\tthrow new Error(`socket path is too long (${bytes} bytes, max ${MAX_SOCKET_PATH_BYTES}): ${socketPath}`);\n\t}\n}\n\n/** Create the run dir with mode 0o700 (tightening an existing one) and return it. */\nexport function ensureRunDir(runDir: string): string {\n\tmkdirSync(runDir, { recursive: true, mode: 0o700 });\n\tchmodSync(runDir, 0o700);\n\treturn runDir;\n}\n\n/** True when the path exists and is a Unix socket. */\nexport function isSocketFile(path: string): boolean {\n\ttry {\n\t\treturn lstatSync(path).isSocket();\n\t} catch {\n\t\treturn false;\n\t}\n}\n\n/** True when a process with this pid exists (including ones we may not signal). */\nexport function isPidAlive(pid: number): boolean {\n\ttry {\n\t\tprocess.kill(pid, 0);\n\t\treturn true;\n\t} catch (error) {\n\t\tconst code = (error as NodeJS.ErrnoException).code;\n\t\tif (code === \"EPERM\") return true;\n\t\treturn false;\n\t}\n}\n\n/** Atomically write a descriptor file (mode 0o600) via a temp file and rename. */\nexport function writeDescriptor(runDir: string, descriptor: WireDescriptor): void {\n\tconst target = descriptorPath(runDir, descriptor.pid);\n\tconst tmp = `${target}.${process.pid}.tmp`;\n\ttry {\n\t\twriteFileSync(tmp, `${JSON.stringify(descriptor)}\\n`, { mode: 0o600 });\n\t\trenameSync(tmp, target);\n\t} catch (error) {\n\t\ttry {\n\t\t\tunlinkSync(tmp);\n\t\t} catch {\n\t\t\t// ignore\n\t\t}\n\t\tthrow error;\n\t}\n}\n\n/**\n * Read all valid descriptors in filename order; a missing dir yields []. A\n * descriptor needs a numeric `pid` and a string `socket`; extra fields (a\n * foreign program's) are kept, and a missing `name` reads as \"unknown\".\n */\nexport function readDescriptors(runDir: string): WireDescriptor[] {\n\tlet names: string[];\n\ttry {\n\t\tnames = readdirSync(runDir);\n\t} catch (error) {\n\t\tif ((error as NodeJS.ErrnoException).code === \"ENOENT\") return [];\n\t\tthrow error;\n\t}\n\tconst result: WireDescriptor[] = [];\n\tfor (const name of names.filter((n) => n.endsWith(\".json\")).sort()) {\n\t\tlet parsed: unknown;\n\t\ttry {\n\t\t\tparsed = JSON.parse(readFileSync(join(runDir, name), \"utf8\"));\n\t\t} catch {\n\t\t\tcontinue;\n\t\t}\n\t\tif (\n\t\t\ttypeof parsed !== \"object\" ||\n\t\t\tparsed === null ||\n\t\t\ttypeof (parsed as { pid?: unknown }).pid !== \"number\" ||\n\t\t\ttypeof (parsed as { socket?: unknown }).socket !== \"string\"\n\t\t) {\n\t\t\tcontinue;\n\t\t}\n\t\tconst record = parsed as WireDescriptor;\n\t\tif (typeof record.name !== \"string\") record.name = \"unknown\";\n\t\tresult.push(record);\n\t}\n\treturn result;\n}\n\n/** Remove a descriptor file; a missing file is not an error. */\nexport function removeDescriptor(runDir: string, pid: number): void {\n\ttry {\n\t\tunlinkSync(descriptorPath(runDir, pid));\n\t} catch (error) {\n\t\tif ((error as NodeJS.ErrnoException).code === \"ENOENT\") return;\n\t\tthrow error;\n\t}\n}\n\n/** Delete descriptors (and their sockets) of dead processes; return the live descriptors. */\nexport function pruneDescriptors(runDir: string): WireDescriptor[] {\n\tconst live: WireDescriptor[] = [];\n\tfor (const descriptor of readDescriptors(runDir)) {\n\t\tif (isPidAlive(descriptor.pid)) {\n\t\t\tlive.push(descriptor);\n\t\t\tcontinue;\n\t\t}\n\t\ttry {\n\t\t\tunlinkSync(descriptorPath(runDir, descriptor.pid));\n\t\t} catch {\n\t\t\t// ignore\n\t\t}\n\t\t// Only a default-path socket is known to belong to the dead pid. An explicit\n\t\t// path may have been reclaimed by a live process since, so prune never touches it.\n\t\tif (descriptor.socket === defaultSocketPath(runDir, descriptor.pid) && isSocketFile(descriptor.socket)) {\n\t\t\ttry {\n\t\t\t\tunlinkSync(descriptor.socket);\n\t\t\t} catch {\n\t\t\t\t// ignore\n\t\t\t}\n\t\t}\n\t}\n\treturn live;\n}\n"]}

package/dist/wire/framing.d.ts

@@ -0,0 +1,11 @@
+import type { Readable } from "node:stream";
+/** The default line cap on both ends: a large payload fits. */
+export declare const DEFAULT_MAX_LINE_BYTES: number;
+/**
+ * LF-only line reader with a byte cap. Modeled on `attachJsonlLineReader`
+ * Chunks stay
+ * buffers and only the newest one is scanned for the newline, so a large
+ * line costs one concatenation instead of a rescan per chunk.
+ */
+export declare function attachCappedLineReader(socket: Readable, maxLineBytes: number, onLine: (line: string) => void, onOverflow: () => void): () => void;
+//# sourceMappingURL=framing.d.ts.map

package/dist/wire/framing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"framing.d.ts","sourceRoot":"","sources":["../../src/wire/framing.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C,+DAA+D;AAC/D,eAAO,MAAM,sBAAsB,QAAmB,CAAC;AAEvD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACrC,MAAM,EAAE,QAAQ,EAChB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,EAC9B,UAAU,EAAE,MAAM,IAAI,GACpB,MAAM,IAAI,CA8BZ","sourcesContent":["// Line framing for the wire protocol.\nimport type { Readable } from \"node:stream\";\n\n/** The default line cap on both ends: a large payload fits. */\nexport const DEFAULT_MAX_LINE_BYTES = 64 * 1024 * 1024;\n\n/**\n * LF-only line reader with a byte cap. Modeled on `attachJsonlLineReader`\n * Chunks stay\n * buffers and only the newest one is scanned for the newline, so a large\n * line costs one concatenation instead of a rescan per chunk.\n */\nexport function attachCappedLineReader(\n\tsocket: Readable,\n\tmaxLineBytes: number,\n\tonLine: (line: string) => void,\n\tonOverflow: () => void,\n): () => void {\n\tlet chunks: Buffer[] = [];\n\tlet pendingBytes = 0;\n\tconst onData = (data: string | Buffer) => {\n\t\tlet chunk = typeof data === \"string\" ? Buffer.from(data, \"utf8\") : data;\n\t\twhile (true) {\n\t\t\tconst newlineIndex = chunk.indexOf(10);\n\t\t\tif (newlineIndex === -1) break;\n\t\t\tconst head = chunk.subarray(0, newlineIndex);\n\t\t\tconst line = (chunks.length === 0 ? head : Buffer.concat([...chunks, head])).toString(\"utf8\");\n\t\t\tchunks = [];\n\t\t\tpendingBytes = 0;\n\t\t\tchunk = chunk.subarray(newlineIndex + 1);\n\t\t\tonLine(line.endsWith(\"\\r\") ? line.slice(0, -1) : line);\n\t\t\tif (socket.destroyed) return;\n\t\t}\n\t\tif (chunk.length > 0) {\n\t\t\tchunks.push(chunk);\n\t\t\tpendingBytes += chunk.length;\n\t\t\tif (pendingBytes > maxLineBytes) {\n\t\t\t\tchunks = [];\n\t\t\t\tpendingBytes = 0;\n\t\t\t\tonOverflow();\n\t\t\t}\n\t\t}\n\t};\n\tsocket.on(\"data\", onData);\n\treturn () => {\n\t\tsocket.off(\"data\", onData);\n\t};\n}\n"]}

package/dist/wire/framing.js

@@ -0,0 +1,42 @@
+/** The default line cap on both ends: a large payload fits. */
+export const DEFAULT_MAX_LINE_BYTES = 64 * 1024 * 1024;
+/**
+ * LF-only line reader with a byte cap. Modeled on `attachJsonlLineReader`
+ * Chunks stay
+ * buffers and only the newest one is scanned for the newline, so a large
+ * line costs one concatenation instead of a rescan per chunk.
+ */
+export function attachCappedLineReader(socket, maxLineBytes, onLine, onOverflow) {
+    let chunks = [];
+    let pendingBytes = 0;
+    const onData = (data) => {
+        let chunk = typeof data === "string" ? Buffer.from(data, "utf8") : data;
+        while (true) {
+            const newlineIndex = chunk.indexOf(10);
+            if (newlineIndex === -1)
+                break;
+            const head = chunk.subarray(0, newlineIndex);
+            const line = (chunks.length === 0 ? head : Buffer.concat([...chunks, head])).toString("utf8");
+            chunks = [];
+            pendingBytes = 0;
+            chunk = chunk.subarray(newlineIndex + 1);
+            onLine(line.endsWith("\r") ? line.slice(0, -1) : line);
+            if (socket.destroyed)
+                return;
+        }
+        if (chunk.length > 0) {
+            chunks.push(chunk);
+            pendingBytes += chunk.length;
+            if (pendingBytes > maxLineBytes) {
+                chunks = [];
+                pendingBytes = 0;
+                onOverflow();
+            }
+        }
+    };
+    socket.on("data", onData);
+    return () => {
+        socket.off("data", onData);
+    };
+}
+//# sourceMappingURL=framing.js.map

package/dist/wire/framing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"framing.js","sourceRoot":"","sources":["../../src/wire/framing.ts"],"names":[],"mappings":"AAGA,+DAA+D;AAC/D,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CACrC,MAAgB,EAChB,YAAoB,EACpB,MAA8B,EAC9B,UAAsB,EACT;IACb,IAAI,MAAM,GAAa,EAAE,CAAC;IAC1B,IAAI,YAAY,GAAG,CAAC,CAAC;IACrB,MAAM,MAAM,GAAG,CAAC,IAAqB,EAAE,EAAE,CAAC;QACzC,IAAI,KAAK,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QACxE,OAAO,IAAI,EAAE,CAAC;YACb,MAAM,YAAY,GAAG,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;YACvC,IAAI,YAAY,KAAK,CAAC,CAAC;gBAAE,MAAM;YAC/B,MAAM,IAAI,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC;YAC7C,MAAM,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;YAC9F,MAAM,GAAG,EAAE,CAAC;YACZ,YAAY,GAAG,CAAC,CAAC;YACjB,KAAK,GAAG,KAAK,CAAC,QAAQ,CAAC,YAAY,GAAG,CAAC,CAAC,CAAC;YACzC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;YACvD,IAAI,MAAM,CAAC,SAAS;gBAAE,OAAO;QAC9B,CAAC;QACD,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACtB,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACnB,YAAY,IAAI,KAAK,CAAC,MAAM,CAAC;YAC7B,IAAI,YAAY,GAAG,YAAY,EAAE,CAAC;gBACjC,MAAM,GAAG,EAAE,CAAC;gBACZ,YAAY,GAAG,CAAC,CAAC;gBACjB,UAAU,EAAE,CAAC;YACd,CAAC;QACF,CAAC;IAAA,CACD,CAAC;IACF,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1B,OAAO,GAAG,EAAE,CAAC;QACZ,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAA,CAC3B,CAAC;AAAA,CACF","sourcesContent":["// Line framing for the wire protocol.\nimport type { Readable } from \"node:stream\";\n\n/** The default line cap on both ends: a large payload fits. */\nexport const DEFAULT_MAX_LINE_BYTES = 64 * 1024 * 1024;\n\n/**\n * LF-only line reader with a byte cap. Modeled on `attachJsonlLineReader`\n * Chunks stay\n * buffers and only the newest one is scanned for the newline, so a large\n * line costs one concatenation instead of a rescan per chunk.\n */\nexport function attachCappedLineReader(\n\tsocket: Readable,\n\tmaxLineBytes: number,\n\tonLine: (line: string) => void,\n\tonOverflow: () => void,\n): () => void {\n\tlet chunks: Buffer[] = [];\n\tlet pendingBytes = 0;\n\tconst onData = (data: string | Buffer) => {\n\t\tlet chunk = typeof data === \"string\" ? Buffer.from(data, \"utf8\") : data;\n\t\twhile (true) {\n\t\t\tconst newlineIndex = chunk.indexOf(10);\n\t\t\tif (newlineIndex === -1) break;\n\t\t\tconst head = chunk.subarray(0, newlineIndex);\n\t\t\tconst line = (chunks.length === 0 ? head : Buffer.concat([...chunks, head])).toString(\"utf8\");\n\t\t\tchunks = [];\n\t\t\tpendingBytes = 0;\n\t\t\tchunk = chunk.subarray(newlineIndex + 1);\n\t\t\tonLine(line.endsWith(\"\\r\") ? line.slice(0, -1) : line);\n\t\t\tif (socket.destroyed) return;\n\t\t}\n\t\tif (chunk.length > 0) {\n\t\t\tchunks.push(chunk);\n\t\t\tpendingBytes += chunk.length;\n\t\t\tif (pendingBytes > maxLineBytes) {\n\t\t\t\tchunks = [];\n\t\t\t\tpendingBytes = 0;\n\t\t\t\tonOverflow();\n\t\t\t}\n\t\t}\n\t};\n\tsocket.on(\"data\", onData);\n\treturn () => {\n\t\tsocket.off(\"data\", onData);\n\t};\n}\n"]}

package/dist/wire/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./descriptor.ts";
+export * from "./framing.ts";
+export * from "./protocol.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/wire/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/wire/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC","sourcesContent":["export * from \"./descriptor.ts\";\nexport * from \"./framing.ts\";\nexport * from \"./protocol.ts\";\n"]}

package/dist/wire/index.js

@@ -0,0 +1,4 @@
+export * from "./descriptor.js";
+export * from "./framing.js";
+export * from "./protocol.js";
+//# sourceMappingURL=index.js.map

package/dist/wire/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/wire/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC","sourcesContent":["export * from \"./descriptor.ts\";\nexport * from \"./framing.ts\";\nexport * from \"./protocol.ts\";\n"]}

package/dist/wire/protocol.d.ts

@@ -0,0 +1,257 @@
+import type { Manifest } from "../manifest/manifest.ts";
+export declare const PROTOCOL_VERSION = 1;
+/**
+ * The extensions a TypeScript stub speaks beyond the v1 core, named in
+ * `hello.abai.extensions` so a client speaks each only when it is offered:
+ * `consent` (consent stated on a request or hook answer), `content` (the
+ * install, use and turn slots on `get_content`), `turns` (turns and
+ * touchpoints as messages), `call_codes` (a code beside every error),
+ * `defaults` (a `hook_response` whose `result` is null asks the program to
+ * apply the decision's default, audited as a default; a v1-core host has no
+ * such answer, so the client sends it the manifest default instead),
+ * `lifecycle` (the `lifecycle {op}` command of section 5.5 and a cause on
+ * `turn_end`), `messages` (the `record_message` command: the harness hands
+ * the stub one message sent or received over the run's network for the
+ * audit log, section 10).
+ */
+export declare const EXTENSIONS: readonly ["consent", "content", "turns", "call_codes", "defaults", "lifecycle", "messages"];
+export type Extension = (typeof EXTENSIONS)[number];
+/** Why a request failed, in the capability error vocabulary (the `call_codes` extension). */
+export type WireErrorCode = "unknown" | "forbidden" | "denied" | "invalid" | "timeout" | "error";
+/** The abai identity of the program, in `hello`. */
+export interface HelloAbai {
+    name: string;
+    abaigrammar: string;
+    modes: string[];
+    audit: {
+        path: string;
+        failed: string | null;
+    };
+    /** Wire extensions beyond the v1 core; absent means none. */
+    extensions?: string[];
+}
+export interface HelloMessage {
+    type: "hello";
+    protocol: number;
+    pid: number;
+    /** The program's own version string, when it has one. */
+    version?: string;
+    cwd: string;
+    /** A directory the program calls its own (arx-06's agent dir); absent for most programs. */
+    agentDir?: string;
+    mode: string;
+    /** What this host offers: hooks and commands policy does not forbid. */
+    capabilities: {
+        hooks: string[];
+        commands: string[];
+    };
+    /** Sequence number of the last event the host counted. */
+    lastSeq: number;
+    /** This connection's id (`k1`, `k2`, ...), as the audit log names it. */
+    connection: string;
+    abai: HelloAbai;
+}
+export type WireEvent = {
+    type: string;
+} & Record<string, unknown>;
+export interface EventMessage {
+    type: "event";
+    seq: number;
+    ts: number;
+    event: WireEvent;
+    /** A sized field was cut to its declared max. An additive field; a v1-core client ignores it. */
+    truncated?: boolean;
+}
+/** A `snapshot` message some hosts send; parsed, its shape is the host's. */
+export type LooseSnapshotMessage = {
+    type: "snapshot";
+} & Record<string, unknown>;
+/** An event that could not be serialized was dropped; the program continues. */
+export interface SerializeErrorMessage {
+    type: "serialize_error";
+    seq: number;
+    ts: number;
+    eventType: string;
+    error: string;
+}
+export type WireResponse = {
+    type: "response";
+    id?: string;
+    command: string;
+    success: true;
+    data?: unknown;
+} | {
+    type: "response";
+    id?: string;
+    command: string;
+    success: false;
+    error: string;
+    code?: WireErrorCode;
+};
+/** Extension `turns`: the program gives the harness a turn; `turn_end` hands control back. */
+export interface TurnMessage {
+    type: "turn";
+    id: string;
+    name: string;
+    /** How long the program waits before the turn ends on its own. */
+    timeoutMs: number;
+    content?: string;
+}
+/** Extension `turns`: a program-initiated `install` or `session`; `touchpoint_end` returns it. */
+export interface TouchpointMessage {
+    type: "touchpoint";
+    id: string;
+    kind: "install" | "session";
+    content?: string;
+}
+/** Interceptable hook round trip. Only sent to the connection holding the hook. */
+export interface HookMessage {
+    type: "hook";
+    id: string;
+    hook: string;
+    timeoutMs: number;
+    payload: unknown;
+}
+export interface HookTimeoutMessage {
+    type: "hook_timeout";
+    hook: string;
+    id: string;
+}
+/** The claimant's claims were dropped by the host (three consecutive timeouts). */
+export interface HookClaimsReleasedMessage {
+    type: "hook_claims_released";
+    reason: string;
+    hooks: string[];
+}
+/**
+ * A hook could not be served: the payload was not serializable (no `hook`
+ * message was sent for this id) or the claimant's result failed validation.
+ * The run continued as if the hook were unclaimed.
+ */
+export interface HookRejectedMessage {
+    type: "hook_rejected";
+    id: string;
+    hook: string;
+    error: string;
+}
+export type ServerMessage = HelloMessage | EventMessage | LooseSnapshotMessage | SerializeErrorMessage | WireResponse | HookMessage | HookTimeoutMessage | HookClaimsReleasedMessage | HookRejectedMessage | TurnMessage | TouchpointMessage;
+/**
+ * Per-connection event filter. `include` restricts the stream to the listed
+ * event types; `exclude` drops the listed types. A `subscribe` request
+ * replaces the whole filter, so an omitted `exclude` means no exclusions.
+ */
+export interface SubscriptionFilter {
+    include?: string[];
+    exclude?: string[];
+}
+/** The library's commands: the connection's own, the stub's, and the cells channel. */
+export type LibraryCommand = {
+    type: "ping";
+} | ({
+    type: "subscribe";
+} & SubscriptionFilter) | {
+    type: "claim_hooks";
+    hooks: string[];
+    timeoutMs?: number;
+} | {
+    type: "release_hooks";
+    hooks?: string[];
+} | {
+    type: "get_manifest";
+} | {
+    type: "get_content";
+} | {
+    type: "get_audit";
+    limit?: number;
+} | {
+    type: "get_cells";
+} | {
+    type: "set_cell";
+    name: string;
+    value: unknown;
+} | {
+    type: "lifecycle";
+    op: string;
+};
+/**
+ * Every command a client can send: the library commands, plus any capability
+ * call sent as `{ type: <capability name>, ...params }`. The advertised list
+ * is the host's (`hello.capabilities.commands`).
+ */
+export type WireCommand = LibraryCommand | ({
+    type: string;
+} & Record<string, unknown>);
+/** Consent stated for an act whose policy is `confirm` (abaigrammar section 10); the `consent` extension. */
+export type WireConsent = "approved" | "auto" | "denied";
+export interface RequestMessage {
+    type: "request";
+    id: string;
+    command: WireCommand;
+    /** The agent's stated reason for an act of control; written to the audit log. */
+    reason?: string;
+    /** Extension `consent`: ignored by a v1-core host. */
+    consent?: WireConsent;
+}
+export interface HookResponseMessage {
+    type: "hook_response";
+    id: string;
+    result: unknown;
+    /** The agent's stated reason for its answer; written to the audit log. */
+    reason?: string;
+    /** Extension `consent`: ignored by a v1-core host. */
+    consent?: WireConsent;
+}
+/** Extension `turns`: the harness is done with a turn. `cause` says why the agent did nothing with it (`budget`). */
+export interface TurnEndMessage {
+    type: "turn_end";
+    id: string;
+    cause?: string;
+}
+/** Extension `turns`: the harness is done with a touchpoint. */
+export interface TouchpointEndMessage {
+    type: "touchpoint_end";
+    id: string;
+}
+export type ClientMessage = RequestMessage | HookResponseMessage | TurnEndMessage | TouchpointEndMessage;
+/** `get_cells`: every cell's value (sized ones cut to their max) and the host's event sequence number. */
+export interface GetCellsData {
+    seq: number;
+    cells: Record<string, unknown>;
+}
+/** `set_cell`: the knob and the value that landed (it may be clamped). */
+export interface SetCellData {
+    name: string;
+    value: unknown;
+}
+/** `get_manifest`: the effective manifest of this running host. */
+export interface GetManifestData {
+    manifest: Manifest;
+}
+/** `get_content`: the content slots the stub embeds (abaigrammar section 8). A v1-core host sends `identity` only. */
+export interface GetContentData {
+    identity: string;
+    install?: string;
+    use?: string;
+    turns?: Record<string, string>;
+}
+/** `lifecycle {op: "status"}`: what the stub knows of its own process. */
+export interface LifecycleStatusData {
+    pid: number;
+    name: string;
+    mode: string;
+    cwd: string;
+    startedAt: string;
+    connections: number;
+    paused: boolean;
+    /** A launcher handed this program its connection, so the full lifecycle is available to it. */
+    launched: boolean;
+}
+/** `get_audit`: the log's location and state, and its last records. */
+export interface GetAuditData {
+    path: string;
+    failed: string | null;
+    records: unknown[];
+    /** More records exist than were returned. */
+    truncated: boolean;
+}
+//# sourceMappingURL=protocol.d.ts.map

package/dist/wire/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../src/wire/protocol.ts"],"names":[],"mappings":"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","sourcesContent":["// abai wire protocol v1 (abaigrammar section 6.3): LF-framed JSON lines over a\n// local socket. The core is the generic part of arx-06's supervisor protocol,\n// unchanged, so a running arx-06 is a sidecar target; extensions are\n// advertised in hello.abai.extensions.\nimport type { Manifest } from \"../manifest/manifest.ts\";\n\nexport const PROTOCOL_VERSION = 1;\n\n/**\n * The extensions a TypeScript stub speaks beyond the v1 core, named in\n * `hello.abai.extensions` so a client speaks each only when it is offered:\n * `consent` (consent stated on a request or hook answer), `content` (the\n * install, use and turn slots on `get_content`), `turns` (turns and\n * touchpoints as messages), `call_codes` (a code beside every error),\n * `defaults` (a `hook_response` whose `result` is null asks the program to\n * apply the decision's default, audited as a default; a v1-core host has no\n * such answer, so the client sends it the manifest default instead),\n * `lifecycle` (the `lifecycle {op}` command of section 5.5 and a cause on\n * `turn_end`), `messages` (the `record_message` command: the harness hands\n * the stub one message sent or received over the run's network for the\n * audit log, section 10).\n */\nexport const EXTENSIONS = [\"consent\", \"content\", \"turns\", \"call_codes\", \"defaults\", \"lifecycle\", \"messages\"] as const;\nexport type Extension = (typeof EXTENSIONS)[number];\n\n/** Why a request failed, in the capability error vocabulary (the `call_codes` extension). */\nexport type WireErrorCode = \"unknown\" | \"forbidden\" | \"denied\" | \"invalid\" | \"timeout\" | \"error\";\n\n// ---------------------------------------------------------------------------\n// Server -> client\n// ---------------------------------------------------------------------------\n\n/** The abai identity of the program, in `hello`. */\nexport interface HelloAbai {\n\tname: string;\n\tabaigrammar: string;\n\tmodes: string[];\n\taudit: { path: string; failed: string | null };\n\t/** Wire extensions beyond the v1 core; absent means none. */\n\textensions?: string[];\n}\n\nexport interface HelloMessage {\n\ttype: \"hello\";\n\tprotocol: number;\n\tpid: number;\n\t/** The program's own version string, when it has one. */\n\tversion?: string;\n\tcwd: string;\n\t/** A directory the program calls its own (arx-06's agent dir); absent for most programs. */\n\tagentDir?: string;\n\tmode: string;\n\t/** What this host offers: hooks and commands policy does not forbid. */\n\tcapabilities: { hooks: string[]; commands: string[] };\n\t/** Sequence number of the last event the host counted. */\n\tlastSeq: number;\n\t/** This connection's id (`k1`, `k2`, ...), as the audit log names it. */\n\tconnection: string;\n\tabai: HelloAbai;\n}\n\nexport type WireEvent = { type: string } & Record<string, unknown>;\n\nexport interface EventMessage {\n\ttype: \"event\";\n\tseq: number;\n\tts: number;\n\tevent: WireEvent;\n\t/** A sized field was cut to its declared max. An additive field; a v1-core client ignores it. */\n\ttruncated?: boolean;\n}\n\n/** A `snapshot` message some hosts send; parsed, its shape is the host's. */\nexport type LooseSnapshotMessage = { type: \"snapshot\" } & Record<string, unknown>;\n\n/** An event that could not be serialized was dropped; the program continues. */\nexport interface SerializeErrorMessage {\n\ttype: \"serialize_error\";\n\tseq: number;\n\tts: number;\n\teventType: string;\n\terror: string;\n}\n\nexport type WireResponse =\n\t| { type: \"response\"; id?: string; command: string; success: true; data?: unknown }\n\t| { type: \"response\"; id?: string; command: string; success: false; error: string; code?: WireErrorCode };\n\n/** Extension `turns`: the program gives the harness a turn; `turn_end` hands control back. */\nexport interface TurnMessage {\n\ttype: \"turn\";\n\tid: string;\n\tname: string;\n\t/** How long the program waits before the turn ends on its own. */\n\ttimeoutMs: number;\n\tcontent?: string;\n}\n\n/** Extension `turns`: a program-initiated `install` or `session`; `touchpoint_end` returns it. */\nexport interface TouchpointMessage {\n\ttype: \"touchpoint\";\n\tid: string;\n\tkind: \"install\" | \"session\";\n\tcontent?: string;\n}\n\n/** Interceptable hook round trip. Only sent to the connection holding the hook. */\nexport interface HookMessage {\n\ttype: \"hook\";\n\tid: string;\n\thook: string;\n\ttimeoutMs: number;\n\tpayload: unknown;\n}\n\nexport interface HookTimeoutMessage {\n\ttype: \"hook_timeout\";\n\thook: string;\n\tid: string;\n}\n\n/** The claimant's claims were dropped by the host (three consecutive timeouts). */\nexport interface HookClaimsReleasedMessage {\n\ttype: \"hook_claims_released\";\n\treason: string;\n\thooks: string[];\n}\n\n/**\n * A hook could not be served: the payload was not serializable (no `hook`\n * message was sent for this id) or the claimant's result failed validation.\n * The run continued as if the hook were unclaimed.\n */\nexport interface HookRejectedMessage {\n\ttype: \"hook_rejected\";\n\tid: string;\n\thook: string;\n\terror: string;\n}\n\nexport type ServerMessage =\n\t| HelloMessage\n\t| EventMessage\n\t| LooseSnapshotMessage\n\t| SerializeErrorMessage\n\t| WireResponse\n\t| HookMessage\n\t| HookTimeoutMessage\n\t| HookClaimsReleasedMessage\n\t| HookRejectedMessage\n\t| TurnMessage\n\t| TouchpointMessage;\n\n// ---------------------------------------------------------------------------\n// Client -> server\n// ---------------------------------------------------------------------------\n\n/**\n * Per-connection event filter. `include` restricts the stream to the listed\n * event types; `exclude` drops the listed types. A `subscribe` request\n * replaces the whole filter, so an omitted `exclude` means no exclusions.\n */\nexport interface SubscriptionFilter {\n\tinclude?: string[];\n\texclude?: string[];\n}\n\n/** The library's commands: the connection's own, the stub's, and the cells channel. */\nexport type LibraryCommand =\n\t// connection\n\t| { type: \"ping\" }\n\t| ({ type: \"subscribe\" } & SubscriptionFilter)\n\t| { type: \"claim_hooks\"; hooks: string[]; timeoutMs?: number }\n\t| { type: \"release_hooks\"; hooks?: string[] }\n\t// library\n\t| { type: \"get_manifest\" }\n\t| { type: \"get_content\" }\n\t| { type: \"get_audit\"; limit?: number }\n\t// cells (abaigrammar section 5.2)\n\t| { type: \"get_cells\" }\n\t| { type: \"set_cell\"; name: string; value: unknown }\n\t// lifecycle (abaigrammar section 5.5), the `lifecycle` extension: status always, pause and resume for a\n\t// cooperative pause, stop for the declared stop handler; start and restart are the launcher's own\n\t| { type: \"lifecycle\"; op: string };\n\n/**\n * Every command a client can send: the library commands, plus any capability\n * call sent as `{ type: <capability name>, ...params }`. The advertised list\n * is the host's (`hello.capabilities.commands`).\n */\nexport type WireCommand = LibraryCommand | ({ type: string } & Record<string, unknown>);\n\n/** Consent stated for an act whose policy is `confirm` (abaigrammar section 10); the `consent` extension. */\nexport type WireConsent = \"approved\" | \"auto\" | \"denied\";\n\nexport interface RequestMessage {\n\ttype: \"request\";\n\tid: string;\n\tcommand: WireCommand;\n\t/** The agent's stated reason for an act of control; written to the audit log. */\n\treason?: string;\n\t/** Extension `consent`: ignored by a v1-core host. */\n\tconsent?: WireConsent;\n}\n\nexport interface HookResponseMessage {\n\ttype: \"hook_response\";\n\tid: string;\n\tresult: unknown;\n\t/** The agent's stated reason for its answer; written to the audit log. */\n\treason?: string;\n\t/** Extension `consent`: ignored by a v1-core host. */\n\tconsent?: WireConsent;\n}\n\n/** Extension `turns`: the harness is done with a turn. `cause` says why the agent did nothing with it (`budget`). */\nexport interface TurnEndMessage {\n\ttype: \"turn_end\";\n\tid: string;\n\tcause?: string;\n}\n\n/** Extension `turns`: the harness is done with a touchpoint. */\nexport interface TouchpointEndMessage {\n\ttype: \"touchpoint_end\";\n\tid: string;\n}\n\nexport type ClientMessage = RequestMessage | HookResponseMessage | TurnEndMessage | TouchpointEndMessage;\n\n// ---------------------------------------------------------------------------\n// Response data of the library commands\n// ---------------------------------------------------------------------------\n\n/** `get_cells`: every cell's value (sized ones cut to their max) and the host's event sequence number. */\nexport interface GetCellsData {\n\tseq: number;\n\tcells: Record<string, unknown>;\n}\n\n/** `set_cell`: the knob and the value that landed (it may be clamped). */\nexport interface SetCellData {\n\tname: string;\n\tvalue: unknown;\n}\n\n/** `get_manifest`: the effective manifest of this running host. */\nexport interface GetManifestData {\n\tmanifest: Manifest;\n}\n\n/** `get_content`: the content slots the stub embeds (abaigrammar section 8). A v1-core host sends `identity` only. */\nexport interface GetContentData {\n\tidentity: string;\n\tinstall?: string;\n\tuse?: string;\n\tturns?: Record<string, string>;\n}\n\n/** `lifecycle {op: \"status\"}`: what the stub knows of its own process. */\nexport interface LifecycleStatusData {\n\tpid: number;\n\tname: string;\n\tmode: string;\n\tcwd: string;\n\tstartedAt: string;\n\tconnections: number;\n\tpaused: boolean;\n\t/** A launcher handed this program its connection, so the full lifecycle is available to it. */\n\tlaunched: boolean;\n}\n\n/** `get_audit`: the log's location and state, and its last records. */\nexport interface GetAuditData {\n\tpath: string;\n\tfailed: string | null;\n\trecords: unknown[];\n\t/** More records exist than were returned. */\n\ttruncated: boolean;\n}\n"]}

package/dist/wire/protocol.js

@@ -0,0 +1,17 @@
+export const PROTOCOL_VERSION = 1;
+/**
+ * The extensions a TypeScript stub speaks beyond the v1 core, named in
+ * `hello.abai.extensions` so a client speaks each only when it is offered:
+ * `consent` (consent stated on a request or hook answer), `content` (the
+ * install, use and turn slots on `get_content`), `turns` (turns and
+ * touchpoints as messages), `call_codes` (a code beside every error),
+ * `defaults` (a `hook_response` whose `result` is null asks the program to
+ * apply the decision's default, audited as a default; a v1-core host has no
+ * such answer, so the client sends it the manifest default instead),
+ * `lifecycle` (the `lifecycle {op}` command of section 5.5 and a cause on
+ * `turn_end`), `messages` (the `record_message` command: the harness hands
+ * the stub one message sent or received over the run's network for the
+ * audit log, section 10).
+ */
+export const EXTENSIONS = ["consent", "content", "turns", "call_codes", "defaults", "lifecycle", "messages"];
+//# sourceMappingURL=protocol.js.map

package/dist/wire/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../src/wire/protocol.ts"],"names":[],"mappings":"AAMA,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAElC;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,CAAU,CAAC","sourcesContent":["// abai wire protocol v1 (abaigrammar section 6.3): LF-framed JSON lines over a\n// local socket. The core is the generic part of arx-06's supervisor protocol,\n// unchanged, so a running arx-06 is a sidecar target; extensions are\n// advertised in hello.abai.extensions.\nimport type { Manifest } from \"../manifest/manifest.ts\";\n\nexport const PROTOCOL_VERSION = 1;\n\n/**\n * The extensions a TypeScript stub speaks beyond the v1 core, named in\n * `hello.abai.extensions` so a client speaks each only when it is offered:\n * `consent` (consent stated on a request or hook answer), `content` (the\n * install, use and turn slots on `get_content`), `turns` (turns and\n * touchpoints as messages), `call_codes` (a code beside every error),\n * `defaults` (a `hook_response` whose `result` is null asks the program to\n * apply the decision's default, audited as a default; a v1-core host has no\n * such answer, so the client sends it the manifest default instead),\n * `lifecycle` (the `lifecycle {op}` command of section 5.5 and a cause on\n * `turn_end`), `messages` (the `record_message` command: the harness hands\n * the stub one message sent or received over the run's network for the\n * audit log, section 10).\n */\nexport const EXTENSIONS = [\"consent\", \"content\", \"turns\", \"call_codes\", \"defaults\", \"lifecycle\", \"messages\"] as const;\nexport type Extension = (typeof EXTENSIONS)[number];\n\n/** Why a request failed, in the capability error vocabulary (the `call_codes` extension). */\nexport type WireErrorCode = \"unknown\" | \"forbidden\" | \"denied\" | \"invalid\" | \"timeout\" | \"error\";\n\n// ---------------------------------------------------------------------------\n// Server -> client\n// ---------------------------------------------------------------------------\n\n/** The abai identity of the program, in `hello`. */\nexport interface HelloAbai {\n\tname: string;\n\tabaigrammar: string;\n\tmodes: string[];\n\taudit: { path: string; failed: string | null };\n\t/** Wire extensions beyond the v1 core; absent means none. */\n\textensions?: string[];\n}\n\nexport interface HelloMessage {\n\ttype: \"hello\";\n\tprotocol: number;\n\tpid: number;\n\t/** The program's own version string, when it has one. */\n\tversion?: string;\n\tcwd: string;\n\t/** A directory the program calls its own (arx-06's agent dir); absent for most programs. */\n\tagentDir?: string;\n\tmode: string;\n\t/** What this host offers: hooks and commands policy does not forbid. */\n\tcapabilities: { hooks: string[]; commands: string[] };\n\t/** Sequence number of the last event the host counted. */\n\tlastSeq: number;\n\t/** This connection's id (`k1`, `k2`, ...), as the audit log names it. */\n\tconnection: string;\n\tabai: HelloAbai;\n}\n\nexport type WireEvent = { type: string } & Record<string, unknown>;\n\nexport interface EventMessage {\n\ttype: \"event\";\n\tseq: number;\n\tts: number;\n\tevent: WireEvent;\n\t/** A sized field was cut to its declared max. An additive field; a v1-core client ignores it. */\n\ttruncated?: boolean;\n}\n\n/** A `snapshot` message some hosts send; parsed, its shape is the host's. */\nexport type LooseSnapshotMessage = { type: \"snapshot\" } & Record<string, unknown>;\n\n/** An event that could not be serialized was dropped; the program continues. */\nexport interface SerializeErrorMessage {\n\ttype: \"serialize_error\";\n\tseq: number;\n\tts: number;\n\teventType: string;\n\terror: string;\n}\n\nexport type WireResponse =\n\t| { type: \"response\"; id?: string; command: string; success: true; data?: unknown }\n\t| { type: \"response\"; id?: string; command: string; success: false; error: string; code?: WireErrorCode };\n\n/** Extension `turns`: the program gives the harness a turn; `turn_end` hands control back. */\nexport interface TurnMessage {\n\ttype: \"turn\";\n\tid: string;\n\tname: string;\n\t/** How long the program waits before the turn ends on its own. */\n\ttimeoutMs: number;\n\tcontent?: string;\n}\n\n/** Extension `turns`: a program-initiated `install` or `session`; `touchpoint_end` returns it. */\nexport interface TouchpointMessage {\n\ttype: \"touchpoint\";\n\tid: string;\n\tkind: \"install\" | \"session\";\n\tcontent?: string;\n}\n\n/** Interceptable hook round trip. Only sent to the connection holding the hook. */\nexport interface HookMessage {\n\ttype: \"hook\";\n\tid: string;\n\thook: string;\n\ttimeoutMs: number;\n\tpayload: unknown;\n}\n\nexport interface HookTimeoutMessage {\n\ttype: \"hook_timeout\";\n\thook: string;\n\tid: string;\n}\n\n/** The claimant's claims were dropped by the host (three consecutive timeouts). */\nexport interface HookClaimsReleasedMessage {\n\ttype: \"hook_claims_released\";\n\treason: string;\n\thooks: string[];\n}\n\n/**\n * A hook could not be served: the payload was not serializable (no `hook`\n * message was sent for this id) or the claimant's result failed validation.\n * The run continued as if the hook were unclaimed.\n */\nexport interface HookRejectedMessage {\n\ttype: \"hook_rejected\";\n\tid: string;\n\thook: string;\n\terror: string;\n}\n\nexport type ServerMessage =\n\t| HelloMessage\n\t| EventMessage\n\t| LooseSnapshotMessage\n\t| SerializeErrorMessage\n\t| WireResponse\n\t| HookMessage\n\t| HookTimeoutMessage\n\t| HookClaimsReleasedMessage\n\t| HookRejectedMessage\n\t| TurnMessage\n\t| TouchpointMessage;\n\n// ---------------------------------------------------------------------------\n// Client -> server\n// ---------------------------------------------------------------------------\n\n/**\n * Per-connection event filter. `include` restricts the stream to the listed\n * event types; `exclude` drops the listed types. A `subscribe` request\n * replaces the whole filter, so an omitted `exclude` means no exclusions.\n */\nexport interface SubscriptionFilter {\n\tinclude?: string[];\n\texclude?: string[];\n}\n\n/** The library's commands: the connection's own, the stub's, and the cells channel. */\nexport type LibraryCommand =\n\t// connection\n\t| { type: \"ping\" }\n\t| ({ type: \"subscribe\" } & SubscriptionFilter)\n\t| { type: \"claim_hooks\"; hooks: string[]; timeoutMs?: number }\n\t| { type: \"release_hooks\"; hooks?: string[] }\n\t// library\n\t| { type: \"get_manifest\" }\n\t| { type: \"get_content\" }\n\t| { type: \"get_audit\"; limit?: number }\n\t// cells (abaigrammar section 5.2)\n\t| { type: \"get_cells\" }\n\t| { type: \"set_cell\"; name: string; value: unknown }\n\t// lifecycle (abaigrammar section 5.5), the `lifecycle` extension: status always, pause and resume for a\n\t// cooperative pause, stop for the declared stop handler; start and restart are the launcher's own\n\t| { type: \"lifecycle\"; op: string };\n\n/**\n * Every command a client can send: the library commands, plus any capability\n * call sent as `{ type: <capability name>, ...params }`. The advertised list\n * is the host's (`hello.capabilities.commands`).\n */\nexport type WireCommand = LibraryCommand | ({ type: string } & Record<string, unknown>);\n\n/** Consent stated for an act whose policy is `confirm` (abaigrammar section 10); the `consent` extension. */\nexport type WireConsent = \"approved\" | \"auto\" | \"denied\";\n\nexport interface RequestMessage {\n\ttype: \"request\";\n\tid: string;\n\tcommand: WireCommand;\n\t/** The agent's stated reason for an act of control; written to the audit log. */\n\treason?: string;\n\t/** Extension `consent`: ignored by a v1-core host. */\n\tconsent?: WireConsent;\n}\n\nexport interface HookResponseMessage {\n\ttype: \"hook_response\";\n\tid: string;\n\tresult: unknown;\n\t/** The agent's stated reason for its answer; written to the audit log. */\n\treason?: string;\n\t/** Extension `consent`: ignored by a v1-core host. */\n\tconsent?: WireConsent;\n}\n\n/** Extension `turns`: the harness is done with a turn. `cause` says why the agent did nothing with it (`budget`). */\nexport interface TurnEndMessage {\n\ttype: \"turn_end\";\n\tid: string;\n\tcause?: string;\n}\n\n/** Extension `turns`: the harness is done with a touchpoint. */\nexport interface TouchpointEndMessage {\n\ttype: \"touchpoint_end\";\n\tid: string;\n}\n\nexport type ClientMessage = RequestMessage | HookResponseMessage | TurnEndMessage | TouchpointEndMessage;\n\n// ---------------------------------------------------------------------------\n// Response data of the library commands\n// ---------------------------------------------------------------------------\n\n/** `get_cells`: every cell's value (sized ones cut to their max) and the host's event sequence number. */\nexport interface GetCellsData {\n\tseq: number;\n\tcells: Record<string, unknown>;\n}\n\n/** `set_cell`: the knob and the value that landed (it may be clamped). */\nexport interface SetCellData {\n\tname: string;\n\tvalue: unknown;\n}\n\n/** `get_manifest`: the effective manifest of this running host. */\nexport interface GetManifestData {\n\tmanifest: Manifest;\n}\n\n/** `get_content`: the content slots the stub embeds (abaigrammar section 8). A v1-core host sends `identity` only. */\nexport interface GetContentData {\n\tidentity: string;\n\tinstall?: string;\n\tuse?: string;\n\tturns?: Record<string, string>;\n}\n\n/** `lifecycle {op: \"status\"}`: what the stub knows of its own process. */\nexport interface LifecycleStatusData {\n\tpid: number;\n\tname: string;\n\tmode: string;\n\tcwd: string;\n\tstartedAt: string;\n\tconnections: number;\n\tpaused: boolean;\n\t/** A launcher handed this program its connection, so the full lifecycle is available to it. */\n\tlaunched: boolean;\n}\n\n/** `get_audit`: the log's location and state, and its last records. */\nexport interface GetAuditData {\n\tpath: string;\n\tfailed: string | null;\n\trecords: unknown[];\n\t/** More records exist than were returned. */\n\ttruncated: boolean;\n}\n"]}