@abaigram/abai-stub 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joon Hwa Jung
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,23 @@
-# Temporary Holding Version
+# @abaigram/abai-stub
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The library a TypeScript program includes to become an abaigram, with
+`npm install @abaigram/abai-stub @abaigram/abai-embedded-harness`: the
+program side of the contract, `spec/abaigrammar.md` in the
+[abai repository](https://github.com/jjbits/abai). Declarations in code become the
+manifest; cells, events, capabilities, decisions, turns and safepoints are
+the program's end of the five channels; `<prog> abai manifest | doctor`
+is the stub's part of the standard entry.
+
+```ts
+import { createAbaigram } from "@abaigram/abai-stub";
+
+const app = createAbaigram({ name: "counter", modes: ["turns", "sidecar"], cells: {...}, ... });
+if ((await app.entry(process.argv.slice(2))) >= 0) process.exit();
+const depth = app.cell<number>("queue.depth");   // obtain handles once; names are checked here
+const failed = app.event("job.failed");
+depth.set(3);                                     // one store
+await app.decide("on_backlog", { depth: 3 });     // the default, until a harness attaches
+```
+
+In the repository, `implementations/typescript/abai-stub/examples/counter/` is
+the smallest abaigram and the test subject.

package/dist/audit.d.ts

@@ -0,0 +1,102 @@
+import { type DecisionDecl } from "./manifest/manifest.ts";
+export type AuditAct = "capability" | "knob" | "decision" | "turn" | "lifecycle" | "counters" | "message";
+export type AuditOutcome = "ok" | "error" | "forbidden" | "agent" | "default" | "stub" | "failed";
+export interface AuditRecord {
+    ts: string;
+    pid: number;
+    /** The connection that acted (`k1`, `k2`, ...); absent for counters. */
+    conn?: string;
+    act: AuditAct;
+    /** The capability, cell, decision or counter name. */
+    name: string;
+    /** The request id or hook id. */
+    id?: string;
+    /** The parameters (capped, see `capValue`). */
+    params?: unknown;
+    /** A knob's landed value, or a decision answer's summary. */
+    value?: unknown;
+    outcome: AuditOutcome;
+    /** Why a default or stub answer applied, or what a counter counts. */
+    cause?: string;
+    /** What the harness stated for an act whose policy is `confirm`: approved, auto, or denied. */
+    consent?: string;
+    /** The agent's stated reason. */
+    reason?: unknown;
+    error?: unknown;
+    /** Milliseconds from dispatch to settle. */
+    ms?: number;
+    /** Counters only. */
+    count?: number;
+}
+/**
+ * One message sent to or received from a member of the run's network
+ * (section 10), as the harness hands it to the stub for the audit log. The
+ * stub writes it as `act: message` with the counterpart's name as `name`,
+ * the envelope id as `id`, the body capped as `value`.
+ */
+export interface MessageRecord {
+    direction: "sent" | "received";
+    /** The counterpart's name as the network's authority issued it, else its address. */
+    peer: string;
+    addr: string;
+    network: string;
+    /** The envelope id, when the payload carried one. */
+    id?: string;
+    thread?: string;
+    re?: string;
+    /** `msg` is an aiap message; `raw` a plain payload with no envelope. */
+    kind: "msg" | "raw";
+    body: string;
+    outcome: "ok" | "error";
+    /** The agent's stated reason, for a send. */
+    reason?: string;
+    error?: string;
+    /** Milliseconds a send took. */
+    ms?: number;
+}
+/** Whether a value is a `MessageRecord`: what the sidecar endpoint checks before it writes what a harness sent. */
+export declare function isMessageRecord(value: unknown): value is MessageRecord;
+/** Bytes a string or the JSON of a value may take in a record before it is cut. */
+export declare const AUDIT_VALUE_CAP = 512;
+/** Bytes a name, an id or an address from the network may take in a message record. */
+export declare const AUDIT_FIELD_CAP = 256;
+/** A string the harness or the network supplied, cut to `maxBytes` for a record. */
+export declare function capField(value: string, maxBytes?: number): string;
+/** Bytes `tail` reads from the end of the file. */
+export declare const AUDIT_TAIL_BYTES: number;
+/**
+ * Cap a value for a record: a value whose JSON exceeds the cap becomes
+ * `{truncated: true, bytes, head}` with the JSON's first 512 characters, so
+ * the record stays valid JSON. A value that cannot be serialized becomes a
+ * marker string.
+ */
+export declare function capValue(value: unknown): unknown;
+/**
+ * What an audit record keeps of a decision answer: never the transcript.
+ * An options decision keeps the chosen option; any other answer keeps
+ * whether it changed something (a non-empty object).
+ */
+export declare function summarizeAnswer(decision: DecisionDecl | undefined, answer: unknown): unknown;
+export interface AuditTail {
+    records: unknown[];
+    /** More records exist than were returned. */
+    truncated: boolean;
+}
+export declare class AuditLog {
+    readonly path: string;
+    private readonly onFailure;
+    private fd;
+    private _failed;
+    private closed;
+    constructor(path: string, onFailure?: (error: string) => void);
+    /** The error that latched the log off, if any. */
+    get failed(): string | undefined;
+    /** Append one record. Never throws; a no-op once the log failed or was closed. True when the line was written. */
+    append(record: Omit<AuditRecord, "ts" | "pid">): boolean;
+    private fail;
+    /** Close the file descriptor; later appends are dropped. Idempotent; safe inside `process.on("exit")`. */
+    close(): void;
+    /** The last `limit` records, read from the last megabyte of the file. Never throws. */
+    tail(limit: number): AuditTail;
+}
+//# sourceMappingURL=audit.d.ts.map

package/dist/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"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","sourcesContent":["// The audit log (abaigrammar section 10).\n//\n// One JSON line per act of control: a mutate capability call, a knob write\n// by any path, a decision's outcome, and the counters of defaulted decisions\n// flushed at attach, close and exit. Written synchronously, one line per\n// act: acts are rare and a partial line on a crash is worse than a syscall.\n// Nothing here throws into the agent: the first failure latches the log off,\n// reports once through `onFailure`, and every later append is a no-op.\n// `tail` reads the log back for the harness.\nimport { closeSync, fstatSync, mkdirSync, openSync, readSync, writeSync } from \"node:fs\";\nimport { dirname } from \"node:path\";\nimport { cutUtf8, type DecisionDecl } from \"./manifest/manifest.ts\";\n\nexport type AuditAct = \"capability\" | \"knob\" | \"decision\" | \"turn\" | \"lifecycle\" | \"counters\" | \"message\";\nexport type AuditOutcome = \"ok\" | \"error\" | \"forbidden\" | \"agent\" | \"default\" | \"stub\" | \"failed\";\n\nexport interface AuditRecord {\n\tts: string;\n\tpid: number;\n\t/** The connection that acted (`k1`, `k2`, ...); absent for counters. */\n\tconn?: string;\n\tact: AuditAct;\n\t/** The capability, cell, decision or counter name. */\n\tname: string;\n\t/** The request id or hook id. */\n\tid?: string;\n\t/** The parameters (capped, see `capValue`). */\n\tparams?: unknown;\n\t/** A knob's landed value, or a decision answer's summary. */\n\tvalue?: unknown;\n\toutcome: AuditOutcome;\n\t/** Why a default or stub answer applied, or what a counter counts. */\n\tcause?: string;\n\t/** What the harness stated for an act whose policy is `confirm`: approved, auto, or denied. */\n\tconsent?: string;\n\t/** The agent's stated reason. */\n\treason?: unknown;\n\terror?: unknown;\n\t/** Milliseconds from dispatch to settle. */\n\tms?: number;\n\t/** Counters only. */\n\tcount?: number;\n}\n\n/**\n * One message sent to or received from a member of the run's network\n * (section 10), as the harness hands it to the stub for the audit log. The\n * stub writes it as `act: message` with the counterpart's name as `name`,\n * the envelope id as `id`, the body capped as `value`.\n */\nexport interface MessageRecord {\n\tdirection: \"sent\" | \"received\";\n\t/** The counterpart's name as the network's authority issued it, else its address. */\n\tpeer: string;\n\taddr: string;\n\tnetwork: string;\n\t/** The envelope id, when the payload carried one. */\n\tid?: string;\n\tthread?: string;\n\tre?: string;\n\t/** `msg` is an aiap message; `raw` a plain payload with no envelope. */\n\tkind: \"msg\" | \"raw\";\n\tbody: string;\n\toutcome: \"ok\" | \"error\";\n\t/** The agent's stated reason, for a send. */\n\treason?: string;\n\terror?: string;\n\t/** Milliseconds a send took. */\n\tms?: number;\n}\n\nfunction optionalString(value: unknown): boolean {\n\treturn value === undefined || typeof value === \"string\";\n}\n\n/** Whether a value is a `MessageRecord`: what the sidecar endpoint checks before it writes what a harness sent. */\nexport function isMessageRecord(value: unknown): value is MessageRecord {\n\tif (typeof value !== \"object\" || value === null) return false;\n\tconst r = value as Record<string, unknown>;\n\treturn (\n\t\t(r.direction === \"sent\" || r.direction === \"received\") &&\n\t\ttypeof r.peer === \"string\" &&\n\t\ttypeof r.addr === \"string\" &&\n\t\ttypeof r.network === \"string\" &&\n\t\t(r.kind === \"msg\" || r.kind === \"raw\") &&\n\t\ttypeof r.body === \"string\" &&\n\t\t(r.outcome === \"ok\" || r.outcome === \"error\") &&\n\t\toptionalString(r.id) &&\n\t\toptionalString(r.thread) &&\n\t\toptionalString(r.re) &&\n\t\toptionalString(r.reason) &&\n\t\toptionalString(r.error) &&\n\t\t(r.ms === undefined || typeof r.ms === \"number\")\n\t);\n}\n\n/** Bytes a string or the JSON of a value may take in a record before it is cut. */\nexport const AUDIT_VALUE_CAP = 512;\n/** Bytes a name, an id or an address from the network may take in a message record. */\nexport const AUDIT_FIELD_CAP = 256;\n\n/** A string the harness or the network supplied, cut to `maxBytes` for a record. */\nexport function capField(value: string, maxBytes: number = AUDIT_FIELD_CAP): string {\n\treturn cutUtf8(value, maxBytes);\n}\n/** Bytes `tail` reads from the end of the file. */\nexport const AUDIT_TAIL_BYTES = 1024 * 1024;\n\nfunction errorMessage(error: unknown): string {\n\treturn error instanceof Error ? error.message : String(error);\n}\n\n/**\n * Cap a value for a record: a value whose JSON exceeds the cap becomes\n * `{truncated: true, bytes, head}` with the JSON's first 512 characters, so\n * the record stays valid JSON. A value that cannot be serialized becomes a\n * marker string.\n */\nexport function capValue(value: unknown): unknown {\n\tif (value === undefined) return undefined;\n\tlet json: string;\n\ttry {\n\t\tjson = JSON.stringify(value) ?? \"null\";\n\t} catch (error) {\n\t\treturn `<unserializable: ${errorMessage(error)}>`;\n\t}\n\tconst bytes = Buffer.byteLength(json, \"utf8\");\n\tif (bytes <= AUDIT_VALUE_CAP) return value;\n\treturn { truncated: true, bytes, head: cutUtf8(json, AUDIT_VALUE_CAP) };\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\n/**\n * What an audit record keeps of a decision answer: never the transcript.\n * An options decision keeps the chosen option; any other answer keeps\n * whether it changed something (a non-empty object).\n */\nexport function summarizeAnswer(decision: DecisionDecl | undefined, answer: unknown): unknown {\n\tif (answer === undefined) return undefined;\n\tif (decision?.options && typeof answer === \"string\") return { option: answer };\n\treturn { changed: Object.keys(isRecord(answer) ? answer : {}).length > 0 };\n}\n\nexport interface AuditTail {\n\trecords: unknown[];\n\t/** More records exist than were returned. */\n\ttruncated: boolean;\n}\n\nexport class AuditLog {\n\treadonly path: string;\n\tprivate readonly onFailure: ((error: string) => void) | undefined;\n\tprivate fd: number | undefined;\n\tprivate _failed: string | undefined;\n\tprivate closed = false;\n\n\tconstructor(path: string, onFailure?: (error: string) => void) {\n\t\tthis.path = path;\n\t\tthis.onFailure = onFailure;\n\t}\n\n\t/** The error that latched the log off, if any. */\n\tget failed(): string | undefined {\n\t\treturn this._failed;\n\t}\n\n\t/** Append one record. Never throws; a no-op once the log failed or was closed. True when the line was written. */\n\tappend(record: Omit<AuditRecord, \"ts\" | \"pid\">): boolean {\n\t\tif (this._failed !== undefined || this.closed) return false;\n\t\ttry {\n\t\t\tif (this.fd === undefined) {\n\t\t\t\tmkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });\n\t\t\t\tthis.fd = openSync(this.path, \"a\", 0o600);\n\t\t\t}\n\t\t\tconst full: AuditRecord = { ts: new Date().toISOString(), pid: process.pid, ...record };\n\t\t\twriteSync(this.fd, `${JSON.stringify(full)}\\n`);\n\t\t\treturn true;\n\t\t} catch (error) {\n\t\t\tthis.fail(errorMessage(error));\n\t\t\treturn false;\n\t\t}\n\t}\n\n\tprivate fail(error: string): void {\n\t\tthis._failed = error;\n\t\tthis.close();\n\t\ttry {\n\t\t\tthis.onFailure?.(error);\n\t\t} catch {\n\t\t\t// a failure callback must not fail the caller\n\t\t}\n\t}\n\n\t/** Close the file descriptor; later appends are dropped. Idempotent; safe inside `process.on(\"exit\")`. */\n\tclose(): void {\n\t\tthis.closed = true;\n\t\tif (this.fd === undefined) return;\n\t\tconst fd = this.fd;\n\t\tthis.fd = undefined;\n\t\ttry {\n\t\t\tcloseSync(fd);\n\t\t} catch {\n\t\t\t// ignore\n\t\t}\n\t}\n\n\t/** The last `limit` records, read from the last megabyte of the file. Never throws. */\n\ttail(limit: number): AuditTail {\n\t\tlet fd: number | undefined;\n\t\ttry {\n\t\t\tfd = openSync(this.path, \"r\");\n\t\t\tconst size = fstatSync(fd).size;\n\t\t\tconst start = Math.max(0, size - AUDIT_TAIL_BYTES);\n\t\t\tconst buffer = Buffer.alloc(size - start);\n\t\t\tlet read = 0;\n\t\t\twhile (read < buffer.length) {\n\t\t\t\tconst n = readSync(fd, buffer, read, buffer.length - read, start + read);\n\t\t\t\tif (n === 0) break;\n\t\t\t\tread += n;\n\t\t\t}\n\t\t\tconst lines = buffer.toString(\"utf8\", 0, read).split(\"\\n\");\n\t\t\t// the window may start mid-line: drop the first line unless the byte before it ends a line\n\t\t\tif (start > 0) {\n\t\t\t\tconst before = Buffer.alloc(1);\n\t\t\t\tconst n = readSync(fd, before, 0, 1, start - 1);\n\t\t\t\tif (n !== 1 || before[0] !== 0x0a) lines.shift();\n\t\t\t}\n\t\t\tconst records: unknown[] = [];\n\t\t\tfor (const line of lines) {\n\t\t\t\tif (line === \"\") continue;\n\t\t\t\ttry {\n\t\t\t\t\trecords.push(JSON.parse(line));\n\t\t\t\t} catch {\n\t\t\t\t\trecords.push({ raw: line });\n\t\t\t\t}\n\t\t\t}\n\t\t\tconst truncated = start > 0 || records.length > limit;\n\t\t\treturn { records: records.slice(-limit), truncated };\n\t\t} catch (error) {\n\t\t\t// no log yet, or a path that can never hold one (the failure is in `failed`)\n\t\t\tconst code = (error as NodeJS.ErrnoException).code;\n\t\t\tif (code === \"ENOENT\" || code === \"ENOTDIR\") return { records: [], truncated: false };\n\t\t\treturn { records: [{ error: errorMessage(error) }], truncated: false };\n\t\t} finally {\n\t\t\tif (fd !== undefined) {\n\t\t\t\ttry {\n\t\t\t\t\tcloseSync(fd);\n\t\t\t\t} catch {\n\t\t\t\t\t// ignore\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n}\n"]}

