@xenosystem/agent-interface-client 0.1.0

package/dist/local/transport.js

@@ -0,0 +1,276 @@
+/**
+ * Local Agent host wire protocol — framing plus the CLIENT transport.
+ *
+ * 🔴 This lives in the CLIENT package, not in `contract`, and the reason is load-bearing:
+ * `contract` is Node-free and must stay that way. A renderer reaches `contract/index.js`, and
+ * Vite fails a browser build on any `node:` builtin ("stat" is not exported by
+ * "__vite-browser-external") — `browserBarrelPurity.test.ts` pins that. This module needs
+ * `node:net`, `node:crypto` and `node:fs/promises`, so it cannot go there.
+ *
+ * It is also why the split is client-package-and-below rather than contract-and-below: a surface
+ * that wants to ATTACH to a local host needs Node anyway.
+ *
+ * @packageDocumentation
+ */
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { chmod, mkdir, unlink } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { createConnection, createServer, } from 'node:net';
+import { AgentHostProtocolError, XENO_AGENT_HOST_PROTOCOL_VERSION, isAgentHostMethod, isAgentHostEvent, } from '@xenosystem/agent-interface-contract';
+export const LOCAL_AGENT_HOST_DEFAULT_MAX_FRAME_BYTES = 32 * 1024 * 1024;
+export const LOCAL_AGENT_HOST_ABSOLUTE_MAX_FRAME_BYTES = 64 * 1024 * 1024;
+const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+/** Node-side AgentHostTransport implementation for a local host authority. */
+export class LocalAgentHostRpcClientTransport {
+    endpoint;
+    transportToken;
+    protocolVersion;
+    maxFrameBytes;
+    requestTimeoutMs;
+    listeners = new Set();
+    pending = new Map();
+    requestPrefix = randomBytes(12).toString('hex');
+    requestSequence = 0;
+    socket = null;
+    connectPromise = null;
+    constructor(options) {
+        assertLocalRpcOptions(options.endpoint, options.transportToken);
+        this.endpoint = options.endpoint;
+        this.transportToken = options.transportToken;
+        this.protocolVersion = positiveInteger(options.protocolVersion) || XENO_AGENT_HOST_PROTOCOL_VERSION;
+        this.maxFrameBytes = resolveMaxFrameBytes(options.maxFrameBytes);
+        this.requestTimeoutMs = positiveInteger(options.requestTimeoutMs) || DEFAULT_REQUEST_TIMEOUT_MS;
+    }
+    get connected() {
+        return this.socket !== null && !this.socket.destroyed;
+    }
+    async connect() {
+        if (this.connected)
+            return;
+        if (this.connectPromise)
+            return this.connectPromise;
+        this.connectPromise = new Promise((resolveConnect, rejectConnect) => {
+            const socket = createConnection(this.endpoint);
+            const decoder = new JsonLineDecoder(this.maxFrameBytes, (frame) => this.receive(frame));
+            const failConnect = (error) => {
+                socket.off('connect', connected);
+                this.socket = null;
+                rejectConnect(error);
+            };
+            const connected = () => {
+                socket.off('error', failConnect);
+                socket.setNoDelay(true);
+                this.socket = socket;
+                resolveConnect();
+            };
+            socket.once('error', failConnect);
+            socket.once('connect', connected);
+            socket.on('data', (chunk) => {
+                try {
+                    decoder.push(chunk);
+                }
+                catch (error) {
+                    this.disconnect(asError(error));
+                }
+            });
+            socket.on('error', (error) => this.disconnect(error));
+            socket.on('close', () => this.disconnect(new Error('Local Agent host connection closed.')));
+        }).finally(() => {
+            this.connectPromise = null;
+        });
+        return this.connectPromise;
+    }
+    async request(method, input) {
+        await this.connect();
+        const socket = this.socket;
+        if (!socket || socket.destroyed) {
+            throw new AgentHostProtocolError('not_connected', 'Local Agent host is not connected.');
+        }
+        const id = `${this.requestPrefix}:${++this.requestSequence}`;
+        const request = {
+            kind: 'request',
+            id,
+            protocolVersion: this.protocolVersion,
+            token: this.transportToken,
+            method,
+            input: structuredClone(input),
+        };
+        return new Promise((resolveRequest, rejectRequest) => {
+            const requestTimeoutMs = resolveRequestTimeout(method, input, this.requestTimeoutMs);
+            const timeout = setTimeout(() => {
+                this.pending.delete(id);
+                rejectRequest(new AgentHostProtocolError('not_connected', `Local Agent host request timed out: ${method}.`));
+            }, requestTimeoutMs);
+            this.pending.set(id, {
+                resolve: (output) => resolveRequest(output),
+                reject: rejectRequest,
+                timeout,
+            });
+            try {
+                writeClientFrame(socket, request, this.maxFrameBytes);
+            }
+            catch (error) {
+                clearTimeout(timeout);
+                this.pending.delete(id);
+                rejectRequest(asError(error));
+            }
+        });
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    close() {
+        this.disconnect(new Error('Local Agent host client closed.'));
+    }
+    receive(frame) {
+        let value;
+        try {
+            value = JSON.parse(frame);
+        }
+        catch {
+            this.disconnect(new AgentHostProtocolError('invalid_response', 'Local Agent host returned malformed JSON.'));
+            return;
+        }
+        if (isLocalRpcEvent(value)) {
+            for (const listener of [...this.listeners])
+                listener(structuredClone(value.event));
+            return;
+        }
+        if (!isLocalRpcResponse(value)) {
+            this.disconnect(new AgentHostProtocolError('invalid_response', 'Local Agent host returned an invalid RPC frame.'));
+            return;
+        }
+        const pending = this.pending.get(value.id);
+        if (!pending)
+            return;
+        clearTimeout(pending.timeout);
+        this.pending.delete(value.id);
+        if (value.ok)
+            pending.resolve(structuredClone(value.output));
+        else
+            pending.reject(new AgentHostProtocolError(value.error.code, value.error.message));
+    }
+    disconnect(error) {
+        const socket = this.socket;
+        this.socket = null;
+        if (socket && !socket.destroyed)
+            socket.destroy();
+        for (const pending of this.pending.values()) {
+            clearTimeout(pending.timeout);
+            pending.reject(error);
+        }
+        this.pending.clear();
+    }
+}
+function resolveRequestTimeout(method, input, fallback) {
+    if (method !== 'workspace.command.run')
+        return fallback;
+    const requested = isRecord(input) && typeof input.timeoutMs === 'number' && Number.isFinite(input.timeoutMs)
+        ? Math.max(1_000, Math.min(120_000, Math.floor(input.timeoutMs)))
+        : 20_000;
+    return Math.max(fallback, requested + 5_000);
+}
+export function resolveLocalAgentHostEndpoint(rootDirectory, scope = 'default') {
+    if (!rootDirectory.trim())
+        throw new Error('Local Agent host rootDirectory is required.');
+    if (!scope.trim())
+        throw new Error('Local Agent host endpoint scope is required.');
+    const digest = createHash('sha256')
+        .update(`${resolve(rootDirectory)}\0${scope}`, 'utf8')
+        .digest('hex')
+        .slice(0, 24);
+    return process.platform === 'win32'
+        ? `\\\\.\\pipe\\xeno-agent-host-${digest}`
+        : join(rootDirectory, `agent-host-${digest}.sock`);
+}
+export class JsonLineDecoder {
+    maxFrameBytes;
+    onFrame;
+    buffer = Buffer.alloc(0);
+    constructor(maxFrameBytes, onFrame) {
+        this.maxFrameBytes = maxFrameBytes;
+        this.onFrame = onFrame;
+    }
+    push(chunk) {
+        this.buffer = this.buffer.length === 0 ? chunk : Buffer.concat([this.buffer, chunk]);
+        if (this.buffer.length > this.maxFrameBytes && this.buffer.indexOf(0x0a) < 0) {
+            throw new AgentHostProtocolError('invalid_response', 'Local Agent host RPC frame exceeds the size limit.');
+        }
+        let newline = this.buffer.indexOf(0x0a);
+        while (newline >= 0) {
+            if (newline > this.maxFrameBytes) {
+                throw new AgentHostProtocolError('invalid_response', 'Local Agent host RPC frame exceeds the size limit.');
+            }
+            const frameBuffer = this.buffer.subarray(0, newline);
+            this.buffer = this.buffer.subarray(newline + 1);
+            const frame = frameBuffer.toString('utf8').replace(/\r$/, '');
+            if (frame)
+                this.onFrame(frame);
+            newline = this.buffer.indexOf(0x0a);
+        }
+    }
+}
+function isLocalRpcResponse(value) {
+    if (!isRecord(value) || value.kind !== 'response' || typeof value.id !== 'string' || typeof value.ok !== 'boolean') {
+        return false;
+    }
+    if (value.ok)
+        return 'output' in value;
+    return isRecord(value.error)
+        && isProtocolErrorCode(value.error.code)
+        && typeof value.error.message === 'string';
+}
+function isLocalRpcEvent(value) {
+    return isRecord(value) && value.kind === 'event' && isAgentHostEvent(value.event);
+}
+function writeClientFrame(socket, value, maxFrameBytes) {
+    writeFrame(socket, value, maxFrameBytes);
+}
+export function writeFrame(socket, value, maxFrameBytes) {
+    const encoded = `${JSON.stringify(value)}\n`;
+    if (Buffer.byteLength(encoded, 'utf8') > maxFrameBytes) {
+        throw new AgentHostProtocolError('invalid_response', 'Local Agent host RPC frame exceeds the size limit.');
+    }
+    socket.write(encoded, 'utf8');
+}
+export function safeTokenEquals(left, right) {
+    const leftBytes = Buffer.from(left, 'utf8');
+    const rightBytes = Buffer.from(right, 'utf8');
+    return leftBytes.length === rightBytes.length && timingSafeEqual(leftBytes, rightBytes);
+}
+export function assertLocalRpcOptions(endpoint, transportToken) {
+    if (!endpoint.trim())
+        throw new Error('Local Agent host endpoint is required.');
+    if (transportToken.length < 32)
+        throw new Error('Local Agent host transportToken must contain at least 32 characters.');
+}
+export function positiveInteger(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value > 0 ? value : undefined;
+}
+export function resolveMaxFrameBytes(value) {
+    const requested = positiveInteger(value) || LOCAL_AGENT_HOST_DEFAULT_MAX_FRAME_BYTES;
+    if (requested > LOCAL_AGENT_HOST_ABSOLUTE_MAX_FRAME_BYTES) {
+        throw new Error(`Local Agent host RPC frame limit cannot exceed ${LOCAL_AGENT_HOST_ABSOLUTE_MAX_FRAME_BYTES} bytes.`);
+    }
+    return requested;
+}
+function isProtocolErrorCode(value) {
+    return value === 'invalid_handshake'
+        || value === 'protocol_mismatch'
+        || value === 'surface_mismatch'
+        || value === 'not_connected'
+        || value === 'invalid_response';
+}
+export function asError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function isNodeError(error, code) {
+    return error instanceof Error && 'code' in error && error.code === code;
+}
+//# sourceMappingURL=transport.js.map

package/dist/local/transport.js.map

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

package/dist/localAttach.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Attaching to a per-user Agent host — the SURFACE side of ADE §2.7.
+ *
+ * 🔴 `attachToLocalAgentHost` attaches or refuses; it can never become the host. There is no
+ * `createHostTransport` parameter, so there is nothing it could construct even if asked — the
+ * dangerous shape (a CLI started while no app is running WINS the lease and is then expected to
+ * *be* the host) is unrepresentable rather than merely forbidden.
+ *
+ * That property is why this file can live in a publishable package at all: everything here is
+ * what a thin client legitimately needs, and nothing here can take ownership. Acquisition and the
+ * host authority stay in the private `packages/host`.
+ */
+import { type LocalAgentHostLeaseDescriptor } from './localLease.js';
+import { LocalAgentHostRpcClientTransport } from './localTransport.js';
+/**
+ * 🔴 STRUCTURAL, not the concrete server/lease classes.
+ *
+ * The session only ever closes the server and releases or heartbeats the lease — three calls.
+ * Typing those fields as the host's concrete `LocalAgentHostRpcServer` and `LocalAgentHostLease`
+ * dragged the whole server implementation into this file, which is what kept the session
+ * unpublishable. Naming the three calls it actually makes decouples it, and the host's real
+ * classes satisfy these by shape with no adapter.
+ */
+export interface ClosableAuthorityServer {
+    close(): Promise<void>;
+}
+export interface RenewableAuthorityLease {
+    release(): Promise<unknown>;
+    heartbeat(): Promise<unknown>;
+}
+export type LocalAgentHostAuthorityRole = 'owner' | 'attached-client';
+export declare class LocalAgentHostAuthoritySession {
+    readonly role: LocalAgentHostAuthorityRole;
+    readonly descriptor: LocalAgentHostLeaseDescriptor;
+    readonly transport: LocalAgentHostRpcClientTransport;
+    private readonly server;
+    private readonly lease;
+    private readonly onAuthorityLost;
+    private heartbeatTimer;
+    private heartbeatPending;
+    private closed;
+    constructor(options: {
+        role: LocalAgentHostAuthorityRole;
+        descriptor: LocalAgentHostLeaseDescriptor;
+        transport: LocalAgentHostRpcClientTransport;
+        server?: ClosableAuthorityServer;
+        lease?: RenewableAuthorityLease;
+        heartbeatIntervalMs?: number;
+        onAuthorityLost?: (error: Error) => void;
+    });
+    close(): Promise<void>;
+    private heartbeat;
+}
+/**
+ * Elects the one local authority. Only the elected owner invokes
+ * createHostTransport; every other process attaches to its authenticated RPC
+ * endpoint, which prevents duplicate provider processes and split-brain state.
+ */
+/**
+ * Why a surface could not attach. The REASON, not a boolean.
+ *
+ * 🔴 A CLI needs to tell its user what to do next, and "could not connect"
+ * does not. "No host is running" means start the app; "protocol mismatch" means
+ * the two builds disagree and one needs updating; "unreachable" means a host
+ * claims to be there and is not answering, which is a different problem again.
+ * Collapsing them sends a person to fix the wrong thing.
+ */
+export type AttachLocalAgentHostRefusal = {
+    reason: 'no-host';
+    detail: string;
+} | {
+    reason: 'host-gone';
+    detail: string;
+} | {
+    reason: 'protocol-mismatch';
+    detail: string;
+    hostProtocol: number;
+    clientProtocol: number;
+} | {
+    reason: 'unreachable';
+    detail: string;
+};
+export type AttachLocalAgentHostResult = {
+    attached: true;
+    session: LocalAgentHostAuthoritySession;
+} | ({
+    attached: false;
+} & AttachLocalAgentHostRefusal);
+export interface AttachToLocalAgentHostOptions {
+    rootDirectory: string;
+    protocolVersion?: number;
+    connectTimeoutMs?: number;
+    requestTimeoutMs?: number;
+    /** Injected for tests; production reads the real clock and process table. */
+    now?: () => number;
+    staleAfterMs?: number;
+    isProcessAlive?: (pid: number) => boolean;
+}
+/**
+ * Attach to a host someone else owns — and NEVER become one.
+ *
+ * 🔴 This exists because `startLocalAgentHostAuthority` is acquire-or-attach,
+ * and for a surface that is the wrong shape in the most dangerous way: a CLI
+ * started while no app is running would WIN the lease and then be asked to
+ * build a host, which a thin client has no business owning. ADE §2.7 is
+ * explicit that `xeno-agent-cli` "becomes a client of the same per-user host";
+ * a client that can silently become the server is not that.
+ *
+ * 🔴 The defect is made UNREPRESENTABLE rather than documented: there is no
+ * `createHostTransport` parameter here, so there is nothing this function could
+ * construct even if it wanted to. It inspects, it connects, or it refuses with
+ * a reason.
+ */
+export declare function attachToLocalAgentHost(options: AttachToLocalAgentHostOptions): Promise<AttachLocalAgentHostResult>;
+export declare function connectBeforeDeadline(transport: LocalAgentHostRpcClientTransport, timeoutMs: number): Promise<void>;
+//# sourceMappingURL=localAttach.d.ts.map

package/dist/localAttach.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"localAttach.d.ts","sourceRoot":"","sources":["../src/localAttach.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,OAAO,EAIL,KAAK,6BAA6B,EACnC,MAAM,iBAAiB,CAAA;AACxB,OAAO,EACL,gCAAgC,EAGjC,MAAM,qBAAqB,CAAA;AAE5B;;;;;;;;GAQG;AACH,MAAM,WAAW,uBAAuB;IACtC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACvB;AAED,MAAM,WAAW,uBAAuB;IAItC,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,CAAA;IAC3B,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC,CAAA;CAC9B;AAGD,MAAM,MAAM,2BAA2B,GAAG,OAAO,GAAG,iBAAiB,CAAA;AAErE,qBAAa,8BAA8B;IACzC,QAAQ,CAAC,IAAI,EAAE,2BAA2B,CAAA;IAC1C,QAAQ,CAAC,UAAU,EAAE,6BAA6B,CAAA;IAClD,QAAQ,CAAC,SAAS,EAAE,gCAAgC,CAAA;IACpD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqC;IAC5D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqC;IAC3D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAsC;IACtE,OAAO,CAAC,cAAc,CAA4C;IAClE,OAAO,CAAC,gBAAgB,CAAQ;IAChC,OAAO,CAAC,MAAM,CAAQ;gBAEV,OAAO,EAAE;QACnB,IAAI,EAAE,2BAA2B,CAAA;QACjC,UAAU,EAAE,6BAA6B,CAAA;QACzC,SAAS,EAAE,gCAAgC,CAAA;QAC3C,MAAM,CAAC,EAAE,uBAAuB,CAAA;QAChC,KAAK,CAAC,EAAE,uBAAuB,CAAA;QAC/B,mBAAmB,CAAC,EAAE,MAAM,CAAA;QAC5B,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAA;KACzC;IAaK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAYd,SAAS;CAaxB;AAED;;;;GAIG;AACH;;;;;;;;GAQG;AACH,MAAM,MAAM,2BAA2B,GACnC;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACvC;IAAE,MAAM,EAAE,mBAAmB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,GAC7F;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAE7C,MAAM,MAAM,0BAA0B,GAClC;IAAE,QAAQ,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,8BAA8B,CAAA;CAAE,GAC3D,CAAC;IAAE,QAAQ,EAAE,KAAK,CAAA;CAAE,GAAG,2BAA2B,CAAC,CAAA;AAEvD,MAAM,WAAW,6BAA6B;IAC5C,aAAa,EAAE,MAAM,CAAA;IACrB,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,6EAA6E;IAC7E,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAClB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAA;CAC1C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,0BAA0B,CAAC,CAgFrC;AAGD,wBAAsB,qBAAqB,CACzC,SAAS,EAAE,gCAAgC,EAC3C,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAcf"}

package/dist/localAttach.js

@@ -0,0 +1,187 @@
+/**
+ * Attaching to a per-user Agent host — the SURFACE side of ADE §2.7.
+ *
+ * 🔴 `attachToLocalAgentHost` attaches or refuses; it can never become the host. There is no
+ * `createHostTransport` parameter, so there is nothing it could construct even if asked — the
+ * dangerous shape (a CLI started while no app is running WINS the lease and is then expected to
+ * *be* the host) is unrepresentable rather than merely forbidden.
+ *
+ * That property is why this file can live in a publishable package at all: everything here is
+ * what a thin client legitimately needs, and nothing here can take ownership. Acquisition and the
+ * host authority stay in the private `packages/host`.
+ */
+import { XENO_AGENT_HOST_PROTOCOL_VERSION, } from '@xenosystem/agent-interface-contract';
+import { inspectLocalAgentHostLease, isLeaseOwnerGone, readLocalAgentHostLeaseConnection, } from './localLease.js';
+import { LocalAgentHostRpcClientTransport, positiveInteger, resolveLocalAgentHostEndpoint, } from './localTransport.js';
+export class LocalAgentHostAuthoritySession {
+    role;
+    descriptor;
+    transport;
+    server;
+    lease;
+    onAuthorityLost;
+    heartbeatTimer;
+    heartbeatPending = false;
+    closed = false;
+    constructor(options) {
+        this.role = options.role;
+        this.descriptor = { ...options.descriptor };
+        this.transport = options.transport;
+        this.server = options.server;
+        this.lease = options.lease;
+        this.onAuthorityLost = options.onAuthorityLost;
+        if (this.lease && options.heartbeatIntervalMs) {
+            this.heartbeatTimer = setInterval(() => { void this.heartbeat(); }, options.heartbeatIntervalMs);
+            this.heartbeatTimer.unref?.();
+        }
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = undefined;
+        }
+        this.transport.close();
+        await this.server?.close();
+        await this.lease?.release();
+    }
+    async heartbeat() {
+        if (this.closed || this.heartbeatPending || !this.lease)
+            return;
+        this.heartbeatPending = true;
+        try {
+            await this.lease.heartbeat();
+        }
+        catch (error) {
+            const failure = asError(error);
+            await this.close().catch(() => undefined);
+            this.onAuthorityLost?.(failure);
+        }
+        finally {
+            this.heartbeatPending = false;
+        }
+    }
+}
+/**
+ * Attach to a host someone else owns — and NEVER become one.
+ *
+ * 🔴 This exists because `startLocalAgentHostAuthority` is acquire-or-attach,
+ * and for a surface that is the wrong shape in the most dangerous way: a CLI
+ * started while no app is running would WIN the lease and then be asked to
+ * build a host, which a thin client has no business owning. ADE §2.7 is
+ * explicit that `xeno-agent-cli` "becomes a client of the same per-user host";
+ * a client that can silently become the server is not that.
+ *
+ * 🔴 The defect is made UNREPRESENTABLE rather than documented: there is no
+ * `createHostTransport` parameter here, so there is nothing this function could
+ * construct even if it wanted to. It inspects, it connects, or it refuses with
+ * a reason.
+ */
+export async function attachToLocalAgentHost(options) {
+    const protocolVersion = positiveInteger(options.protocolVersion) || XENO_AGENT_HOST_PROTOCOL_VERSION;
+    const connectTimeoutMs = positiveInteger(options.connectTimeoutMs) || 5_000;
+    const requestTimeoutMs = positiveInteger(options.requestTimeoutMs) || 30_000;
+    const descriptor = await inspectLocalAgentHostLease(options.rootDirectory);
+    if (!descriptor) {
+        return {
+            attached: false,
+            reason: 'no-host',
+            detail: 'No XENO Agent host is running for this user. Start the Agent app, or run the host detached.',
+        };
+    }
+    // 🔴 The SAME staleness rule the acquire path uses — imported, not restated.
+    // A crashed owner leaves its lock file behind, and connecting to it would
+    // hang until the transport timed out with "unreachable", which reads as a
+    // network fault rather than a host that is simply gone.
+    if (isLeaseOwnerGone({
+        heartbeatAt: descriptor.heartbeatAt,
+        pid: descriptor.pid,
+        at: (options.now || Date.now)(),
+        ...(options.staleAfterMs === undefined ? {} : { staleAfterMs: options.staleAfterMs }),
+        ...(options.isProcessAlive ? { isProcessAlive: options.isProcessAlive } : {}),
+    })) {
+        return {
+            attached: false,
+            reason: 'host-gone',
+            detail: `The recorded Agent host (pid ${descriptor.pid}) is no longer running. Start the Agent app again.`,
+        };
+    }
+    if (descriptor.protocolVersion !== protocolVersion) {
+        return {
+            attached: false,
+            reason: 'protocol-mismatch',
+            hostProtocol: descriptor.protocolVersion,
+            clientProtocol: protocolVersion,
+            detail: `The running Agent host speaks protocol ${descriptor.protocolVersion} and this client speaks ${protocolVersion}. Update whichever is older.`,
+        };
+    }
+    const connection = await readLocalAgentHostLeaseConnection(options.rootDirectory);
+    if (!connection || connection.descriptor.instanceId !== descriptor.instanceId) {
+        // The host restarted between the inspection and the read. Refusing beats
+        // connecting to a different instance than the one just vetted.
+        return {
+            attached: false,
+            reason: 'unreachable',
+            detail: 'The Agent host changed while connecting. Retry.',
+        };
+    }
+    const transport = new LocalAgentHostRpcClientTransport({
+        endpoint: connection.descriptor.endpoint,
+        transportToken: connection.transportToken,
+        protocolVersion,
+        requestTimeoutMs,
+    });
+    try {
+        await connectBeforeDeadline(transport, connectTimeoutMs);
+    }
+    catch (error) {
+        transport.close();
+        return {
+            attached: false,
+            reason: 'unreachable',
+            detail: error instanceof Error ? error.message : String(error),
+        };
+    }
+    return {
+        attached: true,
+        session: new LocalAgentHostAuthoritySession({
+            // Always a client. There is no branch here that produces an owner, which
+            // is the property this function exists to guarantee.
+            role: 'attached-client',
+            descriptor: connection.descriptor,
+            transport,
+        }),
+    };
+}
+export async function connectBeforeDeadline(transport, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    let lastError;
+    do {
+        try {
+            await transport.connect();
+            return;
+        }
+        catch (error) {
+            lastError = asError(error);
+            if (!isRetryableConnectionError(lastError) || Date.now() >= deadline)
+                break;
+            await delay(Math.min(50, Math.max(1, deadline - Date.now())));
+        }
+    } while (Date.now() < deadline);
+    throw lastError || new Error('Unable to connect to the local Agent host authority.');
+}
+function isRetryableConnectionError(error) {
+    if (!('code' in error))
+        return false;
+    const code = error.code;
+    return code === 'ENOENT' || code === 'ECONNREFUSED' || code === 'EPIPE';
+}
+function delay(milliseconds) {
+    return new Promise((resolveDelay) => setTimeout(resolveDelay, milliseconds));
+}
+function asError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+//# sourceMappingURL=localAttach.js.map

