@xenosystem/agent-interface-host 0.1.3

package/dist/coordination/permissionWaitRegistry.js

@@ -0,0 +1,59 @@
+export function createPermissionWaitRegistry() {
+    const entries = new Map();
+    const listeners = new Set();
+    const outstanding = (requestId) => {
+        if (!requestId)
+            return 0;
+        let count = 0;
+        for (const entry of entries.values()) {
+            if (entry.requestId === requestId)
+                count += 1;
+        }
+        return count;
+    };
+    const announce = (requestId, waiting) => {
+        if (!requestId)
+            return;
+        for (const listener of [...listeners]) {
+            // Contained: a listener that throws must not break the permission flow it
+            // is only observing. Losing the report costs a peer an accurate state;
+            // losing the prompt would hang the turn.
+            try {
+                listener(requestId, waiting);
+            }
+            catch { /* observer's fault, not ours */ }
+        }
+    };
+    return {
+        set(key, entry) {
+            const before = outstanding(entry.requestId);
+            entries.set(key, entry);
+            // The FIRST outstanding prompt is what makes a run blocked; a second
+            // concurrent one does not make it more blocked, and announcing again
+            // would have a listener count transitions rather than read a state.
+            if (before === 0)
+                announce(entry.requestId, true);
+        },
+        get(key) {
+            return entries.get(key);
+        },
+        delete(key) {
+            const entry = entries.get(key);
+            const removed = entries.delete(key);
+            // The LAST removal clears it. Announcing on every resolution would report
+            // a run free while another prompt is still on screen.
+            if (removed && entry && outstanding(entry.requestId) === 0) {
+                announce(entry.requestId, false);
+            }
+            return removed;
+        },
+        entries() {
+            return entries.entries();
+        },
+        onChange(listener) {
+            listeners.add(listener);
+            return () => { listeners.delete(listener); };
+        },
+    };
+}
+//# sourceMappingURL=permissionWaitRegistry.js.map

