@platless/axom-cli 0.1.0 → 0.5.9

package/dist/workstation/acp/outbox.js

@@ -0,0 +1,330 @@
+/**
+ * ## Subagent relations bypass the window (fix round 1, spec §5.6)
+ *
+ * The server holds back its applied watermark — so its acks — at the first child frame whose subagent relation (`subagent_spawned`,
+ * the server's `TimelineEvent.SubagentSpawned`) it has not received yet (`noteApplied` capped at `nativePendingBefore - 1`,
+ * `ExternalAgentEventApplier.kt`). Every later frame then counts against the window; if the relation comes 256 or more frames after
+ * that first orphan child frame, a window that held it back would stall the session for good (the server waits 30 s, poisons, the
+ * reopen repeats it). So:
+ *
+ * - **producing**: while a child frame whose relation is not recorded yet is unacknowledged ({@link orphanOutstanding}), the record
+ *   loop may run past the window, so the relation can be folded at all. Whatever the branch, this life never holds more than
+ *   {@link RELATION_WAIT_EVENTS} / {@link RELATION_WAIT_BYTES} (1024 frames / 32 MiB) unacknowledged — pinned entries included — plus
+ *   the frames of the one record being folded: that is the daemon's memory bound per session;
+ * - **sending**: once a relation that resolves such a child (a *resolving* relation) is recorded, it and every entry before it stop
+ *   counting against either window ({@link pinnedThrough}): the sender takes them past the window, in seq order (sending the
+ *   relation first would make the server drop the lower seqs as duplicates); the socket gate still applies. They must keep not
+ *   counting after they are sent: the server applied them but wasted its acks while capped (each ack attempt resets its 32-event
+ *   count), so its next ack needs up to 31 more applied frames — a window still full of them would deadlock there. They leave the
+ *   outbox with that ack. A relation that resolves nothing recorded is not what the server waits for and keeps to the window
+ *   (sending past it could overflow a parked server's 512-frame hold-off).
+ *
+ * ## Residual (documented, not fixed)
+ *
+ * While the producing window is full — a server parked on an approval with ≥ 256 root frames held, a connection that is down, an
+ * applier that never acknowledges — the record loop folds nothing: a steer or config RPC waits for the processor's reply and can
+ * time out on the server; an `agent_interrupt` note is folded (and the `session/cancel` written) only once the server unparks.
+ */
+/** Unacknowledged events per session (spec §5.6, `W_EVT`). `ACK_EVERY_EVENTS(32) < W_EVT ≤ HOLD_OFF_CAPACITY(512)`. */
+export const SESSION_WINDOW_EVENTS = 256;
+/** Unacknowledged bytes per session (spec §5.6): a few huge frames cannot hog the window. */
+export const SESSION_WINDOW_BYTES = 8 * 1024 * 1024;
+/** How far production may run past the window while a recorded child frame still waits for its relation (bounds memory). */
+export const RELATION_WAIT_EVENTS = 4 * SESSION_WINDOW_EVENTS;
+export const RELATION_WAIT_BYTES = 4 * SESSION_WINDOW_BYTES;
+/** A frame carrying a subagent relation (the server's `SubagentSpawned`): it bypasses the session window. */
+export function isRelationFrame(frame) {
+    return frame.t === 'agent_event' && frame.eventName === 'subagent_spawned';
+}
+/**
+ * `src.i` of an outbox entry no record produced: a frame this daemon numbered itself (a degraded session's failed `turn_done`,
+ * `src.o` = the last record folded before it) or one imported from a legacy journal (`src.o` = 0). A replay never reproduces it
+ * (T21 skips it when comparing). Far above any per-record frame index.
+ */
+export const DAEMON_FRAME_INDEX = 1 << 24;
+/**
+ * Connection epoch of an entry that may have reached the server on an earlier connection (or in an earlier daemon life): it is not
+ * sent again until the server reopens the ref and says how far it got ({@link SessionOutbox.resendAll} after an `ack` of the open's
+ * `resumeFromSeq`) — resending a frame the server already applied could, for a `turn_done`, end a newer turn (analysis B §3.1).
+ */
+export const SENT_EARLIER = -1;
+const frameBytes = (frame) => Buffer.byteLength(JSON.stringify(frame));
+export function isOutboxTail(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const { seq, src } = value;
+    return Number.isSafeInteger(seq) && typeof src === 'object' && src !== null &&
+        Number.isSafeInteger(src.o) && Number.isSafeInteger(src.i);
+}
+export class SessionOutbox {
+    store;
+    items = [];
+    committed;
+    highestSeq = 0;
+    ownEvents = 0;
+    ownBytes = 0;
+    chain = Promise.resolve();
+    roomWaiters = new Set();
+    listeners = new Set();
+    stopped = false;
+    /** Children whose relation frame this outbox recorded. */
+    related = new Set();
+    /** Seq of the latest resolving relation: entries at or below it count against neither window (file comment). */
+    pinned = 0;
+    isRelated;
+    /**
+     * `isRelated`: whether the session already knows a child's relation from elsewhere (the processor's relation graph — a relation
+     * recorded by an earlier life, or replayed by a load). Without it only relations this outbox recorded count.
+     */
+    constructor(store, init = {}) {
+        this.store = store;
+        this.isRelated = init.isRelated ?? (() => false);
+        this.committed = isOutboxTail(init.committedTail) ? { seq: init.committedTail.seq, src: { ...init.committedTail.src } } : null;
+        this.highestSeq = this.committed?.seq ?? 0;
+        for (const record of init.leftovers ?? []) {
+            // Read back past the watermark only; a record at or below it is acknowledged (truncation is by whole segments).
+            if (this.committed && record.seq <= this.committed.seq)
+                continue;
+            this.items.push({ o: record.o, seq: record.seq, src: { ...record.src }, frame: record.frame, bytes: frameBytes(record.frame), leftover: true,
+                ...this.classify(record.seq, record.frame), sentOn: SENT_EARLIER });
+            this.highestSeq = Math.max(this.highestSeq, record.seq);
+        }
+    }
+    /**
+     * Resolving relation / orphan frame, in record order (a relation relates its child for every later frame). An orphan is a frame
+     * the server retains until a relation it has not received: a child frame (`acpSessionId`) whose child is unrelated, and — Task
+     * 22 — a `subagent_state_update` (any origin) naming an unrelated child (`payload.subagentSessionId`): the server's
+     * `receiveNativeEventLocked` holds it, and with it its acks, until that child's `subagent_spawned` exactly as it holds a child
+     * frame. The state update's own child is the key: a root-origin one would otherwise not be an orphan at all, its relation would
+     * keep to the window, and the session would stall where Task 20 fixed it for child frames.
+     */
+    classify(seq, frame) {
+        const unrelated = (child) => child !== undefined && !this.related.has(child) && !this.isRelated(child) ? child : undefined;
+        const origin = frame.t === 'agent_event' && typeof frame.acpSessionId === 'string' ? frame.acpSessionId : undefined;
+        const stateChild = frame.t === 'agent_event' && frame.eventName === 'subagent_state_update'
+            ? frame.payload?.subagentSessionId
+            : undefined;
+        const orphanOf = unrelated(typeof stateChild === 'string' ? stateChild : undefined) ?? unrelated(origin);
+        let resolving = false;
+        if (isRelationFrame(frame)) {
+            const child = frame.payload?.subagentSessionId;
+            if (typeof child === 'string') {
+                resolving = this.items.some((item) => item.orphanOf === child);
+                this.related.add(child);
+                if (resolving)
+                    this.pinned = Math.max(this.pinned, seq);
+            }
+        }
+        return { resolving, ...(orphanOf !== undefined ? { orphanOf } : {}) };
+    }
+    /** Entries at or below this seq count against neither window (the latest resolving relation; 0: none). */
+    get pinnedThrough() { return this.pinned; }
+    /** An unacknowledged child frame whose relation is still not recorded: the server is (likely) holding its acks for it. */
+    orphanOutstanding() {
+        return this.items.some((item) => item.orphanOf !== undefined && !this.related.has(item.orphanOf) && !this.isRelated(item.orphanOf));
+    }
+    /** Highest seq this outbox ever held (entries, or the acknowledged watermark): a new life numbers after it (§5.5). */
+    get lastSeq() { return this.highestSeq; }
+    /** The acknowledged watermark (`committedTail`), `null` before the first truncating ack. */
+    get committedTail() { return this.committed; }
+    /** Unacknowledged entries, in seq order. */
+    get pending() { return this.items; }
+    /** Unacknowledged entries appended by this life (the producing window), past {@link pinnedThrough}. */
+    get backlog() {
+        if (this.pinned === 0)
+            return { events: this.ownEvents, bytes: this.ownBytes };
+        let events = 0;
+        let bytes = 0;
+        for (const item of this.items)
+            if (!item.leftover && item.seq > this.pinned) {
+                events += 1;
+                bytes += item.bytes;
+            }
+        return { events, bytes };
+    }
+    /**
+     * Entries sent on connection `epoch` and not acknowledged (the sending window). Entries at or below {@link pinnedThrough} are
+     * sent past the window either way (the sender bypasses it for them); once sent they count only when `pinnedCountsWhenSent` —
+     * a server that acknowledges as soon as the relation releases its cap (`AGENT_WIRE_RELATION_ACK_VERSION`, Task 22). An older
+     * server wastes its acks while capped, so its first ack after the relation can need up to 31 more applied frames: counting the
+     * pinned ones there would deadlock right after the relation (fix round 1 of Task 20).
+     */
+    inflight(epoch, pinnedCountsWhenSent = false) {
+        let events = 0;
+        let bytes = 0;
+        for (const item of this.items) {
+            if (item.sentOn === epoch && (pinnedCountsWhenSent || item.seq > this.pinned)) {
+                events += 1;
+                bytes += item.bytes;
+            }
+        }
+        return { events, bytes };
+    }
+    /** Called whenever there may be something new to send (an append, an ack opening the window, a resend). */
+    onChange(listener) {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    }
+    changed() { for (const listener of [...this.listeners])
+        listener(); }
+    run(op) {
+        const result = this.chain.then(op);
+        this.chain = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    /** Waits for every stream operation queued so far. */
+    flush() { return this.chain; }
+    /**
+     * Record frames before they are sent. Resolves once they are durable; rejects when the stream refused them (the caller degrades
+     * the session — a frame that could not be recorded is not sent either).
+     */
+    append(frames) {
+        if (frames.length === 0)
+            return this.chain;
+        return this.run(async () => {
+            const entries = frames.map((f) => ({ seq: f.seq, src: { o: f.src.o, i: f.src.i }, frame: { ...f.frame } }));
+            const { first } = await this.store.append(entries);
+            entries.forEach((entry, index) => {
+                const bytes = frameBytes(entry.frame);
+                this.items.push({ o: first + index, seq: entry.seq, src: entry.src, frame: entry.frame, bytes, leftover: false, ...this.classify(entry.seq, entry.frame), sentOn: null });
+                this.highestSeq = Math.max(this.highestSeq, entry.seq);
+                this.ownEvents += 1;
+                this.ownBytes += bytes;
+            });
+            this.wakeRoom(); // a resolving relation unpins the producing window
+            this.changed();
+        });
+    }
+    /**
+     * The server applied everything through `throughSeq` (`agent_event_ack`, or an open's `resumeFromSeq`): forget those entries and
+     * truncate the stream through the last of them, persisting `{seq, src}` of that entry as the watermark. Nothing held at or below
+     * it: nothing changes. A failed commit is reported (`onError`) — the entries are acknowledged either way; the stream keeps them
+     * until a later commit passes them.
+     */
+    ack(throughSeq, onError) {
+        return this.run(async () => {
+            let k = -1;
+            for (let i = 0; i < this.items.length && this.items[i].seq <= throughSeq; i++)
+                k = i;
+            if (k < 0)
+                return;
+            const last = this.items[k];
+            const removed = this.items.splice(0, k + 1);
+            for (const item of removed)
+                if (!item.leftover) {
+                    this.ownEvents -= 1;
+                    this.ownBytes -= item.bytes;
+                }
+            this.committed = { seq: last.seq, src: { ...last.src } };
+            this.wakeRoom();
+            this.changed();
+            try {
+                await this.store.commit({ outbox: { through: last.o, tail: { seq: last.seq, src: { ...last.src } } } });
+            }
+            catch (error) {
+                onError?.(error);
+            }
+        });
+    }
+    /**
+     * A processor checkpoint at raw `offset`, and raw truncation through it (the keeper refuses anything past it) unless `truncate` is
+     * false (a marker checkpoint, Task 21).
+     */
+    commitCheckpoint(offset, blob, truncate = true) {
+        return this.run(async () => {
+            await this.store.commit({ checkpoint: { offset, blob }, ...(truncate ? { rawThrough: offset } : {}) });
+        });
+    }
+    /**
+     * The session re-attached to keeper-acp after its connection was lost (Task 21): the stream is the truth again. An append whose
+     * reply was lost may have landed (it is in `leftovers` now) or not (it is gone, and the record loop folds its record again). The
+     * entries are replaced by what the stream holds past its watermark; an entry this object already had keeps whether (and on which
+     * connection) it was sent and whether an earlier life left it; one it never saw was never sent. Call it with no stream operation
+     * in flight ({@link flush} first). Listeners and room waiters are kept.
+     */
+    rebase(init) {
+        const previous = new Map(this.items.map((item) => [item.seq, item]));
+        this.items.length = 0;
+        this.related.clear();
+        this.pinned = 0;
+        this.ownEvents = 0;
+        this.ownBytes = 0;
+        if (isOutboxTail(init.committedTail) && (this.committed === null || init.committedTail.seq >= this.committed.seq)) {
+            this.committed = { seq: init.committedTail.seq, src: { ...init.committedTail.src } };
+        }
+        this.highestSeq = Math.max(this.highestSeq, this.committed?.seq ?? 0);
+        for (const record of init.leftovers) {
+            if (this.committed && record.seq <= this.committed.seq)
+                continue;
+            const before = previous.get(record.seq);
+            const leftover = before?.leftover ?? false;
+            const bytes = frameBytes(record.frame);
+            this.items.push({ o: record.o, seq: record.seq, src: { ...record.src }, frame: record.frame, bytes, leftover,
+                ...this.classify(record.seq, record.frame), sentOn: before ? before.sentOn : null });
+            if (!leftover) {
+                this.ownEvents += 1;
+                this.ownBytes += bytes;
+            }
+            this.highestSeq = Math.max(this.highestSeq, record.seq);
+        }
+        this.wakeRoom();
+        this.changed();
+    }
+    /** Mark every unacknowledged entry unsent: the sender resends them in order (a reopen's replay, after the ack of its watermark). */
+    resendAll() {
+        for (const item of this.items)
+            item.sentOn = null;
+        this.changed();
+    }
+    /**
+     * A new connection: everything recorded so far — sent on an earlier connection or produced while none was bound — is held until
+     * the server reopens the ref and says how far it got ({@link SENT_EARLIER}); what is recorded from now on is sent at once. (The
+     * journal's semantics: frames produced while unbound were replayed by the reopen, never sent on their own.)
+     */
+    connectionChanged() {
+        for (const item of this.items)
+            item.sentOn = SENT_EARLIER;
+    }
+    /** The first entry never sent (the sender's next candidate), in seq order. */
+    nextUnsent() {
+        return this.items.find((item) => item.sentOn === null);
+    }
+    /** Resolves when this life's unacknowledged backlog is below the window (immediately once {@link stopWaiting} ran). */
+    room() {
+        if (this.hasRoom())
+            return undefined;
+        return new Promise((resolve) => { this.roomWaiters.add(resolve); });
+    }
+    hasRoom() {
+        if (this.stopped)
+            return true;
+        // A hard bound on everything this life holds unacknowledged, pinned or not: chained resolving relations each reset `backlog`,
+        // but pinned entries leave memory only with an ack.
+        if (this.ownEvents >= RELATION_WAIT_EVENTS || this.ownBytes >= RELATION_WAIT_BYTES)
+            return false;
+        const { events, bytes } = this.backlog;
+        if (events < SESSION_WINDOW_EVENTS && bytes < SESSION_WINDOW_BYTES)
+            return true;
+        // Past the window only while a relation is awaited: the server cannot acknowledge before it, so it must be folded.
+        return this.orphanOutstanding();
+    }
+    wakeRoom() {
+        if (!this.hasRoom())
+            return;
+        for (const resolve of [...this.roomWaiters])
+            resolve();
+        this.roomWaiters.clear();
+    }
+    /** The session is closing or degraded: nobody waits for room any more. */
+    stopWaiting() {
+        this.stopped = true;
+        this.wakeRoom();
+    }
+}
+/** An outbox store over a transport session (`acp.outbox.append` / `acp.commit`). */
+export function transportOutboxStore(transport, sessionKey) {
+    return {
+        append: (entries) => transport.appendOutbox(sessionKey, entries),
+        commit: (params) => transport.commit(sessionKey, params),
+    };
+}

package/dist/workstation/acp/patchAssets.js

@@ -0,0 +1,80 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import semver from 'semver';
+// Production reads only assets shipped in this CLI. The .ts path is for source-based tests.
+export const patchAssetRoot = new URL(import.meta.url.endsWith('.ts') ? '../../../../axom-patch/cli/' : '../../axom-patch/cli/', import.meta.url);
+const runtime = JSON.parse(readFileSync(new URL('runtime.json', patchAssetRoot), 'utf8'));
+if (runtime.schema_version !== 1)
+    throw new Error('Unsupported bundled Axom patch schema');
+for (const entry of runtime.overrides)
+    validateOverride(entry);
+function validateCondition(id, when, until, whenKey, untilKey) {
+    if (when !== undefined && until !== undefined)
+        throw new Error(`Axom patch ${id}: ${whenKey} and ${untilKey} are exclusive`);
+    if (when !== undefined && (!Array.isArray(when) || when.length === 0 || when.some((version) => !semver.valid(version)))) {
+        throw new Error(`Axom patch ${id}: ${whenKey} must list exact versions`);
+    }
+    if (until !== undefined && !semver.valid(until))
+        throw new Error(`Axom patch ${id}: ${untilKey} is not a version`);
+}
+export function validateOverride(entry) {
+    validateCondition(entry.id, entry.when_registry_version, entry.until_registry_version, 'when_registry_version', 'until_registry_version');
+    const until = entry.until_registry_version;
+    // A catch-up pin may equal its bound: use it until the registry publishes that release.
+    // A pin above the bound would instead let the registry replace it with an older release.
+    if (until !== undefined && entry.distribution && !(semver.valid(entry.distribution.version) && semver.lte(entry.distribution.version, until))) {
+        throw new Error(`Axom patch ${entry.id}: pinned ${entry.distribution.version} must not sort above ${until}`);
+    }
+}
+export function validatePackagePatch(recipe) {
+    validateCondition(recipe.id, recipe.versions, recipe.until_version, 'versions', 'until_version');
+    if (recipe.versions === undefined && recipe.until_version === undefined) {
+        throw new Error(`Axom patch ${recipe.id}: needs versions or until_version`);
+    }
+}
+function inRange(version, when, until) {
+    if (when)
+        return semver.valid(version) !== null && when.some((listed) => semver.eq(listed, version));
+    if (until)
+        return !(semver.valid(version) && semver.gte(version, until));
+    return true;
+}
+export function overrideApplies(entry, registryVersion) {
+    return inRange(registryVersion, entry.when_registry_version, entry.until_registry_version);
+}
+/** Exact versions are a promise that the bytes match; a range only says the recipe may fit. */
+export function packagePatchMatch(recipe, version) {
+    if (recipe.versions)
+        return recipe.versions.includes(version) ? 'exact' : undefined;
+    return inRange(version, undefined, recipe.until_version) ? 'range' : undefined;
+}
+/** The overrides that apply to `agent` at `registryVersion`, merged: the first distribution wins, env merges. */
+export function patchOverridesFor(agent, registryVersion, overrides = runtime.overrides) {
+    const matching = overrides.filter((entry) => entry.agent === agent && overrideApplies(entry, registryVersion));
+    const distribution = matching.find((entry) => entry.distribution)?.distribution;
+    const env = Object.assign({}, ...matching.map((entry) => entry.env ?? {}));
+    return { ...(distribution && { distribution }), ...(Object.keys(env).length && { env }) };
+}
+export const packagePatches = runtime.package_patches.map((file) => {
+    if (!/^[a-z0-9-]+\.json$/.test(file))
+        throw new Error('Invalid bundled Axom patch filename');
+    const recipe = JSON.parse(readFileSync(fileURLToPath(new URL(file, patchAssetRoot)), 'utf8'));
+    validatePackagePatch(recipe);
+    return recipe;
+});
+/** The declared native wrappers, for the catalog↔patch consistency guard in `catalog.test.ts`. */
+export const nativeExtensions = runtime.native_extensions ?? [];
+/** The bundled overrides, for the same catalog↔patch consistency guard. */
+export const runtimeOverrides = runtime.overrides;
+/** Native wrappers are declared in the patch inventory, never selected by agent-specific launch branches. */
+export function nativeExtensionFor(agent, version) {
+    const extension = runtime.native_extensions?.find(entry => entry.agent === agent && entry.versions.includes(version));
+    if (!extension)
+        return undefined;
+    if (extension.entry.startsWith('/') || extension.entry.split('/').includes('..'))
+        throw new Error('Invalid native extension path');
+    return new URL(extension.entry, patchAssetRoot);
+}
+export function nativeAccountLimitsVersionFor(agent, version) {
+    return runtime.native_extensions?.find(entry => entry.agent === agent && entry.versions.includes(version))?.accountLimitsVersion ?? 2;
+}