package/dist/audit.js

@@ -0,0 +1,196 @@
+// The audit log (abaigrammar section 10).
+//
+// One JSON line per act of control: a mutate capability call, a knob write
+// by any path, a decision's outcome, and the counters of defaulted decisions
+// flushed at attach, close and exit. Written synchronously, one line per
+// act: acts are rare and a partial line on a crash is worse than a syscall.
+// Nothing here throws into the agent: the first failure latches the log off,
+// reports once through `onFailure`, and every later append is a no-op.
+// `tail` reads the log back for the harness.
+import { closeSync, fstatSync, mkdirSync, openSync, readSync, writeSync } from "node:fs";
+import { dirname } from "node:path";
+import { cutUtf8 } from "./manifest/manifest.js";
+function optionalString(value) {
+    return value === undefined || typeof value === "string";
+}
+/** Whether a value is a `MessageRecord`: what the sidecar endpoint checks before it writes what a harness sent. */
+export function isMessageRecord(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const r = value;
+    return ((r.direction === "sent" || r.direction === "received") &&
+        typeof r.peer === "string" &&
+        typeof r.addr === "string" &&
+        typeof r.network === "string" &&
+        (r.kind === "msg" || r.kind === "raw") &&
+        typeof r.body === "string" &&
+        (r.outcome === "ok" || r.outcome === "error") &&
+        optionalString(r.id) &&
+        optionalString(r.thread) &&
+        optionalString(r.re) &&
+        optionalString(r.reason) &&
+        optionalString(r.error) &&
+        (r.ms === undefined || typeof r.ms === "number"));
+}
+/** Bytes a string or the JSON of a value may take in a record before it is cut. */
+export const AUDIT_VALUE_CAP = 512;
+/** Bytes a name, an id or an address from the network may take in a message record. */
+export const AUDIT_FIELD_CAP = 256;
+/** A string the harness or the network supplied, cut to `maxBytes` for a record. */
+export function capField(value, maxBytes = AUDIT_FIELD_CAP) {
+    return cutUtf8(value, maxBytes);
+}
+/** Bytes `tail` reads from the end of the file. */
+export const AUDIT_TAIL_BYTES = 1024 * 1024;
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Cap a value for a record: a value whose JSON exceeds the cap becomes
+ * `{truncated: true, bytes, head}` with the JSON's first 512 characters, so
+ * the record stays valid JSON. A value that cannot be serialized becomes a
+ * marker string.
+ */
+export function capValue(value) {
+    if (value === undefined)
+        return undefined;
+    let json;
+    try {
+        json = JSON.stringify(value) ?? "null";
+    }
+    catch (error) {
+        return `<unserializable: ${errorMessage(error)}>`;
+    }
+    const bytes = Buffer.byteLength(json, "utf8");
+    if (bytes <= AUDIT_VALUE_CAP)
+        return value;
+    return { truncated: true, bytes, head: cutUtf8(json, AUDIT_VALUE_CAP) };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * What an audit record keeps of a decision answer: never the transcript.
+ * An options decision keeps the chosen option; any other answer keeps
+ * whether it changed something (a non-empty object).
+ */
+export function summarizeAnswer(decision, answer) {
+    if (answer === undefined)
+        return undefined;
+    if (decision?.options && typeof answer === "string")
+        return { option: answer };
+    return { changed: Object.keys(isRecord(answer) ? answer : {}).length > 0 };
+}
+export class AuditLog {
+    path;
+    onFailure;
+    fd;
+    _failed;
+    closed = false;
+    constructor(path, onFailure) {
+        this.path = path;
+        this.onFailure = onFailure;
+    }
+    /** The error that latched the log off, if any. */
+    get failed() {
+        return this._failed;
+    }
+    /** Append one record. Never throws; a no-op once the log failed or was closed. True when the line was written. */
+    append(record) {
+        if (this._failed !== undefined || this.closed)
+            return false;
+        try {
+            if (this.fd === undefined) {
+                mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });
+                this.fd = openSync(this.path, "a", 0o600);
+            }
+            const full = { ts: new Date().toISOString(), pid: process.pid, ...record };
+            writeSync(this.fd, `${JSON.stringify(full)}\n`);
+            return true;
+        }
+        catch (error) {
+            this.fail(errorMessage(error));
+            return false;
+        }
+    }
+    fail(error) {
+        this._failed = error;
+        this.close();
+        try {
+            this.onFailure?.(error);
+        }
+        catch {
+            // a failure callback must not fail the caller
+        }
+    }
+    /** Close the file descriptor; later appends are dropped. Idempotent; safe inside `process.on("exit")`. */
+    close() {
+        this.closed = true;
+        if (this.fd === undefined)
+            return;
+        const fd = this.fd;
+        this.fd = undefined;
+        try {
+            closeSync(fd);
+        }
+        catch {
+            // ignore
+        }
+    }
+    /** The last `limit` records, read from the last megabyte of the file. Never throws. */
+    tail(limit) {
+        let fd;
+        try {
+            fd = openSync(this.path, "r");
+            const size = fstatSync(fd).size;
+            const start = Math.max(0, size - AUDIT_TAIL_BYTES);
+            const buffer = Buffer.alloc(size - start);
+            let read = 0;
+            while (read < buffer.length) {
+                const n = readSync(fd, buffer, read, buffer.length - read, start + read);
+                if (n === 0)
+                    break;
+                read += n;
+            }
+            const lines = buffer.toString("utf8", 0, read).split("\n");
+            // the window may start mid-line: drop the first line unless the byte before it ends a line
+            if (start > 0) {
+                const before = Buffer.alloc(1);
+                const n = readSync(fd, before, 0, 1, start - 1);
+                if (n !== 1 || before[0] !== 0x0a)
+                    lines.shift();
+            }
+            const records = [];
+            for (const line of lines) {
+                if (line === "")
+                    continue;
+                try {
+                    records.push(JSON.parse(line));
+                }
+                catch {
+                    records.push({ raw: line });
+                }
+            }
+            const truncated = start > 0 || records.length > limit;
+            return { records: records.slice(-limit), truncated };
+        }
+        catch (error) {
+            // no log yet, or a path that can never hold one (the failure is in `failed`)
+            const code = error.code;
+            if (code === "ENOENT" || code === "ENOTDIR")
+                return { records: [], truncated: false };
+            return { records: [{ error: errorMessage(error) }], truncated: false };
+        }
+        finally {
+            if (fd !== undefined) {
+                try {
+                    closeSync(fd);
+                }
+                catch {
+                    // ignore
+                }
+            }
+        }
+    }
+}
+//# sourceMappingURL=audit.js.map