package/dist/coordination/permissionWaitRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissionWaitRegistry.js","sourceRoot":"","sources":["../../src/coordination/permissionWaitRegistry.ts"],"names":[],"mappings":"AAiCA,MAAM,UAAU,4BAA4B;IAC1C,MAAM,OAAO,GAAG,IAAI,GAAG,EAAa,CAAA;IACpC,MAAM,SAAS,GAAG,IAAI,GAAG,EAA0B,CAAA;IAEnD,MAAM,WAAW,GAAG,CAAC,SAA6B,EAAU,EAAE;QAC5D,IAAI,CAAC,SAAS;YAAE,OAAO,CAAC,CAAA;QACxB,IAAI,KAAK,GAAG,CAAC,CAAA;QACb,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;YACrC,IAAI,KAAK,CAAC,SAAS,KAAK,SAAS;gBAAE,KAAK,IAAI,CAAC,CAAA;QAC/C,CAAC;QACD,OAAO,KAAK,CAAA;IACd,CAAC,CAAA;IAED,MAAM,QAAQ,GAAG,CAAC,SAA6B,EAAE,OAAgB,EAAQ,EAAE;QACzE,IAAI,CAAC,SAAS;YAAE,OAAM;QACtB,KAAK,MAAM,QAAQ,IAAI,CAAC,GAAG,SAAS,CAAC,EAAE,CAAC;YACtC,0EAA0E;YAC1E,uEAAuE;YACvE,yCAAyC;YACzC,IAAI,CAAC;gBAAC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC,CAAA;YAAC,CAAC;YAAC,MAAM,CAAC,CAAC,gCAAgC,CAAC,CAAC;QACjF,CAAC;IACH,CAAC,CAAA;IAED,OAAO;QACL,GAAG,CAAC,GAAG,EAAE,KAAK;YACZ,MAAM,MAAM,GAAG,WAAW,CAAC,KAAK,CAAC,SAAS,CAAC,CAAA;YAC3C,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;YACvB,qEAAqE;YACrE,qEAAqE;YACrE,oEAAoE;YACpE,IAAI,MAAM,KAAK,CAAC;gBAAE,QAAQ,CAAC,KAAK,CAAC,SAAS,EAAE,IAAI,CAAC,CAAA;QACnD,CAAC;QACD,GAAG,CAAC,GAAG;YACL,OAAO,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QACzB,CAAC;QACD,MAAM,CAAC,GAAG;YACR,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;YAC9B,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;YACnC,0EAA0E;YAC1E,sDAAsD;YACtD,IAAI,OAAO,IAAI,KAAK,IAAI,WAAW,CAAC,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC3D,QAAQ,CAAC,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,CAAA;YAClC,CAAC;YACD,OAAO,OAAO,CAAA;QAChB,CAAC;QACD,OAAO;YACL,OAAO,OAAO,CAAC,OAAO,EAAE,CAAA;QAC1B,CAAC;QACD,QAAQ,CAAC,QAAQ;YACf,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;YACvB,OAAO,GAAG,EAAE,GAAG,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA,CAAC,CAAC,CAAA;QAC7C,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/coordination/query.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Query — the pull half of coordination.
+ *
+ * `XENO_AGENT_COORDINATION_SPEC.md` §7: messaging is a notification channel, but
+ * because runs share a host an agent can also **ask**. That changes the
+ * coordination style from *"hope someone told me"* to *"check before you act"*,
+ * which the spec calls the only version that scales past a handful of agents.
+ *
+ * > "This is the capability a peer-to-peer design cannot offer, because peers
+ * > hold no shared state."
+ *
+ * ## Summary, never transcript — enforced by the type, not by discipline
+ *
+ * Gate 9 requires `run.summary` to return a summary and **never** a transcript
+ * or file contents, and §2.3's rule holds for pull as well as push: moving whole
+ * context between runs "prevents context bleeding between runs that the user
+ * separated on purpose".
+ *
+ * So `RunSummary` has **no field capable of holding one**. There is no
+ * `transcript`, no `messages`, no `contents`, no `diff` — `filesTouched` is a
+ * list of PATHS. A reviewer checking this rule reads the type, not the call
+ * sites, and a future field that could carry content has to be added
+ * deliberately rather than slipped in.
+ *
+ * ## Truncation is reported, never silent
+ *
+ * A summary is bounded, because an unbounded one is a transcript wearing a
+ * different name. When the caps bite, the result SAYS SO: a shortened list that
+ * does not announce itself is indistinguishable from a run that touched fewer
+ * files, and the reader would draw a conclusion from an absence that is an
+ * artefact.
+ */
+import type { Claim, ClaimScope } from './claims.js';
+import type { RunPosture } from './messages.js';
+export type RunState = 'idle' | 'running' | 'awaiting-approval' | 'stopped';
+/** What a peer looks like from another run (§3, §7). */
+/**
+ * A run's activity changed — ADE §5.2b, §7's "last decision".
+ *
+ * 🔴 `awaiting-approval` is a DECLARED state that nothing ever produced, and
+ * the gap is not cosmetic: a peer deciding whether to wait for a run or take
+ * the work itself needs "blocked on a human" to look different from "busy". A
+ * run reported `running` while it sits on a permission prompt is the one case
+ * where waiting is guaranteed to be wrong.
+ */
+export interface RunActivitySignal {
+    runId: string;
+    state: RunState;
+    /** §7's fourth summary field. Absent means "no change", never "none". */
+    lastDecision?: string;
+}
+export type RunActivityListener = (signal: RunActivitySignal) => void;
+export interface PeerDescriptor {
+    runId: string;
+    /** Human-readable, defaults from the workspace, settable by the user (§3). */
+    name: string;
+    state: RunState;
+    /** Workspace IDENTITY so a human can disambiguate — never its contents. */
+    workspace: string;
+}
+/**
+ * What a run has changed, as §7 defines it: "files touched, commands run,
+ * current claim set, last decision."
+ */
+export interface RunSummary {
+    runId: string;
+    name: string;
+    state: RunState;
+    workspace: string;
+    /** Paths only. There is deliberately no field for their contents. */
+    filesTouched: string[];
+    commandsRun: string[];
+    /**
+     * False when the lists above are not the whole story — see `RunRecord`.
+     *
+     * Distinct from `truncated`, which says a complete account was CUT to a cap.
+     * This says the account was never complete to begin with, and the reader's
+     * next action differs: ask for more versus do not conclude anything from an
+     * empty list.
+     */
+    complete: boolean;
+    claims: ClaimScope[];
+    /** One line. Not a transcript, not the reasoning that produced it. */
+    lastDecision?: string;
+    /**
+     * True when a cap shortened any list above.
+     *
+     * Present so a bounded summary cannot be mistaken for a complete one — the
+     * same reason the sandbox observation surface reports `degraded` rather than
+     * letting an empty result mean two different things.
+     */
+    truncated: boolean;
+}
+export interface RunRecord {
+    runId: string;
+    name: string;
+    state: RunState;
+    workspace: string;
+    filesTouched: string[];
+    commandsRun: string[];
+    lastDecision?: string;
+    /**
+     * Whether this account of what the run has done is WHOLE.
+     *
+     * 🔴 Defaults to false, and the default is the point. An empty
+     * `commandsRun` means "ran nothing" to whoever reads it, and a host that
+     * simply does not observe commands would be asserting that — the same
+     * empty-versus-unknown conflation `runSummary` already refuses when it
+     * returns `undefined` for an invisible run rather than an empty summary.
+     *
+     * Today the standalone host observes FILES and not commands: the process
+     * sensor lives behind `xeno-use` and this host consumes only the
+     * file-change port. So it registers runs with this false, and a peer reading
+     * the summary can tell "no commands" from "commands unknown".
+     */
+    complete?: boolean;
+    /**
+     * The capabilities this run is executing with — §6's derivation input.
+     *
+     * ⚠️ Optional, and absent means UNKNOWN rather than "no capabilities" — the
+     * same distinction `complete` above exists to preserve. A host that does not
+     * know a run's posture must not have that read as the most constrained
+     * posture, because a maximally-constrained *receiver* is precisely the case
+     * that holds everything, and a maximally-constrained *sender* is the case that
+     * is never held. Guessing in either direction would be a safety decision
+     * disguised as a default; `deriveInboundPolicy` refuses to compare instead.
+     *
+     * Not part of `RunSummary`: §7 answers what a run has CHANGED, and a peer
+     * learning exactly which capabilities another run holds is reconnaissance,
+     * not coordination.
+     */
+    posture?: RunPosture;
+}
+export interface CoordinationQueryOptions {
+    maxFiles?: number;
+    maxCommands?: number;
+    /**
+     * Decides which runs a caller may see (§7: "every run the caller is permitted
+     * to see"). Defaults to same-workspace visibility, which is the conservative
+     * reading: a run should not learn that unrelated work exists just because it
+     * shares a host.
+     */
+    canSee?: (caller: RunRecord, candidate: RunRecord) => boolean;
+}
+/**
+ * The host's read side.
+ *
+ * Every method is a host call over host-held state. §3: "Discovery is a host
+ * query, never a filesystem scan" — which is also why this works across sandbox
+ * boundaries at all, since a container cannot scan a directory it cannot see.
+ */
+export declare class CoordinationQuery {
+    #private;
+    constructor(options?: CoordinationQueryOptions);
+    upsertRun(record: RunRecord): void;
+    removeRun(runId: string): void;
+    /**
+     * §7 `coordination.peers.list`.
+     *
+     * A run that no window is attached to is still listed: §3 says addressing
+     * survives the disappearance of any surface, because the run lives in the
+     * host rather than in a window.
+     */
+    peers(callerRunId: string): PeerDescriptor[];
+    /**
+     * A run's permission posture, for §6's inbound-policy derivation.
+     *
+     * ⚠️ NOT a host method and NOT reachable by an agent — deliberately. It is
+     * read by the message bus inside the host to decide a policy; exposing it as a
+     * peer-visible fact would hand one agent an inventory of another's
+     * capabilities, which §7's summary-not-transcript rule exists to prevent.
+     *
+     * `undefined` for a run this registry has never seen AND for a registered run
+     * that carried no posture — both are honestly "unknown", and the caller must
+     * not be able to tell them apart, because it must treat them identically.
+     */
+    postureOf(runId: string): RunPosture | undefined;
+    /**
+     * §7 `coordination.run.summary`. Gate 9: a summary, never a transcript.
+     *
+     * Returns `undefined` rather than an empty summary when the caller may not see
+     * the run: an empty summary would report "this run changed nothing", which is
+     * a different and false statement from "you cannot see this run".
+     */
+    runSummary(callerRunId: string, targetRunId: string, claims: Claim[]): RunSummary | undefined;
+}
+//# sourceMappingURL=query.d.ts.map

