@abaigram/abai-stub 0.0.0-stage → 0.2.0

package/dist/harness-binding.js

@@ -0,0 +1,618 @@
+// The direct face (abaigrammar section 4.1): what the stub hands a harness
+// that attaches in-process. One object serves both sides. To the program it
+// is the AttachedHarness that decisions, turns, touchpoints and emits reach;
+// to the harness it is the channels: cells and events to read, knobs to
+// write, capabilities to call, decisions and turns to answer, the audit log
+// to tail, the counters to take. Every act of control is audited here, on
+// the program side, as section 10 says, with the consent the harness states
+// for an act whose policy is `confirm`.
+import { resolve } from "node:path";
+import { AUDIT_VALUE_CAP, AuditLog, capField, capValue, summarizeAnswer, } from "./audit.js";
+import { validateKnobValue } from "./cells/fit.js";
+import { expandHome } from "./env.js";
+import { durationMs, fieldOf, matchesType, } from "./manifest/manifest.js";
+/** A capability call that did not return a result. */
+export class CallError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "CallError";
+        this.code = code;
+    }
+}
+/**
+ * A touchpoint has no timeout of its own, so nothing of the program's holds
+ * its event loop open while a harness in another process holds the
+ * touchpoint; this ref'd timer does, and never fires in practice (the
+ * longest delay a timer takes). Cleared when the touchpoint ends.
+ */
+const TOUCHPOINT_KEEPALIVE_MS = 2 ** 31 - 1;
+/**
+ * Check a value against a schema: an object with no undeclared field, whose
+ * every present field is of its declared type. A declared field may be
+ * absent (decided 2026-10-14: the schema language has no required marker,
+ * and a manifest's own defaults omit fields); `nullable` governs an
+ * explicit null. Nested objects and lists are checked by `matchesType`.
+ */
+export function schemaProblem(schema, value, what) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return `${what} must be an object`;
+    const record = value;
+    for (const [key, field] of Object.entries(schema)) {
+        const item = record[key];
+        if (item === undefined)
+            continue;
+        if (!matchesType(item, field))
+            return `${what}.${key} must be a ${fieldOf(field).type}`;
+    }
+    for (const key of Object.keys(record)) {
+        if (!(key in schema))
+            return `${what} has an undeclared field ${key}`;
+    }
+    return undefined;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function consentGranted(consent) {
+    return consent === "approved" || consent === "auto";
+}
+export class DirectBinding {
+    manifest;
+    name;
+    connection;
+    mode;
+    app;
+    audit;
+    listeners = {
+        event: new Set(),
+        decision: new Set(),
+        decision_timeout: new Set(),
+        turn: new Set(),
+        touchpoint: new Set(),
+        detach: new Set(),
+    };
+    decisions = new Map();
+    turns = new Map();
+    touchpoints = new Map();
+    capabilityIndex = new Map();
+    /** Touchpoints in progress: while one is open the program sits at a safepoint, so queued work runs at once (section 5.3). */
+    openTouchpoints = 0;
+    nextId = 1;
+    _attached = true;
+    constructor(app, options = {}) {
+        this.app = app;
+        this.manifest = app.manifest;
+        this.name = app.manifest.name;
+        this.connection = options.connection ?? "direct";
+        this.mode = app.mode;
+        for (const capability of this.manifest.capabilities)
+            this.capabilityIndex.set(capability.name, capability);
+        const auditPath = options.auditPath ?? resolve(app.content.root, expandHome(this.manifest.audit.path));
+        this.audit = new AuditLog(auditPath, (error) => {
+            app.emitLibrary("abai.audit.failed", { error });
+        });
+    }
+    get attached() {
+        return this._attached;
+    }
+    /** @internal Called by the program once the binding is set: the counters go to the log first (section 10). */
+    flushCounters() {
+        const counters = this.app.takeCounters();
+        for (const [name, count] of Object.entries(counters)) {
+            if (count === 0)
+                continue;
+            const cause = name === "abai.mode_fallback" ? "mode_fallback" : "no_harness";
+            this.audit.append({ act: "counters", name, outcome: "default", cause, count });
+        }
+    }
+    /** Queue work for the program's next safepoint, or run it now when a touchpoint holds the program at one. */
+    atSafepoint(work) {
+        this.app.enqueue(work);
+        if (this.openTouchpoints > 0)
+            this.app.drain();
+    }
+    /**
+     * @internal The program is at a safepoint and will stay there (its entry
+     * serving an MCP client): safepoint-dispatched work runs at once rather
+     * than waiting for a safepoint the program would never reach. Paired
+     * with `leaveSafepoint`.
+     */
+    enterSafepoint() {
+        this.openTouchpoints += 1;
+        this.app.drain();
+    }
+    /** @internal */
+    leaveSafepoint() {
+        if (this.openTouchpoints > 0)
+            this.openTouchpoints -= 1;
+    }
+    // -----------------------------------------------------------------------
+    // Harness side
+    // -----------------------------------------------------------------------
+    content() {
+        const slots = this.app.content;
+        return {
+            identity: slots.identity(),
+            install: slots.install(),
+            use: slots.use(),
+            turn: (name) => slots.turn(name),
+        };
+    }
+    readCells(names) {
+        const all = this.app.readCells();
+        const cells = {};
+        for (const name of names ?? Object.keys(all)) {
+            if (!(name in all))
+                throw new Error(`unknown cell: ${name}`);
+            cells[name] = { value: all[name], version: this.app.version(name) };
+        }
+        return { seq: this.app.region.lastSeq, cells };
+    }
+    readEvents(after) {
+        const read = this.app.region.readEvents(after);
+        return { events: read.slots.map((slot) => this.live(slot)), dropped: read.dropped, next: read.next };
+    }
+    live(slot) {
+        return {
+            seq: slot.seq,
+            name: this.app.eventName(slot.event),
+            payload: slot.payload,
+            truncated: slot.truncated,
+            ts: slot.ts,
+        };
+    }
+    async writeKnob(name, value, reason, consent, conn) {
+        const decl = this.manifest.cells.find((cell) => cell.name === name);
+        const started = this.app.now();
+        const record = (outcome, landed, error, cause) => {
+            this.audit.append({
+                conn: conn ?? this.connection,
+                act: "knob",
+                name,
+                value: capValue(landed),
+                outcome,
+                ...(cause === undefined ? {} : { cause }),
+                ...(consent === undefined ? {} : { consent }),
+                reason,
+                ...(error === undefined ? {} : { error }),
+                ms: this.app.now() - started,
+            });
+            return outcome === "ok"
+                ? { value: landed, outcome: "done" }
+                : { value: landed, outcome: "failed", error, ...(cause === undefined ? {} : { code: cause }) };
+        };
+        if (!decl)
+            return record("error", undefined, `unknown cell: ${name}`, "unknown");
+        if (decl.access !== "readwrite")
+            return record("error", undefined, `${name} is read-only`, "invalid");
+        if (decl.policy === "confirm" && !consentGranted(consent)) {
+            return record("error", undefined, `${name} needs consent (its policy is confirm)`, "denied");
+        }
+        const problem = validateKnobValue(decl, value);
+        if (problem !== undefined)
+            return record("error", undefined, problem, "invalid");
+        const sized = decl.type === "string" || decl.type === "object" || decl.type === "list";
+        if (!sized) {
+            this.app.knob(name).set(value);
+            return record("ok", this.app.cell(name).get());
+        }
+        // a sized knob is delivered at the program's next safepoint, to its handler, within its delivery timeout (section 5.2)
+        const handler = this.app.knobHandler(name);
+        if (!handler) {
+            return record("failed", undefined, `no handler registered for ${name}: nothing can receive it`, "error");
+        }
+        const timeoutMs = durationMs(decl.timeout ?? "30s");
+        return new Promise((done) => {
+            let settled = false;
+            const work = () => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                this.app.cell(name).set(value);
+                const landed = this.app.cell(name).get();
+                try {
+                    handler(landed);
+                    done(record("ok", landed));
+                }
+                catch (error) {
+                    done(record("error", landed, errorMessage(error), "error"));
+                }
+            };
+            const timer = setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                this.app.dequeue(work);
+                done(record("failed", undefined, `not delivered within ${decl.timeout ?? "30s"}: the program reached no safepoint`, "timeout"));
+            }, timeoutMs);
+            timer.unref();
+            this.atSafepoint(work);
+        });
+    }
+    async call(name, params, reason, consent, conn) {
+        const decl = this.capabilityIndex.get(name);
+        const started = this.app.now();
+        const record = (outcome, extra = {}) => {
+            this.audit.append({
+                conn: conn ?? this.connection,
+                act: "capability",
+                name,
+                params: capValue(params),
+                outcome,
+                ...(consent === undefined ? {} : { consent }),
+                reason,
+                ...extra,
+                ms: this.app.now() - started,
+            });
+        };
+        const fail = (code, message) => {
+            record(code === "forbidden" ? "forbidden" : "error", { error: message, cause: code });
+            return new CallError(code, message);
+        };
+        if (!decl)
+            throw fail("unknown", `${this.name} declares no capability ${name}`);
+        if (decl.policy === "forbid")
+            throw fail("forbidden", `the program's policy forbids ${name}`);
+        if (decl.policy === "confirm" && !consentGranted(consent))
+            throw fail("denied", `${name} needs consent (its policy is confirm)`);
+        const problem = schemaProblem(decl.params, params ?? {}, "params");
+        if (problem !== undefined)
+            throw fail("invalid", problem);
+        const timeoutMs = durationMs(decl.timeout ?? "30s");
+        const result = await new Promise((done, reject) => {
+            let settled = false;
+            const settle = (fn) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                fn();
+            };
+            // the handler is resolved at dispatch, so one registered after startup still serves
+            const run = () => {
+                if (settled)
+                    return;
+                const handler = this.app.capabilityHandler(name);
+                if (!handler) {
+                    settle(() => reject(new CallError("error", `${name} has no handler registered`)));
+                    return;
+                }
+                let outcome;
+                try {
+                    outcome = handler(params ?? {}); // synchronous part runs inside the safepoint, on the program's thread
+                }
+                catch (error) {
+                    settle(() => reject(new CallError("error", errorMessage(error))));
+                    return;
+                }
+                Promise.resolve(outcome).then((value) => settle(() => done(value)), (error) => settle(() => reject(new CallError("error", errorMessage(error)))));
+            };
+            const timer = setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                this.app.dequeue(run);
+                reject(new CallError("timeout", `${name} did not answer within ${decl.timeout ?? "30s"}`));
+            }, timeoutMs);
+            timer.unref();
+            if (decl.dispatch === "immediate")
+                run();
+            else
+                this.atSafepoint(run);
+        }).catch((error) => {
+            record("error", { error: error.message, cause: error.code });
+            throw error;
+        });
+        record("ok");
+        return result;
+    }
+    recordMessage(record, conn) {
+        const cut = (value, cap) => value === undefined ? undefined : capField(value, cap);
+        const thread = cut(record.thread);
+        const re = cut(record.re);
+        const reason = cut(record.reason, AUDIT_VALUE_CAP);
+        const error = cut(record.error, AUDIT_VALUE_CAP);
+        const id = cut(record.id);
+        return this.audit.append({
+            conn: conn ?? this.connection,
+            act: "message",
+            name: capField(record.peer),
+            ...(id === undefined ? {} : { id }),
+            params: {
+                direction: record.direction,
+                network: capField(record.network),
+                addr: capField(record.addr),
+                kind: record.kind,
+                ...(thread === undefined ? {} : { thread }),
+                ...(re === undefined ? {} : { re }),
+            },
+            value: capValue(record.body),
+            outcome: record.outcome,
+            ...(reason === undefined ? {} : { reason }),
+            ...(error === undefined ? {} : { error }),
+            ...(typeof record.ms === "number" && Number.isFinite(record.ms) ? { ms: record.ms } : {}),
+        });
+    }
+    auditTail(limit) {
+        return this.audit.tail(limit);
+    }
+    auditInfo() {
+        return { path: this.audit.path, failed: this.audit.failed ?? null };
+    }
+    takeCounters() {
+        return this.app.takeCounters();
+    }
+    on(type, listener) {
+        const set = this.listeners[type];
+        set.add(listener);
+        return () => {
+            set.delete(listener);
+        };
+    }
+    notify(type, ...args) {
+        for (const listener of this.listeners[type]) {
+            try {
+                listener(...args);
+            }
+            catch {
+                // a harness listener's failure never reaches the program
+            }
+        }
+    }
+    answerDecision(id, answer, reason, consent, conn) {
+        const pending = this.decisions.get(id);
+        if (!pending)
+            throw new Error(`no pending decision ${id}`);
+        if (reason.trim() === "")
+            throw new Error("a decision needs a reason");
+        if (conn !== undefined)
+            pending.conn = conn;
+        const { decision } = pending.request;
+        if (answer !== null) {
+            const problem = decision.options
+                ? decision.options.includes(answer)
+                    ? undefined
+                    : `answer must be one of: ${decision.options.join(", ")}`
+                : schemaProblem(decision.answer ?? {}, answer, "answer");
+            if (problem !== undefined) {
+                this.settleDecision(id, { source: "default", cause: "invalid", reason, answer });
+                throw new Error(problem);
+            }
+            if (decision.policy === "confirm" && !consentGranted(consent)) {
+                this.settleDecision(id, { source: "default", cause: "denied", reason, consent });
+                return;
+            }
+        }
+        this.settleDecision(id, answer === null
+            ? { source: "default", cause: "answered", reason }
+            : { source: "agent", reason, answer, consent });
+    }
+    defaultDecision(id, cause, conn) {
+        const pending = this.decisions.get(id);
+        if (!pending)
+            return;
+        if (conn !== undefined)
+            pending.conn = conn;
+        this.settleDecision(id, { source: "default", cause });
+    }
+    assignDecision(id, conn) {
+        const pending = this.decisions.get(id);
+        if (pending)
+            pending.conn = conn;
+    }
+    pendingDecisions() {
+        return [...this.decisions.values()].map((p) => p.request);
+    }
+    settleDecision(id, outcome) {
+        const pending = this.decisions.get(id);
+        if (!pending)
+            return;
+        this.decisions.delete(id);
+        if (pending.timer)
+            clearTimeout(pending.timer);
+        this.openTouchpoints -= 1;
+        const { decision } = pending.request;
+        this.audit.append({
+            conn: pending.conn ?? this.connection,
+            act: "decision",
+            name: decision.name,
+            id,
+            value: summarizeAnswer(decision, outcome.source === "agent" ? outcome.answer : decision.default),
+            outcome: outcome.source,
+            ...(outcome.cause === undefined ? {} : { cause: outcome.cause }),
+            ...(outcome.consent === undefined ? {} : { consent: outcome.consent }),
+            ...(outcome.reason === undefined ? {} : { reason: outcome.reason }),
+            ms: this.app.now() - pending.startedAt,
+        });
+        if (outcome.source === "agent")
+            pending.resolve(outcome.answer);
+        else
+            pending.reject(new Error(outcome.cause ?? "default"));
+        if (outcome.cause === "timeout")
+            this.notify("decision_timeout", id, decision.name);
+    }
+    endTurn(id, conn, cause) {
+        const pending = this.turns.get(id);
+        if (!pending)
+            return;
+        if (conn !== undefined)
+            pending.conn = conn;
+        // a turn the agent did nothing with (held back by its budget) is a default, with the cause it names
+        if (cause === undefined)
+            this.settleTurn(id, "ok");
+        else
+            this.settleTurn(id, "default", cause);
+    }
+    /** @internal Queue work for the program's next safepoint, running it now when one is held open. */
+    atNextSafepoint(work) {
+        this.atSafepoint(work);
+    }
+    lifecycle(op, reason, consent, conn) {
+        const declared = this.manifest.lifecycle;
+        const started = this.app.now();
+        const record = (outcome, extra = {}) => {
+            this.audit.append({
+                conn: conn ?? this.connection,
+                act: "lifecycle",
+                name: op,
+                outcome,
+                ...(consent === undefined ? {} : { consent }),
+                reason,
+                ...extra,
+                ms: this.app.now() - started,
+            });
+        };
+        const refuse = (code, error) => {
+            record(code === "forbidden" ? "forbidden" : "error", { cause: code, error });
+            return { ok: false, code, error };
+        };
+        if (op === "status")
+            return { ok: true, data: this.app.lifecycleStatus() };
+        if (op !== "pause" && op !== "resume" && op !== "stop" && op !== "restart" && op !== "start") {
+            return { ok: false, code: "unknown", error: `unknown lifecycle operation: ${op}` };
+        }
+        // section 10: pause and resume are auto, stop and restart confirm, unless the manifest says otherwise
+        const policy = declared?.policy?.[op] ??
+            (op === "stop" || op === "restart" ? "confirm" : "auto");
+        if (policy === "forbid")
+            return refuse("forbidden", `the program's policy forbids lifecycle ${op}`);
+        if (policy === "confirm" && !consentGranted(consent)) {
+            return refuse("denied", `lifecycle ${op} needs consent (its policy is confirm)`);
+        }
+        switch (op) {
+            case "pause":
+                if (declared?.pause !== "cooperative") {
+                    return refuse("invalid", declared?.pause === "os"
+                        ? "this program declares os pause, which its launcher performs"
+                        : "this program declares no cooperative pause");
+                }
+                this.app.requestPause();
+                record("ok");
+                return { ok: true };
+            case "resume":
+                this.app.resumeFromPause();
+                record("ok");
+                return { ok: true };
+            case "stop": {
+                if (!this.app.stopHandler)
+                    return refuse("invalid", "this program declares no stop handler");
+                // a stop supersedes a pause: a program held at a touchpoint goes on to the safepoint where the handler runs
+                this.app.resumeFromPause();
+                // at the next safepoint, on the thread that reaches it (5.5); the program is expected to exit
+                const handler = this.app.stopHandler;
+                this.atNextSafepoint(() => {
+                    // on the thread that reached the safepoint; a failing handler is the program's own matter, and the
+                    // launcher's window runs either way
+                    try {
+                        Promise.resolve(handler()).catch(() => { });
+                    }
+                    catch {
+                        // same
+                    }
+                });
+                record("ok");
+                return { ok: true, data: { op, requested: true } };
+            }
+            default:
+                return refuse("invalid", `lifecycle ${op} is the launcher's, not the program's`);
+        }
+    }
+    settleTurn(id, outcome, cause) {
+        const pending = this.turns.get(id);
+        if (!pending)
+            return;
+        this.turns.delete(id);
+        if (pending.timer)
+            clearTimeout(pending.timer);
+        this.openTouchpoints -= 1;
+        this.audit.append({
+            conn: pending.conn ?? this.connection,
+            act: "turn",
+            name: pending.request.name,
+            id,
+            outcome,
+            ...(cause === undefined ? {} : { cause }),
+            ms: this.app.now() - pending.startedAt,
+        });
+        pending.resolve();
+    }
+    endTouchpoint(id) {
+        const pending = this.touchpoints.get(id);
+        if (!pending)
+            return;
+        this.touchpoints.delete(id);
+        if (pending.timer)
+            clearInterval(pending.timer);
+        this.openTouchpoints -= 1;
+        pending.resolve();
+    }
+    detach(reason) {
+        if (!this._attached)
+            return;
+        this._attached = false;
+        for (const id of [...this.decisions.keys()])
+            this.settleDecision(id, { source: "default", cause: "detached", reason });
+        for (const id of [...this.turns.keys()])
+            this.settleTurn(id, "default", "detached");
+        for (const id of [...this.touchpoints.keys()])
+            this.endTouchpoint(id);
+        this.notify("detach", reason);
+        this.app.clearHarness(reason);
+        this.audit.close();
+    }
+    // -----------------------------------------------------------------------
+    // Program side (AttachedHarness)
+    // -----------------------------------------------------------------------
+    decide(decision, context, deadline) {
+        if (decision.policy === "forbid") {
+            this.audit.append({
+                conn: this.connection,
+                act: "decision",
+                name: decision.name,
+                outcome: "default",
+                cause: "forbidden",
+            });
+            return Promise.reject(new Error("forbidden"));
+        }
+        const id = `d${this.nextId++}`;
+        const request = { id, name: decision.name, decision, context, deadline };
+        return new Promise((resolve, reject) => {
+            // this timer bounds the program's own wait: it keeps the process alive until the answer or the default
+            const timer = setTimeout(() => this.settleDecision(id, { source: "default", cause: "timeout" }), Math.max(0, deadline - this.app.now()));
+            this.decisions.set(id, { request, resolve, reject, timer, startedAt: this.app.now() });
+            this.openTouchpoints += 1;
+            this.notify("decision", request);
+        });
+    }
+    turn(turn, deadline) {
+        const id = `t${this.nextId++}`;
+        const request = { id, name: turn.name, turn, deadline, content: this.app.content.turn(turn.name) };
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => this.settleTurn(id, "default", "timeout"), Math.max(0, deadline - this.app.now()));
+            this.turns.set(id, { request, resolve, reject, timer, startedAt: this.app.now() });
+            this.openTouchpoints += 1;
+            this.notify("turn", request);
+        });
+    }
+    /** @internal A program-initiated `install` or `session`; resolves when the harness ends it or detaches. */
+    touchpoint(kind) {
+        const id = `p${this.nextId++}`;
+        const content = kind === "install" ? this.app.content.install() : this.app.content.use();
+        const request = { id, kind, content };
+        return new Promise((resolve, reject) => {
+            const timer = setInterval(() => { }, TOUCHPOINT_KEEPALIVE_MS);
+            this.touchpoints.set(id, { request, resolve, reject, timer, startedAt: this.app.now() });
+            this.openTouchpoints += 1;
+            this.notify("touchpoint", request);
+        });
+    }
+    emitted(seq) {
+        const read = this.app.region.readEvents(seq - 1);
+        const slot = read.slots.find((s) => s.seq === seq);
+        if (slot)
+            this.notify("event", this.live(slot));
+    }
+}
+//# sourceMappingURL=harness-binding.js.map