@songsid/agend 2.3.5-alpha.3 → 2.3.5-alpha.5

package/dist/hub/member/exposures.js

@@ -0,0 +1,282 @@
+import { randomUUID } from "node:crypto";
+import { canonicalArguments } from "../identity.js";
+import { HubProtocolError } from "../validation.js";
+import { executionPolicyDigest } from "../execution/views.js";
+import { HUB_AGENT_MODE, agentPolicyDigest } from "./agent-mode.js";
+/** P1: at most this many published exposures a member (protocol: the snapshot's 64). */
+export const HUB_EXPOSURE_MAX = 64;
+export const HUB_EXPOSURE_MIGRATION = {
+    component: "s3c-exposures",
+    version: 1,
+    up(db) {
+        db.exec(`CREATE TABLE IF NOT EXISTS hub_exposure_meta(singleton INTEGER PRIMARY KEY CHECK(singleton=1), revision INTEGER NOT NULL);
+      CREATE TABLE IF NOT EXISTS hub_exposures(id TEXT PRIMARY KEY, agent TEXT UNIQUE NOT NULL, committed TEXT, staged TEXT);`);
+    },
+};
+export class HubExposureRefusal extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+    }
+}
+const parse = (s) => (s ? JSON.parse(s) : null);
+const same = (a, b) => canonicalArguments([a]) === canonicalArguments([b]);
+/**
+ * An exposure's policy digest. P1's representative agent (agent-mode.ts): exactly providerId "agent", dataViewId
+ * "agent" and no tools, else refused. Any other descriptor is a legacy approved-view mapping, judged as before.
+ */
+function policyDigestOf(views, d) {
+    if (d.providerId === HUB_AGENT_MODE || d.dataViewId === HUB_AGENT_MODE) {
+        if (d.providerId !== HUB_AGENT_MODE || d.dataViewId !== HUB_AGENT_MODE || d.allowedTools.length !== 0)
+            throw new HubExposureRefusal("not_enforceable");
+        return agentPolicyDigest(d.agent);
+    }
+    const view = views.get(d.dataViewId);
+    if (!view)
+        throw new HubExposureRefusal("unknown_view");
+    try {
+        return executionPolicyDigest(view, d.allowedTools);
+    }
+    catch {
+        throw new HubExposureRefusal("not_enforceable");
+    }
+}
+export class HubExposureStore {
+    database;
+    options;
+    failed = false;
+    constructor(database, options) {
+        this.database = database;
+        this.options = options;
+    }
+    /** A new member set only: floor 0 and no meta row (S5 initializes every floor of the set together). */
+    initialize() {
+        if (this.options.floor.read() !== 0 || this.database.prepare("SELECT 1 FROM hub_exposure_meta").get())
+            throw new HubProtocolError("uncertain");
+        this.database.prepare("INSERT INTO hub_exposure_meta VALUES(1,0)").run();
+    }
+    /** The store revision (== the floor), or uncertain. */
+    check() {
+        if (this.failed)
+            throw new HubProtocolError("uncertain");
+        try {
+            const row = this.database.prepare("SELECT revision FROM hub_exposure_meta WHERE singleton=1").get();
+            if (!row || !Number.isSafeInteger(row.revision) || row.revision !== this.options.floor.read())
+                throw Error();
+            return row.revision;
+        }
+        catch {
+            this.failed = true;
+            throw new HubProtocolError("uncertain");
+        }
+    }
+    change(action, exposureId, work) {
+        let writing = false;
+        try {
+            return this.database.transaction(() => {
+                const revision = this.check(), value = work(revision);
+                writing = true;
+                // #3115 r1 P6: required audit finishes in THIS transaction. A thenable (an async sink) is refused: the store
+                // goes uncertain, the transaction rolls back, and a late rejection is observed (never unhandled).
+                const result = this.options.audit.appendInTransaction({ id: randomUUID(), sequence: revision + 1, at: (this.options.now ?? Date.now)(), requestId: randomUUID(),
+                    actor: { kind: "local-host" }, action, result: "completed", exposureId, policyVersion: revision + 1 }, this.database);
+                if (result && typeof result.then === "function") {
+                    void Promise.resolve(result).catch(() => { });
+                    throw new HubProtocolError("uncertain");
+                }
+                this.options.floor.raise(revision + 1);
+                this.database.prepare("UPDATE hub_exposure_meta SET revision=? WHERE singleton=1").run(revision + 1);
+                return value;
+            }).immediate();
+        }
+        catch (error) {
+            if (writing)
+                this.failed = true;
+            throw error;
+        }
+    }
+    rowOf(agent) { return this.database.prepare("SELECT * FROM hub_exposures WHERE agent=?").get(agent); }
+    rowById(id) { return this.database.prepare("SELECT * FROM hub_exposures WHERE id=?").get(id); }
+    // ── Readers (unchanged signatures for S1 and S4) ──
+    /** S1 admission: the COMMITTED exposure only (a staged candidate is never visible; a withdrawn one says so). */
+    exposure(id) {
+        this.check();
+        const r = this.rowById(id);
+        return parse(r?.committed ?? null)?.exposure ?? null;
+    }
+    /** S4: the committed mapping while published or frozen; withdrawn (or none): null — fenced. */
+    localExposure(id) {
+        this.check();
+        const c = parse(this.rowById(id)?.committed ?? null);
+        return c && c.exposure.state !== "withdrawn" ? c : null;
+    }
+    /** The complete set the Hub mirrors at this revision (published and frozen; withdrawn left out). */
+    snapshot() {
+        const revision = this.check();
+        const rows = this.database.prepare("SELECT committed FROM hub_exposures WHERE committed IS NOT NULL ORDER BY id").all();
+        return { revision, exposures: rows.map((r) => parse(r.committed).exposure).filter((e) => e.state !== "withdrawn") };
+    }
+    list() {
+        this.check();
+        return this.database.prepare("SELECT * FROM hub_exposures ORDER BY agent").all().map((r) => ({ agent: r.agent, committed: parse(r.committed), staged: parse(r.staged) }));
+    }
+    // ── The owner's changes ──
+    /**
+     * Stage the next revision of `agent`'s exposure (or its first): a candidate S4 can judge (readinessCandidate) and
+     * nobody can admit (state "withdrawn" until publish). Refused: not paired, a descriptor that is neither the exact
+     * representative agent nor an approved view (agent-mode.ts), a committed revision other than the one the owner saw (conflict), more than HUB_EXPOSURE_MAX published.
+     */
+    stage(input) {
+        const binding = this.options.binding();
+        if (!binding)
+            throw new HubExposureRefusal("not_paired");
+        const policyDigest = policyDigestOf(this.options.views, input);
+        const before = this.rowOf(input.agent), id = before?.id ?? randomUUID();
+        return this.change("exposure.staged", id, () => {
+            const row = this.rowOf(input.agent), committed = parse(row?.committed ?? null);
+            if ((committed?.exposure.revision ?? 0) !== input.expectedRevision || (row && row.id !== id))
+                throw new HubExposureRefusal("conflict");
+            if (!(committed && committed.exposure.state === "published") && this.published() >= HUB_EXPOSURE_MAX)
+                throw new HubExposureRefusal("limit");
+            const candidate = {
+                agent: input.agent, providerId: input.providerId, consentId: randomUUID(), generation: (committed?.generation ?? 0) + 1,
+                exposure: { id, fleetId: binding.fleetId, owner: binding.owner, displayName: input.displayName, revision: input.expectedRevision + 1,
+                    state: "withdrawn", dataViewId: input.dataViewId, allowedTools: [...input.allowedTools].sort(), policyDigest },
+            };
+            if (row)
+                this.database.prepare("UPDATE hub_exposures SET staged=? WHERE id=?").run(JSON.stringify(candidate), id);
+            else
+                this.database.prepare("INSERT INTO hub_exposures VALUES(?,?,NULL,?)").run(id, input.agent, JSON.stringify(candidate));
+            return candidate;
+        });
+    }
+    /**
+     * The atomic publish: in ONE transaction, recheck that the staged candidate is exactly `candidate`, the committed
+     * revision is still the one before it, the binding and the view's policy digest are unchanged, and S4's readiness
+     * (called again here, immediately before the write) still holds; then promote it to the committed, published mapping.
+     */
+    publish(candidate, ready) {
+        const id = candidate.exposure.id;
+        return this.change("exposure.published", id, () => {
+            const row = this.rowById(id), committed = parse(row?.committed ?? null), binding = this.options.binding();
+            if (!row || !same(parse(row.staged), candidate) || (committed?.exposure.revision ?? 0) !== candidate.exposure.revision - 1)
+                throw new HubExposureRefusal("conflict");
+            if (!binding || !same(binding.owner, candidate.exposure.owner) || binding.fleetId !== candidate.exposure.fleetId)
+                throw new HubExposureRefusal("conflict");
+            let digest = "";
+            try {
+                digest = policyDigestOf(this.options.views, { agent: candidate.agent, providerId: candidate.providerId, dataViewId: candidate.exposure.dataViewId, allowedTools: candidate.exposure.allowedTools });
+            }
+            catch {
+                digest = "";
+            }
+            if (digest !== candidate.exposure.policyDigest)
+                throw new HubExposureRefusal("not_enforceable");
+            const r = ready(candidate);
+            if (!r.ok || r.policyDigest !== candidate.exposure.policyDigest || r.exposureRevision !== candidate.exposure.revision)
+                throw new HubExposureRefusal("not_enforceable");
+            if (!(committed && committed.exposure.state === "published") && this.published() >= HUB_EXPOSURE_MAX)
+                throw new HubExposureRefusal("limit");
+            const published = { ...candidate, exposure: { ...candidate.exposure, state: "published" } };
+            this.database.prepare("UPDATE hub_exposures SET committed=?, staged=NULL WHERE id=?").run(JSON.stringify(published), id);
+            return published;
+        });
+    }
+    /** Drop a staged candidate (a refused readiness, a cancelled confirmation); the committed mapping is untouched. */
+    discard(id) {
+        const row = this.rowById(id);
+        if (!row || !row.staged)
+            return;
+        this.change("exposure.discarded", id, () => {
+            if (row.committed)
+                this.database.prepare("UPDATE hub_exposures SET staged=NULL WHERE id=?").run(id);
+            else
+                this.database.prepare("DELETE FROM hub_exposures WHERE id=?").run(id);
+        });
+    }
+    /**
+     * Withdraw at once (narrowing needs no consent): the committed mapping becomes withdrawn at the next revision (S1
+     * admission then refuses, S4 sees null), any staged candidate goes. `expectedRevision`: the one the owner saw.
+     */
+    withdraw(id, expectedRevision) {
+        return this.change("exposure.withdrawn", id, () => {
+            const row = this.rowById(id), committed = parse(row?.committed ?? null);
+            if (!committed || committed.exposure.revision !== expectedRevision || committed.exposure.state === "withdrawn")
+                throw new HubExposureRefusal("conflict");
+            const out = { ...committed, exposure: { ...committed.exposure, revision: committed.exposure.revision + 1, state: "withdrawn" } };
+            this.database.prepare("UPDATE hub_exposures SET committed=?, staged=NULL WHERE id=?").run(JSON.stringify(out), id);
+            return out;
+        });
+    }
+    published() {
+        return this.database.prepare("SELECT committed FROM hub_exposures WHERE committed IS NOT NULL").all()
+            .filter((r) => parse(r.committed).exposure.state === "published").length;
+    }
+}
+/**
+ * The owner's publish, end to end: stage → S4 readinessCandidate (capability evidence, not consent) → recheck and
+ * atomic publish (readiness asked again inside it). A refusal at any step drops the candidate and leaves the committed
+ * mapping as it was.
+ */
+export function publishExposure(store, input, ready) {
+    const candidate = store.stage(input);
+    try {
+        const first = ready(candidate);
+        if (!first.ok)
+            throw new HubExposureRefusal("not_enforceable");
+        return store.publish(candidate, ready);
+    }
+    catch (error) {
+        try {
+            store.discard(candidate.exposure.id);
+        }
+        catch { /* the store says uncertain on its own */ }
+        throw error;
+    }
+}
+/**
+ * The snapshot to the Hub through S1 (Sentinel's rules, S-55 Q2): `{ v:1, type:"exposure.snapshot", requestId: fresh,
+ * linkEpoch: the link's, payload: store.snapshot() }`.
+ * - `publishSnapshot(link)`: S-56's handshake step, before the link is ready (`link.send`); it remembers the link.
+ * - `afterCommit()`: after an owner's publish or withdraw, on that link while it is current; otherwise the next
+ *   handshake carries it. Socket acceptance is all a send proves (no ack frame): the owner is told "pending".
+ * Never an older revision than one sent (the store's revision only goes up, and this checks it); the same revision is
+ * sent again on a new link (metadata retry, never input replay); a fresh requestId every time; the link is checked
+ * again after the await, and a send on an old link promotes nothing.
+ */
+export function exposureSnapshotSender(store) {
+    let link = null, sent = 0;
+    const push = async (l) => {
+        if (!l.current())
+            return false;
+        const payload = store.snapshot();
+        if (payload.revision < sent)
+            throw new HubProtocolError("stale");
+        await l.send({ v: 1, type: "exposure.snapshot", requestId: randomUUID(), linkEpoch: l.linkEpoch, payload });
+        if (!l.current())
+            return false;
+        sent = Math.max(sent, payload.revision);
+        return true;
+    };
+    return {
+        async publishSnapshot(l) {
+            link = l;
+            if (!(await push(l)))
+                throw new HubProtocolError("stale");
+        },
+        async afterCommit() {
+            const l = link;
+            if (l && l.current()) {
+                try {
+                    await push(l);
+                }
+                catch { /* the next handshake carries the current snapshot */ }
+            }
+            return "pending";
+        },
+        /** The highest revision handed to a current link (socket acceptance only). */
+        sentRevision: () => sent,
+    };
+}
+//# sourceMappingURL=exposures.js.map