package/dist/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"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","sourcesContent":["// The audit log (abaigrammar section 10).\n//\n// One JSON line per act of control: a mutate capability call, a knob write\n// by any path, a decision's outcome, and the counters of defaulted decisions\n// flushed at attach, close and exit. Written synchronously, one line per\n// act: acts are rare and a partial line on a crash is worse than a syscall.\n// Nothing here throws into the agent: the first failure latches the log off,\n// reports once through `onFailure`, and every later append is a no-op.\n// `tail` reads the log back for the harness.\nimport { closeSync, fstatSync, mkdirSync, openSync, readSync, writeSync } from \"node:fs\";\nimport { dirname } from \"node:path\";\nimport { cutUtf8, type DecisionDecl } from \"./manifest/manifest.ts\";\n\nexport type AuditAct = \"capability\" | \"knob\" | \"decision\" | \"turn\" | \"lifecycle\" | \"counters\" | \"message\";\nexport type AuditOutcome = \"ok\" | \"error\" | \"forbidden\" | \"agent\" | \"default\" | \"stub\" | \"failed\";\n\nexport interface AuditRecord {\n\tts: string;\n\tpid: number;\n\t/** The connection that acted (`k1`, `k2`, ...); absent for counters. */\n\tconn?: string;\n\tact: AuditAct;\n\t/** The capability, cell, decision or counter name. */\n\tname: string;\n\t/** The request id or hook id. */\n\tid?: string;\n\t/** The parameters (capped, see `capValue`). */\n\tparams?: unknown;\n\t/** A knob's landed value, or a decision answer's summary. */\n\tvalue?: unknown;\n\toutcome: AuditOutcome;\n\t/** Why a default or stub answer applied, or what a counter counts. */\n\tcause?: string;\n\t/** What the harness stated for an act whose policy is `confirm`: approved, auto, or denied. */\n\tconsent?: string;\n\t/** The agent's stated reason. */\n\treason?: unknown;\n\terror?: unknown;\n\t/** Milliseconds from dispatch to settle. */\n\tms?: number;\n\t/** Counters only. */\n\tcount?: number;\n}\n\n/**\n * One message sent to or received from a member of the run's network\n * (section 10), as the harness hands it to the stub for the audit log. The\n * stub writes it as `act: message` with the counterpart's name as `name`,\n * the envelope id as `id`, the body capped as `value`.\n */\nexport interface MessageRecord {\n\tdirection: \"sent\" | \"received\";\n\t/** The counterpart's name as the network's authority issued it, else its address. */\n\tpeer: string;\n\taddr: string;\n\tnetwork: string;\n\t/** The envelope id, when the payload carried one. */\n\tid?: string;\n\tthread?: string;\n\tre?: string;\n\t/** `msg` is an aiap message; `raw` a plain payload with no envelope. */\n\tkind: \"msg\" | \"raw\";\n\tbody: string;\n\toutcome: \"ok\" | \"error\";\n\t/** The agent's stated reason, for a send. */\n\treason?: string;\n\terror?: string;\n\t/** Milliseconds a send took. */\n\tms?: number;\n}\n\nfunction optionalString(value: unknown): boolean {\n\treturn value === undefined || typeof value === \"string\";\n}\n\n/** Whether a value is a `MessageRecord`: what the sidecar endpoint checks before it writes what a harness sent. */\nexport function isMessageRecord(value: unknown): value is MessageRecord {\n\tif (typeof value !== \"object\" || value === null) return false;\n\tconst r = value as Record<string, unknown>;\n\treturn (\n\t\t(r.direction === \"sent\" || r.direction === \"received\") &&\n\t\ttypeof r.peer === \"string\" &&\n\t\ttypeof r.addr === \"string\" &&\n\t\ttypeof r.network === \"string\" &&\n\t\t(r.kind === \"msg\" || r.kind === \"raw\") &&\n\t\ttypeof r.body === \"string\" &&\n\t\t(r.outcome === \"ok\" || r.outcome === \"error\") &&\n\t\toptionalString(r.id) &&\n\t\toptionalString(r.thread) &&\n\t\toptionalString(r.re) &&\n\t\toptionalString(r.reason) &&\n\t\toptionalString(r.error) &&\n\t\t(r.ms === undefined || typeof r.ms === \"number\")\n\t);\n}\n\n/** Bytes a string or the JSON of a value may take in a record before it is cut. */\nexport const AUDIT_VALUE_CAP = 512;\n/** Bytes a name, an id or an address from the network may take in a message record. */\nexport const AUDIT_FIELD_CAP = 256;\n\n/** A string the harness or the network supplied, cut to `maxBytes` for a record. */\nexport function capField(value: string, maxBytes: number = AUDIT_FIELD_CAP): string {\n\treturn cutUtf8(value, maxBytes);\n}\n/** Bytes `tail` reads from the end of the file. */\nexport const AUDIT_TAIL_BYTES = 1024 * 1024;\n\nfunction errorMessage(error: unknown): string {\n\treturn error instanceof Error ? error.message : String(error);\n}\n\n/**\n * Cap a value for a record: a value whose JSON exceeds the cap becomes\n * `{truncated: true, bytes, head}` with the JSON's first 512 characters, so\n * the record stays valid JSON. A value that cannot be serialized becomes a\n * marker string.\n */\nexport function capValue(value: unknown): unknown {\n\tif (value === undefined) return undefined;\n\tlet json: string;\n\ttry {\n\t\tjson = JSON.stringify(value) ?? \"null\";\n\t} catch (error) {\n\t\treturn `<unserializable: ${errorMessage(error)}>`;\n\t}\n\tconst bytes = Buffer.byteLength(json, \"utf8\");\n\tif (bytes <= AUDIT_VALUE_CAP) return value;\n\treturn { truncated: true, bytes, head: cutUtf8(json, AUDIT_VALUE_CAP) };\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\n/**\n * What an audit record keeps of a decision answer: never the transcript.\n * An options decision keeps the chosen option; any other answer keeps\n * whether it changed something (a non-empty object).\n */\nexport function summarizeAnswer(decision: DecisionDecl | undefined, answer: unknown): unknown {\n\tif (answer === undefined) return undefined;\n\tif (decision?.options && typeof answer === \"string\") return { option: answer };\n\treturn { changed: Object.keys(isRecord(answer) ? answer : {}).length > 0 };\n}\n\nexport interface AuditTail {\n\trecords: unknown[];\n\t/** More records exist than were returned. */\n\ttruncated: boolean;\n}\n\nexport class AuditLog {\n\treadonly path: string;\n\tprivate readonly onFailure: ((error: string) => void) | undefined;\n\tprivate fd: number | undefined;\n\tprivate _failed: string | undefined;\n\tprivate closed = false;\n\n\tconstructor(path: string, onFailure?: (error: string) => void) {\n\t\tthis.path = path;\n\t\tthis.onFailure = onFailure;\n\t}\n\n\t/** The error that latched the log off, if any. */\n\tget failed(): string | undefined {\n\t\treturn this._failed;\n\t}\n\n\t/** Append one record. Never throws; a no-op once the log failed or was closed. True when the line was written. */\n\tappend(record: Omit<AuditRecord, \"ts\" | \"pid\">): boolean {\n\t\tif (this._failed !== undefined || this.closed) return false;\n\t\ttry {\n\t\t\tif (this.fd === undefined) {\n\t\t\t\tmkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });\n\t\t\t\tthis.fd = openSync(this.path, \"a\", 0o600);\n\t\t\t}\n\t\t\tconst full: AuditRecord = { ts: new Date().toISOString(), pid: process.pid, ...record };\n\t\t\twriteSync(this.fd, `${JSON.stringify(full)}\\n`);\n\t\t\treturn true;\n\t\t} catch (error) {\n\t\t\tthis.fail(errorMessage(error));\n\t\t\treturn false;\n\t\t}\n\t}\n\n\tprivate fail(error: string): void {\n\t\tthis._failed = error;\n\t\tthis.close();\n\t\ttry {\n\t\t\tthis.onFailure?.(error);\n\t\t} catch {\n\t\t\t// a failure callback must not fail the caller\n\t\t}\n\t}\n\n\t/** Close the file descriptor; later appends are dropped. Idempotent; safe inside `process.on(\"exit\")`. */\n\tclose(): void {\n\t\tthis.closed = true;\n\t\tif (this.fd === undefined) return;\n\t\tconst fd = this.fd;\n\t\tthis.fd = undefined;\n\t\ttry {\n\t\t\tcloseSync(fd);\n\t\t} catch {\n\t\t\t// ignore\n\t\t}\n\t}\n\n\t/** The last `limit` records, read from the last megabyte of the file. Never throws. */\n\ttail(limit: number): AuditTail {\n\t\tlet fd: number | undefined;\n\t\ttry {\n\t\t\tfd = openSync(this.path, \"r\");\n\t\t\tconst size = fstatSync(fd).size;\n\t\t\tconst start = Math.max(0, size - AUDIT_TAIL_BYTES);\n\t\t\tconst buffer = Buffer.alloc(size - start);\n\t\t\tlet read = 0;\n\t\t\twhile (read < buffer.length) {\n\t\t\t\tconst n = readSync(fd, buffer, read, buffer.length - read, start + read);\n\t\t\t\tif (n === 0) break;\n\t\t\t\tread += n;\n\t\t\t}\n\t\t\tconst lines = buffer.toString(\"utf8\", 0, read).split(\"\\n\");\n\t\t\t// the window may start mid-line: drop the first line unless the byte before it ends a line\n\t\t\tif (start > 0) {\n\t\t\t\tconst before = Buffer.alloc(1);\n\t\t\t\tconst n = readSync(fd, before, 0, 1, start - 1);\n\t\t\t\tif (n !== 1 || before[0] !== 0x0a) lines.shift();\n\t\t\t}\n\t\t\tconst records: unknown[] = [];\n\t\t\tfor (const line of lines) {\n\t\t\t\tif (line === \"\") continue;\n\t\t\t\ttry {\n\t\t\t\t\trecords.push(JSON.parse(line));\n\t\t\t\t} catch {\n\t\t\t\t\trecords.push({ raw: line });\n\t\t\t\t}\n\t\t\t}\n\t\t\tconst truncated = start > 0 || records.length > limit;\n\t\t\treturn { records: records.slice(-limit), truncated };\n\t\t} catch (error) {\n\t\t\t// no log yet, or a path that can never hold one (the failure is in `failed`)\n\t\t\tconst code = (error as NodeJS.ErrnoException).code;\n\t\t\tif (code === \"ENOENT\" || code === \"ENOTDIR\") return { records: [], truncated: false };\n\t\t\treturn { records: [{ error: errorMessage(error) }], truncated: false };\n\t\t} finally {\n\t\t\tif (fd !== undefined) {\n\t\t\t\ttry {\n\t\t\t\t\tcloseSync(fd);\n\t\t\t\t} catch {\n\t\t\t\t\t// ignore\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n}\n"]}