package/dist/localAttach.js.map

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

package/dist/localLease.d.ts

@@ -0,0 +1,50 @@
+export interface LocalAgentHostLeaseDescriptor {
+    schemaVersion: 1;
+    instanceId: string;
+    pid: number;
+    endpoint: string;
+    protocolVersion: number;
+    acquiredAt: number;
+    heartbeatAt: number;
+}
+export interface LocalAgentHostLeaseConnectionInfo {
+    descriptor: LocalAgentHostLeaseDescriptor;
+    /** Sensitive same-user bearer credential. Never expose this to a renderer or diagnostic export. */
+    transportToken: string;
+}
+export interface LocalAgentHostLeaseRecord extends LocalAgentHostLeaseDescriptor {
+    transportToken: string;
+}
+export declare const DEFAULT_LEASE_STALE_AFTER_MS = 15000;
+/**
+ * Is the recorded owner gone?
+ *
+ * 🔴 TWO conditions, and the second is the one that matters. A missed
+ * heartbeat alone does not mean a dead host — a process paused by a debugger,
+ * a laptop resumed from sleep, or a machine under load all produce one. Taking
+ * the lease from a LIVE owner is the split-brain the lease exists to prevent,
+ * so the pid must also be gone.
+ *
+ * Exported and shared because a second caller now needs the same question
+ * answered without acquiring anything: a surface deciding whether a host is
+ * actually there. Two spellings of "is the owner dead" would eventually
+ * disagree, and the two answers are "take over" and "connect".
+ */
+export declare function isLeaseOwnerGone(input: {
+    heartbeatAt: number;
+    pid: number;
+    at: number;
+    staleAfterMs?: number;
+    isProcessAlive?: (pid: number) => boolean;
+}): boolean;
+export declare function inspectLocalAgentHostLease(rootDirectory: string): Promise<LocalAgentHostLeaseDescriptor | null>;
+/**
+ * Reads connection material for another trusted main/host process owned by the
+ * same OS user. Callers must keep the token outside renderers, logs, and IPC.
+ */
+export declare function readLocalAgentHostLeaseConnection(rootDirectory: string): Promise<LocalAgentHostLeaseConnectionInfo | null>;
+export declare function readLeaseRecord(path: string): Promise<LocalAgentHostLeaseRecord>;
+export declare function parseLeaseRecord(value: string): LocalAgentHostLeaseRecord;
+export declare function publicDescriptor(record: LocalAgentHostLeaseRecord): LocalAgentHostLeaseDescriptor;
+export declare function defaultProcessAlive(pid: number): boolean;
+//# sourceMappingURL=localLease.d.ts.map