package/dist/hub/member/exposures.js.map

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

package/dist/hub/member/pairing-api.d.ts

@@ -0,0 +1,85 @@
+import { beginHubPairing as realBegin, claimHubPairing as realClaim } from "../pairing-client.js";
+import { HubMemberProfileStore } from "../profile.js";
+import { type HubConnectError, type HubPairingHold, type HubPairingView } from "../../hub-pairing-summary.js";
+export { httpsOrigin, pairingSummary } from "../../hub-pairing-summary.js";
+export type { HubConnectError, HubPairingHold, HubPairingView } from "../../hub-pairing-summary.js";
+export interface HubMemberPairingDeps {
+    home: string;
+    /** S5's client lifecycle (absent: offline). */
+    link?(): "online" | "offline";
+    /** A composition hold (S5), if any. */
+    hold?(): HubPairingHold | null;
+    /** S5: stop and fence the member client now (synchronous). */
+    fence?(): void;
+    /** S3c: withdraw every exposure locally (saved before it returns). */
+    withdrawAll?(): Promise<void> | void;
+    /** Whether hub_member is still on (S5; absent: on). The claim loop stops the moment it is off. */
+    enabled?(): boolean;
+    /**
+     * S5 (dev-claude): told synchronously after the binding changed and was saved — a claim's profile saved (paired), a
+     * disconnect's tombstone, a cancel / Start over / abandonment. S5 then fences, closes and rebuilds the member service
+     * only for currentBinding(home). A throw here is S5's own; the change stands.
+     */
+    bindingChanged?(): void;
+    now?(): number;
+    pollMs?: number;
+    maxPolls?: number;
+    sleep?(ms: number): Promise<void>;
+    begin?: typeof realBegin;
+    claim?: typeof realClaim;
+    profiles?(home: string, hubId: string): Pick<HubMemberProfileStore, "readProfile" | "readPending" | "profileDigest" | "clearPending">;
+}
+export declare function createHubMemberPairingApi(deps: HubMemberPairingDeps): {
+    view: () => HubPairingView;
+    /** Start pairing (a confirmed Settings replay's continuation): S1 persists the pending claim at once. */
+    connect(input: {
+        address: unknown;
+        code: unknown;
+    }, current: () => boolean): Promise<{
+        ok: true;
+        pairing: HubPairingView;
+    } | {
+        ok: false;
+        error: HubConnectError;
+    }>;
+    /** The local owner compared the fingerprint (confirmed in Settings): save the receipt, then claim (see poll). */
+    confirmFingerprint(digest: unknown, current: () => boolean): Promise<{
+        ok: true;
+        pairing: HubPairingView;
+    } | {
+        ok: false;
+        error: "conflict" | "expired" | "unsaved" | "refused";
+    }>;
+    /** Withdraw the local pending request (or clear an expired/refused hold): the in-flight generation first. */
+    cancel(): HubPairingView;
+    /** Leave the Hub (a confirmed Settings replay): fence, tombstone, withdraw every exposure; the Hub revokes later. */
+    disconnect(expected?: {
+        hubId?: unknown;
+        binding?: unknown;
+    }): Promise<{
+        ok: true;
+        remote: "pending";
+    } | {
+        ok: false;
+        error: "unsaved" | "conflict";
+    }>;
+    /**
+     * Whether S5 must refuse to connect with `hubId`'s profile (#3115 r1 P5: fails closed). It may connect only while
+     * the state names exactly this hub, unheld and not disconnected, and its profile is not a retired one; anything
+     * else — no state, another hub, unreadable state — refuses.
+     */
+    disconnected(hubId: string): boolean;
+    /** The current binding (for a disconnect's confirmation): its hub and bindingId (null: no profile), or null. */
+    boundHub: () => {
+        hubId: string;
+        binding: string | null;
+    } | null;
+};
+/**
+ * S5's member factory reads this (dev-claude): the hub a member service may be built for — the state names it, its
+ * profile exists and reads, and it is neither disconnected, held, nor a retired profile; else null. The same checks as
+ * the pairing API's view() and disconnected(); a fresh read of the files (no memory of this process).
+ */
+export declare function currentBinding(home: string, profiles?: (home: string, hubId: string) => Pick<HubMemberProfileStore, "readProfile" | "profileDigest">): {
+    hubId: string;
+} | null;