package/dist/cells/fit.d.ts

@@ -0,0 +1,6 @@
+import { type CellDecl } from "../manifest/manifest.ts";
+/** Fit a value to its cell: strings cut to `max` bytes, lists cut to the items whose JSON fits. */
+export declare function fitValue(value: unknown, decl: CellDecl): unknown;
+/** Whether a value can be written to a knob: the declared type, enum and range. */
+export declare function validateKnobValue(decl: CellDecl, value: unknown): string | undefined;
+//# sourceMappingURL=fit.d.ts.map

package/dist/cells/fit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fit.d.ts","sourceRoot":"","sources":["../../src/cells/fit.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,QAAQ,EAAiE,MAAM,yBAAyB,CAAC;AAOvH,mGAAmG;AACnG,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,GAAG,OAAO,CAsBhE;AAED,mFAAmF;AACnF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAQpF","sourcesContent":["// Fitting cell values to their declared sizes and validating knob writes\n// (abaigrammar section 5.2).\nimport { type CellDecl, cutUtf8, encodedBytes, type FieldSchema, fieldOf, matchesType } from \"../manifest/manifest.ts\";\n\n/** Cut a string to at most `max` bytes without splitting a code point (one encode, one decode). */\nfunction cutString(value: string, max: number): string {\n\treturn cutUtf8(value, max);\n}\n\n/** Fit a value to its cell: strings cut to `max` bytes, lists cut to the items whose JSON fits. */\nexport function fitValue(value: unknown, decl: CellDecl): unknown {\n\tif (decl.type === \"string\" && typeof value === \"string\") {\n\t\treturn cutString(value, decl.max ?? 256);\n\t}\n\tif (decl.type === \"object\" && typeof value === \"object\" && value !== null) {\n\t\tconst max = decl.max ?? 1024;\n\t\tconst bytes = encodedBytes(value);\n\t\tif (bytes > max) return { truncated: true, bytes };\n\t\treturn JSON.parse(JSON.stringify(value));\n\t}\n\tif (decl.type === \"list\" && Array.isArray(value)) {\n\t\tconst max = decl.max ?? 1024;\n\t\tconst items = decl.items === undefined ? undefined : fieldOf(decl.items);\n\t\tconst kept: unknown[] = [];\n\t\tfor (const item of value) {\n\t\t\tconst fitted = items?.type === \"string\" && typeof item === \"string\" ? cutString(item, items.max ?? 256) : item;\n\t\t\tif (encodedBytes([...kept, fitted]) > max) break;\n\t\t\tkept.push(fitted);\n\t\t}\n\t\treturn kept;\n\t}\n\treturn value;\n}\n\n/** Whether a value can be written to a knob: the declared type, enum and range. */\nexport function validateKnobValue(decl: CellDecl, value: unknown): string | undefined {\n\tif (!matchesType(value, decl as unknown as FieldSchema)) {\n\t\treturn decl.type === \"enum\" ? `value must be one of: ${decl.enum?.join(\", \")}` : `value must be a ${decl.type}`;\n\t}\n\tif (decl.range && typeof value === \"number\" && (value < decl.range[0] || value > decl.range[1])) {\n\t\treturn `value must be within ${decl.range[0]} and ${decl.range[1]}`;\n\t}\n\treturn undefined;\n}\n"]}

