@xenosystem/agent-interface-host 0.1.3

package/dist/isolation/SandboxCommandExecutor.js

@@ -0,0 +1,189 @@
+/**
+ * `CommandExecutionPort` over a `xeno-use` sandbox — the CONFINING implementation.
+ *
+ * Reached through `RunExecutionEnvironment`, which is what a composition wires
+ * and what decides — in ONE lookup — both that this executor serves a run and
+ * that the run reports `sandboxed`. Nothing constructs this directly.
+ *
+ * ⚠️ What remains before a run is actually confined is the BINDING: no
+ * composition yet spawns a sandbox the agent RUNS in. `XenoUseRunObserver`
+ * spawns an OBSERVATION sandbox, and binding execution to that one is exactly
+ * the convenient wrong turn `isolationIsNotObservation.test.ts` exists to pin —
+ * a sandbox that is watched is not a sandbox that confines. Everything
+ * downstream of the binding is now live, so that step is a spawn plus a
+ * `bind({ sandbox })`, not a rewrite.
+ *
+ * This is the other half of the port `LocalCommandExecutor` exists beside, and
+ * the reason the port was built at all: adopting a sandbox becomes a composition
+ * change rather than a rewrite at each call site. Where the local executor
+ * starts a real process on the user's machine as the signed-in user, this one
+ * runs the command inside a container with `--network none`, `--read-only`,
+ * `--cap-drop ALL`, a non-root uid, and only the mounts it was given.
+ *
+ * ## 🔒 Out of process, always — a licensing boundary before a design preference
+ *
+ * `xeno-use` is AGPL-3.0 and this package is proprietary, so nothing here
+ * imports `@xeno-use/*` or links its N-API binding. The request and response
+ * shapes are written out by hand and reached over `/v1/use/*` — exactly what
+ * `RunObservationSource` and `XenoUseRunObserver` already do, for exactly the
+ * same reason. It looks like duplication and is the boundary.
+ *
+ * ## 🔴 It NEVER falls back to local execution
+ *
+ * The single most important property in this file, and the one most likely to
+ * be "fixed" in later. If the sandbox is unreachable, this returns a FAILED
+ * result — it does not quietly run the command on the host instead. A fallback
+ * would mean a run reporting itself contained while executing with the user's
+ * full privileges, which is strictly worse than having no sandbox at all:
+ * without one the report says `none` and the user knows where they stand.
+ *
+ * Same shape as the convenient wrong turn `isolationIsNotObservation.test.ts`
+ * pins one directory over. A sandbox that is watched is not a sandbox that
+ * confines; a sandbox that silently degrades to the host does not confine
+ * either, and lies about it.
+ *
+ * ## Why the executor is bound to ONE sandbox
+ *
+ * `CommandExecutionRequest` carries no run id, deliberately — a call site asks
+ * to run a command, not to route one. So the binding happens at construction:
+ * the composition makes an executor per run, against that run's sandbox. A
+ * resolver taking a run id would put routing in the hot path and make "which
+ * sandbox did this actually run in?" a question with a computed answer.
+ */
+const DEFAULT_MAX_OUTPUT_BYTES = 200_000;
+/**
+ * Maps a host path into container terms.
+ *
+ * Returns `undefined` when the path is not under the mount — which is not a
+ * security check. Confinement comes from the sandbox's filesystem namespace,
+ * not from a rule applied at the call: a process can `chdir` after it starts,
+ * so a path rule enforced on entry decides nothing. This is a REPRESENTABILITY
+ * question — a host directory outside the mount has no name inside the
+ * container, so the request cannot be expressed and must be refused rather than
+ * silently rewritten to the mount root.
+ *
+ * Case-insensitive on the host segment because Windows paths are, and the run
+ * directory reaching us from a UI and from a config may differ only in case.
+ * The CONTAINER half preserves case exactly — Linux paths are case-sensitive
+ * and folding them would produce a path that does not exist.
+ */
+export function toContainerPath(mount, hostPath) {
+    const normalize = (value) => value.replaceAll('\\', '/').replace(/\/+$/, '');
+    const root = normalize(mount.hostDirectory);
+    const target = normalize(hostPath);
+    const container = normalize(mount.containerDirectory);
+    if (target.toLowerCase() === root.toLowerCase())
+        return container;
+    const prefix = `${root.toLowerCase()}/`;
+    if (!target.toLowerCase().startsWith(prefix))
+        return undefined;
+    // Slice from the ORIGINAL, not the lowercased copy: the remainder names real
+    // files inside a Linux container, where `Source_File.ts` and `source_file.ts`
+    // are different files.
+    return `${container}/${target.slice(root.length + 1)}`;
+}
+export class SandboxCommandExecutor {
+    #baseUrl;
+    #token;
+    #sandboxId;
+    #mount;
+    #fetch;
+    constructor(options) {
+        this.#baseUrl = options.baseUrl.replace(/\/+$/, '');
+        this.#token = options.token;
+        this.#sandboxId = options.sandboxId;
+        this.#mount = options.mount;
+        this.#fetch = options.fetch ?? globalThis.fetch;
+    }
+    async execute(request) {
+        const cwd = toContainerPath(this.#mount, request.cwd);
+        if (cwd === undefined) {
+            // Refused, not rewritten. Running in the mount root "because the real cwd
+            // was outside it" would execute a command somewhere the caller never
+            // asked for, and it would look like it worked.
+            return this.#failed(`The working directory ${request.cwd} is not inside the sandbox mount ${this.#mount.hostDirectory}.`);
+        }
+        let response;
+        try {
+            response = await this.#fetch(`${this.#baseUrl}/v1/use/sandbox/${encodeURIComponent(this.#sandboxId)}/exec`, {
+                method: 'POST',
+                headers: {
+                    authorization: `Bearer ${this.#token}`,
+                    'content-type': 'application/json',
+                },
+                body: JSON.stringify({
+                    // A LIST, unchanged. The port and the substrate agree on this, so
+                    // there is nothing to translate — which is the point of both.
+                    argv: [...request.argv],
+                    cwd,
+                    timeout_ms: request.timeoutMs,
+                }),
+            });
+        }
+        catch (error) {
+            // 🔴 The sandbox is unreachable. This is where a fallback to local
+            // execution would go, and where it must not.
+            return this.#failed(`The sandbox could not be reached: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (!response.ok) {
+            return this.#failed(`The sandbox refused to run the command (HTTP ${response.status}).`);
+        }
+        let wire;
+        try {
+            const body = (await response.json());
+            if (!body.data)
+                throw new Error('the response carried no result');
+            wire = body.data;
+        }
+        catch (error) {
+            return this.#failed(`The sandbox returned an unreadable result: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const outputLimit = request.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
+        const { stdout, stderr, truncated } = trim(wire.stdout, wire.stderr, outputLimit);
+        return {
+            stdout,
+            stderr,
+            // 🔴 Passed through INCLUDING null, exactly as the local executor does.
+            // The substrate already refuses to invent a code for a killed process;
+            // coercing here would throw that honesty away at the last hop.
+            exitCode: wire.exit_code,
+            timedOut: wire.timed_out,
+            truncated,
+            ...(wire.timed_out
+                ? { error: `Command timed out after ${request.timeoutMs}ms.` }
+                : {}),
+        };
+    }
+    /**
+     * A result for a command that could not be run.
+     *
+     * `exitCode: null` because there is no exit code — the same meaning it
+     * carries everywhere on this type — and `error` is what distinguishes this
+     * from a process that was killed. `commandSucceeded` answers false on both
+     * counts, so no caller can read an unreachable sandbox as a passing command.
+     */
+    #failed(reason) {
+        return {
+            stdout: '',
+            stderr: '',
+            exitCode: null,
+            timedOut: false,
+            truncated: false,
+            error: reason,
+        };
+    }
+}
+/** Bounds the output the same way the local executor does, so a caller cannot
+ *  tell the two apart by how much it gets back. */
+function trim(rawStdout, rawStderr, limit) {
+    if (rawStdout.length + rawStderr.length <= limit) {
+        return { stdout: rawStdout, stderr: rawStderr, truncated: false };
+    }
+    const keep = Math.max(4_000, Math.floor(limit / 2));
+    return {
+        stdout: rawStdout.slice(-keep),
+        stderr: rawStderr.slice(-keep),
+        truncated: true,
+    };
+}
+//# sourceMappingURL=SandboxCommandExecutor.js.map