package/dist/coordination/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/coordination/query.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAE/C,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,SAAS,GAAG,mBAAmB,GAAG,SAAS,CAAA;AAE3E,wDAAwD;AACxD;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,QAAQ,CAAA;IACf,yEAAyE;IACzE,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,MAAM,mBAAmB,GAAG,CAAC,MAAM,EAAE,iBAAiB,KAAK,IAAI,CAAA;AAErE,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAA;IACb,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,QAAQ,CAAA;IACf,2EAA2E;IAC3E,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,QAAQ,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IACjB,qEAAqE;IACrE,YAAY,EAAE,MAAM,EAAE,CAAA;IACtB,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB;;;;;;;OAOG;IACH,QAAQ,EAAE,OAAO,CAAA;IACjB,MAAM,EAAE,UAAU,EAAE,CAAA;IACpB,sEAAsE;IACtE,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;;;;OAMG;IACH,SAAS,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,QAAQ,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IACjB,YAAY,EAAE,MAAM,EAAE,CAAA;IACtB,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,EAAE,UAAU,CAAA;CACrB;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,KAAK,OAAO,CAAA;CAC9D;AAKD;;;;;;GAMG;AACH,qBAAa,iBAAiB;;gBAMhB,OAAO,GAAE,wBAA6B;IAmBlD,SAAS,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI;IAIlC,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAI9B;;;;;;OAMG;IACH,KAAK,CAAC,WAAW,EAAE,MAAM,GAAG,cAAc,EAAE;IAa5C;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAIhD;;;;;;OAMG;IACH,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,UAAU,GAAG,SAAS;CAyB9F"}