package/dist/cells/fit.js

@@ -0,0 +1,44 @@
+// Fitting cell values to their declared sizes and validating knob writes
+// (abaigrammar section 5.2).
+import { cutUtf8, encodedBytes, fieldOf, matchesType } from "../manifest/manifest.js";
+/** Cut a string to at most `max` bytes without splitting a code point (one encode, one decode). */
+function cutString(value, max) {
+    return cutUtf8(value, max);
+}
+/** Fit a value to its cell: strings cut to `max` bytes, lists cut to the items whose JSON fits. */
+export function fitValue(value, decl) {
+    if (decl.type === "string" && typeof value === "string") {
+        return cutString(value, decl.max ?? 256);
+    }
+    if (decl.type === "object" && typeof value === "object" && value !== null) {
+        const max = decl.max ?? 1024;
+        const bytes = encodedBytes(value);
+        if (bytes > max)
+            return { truncated: true, bytes };
+        return JSON.parse(JSON.stringify(value));
+    }
+    if (decl.type === "list" && Array.isArray(value)) {
+        const max = decl.max ?? 1024;
+        const items = decl.items === undefined ? undefined : fieldOf(decl.items);
+        const kept = [];
+        for (const item of value) {
+            const fitted = items?.type === "string" && typeof item === "string" ? cutString(item, items.max ?? 256) : item;
+            if (encodedBytes([...kept, fitted]) > max)
+                break;
+            kept.push(fitted);
+        }
+        return kept;
+    }
+    return value;
+}
+/** Whether a value can be written to a knob: the declared type, enum and range. */
+export function validateKnobValue(decl, value) {
+    if (!matchesType(value, decl)) {
+        return decl.type === "enum" ? `value must be one of: ${decl.enum?.join(", ")}` : `value must be a ${decl.type}`;
+    }
+    if (decl.range && typeof value === "number" && (value < decl.range[0] || value > decl.range[1])) {
+        return `value must be within ${decl.range[0]} and ${decl.range[1]}`;
+    }
+    return undefined;
+}
+//# sourceMappingURL=fit.js.map