package/dist/isolation/SandboxCommandExecutor.js.map

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

package/dist/knowledge/WorkspaceKnowledgeService.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Workspace knowledge — ADE §5.8, the host half.
+ *
+ * `core/workspaceKnowledge` owns the rules; this owns the store. Facts are
+ * per-workspace and DURABLE by intent: §5.8's whole point is that a session
+ * ending does not undo what the workspace learned.
+ *
+ * ## 🔴 Recording is idempotent on (workspace, subject, fact)
+ *
+ * An agent that re-establishes a fact it already knows — because it re-read the
+ * same file, or because a retry replayed the turn — must not create a second
+ * copy. Without this, "we use pnpm" accumulates once per run and eventually
+ * fills the whole prompt budget with the same sentence, pushing out everything
+ * else. The identical fact re-recorded returns the ORIGINAL entry, so its
+ * provenance still names the run that first established it.
+ *
+ * ## Persistence is injected
+ *
+ * The store is a port. In-memory is the honest default for a host with nothing
+ * configured — the alternative, silently writing somewhere, is how knowledge
+ * ends up in a directory nobody knows to back up.
+ */
+import { type KnowledgeSelectionOptions, type WorkspaceKnowledgeEntry } from '@xenosystem/agent-interface-core';
+/** Where facts live between sessions. */
+export interface WorkspaceKnowledgeStore {
+    load(workspaceId: string): Promise<WorkspaceKnowledgeEntry[]> | WorkspaceKnowledgeEntry[];
+    save(workspaceId: string, entries: WorkspaceKnowledgeEntry[]): Promise<void> | void;
+}
+/** The default: remembers for this process and says nothing about durability. */
+export declare class InMemoryWorkspaceKnowledgeStore implements WorkspaceKnowledgeStore {
+    #private;
+    load(workspaceId: string): WorkspaceKnowledgeEntry[];
+    save(workspaceId: string, entries: WorkspaceKnowledgeEntry[]): void;
+}
+export interface RecordKnowledgeInput {
+    workspaceId: string;
+    subject: string;
+    fact: string;
+    pinned?: boolean;
+    runId: string;
+    providerId?: string;
+}
+export interface WorkspaceKnowledgeServiceOptions {
+    store?: WorkspaceKnowledgeStore;
+    now?: () => number;
+    /** Injected so ids are deterministic in tests rather than random. */
+    nextId?: () => string;
+    /** True when the configured store survives a restart. Reported, never assumed:
+     *  a surface promising durable memory over an in-memory store would be lying. */
+    durable?: boolean;
+}
+export declare class WorkspaceKnowledgeService {
+    #private;
+    constructor(options?: WorkspaceKnowledgeServiceOptions);
+    get durable(): boolean;
+    list(workspaceId: string): Promise<WorkspaceKnowledgeEntry[]>;
+    /**
+     * Establishes a fact.
+     *
+     * Returns the entry, which may be one that already existed — see the header:
+     * the same fact recorded twice keeps the FIRST provenance, because the run
+     * that discovered it is the interesting one.
+     */
+    record(input: RecordKnowledgeInput): Promise<WorkspaceKnowledgeEntry>;
+    /** Removes a fact outright. Superseding is what happens naturally; this is for
+     *  a fact that was simply WRONG, which no later truth supersedes. */
+    forget(workspaceId: string, entryId: string): Promise<boolean>;
+    /** What should go into a prompt for this workspace. */
+    context(workspaceId: string, options?: KnowledgeSelectionOptions): Promise<import("@xenosystem/agent-interface-core").KnowledgeSelection>;
+}
+//# sourceMappingURL=WorkspaceKnowledgeService.d.ts.map

