@xenosystem/agent-interface-runtime 0.1.12

package/LICENSE

@@ -0,0 +1,67 @@
+XENO Agent — Proprietary Software License
+Copyright © 2026 XENO Corporation. All rights reserved.
+
+This software, including its source code, compiled binaries, published packages,
+assets, and accompanying documentation (collectively, the "Software"), is the
+proprietary and confidential property of XENO Corporation ("XENO"). The Software
+is licensed for use, not sold, and no title to or ownership of the Software is
+transferred to any user.
+
+1. GRANT OF USE
+   Subject to a separate written agreement and/or the terms of service published
+   at https://xenostudio.ai, XENO grants the end user a limited, non-exclusive,
+   non-transferable, revocable license to install and use the Software for its
+   intended purpose. The standalone desktop application ("the Agent") may be used
+   locally at no charge; connected platform features — hosted agent runs, model
+   inference, credits, and account services — are governed by the applicable
+   subscription and the XENO terms of service.
+
+2. PACKAGE DISTRIBUTION
+   The `@xeno-corporation/xeno-agent-interface-*` and
+   `@xeno-corporation/xeno-agents-client` packages are published to a PRIVATE
+   registry and are licensed for use solely by XENO products and by parties
+   holding a separate written agreement with XENO. Access credentials to that
+   registry do not grant redistribution rights. Publication of any package in
+   this repository to a public registry is prohibited without written
+   authorization from XENO.
+
+3. RESTRICTIONS
+   Except to the extent expressly permitted by applicable law or by a separate
+   written agreement with XENO, you may NOT: (a) copy, redistribute, sell, rent,
+   lease, sublicense, or otherwise transfer the Software; (b) modify, adapt,
+   translate, or create derivative works of the Software; (c) reverse-engineer,
+   decompile, or disassemble the Software, or attempt to derive its source code;
+   (d) remove, obscure, or alter any proprietary notices; or (e) use the Software
+   to build a competing product.
+
+4. RESERVATION OF RIGHTS
+   All rights not expressly granted are reserved by XENO Corporation. The Software
+   is protected by copyright and other intellectual-property laws and treaties.
+
+5. DISCLAIMER OF WARRANTY
+   THE SOFTWARE IS PROVIDED "AS IS" AND "AS AVAILABLE", WITHOUT WARRANTY OF ANY
+   KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. THE
+   SOFTWARE EXECUTES AGENT-DIRECTED OPERATIONS AGAINST A USER-SELECTED WORKSPACE,
+   INCLUDING FILE AND PROCESS ACTIONS; THE USER IS RESPONSIBLE FOR THE WORKSPACES
+   AND PERMISSIONS THEY GRANT IT.
+
+6. LIMITATION OF LIABILITY
+   TO THE MAXIMUM EXTENT PERMITTED BY LAW, IN NO EVENT SHALL XENO CORPORATION BE
+   LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, OR PUNITIVE
+   DAMAGES, OR ANY LOSS OF PROFITS OR DATA, ARISING FROM OR RELATED TO THE USE OF
+   OR INABILITY TO USE THE SOFTWARE.
+
+7. THIRD-PARTY COMPONENTS
+   The Software includes third-party open-source components, each licensed under
+   its own terms; those terms govern those components and are not superseded by
+   this license. It also composes third-party agent providers over the Agent
+   Client Protocol and hosted APIs; use of those providers is governed by their
+   own terms.
+
+For licensing inquiries, contact: legal@xenostudio.ai
+
+NOTE TO OPERATOR: confirm the exact legal entity name and notice/contact details
+with counsel before public distribution and code-signing (the code-signing
+publisher name must match the registered entity). No public distribution of this
+product is authorized by this file — see docs/PRODUCT_STATUS.md.