package/dist/cells/fit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fit.js","sourceRoot":"","sources":["../../src/cells/fit.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,6BAA6B;AAC7B,OAAO,EAAiB,OAAO,EAAE,YAAY,EAAoB,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAEvH,mGAAmG;AACnG,SAAS,SAAS,CAAC,KAAa,EAAE,GAAW,EAAU;IACtD,OAAO,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;AAAA,CAC3B;AAED,mGAAmG;AACnG,MAAM,UAAU,QAAQ,CAAC,KAAc,EAAE,IAAc,EAAW;IACjE,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACzD,OAAO,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC;IAC1C,CAAC;IACD,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAC3E,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC;QAC7B,MAAM,KAAK,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;QAClC,IAAI,KAAK,GAAG,GAAG;YAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;QACnD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;IAC1C,CAAC;IACD,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAClD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC;QAC7B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACzE,MAAM,IAAI,GAAc,EAAE,CAAC;QAC3B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YAC1B,MAAM,MAAM,GAAG,KAAK,EAAE,IAAI,KAAK,QAAQ,IAAI,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;YAC/G,IAAI,YAAY,CAAC,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC,GAAG,GAAG;gBAAE,MAAM;YACjD,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACnB,CAAC;QACD,OAAO,IAAI,CAAC;IACb,CAAC;IACD,OAAO,KAAK,CAAC;AAAA,CACb;AAED,mFAAmF;AACnF,MAAM,UAAU,iBAAiB,CAAC,IAAc,EAAE,KAAc,EAAsB;IACrF,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,IAA8B,CAAC,EAAE,CAAC;QACzD,OAAO,IAAI,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,yBAAyB,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,mBAAmB,IAAI,CAAC,IAAI,EAAE,CAAC;IACjH,CAAC;IACD,IAAI,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACjG,OAAO,wBAAwB,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IACrE,CAAC;IACD,OAAO,SAAS,CAAC;AAAA,CACjB","sourcesContent":["// Fitting cell values to their declared sizes and validating knob writes\n// (abaigrammar section 5.2).\nimport { type CellDecl, cutUtf8, encodedBytes, type FieldSchema, fieldOf, matchesType } from \"../manifest/manifest.ts\";\n\n/** Cut a string to at most `max` bytes without splitting a code point (one encode, one decode). */\nfunction cutString(value: string, max: number): string {\n\treturn cutUtf8(value, max);\n}\n\n/** Fit a value to its cell: strings cut to `max` bytes, lists cut to the items whose JSON fits. */\nexport function fitValue(value: unknown, decl: CellDecl): unknown {\n\tif (decl.type === \"string\" && typeof value === \"string\") {\n\t\treturn cutString(value, decl.max ?? 256);\n\t}\n\tif (decl.type === \"object\" && typeof value === \"object\" && value !== null) {\n\t\tconst max = decl.max ?? 1024;\n\t\tconst bytes = encodedBytes(value);\n\t\tif (bytes > max) return { truncated: true, bytes };\n\t\treturn JSON.parse(JSON.stringify(value));\n\t}\n\tif (decl.type === \"list\" && Array.isArray(value)) {\n\t\tconst max = decl.max ?? 1024;\n\t\tconst items = decl.items === undefined ? undefined : fieldOf(decl.items);\n\t\tconst kept: unknown[] = [];\n\t\tfor (const item of value) {\n\t\t\tconst fitted = items?.type === \"string\" && typeof item === \"string\" ? cutString(item, items.max ?? 256) : item;\n\t\t\tif (encodedBytes([...kept, fitted]) > max) break;\n\t\t\tkept.push(fitted);\n\t\t}\n\t\treturn kept;\n\t}\n\treturn value;\n}\n\n/** Whether a value can be written to a knob: the declared type, enum and range. */\nexport function validateKnobValue(decl: CellDecl, value: unknown): string | undefined {\n\tif (!matchesType(value, decl as unknown as FieldSchema)) {\n\t\treturn decl.type === \"enum\" ? `value must be one of: ${decl.enum?.join(\", \")}` : `value must be a ${decl.type}`;\n\t}\n\tif (decl.range && typeof value === \"number\" && (value < decl.range[0] || value > decl.range[1])) {\n\t\treturn `value must be within ${decl.range[0]} and ${decl.range[1]}`;\n\t}\n\treturn undefined;\n}\n"]}