package/dist/coordination/query.js

@@ -0,0 +1,138 @@
+/**
+ * Query — the pull half of coordination.
+ *
+ * `XENO_AGENT_COORDINATION_SPEC.md` §7: messaging is a notification channel, but
+ * because runs share a host an agent can also **ask**. That changes the
+ * coordination style from *"hope someone told me"* to *"check before you act"*,
+ * which the spec calls the only version that scales past a handful of agents.
+ *
+ * > "This is the capability a peer-to-peer design cannot offer, because peers
+ * > hold no shared state."
+ *
+ * ## Summary, never transcript — enforced by the type, not by discipline
+ *
+ * Gate 9 requires `run.summary` to return a summary and **never** a transcript
+ * or file contents, and §2.3's rule holds for pull as well as push: moving whole
+ * context between runs "prevents context bleeding between runs that the user
+ * separated on purpose".
+ *
+ * So `RunSummary` has **no field capable of holding one**. There is no
+ * `transcript`, no `messages`, no `contents`, no `diff` — `filesTouched` is a
+ * list of PATHS. A reviewer checking this rule reads the type, not the call
+ * sites, and a future field that could carry content has to be added
+ * deliberately rather than slipped in.
+ *
+ * ## Truncation is reported, never silent
+ *
+ * A summary is bounded, because an unbounded one is a transcript wearing a
+ * different name. When the caps bite, the result SAYS SO: a shortened list that
+ * does not announce itself is indistinguishable from a run that touched fewer
+ * files, and the reader would draw a conclusion from an absence that is an
+ * artefact.
+ */
+const DEFAULT_MAX_FILES = 50;
+const DEFAULT_MAX_COMMANDS = 25;
+/**
+ * The host's read side.
+ *
+ * Every method is a host call over host-held state. §3: "Discovery is a host
+ * query, never a filesystem scan" — which is also why this works across sandbox
+ * boundaries at all, since a container cannot scan a directory it cannot see.
+ */
+export class CoordinationQuery {
+    #runs = new Map();
+    #maxFiles;
+    #maxCommands;
+    #canSee;
+    constructor(options = {}) {
+        this.#maxFiles = options.maxFiles ?? DEFAULT_MAX_FILES;
+        this.#maxCommands = options.maxCommands ?? DEFAULT_MAX_COMMANDS;
+        /**
+         * 🔴 An UNIDENTIFIED workspace matches nothing, including another
+         * unidentified one.
+         *
+         * Plain string equality made two runs with no workspace id peers of each
+         * other, which is precisely what this rule exists to prevent: §7 says a run
+         * "should not learn that unrelated work exists just because it shares a
+         * host", and `''` is not evidence of shared work — it is the absence of
+         * evidence either way.
+         */
+        this.#canSee =
+            options.canSee
+                ?? ((caller, candidate) => caller.workspace !== '' && caller.workspace === candidate.workspace);
+    }
+    upsertRun(record) {
+        this.#runs.set(record.runId, record);
+    }
+    removeRun(runId) {
+        this.#runs.delete(runId);
+    }
+    /**
+     * §7 `coordination.peers.list`.
+     *
+     * A run that no window is attached to is still listed: §3 says addressing
+     * survives the disappearance of any surface, because the run lives in the
+     * host rather than in a window.
+     */
+    peers(callerRunId) {
+        const caller = this.#runs.get(callerRunId);
+        if (!caller)
+            return [];
+        return [...this.#runs.values()]
+            .filter((candidate) => candidate.runId !== callerRunId && this.#canSee(caller, candidate))
+            .map((candidate) => ({
+            runId: candidate.runId,
+            name: candidate.name,
+            state: candidate.state,
+            workspace: candidate.workspace,
+        }));
+    }
+    /**
+     * A run's permission posture, for §6's inbound-policy derivation.
+     *
+     * ⚠️ NOT a host method and NOT reachable by an agent — deliberately. It is
+     * read by the message bus inside the host to decide a policy; exposing it as a
+     * peer-visible fact would hand one agent an inventory of another's
+     * capabilities, which §7's summary-not-transcript rule exists to prevent.
+     *
+     * `undefined` for a run this registry has never seen AND for a registered run
+     * that carried no posture — both are honestly "unknown", and the caller must
+     * not be able to tell them apart, because it must treat them identically.
+     */
+    postureOf(runId) {
+        return this.#runs.get(runId)?.posture;
+    }
+    /**
+     * §7 `coordination.run.summary`. Gate 9: a summary, never a transcript.
+     *
+     * Returns `undefined` rather than an empty summary when the caller may not see
+     * the run: an empty summary would report "this run changed nothing", which is
+     * a different and false statement from "you cannot see this run".
+     */
+    runSummary(callerRunId, targetRunId, claims) {
+        const caller = this.#runs.get(callerRunId);
+        const target = this.#runs.get(targetRunId);
+        if (!caller || !target)
+            return undefined;
+        if (target.runId !== caller.runId && !this.#canSee(caller, target))
+            return undefined;
+        const files = target.filesTouched.slice(0, this.#maxFiles);
+        const commands = target.commandsRun.slice(0, this.#maxCommands);
+        return {
+            runId: target.runId,
+            name: target.name,
+            state: target.state,
+            workspace: target.workspace,
+            filesTouched: files,
+            commandsRun: commands,
+            complete: target.complete === true,
+            claims: claims
+                .filter((claim) => claim.runId === target.runId)
+                .map((claim) => claim.scope),
+            ...(target.lastDecision === undefined ? {} : { lastDecision: target.lastDecision }),
+            truncated: files.length < target.filesTouched.length ||
+                commands.length < target.commandsRun.length,
+        };
+    }
+}
+//# sourceMappingURL=query.js.map

package/dist/coordination/query.js.map

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

package/dist/coordination/renderInbox.d.ts

@@ -0,0 +1,15 @@
+import type { DeliveredMessage } from './messages.js';
+/**
+ * What a run's peers said, as text an agent will read — ADE §5.2b, §6.
+ *
+ * 🔴 A separate function because the DELIVERY and the WORDING fail
+ * differently: delivery is a host wire that either happens or does not, and the
+ * wording is a prompt-space decision. Keeping them apart is also what makes the
+ * wording assertable without starting a turn.
+ *
+ * Names the sender on every line. A message an agent cannot attribute is one it
+ * cannot reply to — and replying is a `CoordinationSend` away, which is the
+ * whole point of pushing these in rather than letting the agent poll.
+ */
+export declare function renderInbox(delivered: readonly DeliveredMessage[]): string;
+//# sourceMappingURL=renderInbox.d.ts.map

package/dist/coordination/renderInbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderInbox.d.ts","sourceRoot":"","sources":["../../src/coordination/renderInbox.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAErD;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,SAAS,gBAAgB,EAAE,GAAG,MAAM,CAI1E"}

package/dist/coordination/renderInbox.js

@@ -0,0 +1,19 @@
+/**
+ * What a run's peers said, as text an agent will read — ADE §5.2b, §6.
+ *
+ * 🔴 A separate function because the DELIVERY and the WORDING fail
+ * differently: delivery is a host wire that either happens or does not, and the
+ * wording is a prompt-space decision. Keeping them apart is also what makes the
+ * wording assertable without starting a turn.
+ *
+ * Names the sender on every line. A message an agent cannot attribute is one it
+ * cannot reply to — and replying is a `CoordinationSend` away, which is the
+ * whole point of pushing these in rather than letting the agent poll.
+ */
+export function renderInbox(delivered) {
+    if (delivered.length === 0)
+        return '';
+    const lines = delivered.map((item) => `- ${item.message.fromRunId}: ${item.message.text}`);
+    return lines.join('\n');
+}
+//# sourceMappingURL=renderInbox.js.map

package/dist/coordination/renderInbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderInbox.js","sourceRoot":"","sources":["../../src/coordination/renderInbox.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,WAAW,CAAC,SAAsC;IAChE,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAA;IACrC,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,IAAI,CAAC,OAAO,CAAC,SAAS,KAAK,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAA;IAC1F,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACzB,CAAC"}

package/dist/coordination/runtimeEvents.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Coordination events as runtime-timeline events — the other half of gate 8.
+ *
+ * `XENO_AGENT_COORDINATION_SPEC.md` §9 sets the bar and states the consequence
+ * of missing it:
+ *
+ * > "Every message and every claim is a first-class runtime event, recorded in
+ * >  the run timeline and the audit trail with sender, recipient, outcome and
+ * >  timestamp… A reviewer looking at a surprising diff must be able to trace it
+ * >  back to the message that prompted it. **If they cannot, this section is not
+ * >  implemented.**"
+ *
+ * That is why the message TEXT is carried rather than only its id. A reviewer
+ * following an id to a message they cannot read has traced a pointer, not a
+ * reason — and §9's whole claim is that a message is "reviewable evidence of why
+ * a run changed course" rather than "an invisible nudge that changed an agent's
+ * behaviour for reasons a reviewer cannot reconstruct". Carrying the text costs
+ * nothing precisely because §2.3 already bounds a message to one line.
+ *
+ * ## Why this is an adapter and not a method on the service
+ *
+ * `CoordinationService` emits DOMAIN events and knows nothing about the event
+ * store; this maps them onto the timeline contract. Keeping the seam explicit
+ * means the coordination rules stay testable without a store, and the store's
+ * schema can change without touching them.
+ */
+import type { AgentRuntimeEventDraft } from '@xenosystem/agent-interface-contract';
+import type { CoordinationEvent } from './CoordinationService.js';
+export interface CoordinationEventContext {
+    conversationId: string;
+    requestId: string;
+    workspaceId?: string;
+    agentId?: string;
+}
+/**
+ * Every coordination event shares this source, so a timeline query can select
+ * coordination without matching on each type — and a reviewer can see at a
+ * glance which lines are agents talking rather than an agent working.
+ */
+export declare const COORDINATION_EVENT_SOURCE = "coordination";
+/**
+ * Maps one coordination event onto a runtime-event draft.
+ *
+ * `sequence` is deliberately absent: the store assigns it. A caller inventing
+ * one would be asserting an ordering it cannot know, and two callers inventing
+ * them would silently interleave.
+ */
+export declare function coordinationRuntimeEventDraft(event: CoordinationEvent, context: CoordinationEventContext, options: {
+    id: string;
+    timestamp: string;
+    text?: string;
+}): AgentRuntimeEventDraft;
+//# sourceMappingURL=runtimeEvents.d.ts.map

package/dist/coordination/runtimeEvents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtimeEvents.d.ts","sourceRoot":"","sources":["../../src/coordination/runtimeEvents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sCAAsC,CAAA;AAGlF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAEjE,MAAM,WAAW,wBAAwB;IACvC,cAAc,EAAE,MAAM,CAAA;IACtB,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,iBAAiB,CAAA;AAEvD;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,iBAAiB,EACxB,OAAO,EAAE,wBAAwB,EACjC,OAAO,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACxD,sBAAsB,CAwExB"}

package/dist/coordination/runtimeEvents.js

@@ -0,0 +1,112 @@
+/**
+ * Coordination events as runtime-timeline events — the other half of gate 8.
+ *
+ * `XENO_AGENT_COORDINATION_SPEC.md` §9 sets the bar and states the consequence
+ * of missing it:
+ *
+ * > "Every message and every claim is a first-class runtime event, recorded in
+ * >  the run timeline and the audit trail with sender, recipient, outcome and
+ * >  timestamp… A reviewer looking at a surprising diff must be able to trace it
+ * >  back to the message that prompted it. **If they cannot, this section is not
+ * >  implemented.**"
+ *
+ * That is why the message TEXT is carried rather than only its id. A reviewer
+ * following an id to a message they cannot read has traced a pointer, not a
+ * reason — and §9's whole claim is that a message is "reviewable evidence of why
+ * a run changed course" rather than "an invisible nudge that changed an agent's
+ * behaviour for reasons a reviewer cannot reconstruct". Carrying the text costs
+ * nothing precisely because §2.3 already bounds a message to one line.
+ *
+ * ## Why this is an adapter and not a method on the service
+ *
+ * `CoordinationService` emits DOMAIN events and knows nothing about the event
+ * store; this maps them onto the timeline contract. Keeping the seam explicit
+ * means the coordination rules stay testable without a store, and the store's
+ * schema can change without touching them.
+ */
+import { describeClaimScope } from './claims.js';
+/**
+ * Every coordination event shares this source, so a timeline query can select
+ * coordination without matching on each type — and a reviewer can see at a
+ * glance which lines are agents talking rather than an agent working.
+ */
+export const COORDINATION_EVENT_SOURCE = 'coordination';
+/**
+ * Maps one coordination event onto a runtime-event draft.
+ *
+ * `sequence` is deliberately absent: the store assigns it. A caller inventing
+ * one would be asserting an ordering it cannot know, and two callers inventing
+ * them would silently interleave.
+ */
+export function coordinationRuntimeEventDraft(event, context, options) {
+    const base = {
+        conversationId: context.conversationId,
+        requestId: context.requestId,
+        ...(context.workspaceId === undefined ? {} : { workspaceId: context.workspaceId }),
+        ...(context.agentId === undefined ? {} : { agentId: context.agentId }),
+        source: COORDINATION_EVENT_SOURCE,
+    };
+    const envelope = {
+        id: options.id,
+        type: event.type,
+        timestamp: options.timestamp,
+    };
+    switch (event.type) {
+        case 'coordination.message.sent':
+            return {
+                ...base,
+                event: {
+                    ...envelope,
+                    fromRunId: event.fromRunId,
+                    toRunId: event.toRunId,
+                    messageId: event.messageId,
+                    outcome: event.outcome,
+                    // §9 requires sender, recipient, OUTCOME and timestamp. The outcome is
+                    // what makes a refused or held message auditable rather than absent —
+                    // a timeline showing only delivered messages would imply the others
+                    // were never attempted.
+                    ...(options.text === undefined ? {} : { text: options.text }),
+                },
+            };
+        case 'coordination.message.delivered':
+            return {
+                ...base,
+                event: {
+                    ...envelope,
+                    fromRunId: event.fromRunId,
+                    toRunId: event.toRunId,
+                    messageId: event.messageId,
+                    // The text again, on the DELIVERY, because delivery is the moment the
+                    // receiving run could have changed course — and that is the line a
+                    // reviewer lands on when tracing a diff backwards.
+                    ...(options.text === undefined ? {} : { text: options.text }),
+                },
+            };
+        case 'coordination.claim.acquired':
+            return {
+                ...base,
+                event: {
+                    ...envelope,
+                    runId: event.runId,
+                    scope: describeClaimScope(event.scope),
+                    claimId: event.claimId,
+                },
+            };
+        case 'coordination.claim.refused':
+            return {
+                ...base,
+                event: {
+                    ...envelope,
+                    runId: event.runId,
+                    scope: describeClaimScope(event.scope),
+                    // The holder, so the timeline records the COLLISION rather than just a
+                    // failure. §5: the fleet view showing what is claimed by whom is the
+                    // fastest way to see a collision before it becomes a merge.
+                    heldByRunId: event.heldByRunId,
+                },
+            };
+        case 'coordination.claim.released':
+            return { ...base, event: { ...envelope, runId: event.runId, released: event.released } };
+    }
+}
+//# sourceMappingURL=runtimeEvents.js.map

package/dist/coordination/runtimeEvents.js.map

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