package/dist/cloudOptions.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Where the XENO Cloud client looks for credentials and endpoints.
+ *
+ * Shared so there is exactly ONE of these. A second copy was written while
+ * factoring the shared composition (ADE §9 step 3) and it was **wrong** — it
+ * invented `credentialsDirectory` and `platformBaseUrl`, neither of which this
+ * client reads, and dropped `directApiBase` and `platformModelsUrl` entirely.
+ * The result would have typechecked, started, and quietly resolved credentials
+ * from the wrong place.
+ *
+ * That is the argument for extraction stated as a fact rather than a principle:
+ * the duplicate did not drift over months, it was born wrong within minutes,
+ * because reproducing a config mapping from memory is exactly the kind of thing
+ * nobody reproduces correctly.
+ *
+ * No Electron import — `homeDirectory` is a parameter, which is the only part a
+ * windowed process knows and a headless one does not.
+ */
+import type { DiscoverXenoCloudNodeRuntimeOptions } from '@xenosystem/agents-client/node';
+export interface StandaloneCloudOptionsInput {
+    /** The user's home directory, from whichever runtime knows it. */
+    homeDirectory: string;
+    /** This host's own root, used as the credential home under the E2E harness. */
+    hostRoot: string;
+    env?: NodeJS.ProcessEnv;
+}
+export declare function standaloneCloudOptions(input: StandaloneCloudOptionsInput): DiscoverXenoCloudNodeRuntimeOptions;
+//# sourceMappingURL=cloudOptions.d.ts.map

package/dist/cloudOptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudOptions.d.ts","sourceRoot":"","sources":["../src/cloudOptions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,mCAAmC,EAAE,MAAM,gCAAgC,CAAA;AAEzF,MAAM,WAAW,2BAA2B;IAC1C,kEAAkE;IAClE,aAAa,EAAE,MAAM,CAAA;IACrB,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,CAAA;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;CACxB;AAED,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,2BAA2B,GACjC,mCAAmC,CAiBrC"}

package/dist/cloudOptions.js

@@ -0,0 +1,37 @@
+/**
+ * Where the XENO Cloud client looks for credentials and endpoints.
+ *
+ * Shared so there is exactly ONE of these. A second copy was written while
+ * factoring the shared composition (ADE §9 step 3) and it was **wrong** — it
+ * invented `credentialsDirectory` and `platformBaseUrl`, neither of which this
+ * client reads, and dropped `directApiBase` and `platformModelsUrl` entirely.
+ * The result would have typechecked, started, and quietly resolved credentials
+ * from the wrong place.
+ *
+ * That is the argument for extraction stated as a fact rather than a principle:
+ * the duplicate did not drift over months, it was born wrong within minutes,
+ * because reproducing a config mapping from memory is exactly the kind of thing
+ * nobody reproduces correctly.
+ *
+ * No Electron import — `homeDirectory` is a parameter, which is the only part a
+ * windowed process knows and a headless one does not.
+ */
+export function standaloneCloudOptions(input) {
+    const env = input.env ?? process.env;
+    return {
+        // The E2E harness must never read the developer's real credentials, so it
+        // is pointed at the host root it already owns. An explicit override wins
+        // over both, because a test rig that cannot say where to look is a test rig
+        // that reads whatever happens to be there.
+        homeDirectory: env.XENO_AGENT_CLOUD_CREDENTIAL_ROOT
+            || (env.XENO_AGENT_E2E === '1' ? input.hostRoot : input.homeDirectory),
+        ...(env.XENO_AGENT_CLOUD_BASE_URL ? { baseUrl: env.XENO_AGENT_CLOUD_BASE_URL } : {}),
+        ...(env.XENO_AGENT_CLOUD_DIRECT_API_BASE
+            ? { directApiBase: env.XENO_AGENT_CLOUD_DIRECT_API_BASE }
+            : {}),
+        ...(env.XENO_AGENT_CLOUD_PLATFORM_MODELS_URL
+            ? { platformModelsUrl: env.XENO_AGENT_CLOUD_PLATFORM_MODELS_URL }
+            : {}),
+    };
+}
+//# sourceMappingURL=cloudOptions.js.map