package/dist/content.d.ts

@@ -0,0 +1,17 @@
+import type { Manifest } from "./manifest/manifest.ts";
+export declare const MANIFEST_FILE = "abaigram.yaml";
+export interface ContentSlots {
+    readonly root: string;
+    /** The identity text; throws when the slot is missing or empty. */
+    identity(): string;
+    install(): string | undefined;
+    use(): string | undefined;
+    /** The content for a named turn or decision, from the `turns` directory. */
+    turn(name: string): string | undefined;
+}
+/** Whether the manifest file at `path` names this program. */
+export declare function isManifestOf(path: string, name: string): boolean;
+/** The nearest ancestor of `dir` (itself included) holding this program's abaigram.yaml. */
+export declare function findRoot(name: string, dir?: string): string | undefined;
+export declare function createContent(manifest: Manifest, resolveRoot: () => string): ContentSlots;
+//# sourceMappingURL=content.d.ts.map

package/dist/content.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content.d.ts","sourceRoot":"","sources":["../src/content.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAGvD,eAAO,MAAM,aAAa,kBAAkB,CAAC;AAE7C,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,QAAQ,IAAI,MAAM,CAAC;IACnB,OAAO,IAAI,MAAM,GAAG,SAAS,CAAC;IAC9B,GAAG,IAAI,MAAM,GAAG,SAAS,CAAC;IAC1B,4EAA4E;IAC5E,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CACvC;AAED,8DAA8D;AAC9D,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAOhE;AAED,4FAA4F;AAC5F,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,GAAE,MAAsB,GAAG,MAAM,GAAG,SAAS,CAQtF;AAOD,wBAAgB,aAAa,CAAC,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,MAAM,GAAG,YAAY,CA8BzF","sourcesContent":["// The content slots (abaigrammar section 8): the abaigrammer's prompts, read\n// from files under the program's root. The root is where abaigram.yaml lives:\n// an explicit option, else the nearest ancestor of the cwd holding this\n// program's manifest, else the cwd. Reads are lazy, so a program that never\n// attaches never touches the files.\nimport { existsSync, readFileSync } from \"node:fs\";\nimport { dirname, join, resolve } from \"node:path\";\nimport type { Manifest } from \"./manifest/manifest.ts\";\nimport { parseManifestYaml } from \"./manifest/render.ts\";\n\nexport const MANIFEST_FILE = \"abaigram.yaml\";\n\nexport interface ContentSlots {\n\treadonly root: string;\n\t/** The identity text; throws when the slot is missing or empty. */\n\tidentity(): string;\n\tinstall(): string | undefined;\n\tuse(): string | undefined;\n\t/** The content for a named turn or decision, from the `turns` directory. */\n\tturn(name: string): string | undefined;\n}\n\n/** Whether the manifest file at `path` names this program. */\nexport function isManifestOf(path: string, name: string): boolean {\n\ttry {\n\t\tconst parsed = parseManifestYaml(readFileSync(path, \"utf8\"));\n\t\treturn typeof parsed === \"object\" && parsed !== null && (parsed as { name?: unknown }).name === name;\n\t} catch {\n\t\treturn false;\n\t}\n}\n\n/** The nearest ancestor of `dir` (itself included) holding this program's abaigram.yaml. */\nexport function findRoot(name: string, dir: string = process.cwd()): string | undefined {\n\tlet current = resolve(dir);\n\twhile (true) {\n\t\tif (isManifestOf(join(current, MANIFEST_FILE), name)) return current;\n\t\tconst parent = dirname(current);\n\t\tif (parent === current) return undefined;\n\t\tcurrent = parent;\n\t}\n}\n\nfunction readOptional(path: string): string | undefined {\n\tif (!existsSync(path)) return undefined;\n\treturn readFileSync(path, \"utf8\");\n}\n\nexport function createContent(manifest: Manifest, resolveRoot: () => string): ContentSlots {\n\tlet found: string | undefined;\n\tconst root = (): string => {\n\t\tif (found === undefined) found = resolveRoot();\n\t\treturn found;\n\t};\n\tconst slot = (relative: string): string => resolve(root(), relative);\n\treturn {\n\t\tget root() {\n\t\t\treturn root();\n\t\t},\n\t\tidentity() {\n\t\t\tconst path = slot(manifest.content.identity);\n\t\t\tconst text = readOptional(path);\n\t\t\tif (text === undefined) throw new Error(`the identity content is missing: ${path}`);\n\t\t\tif (text.trim() === \"\") throw new Error(`the identity content is empty: ${path}`);\n\t\t\treturn text;\n\t\t},\n\t\t// the undeclared slots default to the abai/ directory (section 8); a missing file is simply no content\n\t\tinstall() {\n\t\t\treturn readOptional(slot(manifest.content.install ?? \"abai/install.md\"));\n\t\t},\n\t\tuse() {\n\t\t\treturn readOptional(slot(manifest.content.use ?? \"abai/use.md\"));\n\t\t},\n\t\tturn(name) {\n\t\t\tconst dir = manifest.content.turns ?? \"abai/turns\";\n\t\t\treturn readOptional(slot(join(dir, `${name}.md`)));\n\t\t},\n\t};\n}\n"]}