package/dist/knowledge/WorkspaceKnowledgeService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkspaceKnowledgeService.d.ts","sourceRoot":"","sources":["../../src/knowledge/WorkspaceKnowledgeService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAEL,KAAK,yBAAyB,EAC9B,KAAK,uBAAuB,EAC7B,MAAM,kCAAkC,CAAA;AAEzC,yCAAyC;AACzC,MAAM,WAAW,uBAAuB;IACtC,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,EAAE,CAAC,GAAG,uBAAuB,EAAE,CAAA;IACzF,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,uBAAuB,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;CACpF;AAED,iFAAiF;AACjF,qBAAa,+BAAgC,YAAW,uBAAuB;;IAG7E,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,uBAAuB,EAAE;IAIpD,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,uBAAuB,EAAE,GAAG,IAAI;CAGpE;AAED,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,gCAAgC;IAC/C,KAAK,CAAC,EAAE,uBAAuB,CAAA;IAC/B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAClB,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,MAAM,CAAA;IACrB;qFACiF;IACjF,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,qBAAa,yBAAyB;;gBAOxB,OAAO,GAAE,gCAAqC;IAS1D,IAAI,OAAO,IAAI,OAAO,CAErB;IAEK,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,EAAE,CAAC;IAInE;;;;;;OAMG;IACG,MAAM,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,uBAAuB,CAAC;IA+B3E;yEACqE;IAC/D,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAQpE,uDAAuD;IACjD,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,yBAA8B;CAG3E"}