package/dist/cloudOptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudOptions.js","sourceRoot":"","sources":["../src/cloudOptions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAYH,MAAM,UAAU,sBAAsB,CACpC,KAAkC;IAElC,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAA;IACpC,OAAO;QACL,0EAA0E;QAC1E,yEAAyE;QACzE,4EAA4E;QAC5E,2CAA2C;QAC3C,aAAa,EAAE,GAAG,CAAC,gCAAgC;eAC9C,CAAC,GAAG,CAAC,cAAc,KAAK,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC;QACxE,GAAG,CAAC,GAAG,CAAC,yBAAyB,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,yBAAyB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACpF,GAAG,CAAC,GAAG,CAAC,gCAAgC;YACtC,CAAC,CAAC,EAAE,aAAa,EAAE,GAAG,CAAC,gCAAgC,EAAE;YACzD,CAAC,CAAC,EAAE,CAAC;QACP,GAAG,CAAC,GAAG,CAAC,oCAAoC;YAC1C,CAAC,CAAC,EAAE,iBAAiB,EAAE,GAAG,CAAC,oCAAoC,EAAE;YACjE,CAAC,CAAC,EAAE,CAAC;KACR,CAAA;AACH,CAAC"}

package/dist/composeHost.d.ts

@@ -0,0 +1,171 @@
+/**
+ * The Agent host composition — ONE of them, used by every product surface.
+ *
+ * ADE §9 build-order step 3 needs the host to be able to run in a process with
+ * no windows. The obvious way to get there is to write a second, smaller
+ * composition for the detached entry. That is a fork, and this repo's own
+ * invariant (`AGENTS.md`: no surface-specific fork) says why it is the wrong
+ * shape: two compositions drift, and the one that drifts is always the one
+ * fewer people run.
+ *
+ * So there is one builder, and the Electron-only capabilities are INJECTED. A
+ * surface that has windows passes them; a headless process passes none.
+ *
+ * ## 🔴 Absent capabilities are declared, never silently dropped
+ *
+ * ⚠️ CORRECTED 2026-08-18. This said the SDK-native lane cannot run without
+ * `createSdkRuntimeWindow`, "its tools take a live BrowserWindow". Measured, that
+ * is false: the loop takes an `SdkAgentSurface` (send + isDestroyed) and loads in
+ * plain Node, and the surface tools act through `SdkAgentSurfaceRuntimeAdapter`,
+ * whose unregistered default refuses honestly. A window is now one way to run the
+ * lane; the headless runner is the other, and it differs only in where events go
+ * and who can answer a prompt.
+ *
+ * The principle the paragraph was written for is untouched, and still applies to
+ * every capability that IS genuinely absent here: the tempting response is to
+ * leave the provider out of the catalog entirely.
+ *
+ * That is wrong, and the reason generalises: **a provider that vanishes looks
+ * like a configuration error.** An operator sees a shorter list and goes looking
+ * for what they broke. A provider that is PRESENT and reports
+ * `runnable: false` with a reason has told them the truth — this build cannot
+ * run that lane, and here is why. The descriptor already carries
+ * `safeUnavailableReason` for exactly this, so honesty costs a string.
+ *
+ * ## §9 step 3 — ADOPTED
+ *
+ * Both entries run this. `apps/desktop/src/main/index.ts` calls it with a full
+ * `surface`; `detachedHostEntry.ts` calls it with `{}`. The fork it existed to
+ * remove is gone, and with it the failure mode that made the case: for weeks
+ * each composition was missing services the other had, in both directions —
+ * the four §5 services reached the detached host and never the app, while
+ * tier-1 observation and the §5.7 landing queue reached the app and never the
+ * detached host. Neither gap is visible from inside one composition, and a test
+ * that mounts its own fixture cannot see them at all.
+ *
+ * 🔴 `createCoordinator()` is DEFERRED, and that is the one thing not to
+ * "simplify". Composing is safe in any process; the coordinator opens the
+ * durable SQLite state, and two of those open at once is the split-brain the
+ * host lease exists to prevent. So the composition is eager — a surface still
+ * needs its shell service and registry while another process owns the host —
+ * and only the coordinator waits for the election.
+ */
+import { AcpAgentRegistryService, AgentHostCoordinator, EngineeringWorkbenchService, RunObservationService, RuntimeEventStore, WorkspaceHostService, WorkspaceShellService, XenoUseRunObserver, type LocalAgentHostPaths } from '@xenosystem/agent-interface-host/node';
+import { type DiscoverXenoCloudNodeRuntimeOptions } from '@xenosystem/agents-client/node';
+/**
+ * What a windowed surface can lend the host.
+ *
+ * Every field is optional and every absence has a stated consequence — that is
+ * what makes this a capability set rather than a pile of nullable arguments.
+ */
+export interface HostSurfaceCapabilities {
+    /**
+     * Opens paths in the OS. Absent, workspace "reveal in folder" is unavailable
+     * rather than silently doing nothing.
+     */
+    shell?: {
+        openPath: (path: string) => Promise<string>;
+        showItemInFolder: (path: string) => void;
+    };
+    /**
+     * Creates a runtime window for the SDK-native lane.
+     *
+     * Absent, that lane still runs — through the headless runner, which routes its two blocking
+     * channels to attached clients and refuses them when nobody is there. What is lost is the
+     * ability to PRESENT a prompt from this process, not the ability to execute a turn.
+     */
+    createSdkRuntimeWindow?: () => unknown;
+    /**
+     * Sends an elicitation to a surface (permission prompts, directory choosers).
+     * Absent, the ACP permission bridge has no interactive half and fails closed,
+     * which is the correct direction: a prompt nobody can answer is a refusal.
+     */
+    sendElicitation?: (channel: string, payload: Record<string, unknown>) => void;
+}
+export interface ComposeAgentHostOptions {
+    homeDirectory: string;
+    hostVersion: string;
+    hostInstanceId: string;
+    /** Where a fixture agent script lives, when the fixture is enabled. */
+    fixtureBaseDirectory: string;
+    surface: HostSurfaceCapabilities;
+    env?: NodeJS.ProcessEnv;
+}
+export interface AgentHostComposition {
+    /**
+     * Builds the coordinator — and everything that owns durable state with it.
+     *
+     * 🔴 Deferred, and called ONLY by the process that won the host lease.
+     * The coordinator opens the SQLite state repository, and two processes
+     * holding that open is the split-brain the lease exists to prevent. Every
+     * other part of this composition is safe to build in any process, which is
+     * why they are eager and this one is not: a surface still needs its shell
+     * service and its registry while another process owns the host.
+     *
+     * Idempotent. A second call returns the same coordinator rather than opening
+     * the state twice, because the lease is acquired once but shutdown paths can
+     * race.
+     */
+    createCoordinator: () => Promise<AgentHostCoordinator>;
+    paths: LocalAgentHostPaths;
+    registry: AcpAgentRegistryService;
+    runtimeStore: RuntimeEventStore;
+    workspaceAuthority: WorkspaceHostService;
+    workspaceShellService: WorkspaceShellService | undefined;
+    engineeringControlService: EngineeringWorkbenchService;
+    /**
+     * Tier-1 observation (§2.9), when an operator configured a `xeno-use`
+     * sidecar. Absent means NO observation — never an empty one, which would
+     * report every run as a clean diff of changes nobody watched.
+     */
+    runObservationService: RunObservationService | undefined;
+    /**
+     * The live observer, exposed so a surface can tear its sandboxes down on its
+     * own schedule. `dispose()` already stops them; this is for a caller that
+     * must stop them EARLIER, before the rest of its shutdown.
+     */
+    runObserver: XenoUseRunObserver | undefined;
+    /** Lanes this composition declared unrunnable, and why. */
+    declaredUnavailable: Array<{
+        lane: string;
+        reason: string;
+    }>;
+    /**
+     * The execution lanes this composition actually REGISTERED.
+     *
+     * 🔴 Exposed so "the lane is available" can be checked against something that executes, rather
+     * than against the declaration alone. The two are independent — a composition can declare a
+     * lane available and register no adapter for it, which is the §7.1 failure in its worst form:
+     * the catalog offers it, the user selects it, and the turn dies at execution time reading as
+     * "the agent is broken" rather than "not here".
+     */
+    turnExecutionAdapterIds: string[];
+    /**
+     * Releases what this composition holds open — today, the SQLite state handle.
+     *
+     * 🔴 A composition that cannot be disposed cannot HAND OVER. The detached
+     * host's own rule is that losing the lease stops the process, because two
+     * writers on one durable state is the split-brain the lease exists to prevent
+     * — and on Windows a held SQLite file blocks the next owner from opening the
+     * same directory. Relying on process exit to release it works only for the
+     * case where the process exits, which is exactly not the interesting one.
+     *
+     * Idempotent: a second call is a no-op, because a stop path that runs twice
+     * under a race must not turn a clean shutdown into an error.
+     */
+    dispose: () => Promise<void>;
+}
+export declare function composeAgentHost(options: ComposeAgentHostOptions): Promise<AgentHostComposition>;
+/**
+ * The provider catalog.
+ *
+ * `sdkRunnable` is a parameter rather than being derived here, because whether
+ * the lane can run is a fact about the SURFACE, and this function only knows
+ * about credentials. Deriving it would make a headless host advertise a lane it
+ * cannot execute — the capability-honesty failure (§7.1) in its plainest form.
+ */
+export declare function loadAgentHostProviders(registry: AcpAgentRegistryService, cloudOptions: DiscoverXenoCloudNodeRuntimeOptions, options: {
+    sdkRunnable: boolean;
+    durablePendingInjections?: boolean;
+}): Promise<import("@xenosystem/agent-interface-contract").AgentRuntimeProviderDescriptor[]>;
+//# sourceMappingURL=composeHost.d.ts.map

