@xenosystem/agent-interface-host 0.1.3

package/dist/coordination/claims.js

@@ -0,0 +1,196 @@
+/**
+ * Task claiming — the third coordination primitive.
+ *
+ * `XENO_AGENT_COORDINATION_SPEC.md` §1 is blunt about why this exists: shared
+ * state means another run *could* know something and a message means it *does*,
+ * but **neither prevents two agents from starting the same work.** Only a claim
+ * does. §5 names the failure it closes: two agents independently rewriting the
+ * same module, each with a green suite, producing a merge that is wrong in a way
+ * neither could have detected alone.
+ *
+ * ## Why the host owns this
+ *
+ * §2.1: overlap is computed by the host **because the host is the only party
+ * that sees all runs**. A run cannot arbitrate a claim it cannot observe, and
+ * peer-to-peer discovery breaks at the container boundary — which is not a
+ * theory, it is Claude Code's own documented limitation, and we sandbox every
+ * run. A claim registry that lived in the fleet rather than above it would be
+ * unable to answer the one question it exists to answer.
+ *
+ * ## Scopes are paths, deliberately
+ *
+ * Spec §13 lists claim granularity as an OPEN DECISION: path, module, or free
+ * label. This implements **paths**, which §13 calls "the obvious start and the
+ * easiest to compute overlap for". Recorded as a decision rather than left
+ * implicit: free labels are more expressive and much harder to arbitrate, and
+ * nothing here forecloses adding them behind the same interface.
+ *
+ * The overlap rule is the same one `xeno-use` applies to sandbox mount targets,
+ * and for the same reason — a claim on `src/` must conflict with a claim on
+ * `src/app.ts`, or the coarser claim silently means nothing.
+ */
+/** A claimed unit of work. Paths are POSIX-style and workspace-relative. */
+/**
+ * A short unique id, without a Node dependency.
+ *
+ * `packages/host`'s portable entry (`index.ts`) has ZERO `node:` imports by
+ * design — it is the half that must run outside a Node host — and coordination
+ * is provider-neutral rules, so it belongs there rather than behind `./node`.
+ * `crypto.randomUUID` is Web Crypto, available in Node 20+ (this package's
+ * floor) and every modern browser, so the portability costs nothing.
+ */
+function shortId(prefix) {
+    return `${prefix}_${globalThis.crypto.randomUUID().replaceAll('-', '').slice(0, 16)}`;
+}
+export function isBranchScope(scope) {
+    return scope.kind === 'branch';
+}
+/**
+ * `refs/heads/x` and `x` are the same branch; whitespace and trailing slashes are spelling.
+ *
+ * ⚠️ Case is SIGNIFICANT and deliberately not folded. Git's ref model is case-sensitive, so
+ * folding would refuse a legitimately distinct branch on Linux. The opposite risk — two agents
+ * on branches differing only by case on a case-insensitive filesystem — is one git itself
+ * refuses to create, so it is not a hole this lock has to cover.
+ */
+function normalizeBranchName(branch) {
+    return branch.trim().replace(/^refs\/heads\//, '').replace(/\/+$/, '');
+}
+/** Canonical form for storage, so `refs/heads/x` and `x` cannot both be held. */
+export function normalizeClaimScope(scope) {
+    return isBranchScope(scope)
+        ? { kind: 'branch', branch: normalizeBranchName(scope.branch) }
+        : { path: normalizeScopePath(scope.path) };
+}
+/** A stable one-line rendering for events and diagnostics. */
+export function describeClaimScope(scope) {
+    // Path claims render as the bare path, byte-for-byte as before this type gained a second
+    // member — the runtime event payload is a wire surface and must not shift under consumers.
+    return isBranchScope(scope) ? `branch:${normalizeBranchName(scope.branch)}` : scope.path;
+}
+const DEFAULT_LEASE_MS = 60_000;
+/** Trailing slashes and `./` prefixes are spelling, not meaning. */
+function normalizeScopePath(path) {
+    const unified = path.replace(/\\/g, '/').replace(/^\.\//, '');
+    const trimmed = unified.replace(/\/+$/, '');
+    return trimmed === '' ? '/' : trimmed;
+}
+/**
+ * Two scopes overlap when they name the same work or one contains the other.
+ *
+ * The containment half is what makes a coarse claim mean anything: without it a
+ * run holding `src/` would not conflict with a run holding `src/app.ts`, and the
+ * coarse claim would be decorative. Compared segment-wise so `src` does not
+ * swallow `srcgen` — the same prefix-boundary bug that widens a scoped grant.
+ */
+export function scopesOverlap(a, b) {
+    // 🔴 A branch and a path NEVER overlap, and this is the load-bearing line of the extension.
+    // They are different axes: an agent may legitimately hold `src/app.ts` while another holds
+    // the branch it will land on. Collapsing them into one namespace — comparing `branch:x`
+    // against a path string — would invent conflicts that do not exist and, worse, would let a
+    // path named `branch:x` take a branch permit.
+    if (isBranchScope(a) !== isBranchScope(b))
+        return false;
+    if (isBranchScope(a) && isBranchScope(b)) {
+        // Exact match is COMPLETE for branches, unlike paths, and not an approximation of
+        // containment: git cannot hold both `feat/a` and `feat/a/b` at once — a ref is a file, so
+        // the parent would have to be a directory too. Nesting is unrepresentable upstream, so
+        // there is no containment case to miss.
+        return normalizeBranchName(a.branch) === normalizeBranchName(b.branch);
+    }
+    const left = normalizeScopePath(a.path);
+    const right = normalizeScopePath(b.path);
+    if (left === right)
+        return true;
+    return right.startsWith(`${left}/`) || left.startsWith(`${right}/`);
+}
+/**
+ * Host-held claim registry.
+ *
+ * Advisory to the agent, authoritative to the human (§5): a refusal tells the
+ * requester who holds the scope so it can coordinate, and the fleet view shows
+ * the collision before it becomes a merge.
+ */
+export class ClaimRegistry {
+    #claims = new Map();
+    #now;
+    #leaseMs;
+    constructor(options = {}) {
+        this.#now = options.now ?? Date.now;
+        this.#leaseMs = options.leaseMs ?? DEFAULT_LEASE_MS;
+    }
+    /**
+     * Drops leases that have run out.
+     *
+     * Called before every read and write rather than on a timer: a timer that
+     * failed to fire would leave a dead run holding the fleet, and the whole point
+     * of a lease is that it cannot outlive its holder's silence. Expiry is
+     * therefore a property of every observation, not a background job.
+     */
+    #sweep() {
+        const at = this.#now();
+        for (const [id, claim] of this.#claims) {
+            if (claim.expiresAt <= at)
+                this.#claims.delete(id);
+        }
+    }
+    /** Live claims, expired ones already removed. */
+    list() {
+        this.#sweep();
+        return [...this.#claims.values()];
+    }
+    acquire(scope, runId) {
+        this.#sweep();
+        for (const claim of this.#claims.values()) {
+            // A run re-claiming its own scope is a renewal, not a conflict: refusing
+            // it would make a run its own blocker across a retry.
+            if (claim.runId === runId && scopesOverlap(claim.scope, scope)) {
+                claim.expiresAt = this.#now() + this.#leaseMs;
+                return { acquired: true, claim };
+            }
+            if (scopesOverlap(claim.scope, scope)) {
+                return { acquired: false, heldBy: claim };
+            }
+        }
+        const acquiredAt = this.#now();
+        const claim = {
+            id: shortId('clm'),
+            scope: normalizeClaimScope(scope),
+            runId,
+            acquiredAt,
+            expiresAt: acquiredAt + this.#leaseMs,
+        };
+        this.#claims.set(claim.id, claim);
+        return { acquired: true, claim };
+    }
+    /** Extends a live lease. Returns false when it has already lapsed. */
+    renew(claimId) {
+        this.#sweep();
+        const claim = this.#claims.get(claimId);
+        if (!claim)
+            return false;
+        claim.expiresAt = this.#now() + this.#leaseMs;
+        return true;
+    }
+    release(claimId) {
+        return this.#claims.delete(claimId);
+    }
+    /**
+     * §5: "released automatically when a run terminates. A crashed run must never
+     * deadlock the fleet." Called by the host on run termination — the expiry
+     * sweep is the backstop for a host that never got the news, not the primary
+     * path, because waiting a full lease for a run we KNOW is gone is a stall
+     * nobody can explain.
+     */
+    releaseRun(runId) {
+        let released = 0;
+        for (const [id, claim] of this.#claims) {
+            if (claim.runId === runId) {
+                this.#claims.delete(id);
+                released += 1;
+            }
+        }
+        return released;
+    }
+}
+//# sourceMappingURL=claims.js.map

package/dist/coordination/claims.js.map

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

package/dist/coordination/coordinationTools.d.ts

@@ -0,0 +1,40 @@
+import type { CoordinationLaneBridge } from './laneBridge.js';
+/**
+ * A tool as the SDK loop registers them: plain data plus a function.
+ *
+ * Redeclared here rather than imported, and that is the point — the shape has
+ * no Electron in it, so the definitions belong in the host where every lane can
+ * reach them. `electron-host` owns the *registration*, not the tools.
+ */
+export interface CoordinationToolDefinition {
+    definition: {
+        name: string;
+        description: string;
+        input_schema: {
+            type: 'object';
+            properties: Record<string, unknown>;
+            required?: string[];
+        };
+    };
+    execute: (input: Record<string, unknown>) => Promise<{
+        success: boolean;
+        output: string;
+        error?: string;
+    }>;
+}
+/**
+ * The SDK lane's names for the three coordination primitives — ADE §5.2b.
+ *
+ * 🔴 **Built from the SAME bridge the ACP lane uses.** An ACP agent reaches
+ * these as `xeno.dev/*` extension methods and an SDK agent as registered tools;
+ * two vocabularies for one set of calls. Implementing them twice would let a
+ * primitive behave differently depending on which runtime happened to be
+ * executing — an agent told a claim was granted in one lane and refused in the
+ * other has no way to tell which answer to believe.
+ *
+ * The caller's run id is bound INTO the bridge by the host, so it is absent
+ * from every schema below. An agent cannot address these calls as another run
+ * because there is no parameter through which to try.
+ */
+export declare function createCoordinationTools(bridge: CoordinationLaneBridge): CoordinationToolDefinition[];
+//# sourceMappingURL=coordinationTools.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"coordinationTools.d.ts","sourceRoot":"","sources":["../../src/coordination/coordinationTools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAA;AAE7D;;;;;;GAMG;AACH,MAAM,WAAW,0BAA0B;IACzC,UAAU,EAAE;QACV,IAAI,EAAE,MAAM,CAAA;QACZ,WAAW,EAAE,MAAM,CAAA;QACnB,YAAY,EAAE;YACZ,IAAI,EAAE,QAAQ,CAAA;YACd,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;YACnC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;SACpB,CAAA;KACF,CAAA;IACD,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAC3G;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,sBAAsB,GAAG,0BAA0B,EAAE,CAiEpG"}

package/dist/coordination/coordinationTools.js

@@ -0,0 +1,92 @@
+/**
+ * The SDK lane's names for the three coordination primitives — ADE §5.2b.
+ *
+ * 🔴 **Built from the SAME bridge the ACP lane uses.** An ACP agent reaches
+ * these as `xeno.dev/*` extension methods and an SDK agent as registered tools;
+ * two vocabularies for one set of calls. Implementing them twice would let a
+ * primitive behave differently depending on which runtime happened to be
+ * executing — an agent told a claim was granted in one lane and refused in the
+ * other has no way to tell which answer to believe.
+ *
+ * The caller's run id is bound INTO the bridge by the host, so it is absent
+ * from every schema below. An agent cannot address these calls as another run
+ * because there is no parameter through which to try.
+ */
+export function createCoordinationTools(bridge) {
+    return [
+        {
+            definition: {
+                name: 'CoordinationSend',
+                description: 'Send a message to another agent run in this fleet. Returns the delivery outcome: '
+                    + 'delivered, held, refused or expired. Held and refused are not failures to retry blindly — '
+                    + 'they mean the recipient is not accepting this message.',
+                input_schema: {
+                    type: 'object',
+                    properties: {
+                        toRunId: { type: 'string', description: 'The run to send to, from CoordinationQuery.' },
+                        text: { type: 'string', description: 'What to tell it.' },
+                    },
+                    required: ['toRunId', 'text'],
+                },
+            },
+            execute: async (input) => report(bridge.send(input)),
+        },
+        {
+            definition: {
+                name: 'CoordinationQuery',
+                description: 'List the other agent runs you can see, or ask about one of them by id: what files it '
+                    + 'has touched, what commands it has run, and what it currently holds a claim on.',
+                input_schema: {
+                    type: 'object',
+                    properties: {
+                        runId: { type: 'string', description: 'Omit to list peers; supply one to ask about it.' },
+                    },
+                },
+            },
+            execute: async (input) => report(bridge.query(input)),
+        },
+        {
+            definition: {
+                name: 'CoordinationClaim',
+                description: 'Take an exclusive claim before editing, so two runs do not collide. Claim a PATH '
+                    + 'before editing files under it, or a BRANCH before committing to it — supply exactly '
+                    + 'one. A refusal names the run that holds it — message that run rather than waiting or '
+                    + 'proceeding anyway.',
+                input_schema: {
+                    type: 'object',
+                    properties: {
+                        path: { type: 'string', description: 'The path to claim. A claim on a directory covers everything under it.' },
+                        branch: {
+                            type: 'string',
+                            description: 'The git branch to claim, instead of a path. Branches do not nest: claiming '
+                                + 'feat/a does not claim feat/a/b.',
+                        },
+                    },
+                    // 🔴 Neither is individually required and the ONE-OF rule is enforced in the bridge,
+                    // not here. JSON Schema could express it with `oneOf`, but this schema is handed to
+                    // several agent runtimes whose support for it varies, and a constraint some providers
+                    // silently drop is worse than one enforced where it is actually checked. The bridge
+                    // refuses both-or-neither with a message naming the fix.
+                    required: [],
+                },
+            },
+            execute: async (input) => report(bridge.claim(input)),
+        },
+    ];
+}
+/**
+ * Turns a bridge answer into a tool result.
+ *
+ * 🔴 An `error` field means the CALL was rejected — a missing parameter, or a
+ * host with no coordination. A `status: 'refused'` does not: the call worked and
+ * the answer is no. Collapsing the two would tell an agent its message failed to
+ * send when the recipient simply declined it, and the corrections differ —
+ * retry the call, versus find another way to reach that run.
+ */
+async function report(answer) {
+    const error = typeof answer.error === 'string' ? answer.error : undefined;
+    return error === undefined
+        ? { success: true, output: JSON.stringify(answer) }
+        : { success: false, output: '', error };
+}
+//# sourceMappingURL=coordinationTools.js.map

package/dist/coordination/coordinationTools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coordinationTools.js","sourceRoot":"","sources":["../../src/coordination/coordinationTools.ts"],"names":[],"mappings":"AAsBA;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAA8B;IACpE,OAAO;QACL;YACE,UAAU,EAAE;gBACV,IAAI,EAAE,kBAAkB;gBACxB,WAAW,EACT,mFAAmF;sBACjF,4FAA4F;sBAC5F,wDAAwD;gBAC5D,YAAY,EAAE;oBACZ,IAAI,EAAE,QAAQ;oBACd,UAAU,EAAE;wBACV,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,6CAA6C,EAAE;wBACvF,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,kBAAkB,EAAE;qBAC1D;oBACD,QAAQ,EAAE,CAAC,SAAS,EAAE,MAAM,CAAC;iBAC9B;aACF;YACD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;SACrD;QACD;YACE,UAAU,EAAE;gBACV,IAAI,EAAE,mBAAmB;gBACzB,WAAW,EACT,uFAAuF;sBACrF,gFAAgF;gBACpF,YAAY,EAAE;oBACZ,IAAI,EAAE,QAAQ;oBACd,UAAU,EAAE;wBACV,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,iDAAiD,EAAE;qBAC1F;iBACF;aACF;YACD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;SACtD;QACD;YACE,UAAU,EAAE;gBACV,IAAI,EAAE,mBAAmB;gBACzB,WAAW,EACT,mFAAmF;sBACjF,sFAAsF;sBACtF,uFAAuF;sBACvF,oBAAoB;gBACxB,YAAY,EAAE;oBACZ,IAAI,EAAE,QAAQ;oBACd,UAAU,EAAE;wBACV,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,uEAAuE,EAAE;wBAC9G,MAAM,EAAE;4BACN,IAAI,EAAE,QAAQ;4BACd,WAAW,EACT,6EAA6E;kCAC3E,iCAAiC;yBACtC;qBACF;oBACD,qFAAqF;oBACrF,oFAAoF;oBACpF,sFAAsF;oBACtF,oFAAoF;oBACpF,yDAAyD;oBACzD,QAAQ,EAAE,EAAE;iBACb;aACF;YACD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;SACtD;KACF,CAAA;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,KAAK,UAAU,MAAM,CACnB,MAA+B;IAE/B,MAAM,KAAK,GAAG,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAA;IACzE,OAAO,KAAK,KAAK,SAAS;QACxB,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE;QACnD,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,CAAA;AAC3C,CAAC"}

package/dist/coordination/laneBridge.d.ts

@@ -0,0 +1,84 @@
+import type { AcquireClaimResult, ClaimScope } from './claims.js';
+import type { MessageOutcome } from './messages.js';
+import type { PeerDescriptor, RunSummary } from './query.js';
+/**
+ * Coordination, reachable by an AGENT — ADE §5.2b. LANE-NEUTRAL.
+ *
+ * 🔴 **One implementation, two vocabularies.** An ACP agent reaches these three
+ * primitives as `xeno.dev/*` extension methods; an SDK agent reaches them as
+ * registered tools. Both are names for the same calls, so both are built from
+ * this bridge rather than from two hand-kept copies — a lane that drifted would
+ * offer an agent a coordination primitive that behaves differently depending on
+ * which runtime happened to be executing it.
+ *
+ * It lives in `coordination/` and not in `acp/` for exactly that reason: the SDK
+ * lane must not have to import from the ACP one to be a peer.
+ *
+ * 🔴 **This is the surface a recorded blocker said did not exist.**
+ *
+ * `coordinationService` was the last unmounted host service, exempted on the
+ * grounds that *"coordination is reached by AGENTS through tools"* and that the
+ * ACP lane *"needs an MCP/protocol surface"*. The first half is right. The
+ * second is wrong, and had been for as long as `choose_directory` has shipped:
+ * XENO already owns an ACP extension surface, and it is live in the shipping
+ * path. `AcpProcessSupervisor` routes `extMethod` into
+ * `handleAcpHostExtensionRequest`, and `DEFAULT_CLIENT_CAPABILITIES` advertises
+ * the available methods under `_meta['xeno.dev'].hostRequests` at `initialize`,
+ * so agents discover them rather than guessing.
+ *
+ * Coordination needed three more entries in that table, not a second protocol —
+ * which is the build doctrine's own instruction: *extend the protocol rather
+ * than work around it.* An MCP server would have been a parallel transport
+ * carrying the same calls to the same service.
+ *
+ * 🔴 **The caller's run id is NOT a parameter, and that is the whole security
+ * model.** It is bound when this bridge is constructed, from the host's own
+ * per-conversation context. An agent that could name its own `fromRunId` could
+ * send messages as another run, read a peer's summary through someone else's
+ * visibility, and take a claim in a third run's name — coordination is
+ * host-mediated precisely so that a participant cannot assert who it is.
+ */
+export interface CoordinationLanePort {
+    send(input: {
+        fromRunId: string;
+        toRunId: string;
+        text: string;
+    }): MessageOutcome;
+    peers(callerRunId: string): PeerDescriptor[];
+    runSummary(callerRunId: string, targetRunId: string): RunSummary | undefined;
+    acquireClaim(scope: ClaimScope, runId: string): AcquireClaimResult;
+}
+export interface CoordinationLaneBridge {
+    send(params: Record<string, unknown>): Record<string, unknown>;
+    query(params: Record<string, unknown>): Record<string, unknown>;
+    claim(params: Record<string, unknown>): Record<string, unknown>;
+}
+/**
+ * The bridge a lane gets when coordination is not mounted.
+ *
+ * Refuses by NAME rather than returning an empty result. "No peers" and "this
+ * host cannot coordinate" are the same empty list and opposite meanings, and an
+ * agent told the first will conclude it is working alone — then edit a file
+ * another run has claimed.
+ */
+export declare class UnavailableCoordinationLaneBridge implements CoordinationLaneBridge {
+    send(): Record<string, unknown>;
+    query(): Record<string, unknown>;
+    claim(): Record<string, unknown>;
+}
+export interface HostCoordinationLaneBridgeOptions {
+    /** Bound by the host from its own conversation context, never by the agent. */
+    callerRunId: string;
+    port: CoordinationLanePort;
+}
+export declare class HostCoordinationLaneBridge implements CoordinationLaneBridge {
+    #private;
+    constructor(options: HostCoordinationLaneBridgeOptions);
+    /** message (push) — §5.2b's first primitive. */
+    send(params: Record<string, unknown>): Record<string, unknown>;
+    /** query (pull) — peers, or one peer's summary. */
+    query(params: Record<string, unknown>): Record<string, unknown>;
+    /** claim (lock) — the primitive that prevents two runs editing one file. */
+    claim(params: Record<string, unknown>): Record<string, unknown>;
+}
+//# sourceMappingURL=laneBridge.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"laneBridge.d.ts","sourceRoot":"","sources":["../../src/coordination/laneBridge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACjE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,WAAW,oBAAoB;IACnC,IAAI,CAAC,KAAK,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,cAAc,CAAA;IACjF,KAAK,CAAC,WAAW,EAAE,MAAM,GAAG,cAAc,EAAE,CAAA;IAC5C,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAA;IAC5E,YAAY,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,kBAAkB,CAAA;CACnE;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC9D,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC/D,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAChE;AAED;;;;;;;GAOG;AACH,qBAAa,iCAAkC,YAAW,sBAAsB;IAC9E,IAAI,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAI/B,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAIhC,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAGjC;AAED,MAAM,WAAW,iCAAiC;IAChD,+EAA+E;IAC/E,WAAW,EAAE,MAAM,CAAA;IACnB,IAAI,EAAE,oBAAoB,CAAA;CAC3B;AAED,qBAAa,0BAA2B,YAAW,sBAAsB;;gBAI3D,OAAO,EAAE,iCAAiC;IAKtD,gDAAgD;IAChD,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAmB9D,mDAAmD;IACnD,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAW/D,4EAA4E;IAC5E,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAuBhE"}

package/dist/coordination/laneBridge.js

@@ -0,0 +1,86 @@
+/**
+ * The bridge a lane gets when coordination is not mounted.
+ *
+ * Refuses by NAME rather than returning an empty result. "No peers" and "this
+ * host cannot coordinate" are the same empty list and opposite meanings, and an
+ * agent told the first will conclude it is working alone — then edit a file
+ * another run has claimed.
+ */
+export class UnavailableCoordinationLaneBridge {
+    send() {
+        return { error: 'Coordination is not available on this host.' };
+    }
+    query() {
+        return { error: 'Coordination is not available on this host.' };
+    }
+    claim() {
+        return { error: 'Coordination is not available on this host.' };
+    }
+}
+export class HostCoordinationLaneBridge {
+    #callerRunId;
+    #port;
+    constructor(options) {
+        this.#callerRunId = options.callerRunId;
+        this.#port = options.port;
+    }
+    /** message (push) — §5.2b's first primitive. */
+    send(params) {
+        const toRunId = stringParam(params.toRunId ?? params.to);
+        const text = stringParam(params.text ?? params.message);
+        if (!toRunId || !text) {
+            // Named, because the two failures need different corrections: a missing
+            // recipient is a different mistake from an empty message.
+            return { error: !toRunId ? 'coordination_send requires toRunId.' : 'coordination_send requires text.' };
+        }
+        const outcome = this.#port.send({ fromRunId: this.#callerRunId, toRunId, text });
+        // \u{1F534} The OUTCOME travels back verbatim. `held`, `refused` and `expired` are
+        // not failures to smooth over into a boolean: an agent that believes a
+        // held message was delivered will wait for an answer that is not coming,
+        // and one that reads `refused` as `delivered` will assume it has handed
+        // work off and stop.
+        return outcome.status === 'delivered'
+            ? { status: outcome.status, messageId: outcome.messageId }
+            : { status: outcome.status, messageId: outcome.messageId, reason: outcome.reason };
+    }
+    /** query (pull) — peers, or one peer's summary. */
+    query(params) {
+        const targetRunId = stringParam(params.runId ?? params.target);
+        if (!targetRunId) {
+            return { peers: this.#port.peers(this.#callerRunId) };
+        }
+        const summary = this.#port.runSummary(this.#callerRunId, targetRunId);
+        // Absent and invisible are the same answer HERE on purpose: telling a caller
+        // that a run exists but it may not look is itself a disclosure.
+        return summary ? { run: summary } : { run: null };
+    }
+    /** claim (lock) — the primitive that prevents two runs editing one file. */
+    claim(params) {
+        const path = stringParam(params.path);
+        const branch = stringParam(params.branch);
+        // Exactly one axis per call. Accepting both would make a partial acquisition expressible —
+        // the path taken and the branch refused — and the caller would have no single answer to act
+        // on, which is the same reason a LIST of paths is refused below.
+        if (path && branch) {
+            return { error: 'coordination_claim takes a path or a branch, not both.' };
+        }
+        if (!path && !branch)
+            return { error: 'coordination_claim requires a path or a branch.' };
+        // ONE path per call, because `ClaimScope` is one unit of work. Accepting a list here
+        // and looping would make a partial acquisition expressible — some paths
+        // taken, some refused — and the caller would have no single answer to act on.
+        const scope = branch ? { kind: 'branch', branch } : { path: path };
+        const result = this.#port.acquireClaim(scope, this.#callerRunId);
+        // \u{1F534} A refusal names WHO HOLDS IT. Coordination §5 is explicit that a bare
+        // `false` leaves the caller with exactly the two behaviours it exists to
+        // prevent — spinning, or proceeding anyway — whereas a holder is someone
+        // the agent can message with the primitive it already has.
+        return result.acquired
+            ? { granted: true, claimId: result.claim.id }
+            : { granted: false, heldByRunId: result.heldBy.runId };
+    }
+}
+function stringParam(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+//# sourceMappingURL=laneBridge.js.map

package/dist/coordination/laneBridge.js.map

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