package/dist/content.js

@@ -0,0 +1,71 @@
+// The content slots (abaigrammar section 8): the abaigrammer's prompts, read
+// from files under the program's root. The root is where abaigram.yaml lives:
+// an explicit option, else the nearest ancestor of the cwd holding this
+// program's manifest, else the cwd. Reads are lazy, so a program that never
+// attaches never touches the files.
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { parseManifestYaml } from "./manifest/render.js";
+export const MANIFEST_FILE = "abaigram.yaml";
+/** Whether the manifest file at `path` names this program. */
+export function isManifestOf(path, name) {
+    try {
+        const parsed = parseManifestYaml(readFileSync(path, "utf8"));
+        return typeof parsed === "object" && parsed !== null && parsed.name === name;
+    }
+    catch {
+        return false;
+    }
+}
+/** The nearest ancestor of `dir` (itself included) holding this program's abaigram.yaml. */
+export function findRoot(name, dir = process.cwd()) {
+    let current = resolve(dir);
+    while (true) {
+        if (isManifestOf(join(current, MANIFEST_FILE), name))
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+}
+function readOptional(path) {
+    if (!existsSync(path))
+        return undefined;
+    return readFileSync(path, "utf8");
+}
+export function createContent(manifest, resolveRoot) {
+    let found;
+    const root = () => {
+        if (found === undefined)
+            found = resolveRoot();
+        return found;
+    };
+    const slot = (relative) => resolve(root(), relative);
+    return {
+        get root() {
+            return root();
+        },
+        identity() {
+            const path = slot(manifest.content.identity);
+            const text = readOptional(path);
+            if (text === undefined)
+                throw new Error(`the identity content is missing: ${path}`);
+            if (text.trim() === "")
+                throw new Error(`the identity content is empty: ${path}`);
+            return text;
+        },
+        // the undeclared slots default to the abai/ directory (section 8); a missing file is simply no content
+        install() {
+            return readOptional(slot(manifest.content.install ?? "abai/install.md"));
+        },
+        use() {
+            return readOptional(slot(manifest.content.use ?? "abai/use.md"));
+        },
+        turn(name) {
+            const dir = manifest.content.turns ?? "abai/turns";
+            return readOptional(slot(join(dir, `${name}.md`)));
+        },
+    };
+}
+//# sourceMappingURL=content.js.map

package/dist/content.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content.js","sourceRoot":"","sources":["../src/content.ts"],"names":[],"mappings":"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","sourcesContent":["// The content slots (abaigrammar section 8): the abaigrammer's prompts, read\n// from files under the program's root. The root is where abaigram.yaml lives:\n// an explicit option, else the nearest ancestor of the cwd holding this\n// program's manifest, else the cwd. Reads are lazy, so a program that never\n// attaches never touches the files.\nimport { existsSync, readFileSync } from \"node:fs\";\nimport { dirname, join, resolve } from \"node:path\";\nimport type { Manifest } from \"./manifest/manifest.ts\";\nimport { parseManifestYaml } from \"./manifest/render.ts\";\n\nexport const MANIFEST_FILE = \"abaigram.yaml\";\n\nexport interface ContentSlots {\n\treadonly root: string;\n\t/** The identity text; throws when the slot is missing or empty. */\n\tidentity(): string;\n\tinstall(): string | undefined;\n\tuse(): string | undefined;\n\t/** The content for a named turn or decision, from the `turns` directory. */\n\tturn(name: string): string | undefined;\n}\n\n/** Whether the manifest file at `path` names this program. */\nexport function isManifestOf(path: string, name: string): boolean {\n\ttry {\n\t\tconst parsed = parseManifestYaml(readFileSync(path, \"utf8\"));\n\t\treturn typeof parsed === \"object\" && parsed !== null && (parsed as { name?: unknown }).name === name;\n\t} catch {\n\t\treturn false;\n\t}\n}\n\n/** The nearest ancestor of `dir` (itself included) holding this program's abaigram.yaml. */\nexport function findRoot(name: string, dir: string = process.cwd()): string | undefined {\n\tlet current = resolve(dir);\n\twhile (true) {\n\t\tif (isManifestOf(join(current, MANIFEST_FILE), name)) return current;\n\t\tconst parent = dirname(current);\n\t\tif (parent === current) return undefined;\n\t\tcurrent = parent;\n\t}\n}\n\nfunction readOptional(path: string): string | undefined {\n\tif (!existsSync(path)) return undefined;\n\treturn readFileSync(path, \"utf8\");\n}\n\nexport function createContent(manifest: Manifest, resolveRoot: () => string): ContentSlots {\n\tlet found: string | undefined;\n\tconst root = (): string => {\n\t\tif (found === undefined) found = resolveRoot();\n\t\treturn found;\n\t};\n\tconst slot = (relative: string): string => resolve(root(), relative);\n\treturn {\n\t\tget root() {\n\t\t\treturn root();\n\t\t},\n\t\tidentity() {\n\t\t\tconst path = slot(manifest.content.identity);\n\t\t\tconst text = readOptional(path);\n\t\t\tif (text === undefined) throw new Error(`the identity content is missing: ${path}`);\n\t\t\tif (text.trim() === \"\") throw new Error(`the identity content is empty: ${path}`);\n\t\t\treturn text;\n\t\t},\n\t\t// the undeclared slots default to the abai/ directory (section 8); a missing file is simply no content\n\t\tinstall() {\n\t\t\treturn readOptional(slot(manifest.content.install ?? \"abai/install.md\"));\n\t\t},\n\t\tuse() {\n\t\t\treturn readOptional(slot(manifest.content.use ?? \"abai/use.md\"));\n\t\t},\n\t\tturn(name) {\n\t\t\tconst dir = manifest.content.turns ?? \"abai/turns\";\n\t\t\treturn readOptional(slot(join(dir, `${name}.md`)));\n\t\t},\n\t};\n}\n"]}