package/dist/knowledge/WorkspaceKnowledgeService.js

@@ -0,0 +1,103 @@
+/**
+ * Workspace knowledge — ADE §5.8, the host half.
+ *
+ * `core/workspaceKnowledge` owns the rules; this owns the store. Facts are
+ * per-workspace and DURABLE by intent: §5.8's whole point is that a session
+ * ending does not undo what the workspace learned.
+ *
+ * ## 🔴 Recording is idempotent on (workspace, subject, fact)
+ *
+ * An agent that re-establishes a fact it already knows — because it re-read the
+ * same file, or because a retry replayed the turn — must not create a second
+ * copy. Without this, "we use pnpm" accumulates once per run and eventually
+ * fills the whole prompt budget with the same sentence, pushing out everything
+ * else. The identical fact re-recorded returns the ORIGINAL entry, so its
+ * provenance still names the run that first established it.
+ *
+ * ## Persistence is injected
+ *
+ * The store is a port. In-memory is the honest default for a host with nothing
+ * configured — the alternative, silently writing somewhere, is how knowledge
+ * ends up in a directory nobody knows to back up.
+ */
+import { selectWorkspaceKnowledge, } from '@xenosystem/agent-interface-core';
+/** The default: remembers for this process and says nothing about durability. */
+export class InMemoryWorkspaceKnowledgeStore {
+    #byWorkspace = new Map();
+    load(workspaceId) {
+        return [...(this.#byWorkspace.get(workspaceId) ?? [])];
+    }
+    save(workspaceId, entries) {
+        this.#byWorkspace.set(workspaceId, [...entries]);
+    }
+}
+export class WorkspaceKnowledgeService {
+    #store;
+    #now;
+    #nextId;
+    #durable;
+    #sequence = 0;
+    constructor(options = {}) {
+        this.#store = options.store ?? new InMemoryWorkspaceKnowledgeStore();
+        this.#now = options.now ?? (() => Date.now());
+        this.#nextId = options.nextId ?? (() => `k${++this.#sequence}`);
+        // Defaults to FALSE with the default store, because the default store is
+        // not durable. Claiming otherwise is the failure this flag exists to stop.
+        this.#durable = options.durable ?? Boolean(options.store);
+    }
+    get durable() {
+        return this.#durable;
+    }
+    async list(workspaceId) {
+        return [...(await this.#store.load(workspaceId))];
+    }
+    /**
+     * Establishes a fact.
+     *
+     * Returns the entry, which may be one that already existed — see the header:
+     * the same fact recorded twice keeps the FIRST provenance, because the run
+     * that discovered it is the interesting one.
+     */
+    async record(input) {
+        const entries = await this.list(input.workspaceId);
+        const existing = entries.find((entry) => entry.subject === input.subject && entry.fact === input.fact);
+        if (existing) {
+            // Pinning an existing fact is a real update rather than a duplicate: it
+            // changes how the fact behaves under budget without changing the fact.
+            if (input.pinned && !existing.pinned) {
+                existing.pinned = true;
+                await this.#store.save(input.workspaceId, entries);
+            }
+            return existing;
+        }
+        const entry = {
+            id: this.#nextId(),
+            workspaceId: input.workspaceId,
+            subject: input.subject,
+            fact: input.fact,
+            ...(input.pinned ? { pinned: true } : {}),
+            provenance: {
+                runId: input.runId,
+                ...(input.providerId ? { providerId: input.providerId } : {}),
+                at: this.#now(),
+            },
+        };
+        await this.#store.save(input.workspaceId, [...entries, entry]);
+        return entry;
+    }
+    /** Removes a fact outright. Superseding is what happens naturally; this is for
+     *  a fact that was simply WRONG, which no later truth supersedes. */
+    async forget(workspaceId, entryId) {
+        const entries = await this.list(workspaceId);
+        const remaining = entries.filter((entry) => entry.id !== entryId);
+        if (remaining.length === entries.length)
+            return false;
+        await this.#store.save(workspaceId, remaining);
+        return true;
+    }
+    /** What should go into a prompt for this workspace. */
+    async context(workspaceId, options = {}) {
+        return selectWorkspaceKnowledge(await this.list(workspaceId), options);
+    }
+}
+//# sourceMappingURL=WorkspaceKnowledgeService.js.map

package/dist/knowledge/WorkspaceKnowledgeService.js.map

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

package/dist/localHostAuthority.d.ts

@@ -0,0 +1,24 @@
+import { type AgentHostTransport } from '@xenosystem/agent-interface-contract';
+import { LocalAgentHostAuthoritySession } from '@xenosystem/agent-interface-client/local';
+/**
+ * Becoming the per-user Agent host authority — the half a surface must not have.
+ *
+ * Attaching moved to `@xenosystem/agent-interface-client` (ADE §2.7). Acquiring the
+ * lease and serving the host stays here, in the private package, so a thin client cannot take
+ * ownership: the code to do it is in a package it does not depend on.
+ */
+export interface StartLocalAgentHostAuthorityOptions {
+    rootDirectory: string;
+    instanceId: string;
+    createHostTransport: () => AgentHostTransport | Promise<AgentHostTransport>;
+    protocolVersion?: number;
+    endpointScope?: string;
+    staleAfterMs?: number;
+    heartbeatIntervalMs?: number;
+    connectTimeoutMs?: number;
+    requestTimeoutMs?: number;
+    onAuthorityLost?: (error: Error) => void;
+}
+export declare function startLocalAgentHostAuthority(options: StartLocalAgentHostAuthorityOptions): Promise<LocalAgentHostAuthoritySession>;
+export { attachToLocalAgentHost, LocalAgentHostAuthoritySession, type AttachToLocalAgentHostOptions, type AttachLocalAgentHostResult, type AttachLocalAgentHostRefusal, type LocalAgentHostAuthorityRole, } from '@xenosystem/agent-interface-client/local';
+//# sourceMappingURL=localHostAuthority.d.ts.map

package/dist/localHostAuthority.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"localHostAuthority.d.ts","sourceRoot":"","sources":["../src/localHostAuthority.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,sCAAsC,CAAA;AAC7C,OAAO,EACL,8BAA8B,EAK/B,MAAM,0CAA0C,CAAA;AAIjD;;;;;;GAMG;AAEH,MAAM,WAAW,mCAAmC;IAClD,aAAa,EAAE,MAAM,CAAA;IACrB,UAAU,EAAE,MAAM,CAAA;IAClB,mBAAmB,EAAE,MAAM,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAA;IAC3E,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAA;CACzC;AACD,wBAAsB,4BAA4B,CAChD,OAAO,EAAE,mCAAmC,GAC3C,OAAO,CAAC,8BAA8B,CAAC,CAkFzC;AAGD,OAAO,EACL,sBAAsB,EACtB,8BAA8B,EAC9B,KAAK,6BAA6B,EAClC,KAAK,0BAA0B,EAC/B,KAAK,2BAA2B,EAChC,KAAK,2BAA2B,GACjC,MAAM,0CAA0C,CAAA"}

package/dist/localHostAuthority.js

@@ -0,0 +1,87 @@
+import { XENO_AGENT_HOST_PROTOCOL_VERSION, } from '@xenosystem/agent-interface-contract';
+import { LocalAgentHostAuthoritySession, LocalAgentHostRpcClientTransport, connectBeforeDeadline, positiveInteger, readLocalAgentHostLeaseConnection, } from '@xenosystem/agent-interface-client/local';
+import { acquireLocalAgentHostLease } from './localHostLease.js';
+import { LocalAgentHostRpcServer, resolveLocalAgentHostEndpoint } from './localRpcTransport.js';
+export async function startLocalAgentHostAuthority(options) {
+    const protocolVersion = positiveInteger(options.protocolVersion) || XENO_AGENT_HOST_PROTOCOL_VERSION;
+    const staleAfterMs = positiveInteger(options.staleAfterMs) || 15_000;
+    const heartbeatIntervalMs = positiveInteger(options.heartbeatIntervalMs)
+        || Math.max(1_000, Math.floor(staleAfterMs / 3));
+    const connectTimeoutMs = positiveInteger(options.connectTimeoutMs) || 5_000;
+    const requestTimeoutMs = positiveInteger(options.requestTimeoutMs) || 30_000;
+    const endpoint = resolveLocalAgentHostEndpoint(options.rootDirectory, options.endpointScope || 'default');
+    const acquisition = await acquireLocalAgentHostLease({
+        rootDirectory: options.rootDirectory,
+        instanceId: options.instanceId,
+        endpoint,
+        protocolVersion,
+        staleAfterMs,
+    });
+    if (acquisition.acquired) {
+        let server;
+        let transport;
+        try {
+            const hostTransport = await options.createHostTransport();
+            server = new LocalAgentHostRpcServer({
+                transport: hostTransport,
+                endpoint,
+                transportToken: acquisition.lease.transportToken,
+                protocolVersion,
+                removeStaleEndpoint: true,
+            });
+            await server.start();
+            transport = new LocalAgentHostRpcClientTransport({
+                endpoint,
+                transportToken: acquisition.lease.transportToken,
+                protocolVersion,
+                requestTimeoutMs,
+            });
+            await connectBeforeDeadline(transport, connectTimeoutMs);
+            return new LocalAgentHostAuthoritySession({
+                role: 'owner',
+                descriptor: acquisition.lease.descriptor,
+                transport,
+                server,
+                lease: acquisition.lease,
+                heartbeatIntervalMs,
+                ...(options.onAuthorityLost ? { onAuthorityLost: options.onAuthorityLost } : {}),
+            });
+        }
+        catch (error) {
+            transport?.close();
+            await server?.close().catch(() => undefined);
+            await acquisition.lease.release().catch(() => undefined);
+            throw error;
+        }
+    }
+    if (acquisition.owner.protocolVersion !== protocolVersion) {
+        throw new Error(`Existing local Agent host protocol ${acquisition.owner.protocolVersion} is incompatible with requested ${protocolVersion}.`);
+    }
+    const connection = await readLocalAgentHostLeaseConnection(options.rootDirectory);
+    if (!connection
+        || connection.descriptor.instanceId !== acquisition.owner.instanceId
+        || connection.descriptor.endpoint !== acquisition.owner.endpoint) {
+        throw new Error('Local Agent host authority changed during connection discovery; retry startup.');
+    }
+    const transport = new LocalAgentHostRpcClientTransport({
+        endpoint: connection.descriptor.endpoint,
+        transportToken: connection.transportToken,
+        protocolVersion,
+        requestTimeoutMs,
+    });
+    try {
+        await connectBeforeDeadline(transport, connectTimeoutMs);
+    }
+    catch (error) {
+        transport.close();
+        throw error;
+    }
+    return new LocalAgentHostAuthoritySession({
+        role: 'attached-client',
+        descriptor: connection.descriptor,
+        transport,
+    });
+}
+// Re-exported so existing importers of this module are unaffected by the extraction.
+export { attachToLocalAgentHost, LocalAgentHostAuthoritySession, } from '@xenosystem/agent-interface-client/local';
+//# sourceMappingURL=localHostAuthority.js.map

package/dist/localHostAuthority.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"localHostAuthority.js","sourceRoot":"","sources":["../src/localHostAuthority.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gCAAgC,GAEjC,MAAM,sCAAsC,CAAA;AAC7C,OAAO,EACL,8BAA8B,EAC9B,gCAAgC,EAChC,qBAAqB,EACrB,eAAe,EACf,iCAAiC,GAClC,MAAM,0CAA0C,CAAA;AACjD,OAAO,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAA;AAChE,OAAO,EAAE,uBAAuB,EAAE,6BAA6B,EAAE,MAAM,wBAAwB,CAAA;AAsB/F,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAChD,OAA4C;IAE5C,MAAM,eAAe,GAAG,eAAe,CAAC,OAAO,CAAC,eAAe,CAAC,IAAI,gCAAgC,CAAA;IACpG,MAAM,YAAY,GAAG,eAAe,CAAC,OAAO,CAAC,YAAY,CAAC,IAAI,MAAM,CAAA;IACpE,MAAM,mBAAmB,GAAG,eAAe,CAAC,OAAO,CAAC,mBAAmB,CAAC;WACnE,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,YAAY,GAAG,CAAC,CAAC,CAAC,CAAA;IAClD,MAAM,gBAAgB,GAAG,eAAe,CAAC,OAAO,CAAC,gBAAgB,CAAC,IAAI,KAAK,CAAA;IAC3E,MAAM,gBAAgB,GAAG,eAAe,CAAC,OAAO,CAAC,gBAAgB,CAAC,IAAI,MAAM,CAAA;IAC5E,MAAM,QAAQ,GAAG,6BAA6B,CAAC,OAAO,CAAC,aAAa,EAAE,OAAO,CAAC,aAAa,IAAI,SAAS,CAAC,CAAA;IACzG,MAAM,WAAW,GAAG,MAAM,0BAA0B,CAAC;QACnD,aAAa,EAAE,OAAO,CAAC,aAAa;QACpC,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,QAAQ;QACR,eAAe;QACf,YAAY;KACb,CAAC,CAAA;IAEF,IAAI,WAAW,CAAC,QAAQ,EAAE,CAAC;QACzB,IAAI,MAA2C,CAAA;QAC/C,IAAI,SAAuD,CAAA;QAC3D,IAAI,CAAC;YACH,MAAM,aAAa,GAAG,MAAM,OAAO,CAAC,mBAAmB,EAAE,CAAA;YACzD,MAAM,GAAG,IAAI,uBAAuB,CAAC;gBACnC,SAAS,EAAE,aAAa;gBACxB,QAAQ;gBACR,cAAc,EAAE,WAAW,CAAC,KAAK,CAAC,cAAc;gBAChD,eAAe;gBACf,mBAAmB,EAAE,IAAI;aAC1B,CAAC,CAAA;YACF,MAAM,MAAM,CAAC,KAAK,EAAE,CAAA;YACpB,SAAS,GAAG,IAAI,gCAAgC,CAAC;gBAC/C,QAAQ;gBACR,cAAc,EAAE,WAAW,CAAC,KAAK,CAAC,cAAc;gBAChD,eAAe;gBACf,gBAAgB;aACjB,CAAC,CAAA;YACF,MAAM,qBAAqB,CAAC,SAAS,EAAE,gBAAgB,CAAC,CAAA;YACxD,OAAO,IAAI,8BAA8B,CAAC;gBACxC,IAAI,EAAE,OAAO;gBACb,UAAU,EAAE,WAAW,CAAC,KAAK,CAAC,UAAU;gBACxC,SAAS;gBACT,MAAM;gBACN,KAAK,EAAE,WAAW,CAAC,KAAK;gBACxB,mBAAmB;gBACnB,GAAG,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACjF,CAAC,CAAA;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,SAAS,EAAE,KAAK,EAAE,CAAA;YAClB,MAAM,MAAM,EAAE,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;YAC5C,MAAM,WAAW,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;YACxD,MAAM,KAAK,CAAA;QACb,CAAC;IACH,CAAC;IAED,IAAI,WAAW,CAAC,KAAK,CAAC,eAAe,KAAK,eAAe,EAAE,CAAC;QAC1D,MAAM,IAAI,KAAK,CACb,sCAAsC,WAAW,CAAC,KAAK,CAAC,eAAe,mCAAmC,eAAe,GAAG,CAC7H,CAAA;IACH,CAAC;IACD,MAAM,UAAU,GAAG,MAAM,iCAAiC,CAAC,OAAO,CAAC,aAAa,CAAC,CAAA;IACjF,IAAI,CAAC,UAAU;WACV,UAAU,CAAC,UAAU,CAAC,UAAU,KAAK,WAAW,CAAC,KAAK,CAAC,UAAU;WACjE,UAAU,CAAC,UAAU,CAAC,QAAQ,KAAK,WAAW,CAAC,KAAK,CAAC,QAAQ,EAChE,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,gFAAgF,CAAC,CAAA;IACnG,CAAC;IACD,MAAM,SAAS,GAAG,IAAI,gCAAgC,CAAC;QACrD,QAAQ,EAAE,UAAU,CAAC,UAAU,CAAC,QAAQ;QACxC,cAAc,EAAE,UAAU,CAAC,cAAc;QACzC,eAAe;QACf,gBAAgB;KACjB,CAAC,CAAA;IACF,IAAI,CAAC;QACH,MAAM,qBAAqB,CAAC,SAAS,EAAE,gBAAgB,CAAC,CAAA;IAC1D,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,SAAS,CAAC,KAAK,EAAE,CAAA;QACjB,MAAM,KAAK,CAAA;IACb,CAAC;IACD,OAAO,IAAI,8BAA8B,CAAC;QACxC,IAAI,EAAE,iBAAiB;QACvB,UAAU,EAAE,UAAU,CAAC,UAAU;QACjC,SAAS;KACV,CAAC,CAAA;AACJ,CAAC;AAED,qFAAqF;AACrF,OAAO,EACL,sBAAsB,EACtB,8BAA8B,GAK/B,MAAM,0CAA0C,CAAA"}

package/dist/localHostLease.d.ts

@@ -0,0 +1,51 @@
+import { type LocalAgentHostLeaseDescriptor, type LocalAgentHostLeaseRecord } from '@xenosystem/agent-interface-client/local';
+/**
+ * Lease ACQUISITION — the half a surface must not have.
+ *
+ * Reading a lease moved to the client package (ADE §2.7); taking one stays here. The separation
+ * is structural rather than documented: a client cannot acquire because the code to acquire is
+ * in a package it does not depend on.
+ */
+export interface AcquireLocalAgentHostLeaseOptions {
+    rootDirectory: string;
+    instanceId: string;
+    endpoint: string;
+    protocolVersion: number;
+    pid?: number;
+    staleAfterMs?: number;
+    now?: () => number;
+    isProcessAlive?: (pid: number) => boolean;
+    /**
+     * Does anything accept a connection on the owner's endpoint? Injectable so both halves of
+     * the ambiguous case are testable: a crashed host whose pid was recycled (nothing listening
+     * -> take over) versus a HUNG host that still holds its listener (the OS backlog answers
+     * even though the process is wedged -> stand down, because it still owns the durable state).
+     */
+    probeEndpoint?: (endpoint: string, timeoutMs: number) => Promise<boolean>;
+}
+export type AcquireLocalAgentHostLeaseResult = {
+    acquired: true;
+    lease: LocalAgentHostLease;
+} | {
+    acquired: false;
+    owner: LocalAgentHostLeaseDescriptor;
+};
+/**
+ * Exclusive, per-user authority lease. The lock record doubles as local
+ * transport discovery; its bearer token is returned only to the lease owner.
+ */
+export declare class LocalAgentHostLease {
+    private readonly path;
+    private readonly record;
+    private readonly now;
+    private released;
+    constructor(path: string, record: LocalAgentHostLeaseRecord, now: () => number);
+    get descriptor(): LocalAgentHostLeaseDescriptor;
+    get transportToken(): string;
+    heartbeat(): Promise<LocalAgentHostLeaseDescriptor>;
+    release(): Promise<boolean>;
+    private assertActive;
+}
+export declare function acquireLocalAgentHostLease(options: AcquireLocalAgentHostLeaseOptions): Promise<AcquireLocalAgentHostLeaseResult>;
+export { DEFAULT_LEASE_STALE_AFTER_MS, isLeaseOwnerGone, inspectLocalAgentHostLease, readLocalAgentHostLeaseConnection, type LocalAgentHostLeaseDescriptor, type LocalAgentHostLeaseConnectionInfo, } from '@xenosystem/agent-interface-client/local';
+//# sourceMappingURL=localHostLease.d.ts.map

package/dist/localHostLease.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"localHostLease.d.ts","sourceRoot":"","sources":["../src/localHostLease.ts"],"names":[],"mappings":"AAGA,OAAO,EAUL,KAAK,6BAA6B,EAClC,KAAK,yBAAyB,EAC/B,MAAM,0CAA0C,CAAA;AAEjD;;;;;;GAMG;AAEH,MAAM,WAAW,iCAAiC;IAChD,aAAa,EAAE,MAAM,CAAA;IACrB,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,eAAe,EAAE,MAAM,CAAA;IACvB,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAClB,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAA;IACzC;;;;;OAKG;IACH,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CAC1E;AACD,MAAM,MAAM,gCAAgC,GACxC;IAAE,QAAQ,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,mBAAmB,CAAA;CAAE,GAC9C;IAAE,QAAQ,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,6BAA6B,CAAA;CAAE,CAAA;AAC7D;;;GAGG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAQ;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA2B;IAClD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAc;IAClC,OAAO,CAAC,QAAQ,CAAQ;gBAEZ,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,yBAAyB,EAAE,GAAG,EAAE,MAAM,MAAM;IAM9E,IAAI,UAAU,IAAI,6BAA6B,CAE9C;IAED,IAAI,cAAc,IAAI,MAAM,CAG3B;IAEK,SAAS,IAAI,OAAO,CAAC,6BAA6B,CAAC;IAyBnD,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC;IAoBjC,OAAO,CAAC,YAAY;CAGrB;AACD,wBAAsB,0BAA0B,CAC9C,OAAO,EAAE,iCAAiC,GACzC,OAAO,CAAC,gCAAgC,CAAC,CA2E3C;AAGD,OAAO,EACL,4BAA4B,EAC5B,gBAAgB,EAChB,0BAA0B,EAC1B,iCAAiC,EACjC,KAAK,6BAA6B,EAClC,KAAK,iCAAiC,GACvC,MAAM,0CAA0C,CAAA"}