package/dist/composeHost.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composeHost.d.ts","sourceRoot":"","sources":["../src/composeHost.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AASH,OAAO,EACL,uBAAuB,EAIvB,oBAAoB,EAKpB,2BAA2B,EAM3B,qBAAqB,EAErB,iBAAiB,EAQjB,oBAAoB,EACpB,qBAAqB,EAErB,kBAAkB,EAalB,KAAK,mBAAmB,EAEzB,MAAM,uCAAuC,CAAA;AAC9C,OAAO,EAIL,KAAK,mCAAmC,EACzC,MAAM,gCAAgC,CAAA;AAuBvC;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,KAAK,CAAC,EAAE;QACN,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;QAC3C,gBAAgB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;KACzC,CAAA;IACD;;;;;;OAMG;IACH,sBAAsB,CAAC,EAAE,MAAM,OAAO,CAAA;IACtC;;;;OAIG;IACH,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;CAC9E;AAED,MAAM,WAAW,uBAAuB;IACtC,aAAa,EAAE,MAAM,CAAA;IACrB,WAAW,EAAE,MAAM,CAAA;IACnB,cAAc,EAAE,MAAM,CAAA;IACtB,uEAAuE;IACvE,oBAAoB,EAAE,MAAM,CAAA;IAC5B,OAAO,EAAE,uBAAuB,CAAA;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;CACxB;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;;;;;;OAaG;IACH,iBAAiB,EAAE,MAAM,OAAO,CAAC,oBAAoB,CAAC,CAAA;IACtD,KAAK,EAAE,mBAAmB,CAAA;IAC1B,QAAQ,EAAE,uBAAuB,CAAA;IACjC,YAAY,EAAE,iBAAiB,CAAA;IAC/B,kBAAkB,EAAE,oBAAoB,CAAA;IACxC,qBAAqB,EAAE,qBAAqB,GAAG,SAAS,CAAA;IACxD,yBAAyB,EAAE,2BAA2B,CAAA;IACtD;;;;OAIG;IACH,qBAAqB,EAAE,qBAAqB,GAAG,SAAS,CAAA;IACxD;;;;OAIG;IACH,WAAW,EAAE,kBAAkB,GAAG,SAAS,CAAA;IAC3C,2DAA2D;IAC3D,mBAAmB,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAC5D;;;;;;;;OAQG;IACH,uBAAuB,EAAE,MAAM,EAAE,CAAA;IACjC;;;;;;;;;;;;OAYG;IACH,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC7B;AAED,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,oBAAoB,CAAC,CAgyB/B;AAED;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,uBAAuB,EACjC,YAAY,EAAE,mCAAmC,EACjD,OAAO,EAAE;IAAE,WAAW,EAAE,OAAO,CAAC;IAAC,wBAAwB,CAAC,EAAE,OAAO,CAAA;CAAE,4FA+BtE"}