@xenosystem/agent-interface-electron-host 0.1.3

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/headless.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The Electron-free entry point: everything a host can run WITHOUT a renderer.
+ *
+ * 🔴 Splitting `sdkAgent.ts` from `permissionIpc.ts` was necessary and not sufficient. The
+ * package's only export was `.`, whose barrel re-exports the IPC module — so a headless host
+ * importing `@xenosystem/agent-interface-electron-host` would still have loaded `electron`
+ * transitively and failed, with the loop itself entirely innocent. The module boundary and the
+ * PACKAGE boundary have to agree, or the fix is invisible to every real consumer.
+ *
+ * So this subpath is the one a headless composition imports. The root export keeps its full
+ * surface, including the IPC registration, for the Electron app.
+ *
+ * ⚠️ Nothing added here may value-import `electron`, directly or transitively.
+ * `headlessLoadability.test.ts` loads this exact built file in a clean `node` subprocess and
+ * fails if it does — and keeps the root barrel as the opposite-result control, so the gate cannot
+ * pass by accident.
+ *
+ * ⚠️ The package NAME is now wrong for half its contents, and that is deliberate for the moment:
+ * renaming a published package is a coordinated change across every consumer, and doing it in the
+ * same commit as the split would confuse a mechanical move with a distribution change. It is
+ * recorded rather than quietly tolerated.
+ */
+export * from './sdkAgent.js';
+export * from './headlessAgentSurface.js';
+export * from './sdkNativeHeadlessRunner.js';
+//# sourceMappingURL=headless.d.ts.map

package/dist/headless.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"headless.d.ts","sourceRoot":"","sources":["../src/headless.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,cAAc,eAAe,CAAA;AAC7B,cAAc,2BAA2B,CAAA;AACzC,cAAc,8BAA8B,CAAA"}

package/dist/headless.js

@@ -0,0 +1,26 @@
+/**
+ * The Electron-free entry point: everything a host can run WITHOUT a renderer.
+ *
+ * 🔴 Splitting `sdkAgent.ts` from `permissionIpc.ts` was necessary and not sufficient. The
+ * package's only export was `.`, whose barrel re-exports the IPC module — so a headless host
+ * importing `@xenosystem/agent-interface-electron-host` would still have loaded `electron`
+ * transitively and failed, with the loop itself entirely innocent. The module boundary and the
+ * PACKAGE boundary have to agree, or the fix is invisible to every real consumer.
+ *
+ * So this subpath is the one a headless composition imports. The root export keeps its full
+ * surface, including the IPC registration, for the Electron app.
+ *
+ * ⚠️ Nothing added here may value-import `electron`, directly or transitively.
+ * `headlessLoadability.test.ts` loads this exact built file in a clean `node` subprocess and
+ * fails if it does — and keeps the root barrel as the opposite-result control, so the gate cannot
+ * pass by accident.
+ *
+ * ⚠️ The package NAME is now wrong for half its contents, and that is deliberate for the moment:
+ * renaming a published package is a coordinated change across every consumer, and doing it in the
+ * same commit as the split would confuse a mechanical move with a distribution change. It is
+ * recorded rather than quietly tolerated.
+ */
+export * from './sdkAgent.js';
+export * from './headlessAgentSurface.js';
+export * from './sdkNativeHeadlessRunner.js';
+//# sourceMappingURL=headless.js.map

package/dist/headless.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"headless.js","sourceRoot":"","sources":["../src/headless.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,cAAc,eAAe,CAAA;AAC7B,cAAc,2BAA2B,CAAA;AACzC,cAAc,8BAA8B,CAAA"}

package/dist/headlessAgentSurface.d.ts

@@ -0,0 +1,97 @@
+import type { SdkAgentSurface } from './sdkAgentSurface.js';
+/**
+ * The SDK agent loop's surface for a host with no renderer.
+ *
+ * ## What this had to establish before it could be written
+ *
+ * The loop sends ten channels. It would be easy to assume a headless host must reimplement all
+ * ten, and wrong: measured at the emission site, `emitRuntimeEvent` **persists the event to the
+ * runtime store and calls `onPersistedRuntimeEvent` FIRST**, and only then forwards the same
+ * enriched event to the renderer. The window traffic is DERIVED from the runtime-event stream,
+ * not parallel to it.
+ *
+ * So a host that consumes `onPersistedRuntimeEvent` — which every composition already does —
+ * receives everything the renderer receives, for display purposes, with no window involved. The
+ * ten channels split cleanly:
+ *
+ * | channels | what a headless host owes them |
+ * |---|---|
+ * | `agent:runtime-event`, `agent:text-chunk`, `agent:done`, `agent:error`, `agent:tool-start`, `agent:tool-end`, `agent:task-event`, `workspaceStorage:changed` | **nothing** — the same facts already reached the host through the runtime-event stream |
+ * | `agent:permission-request`, `agent:ask-user-request` | **a real path to a human**, because nobody else can answer them |
+ *
+ * 🔴 That second row is why this class forwards rather than swallows, and why `onInteraction` is
+ * REQUIRED rather than optional. A permission request that goes nowhere does not degrade the
+ * turn — it hangs it, silently, because the loop is waiting for `grantSdkAccess` /
+ * `denySdkAccess` / `answerSdkAskUser` to be called by whoever displayed the prompt. A surface
+ * that quietly dropped those would produce an agent that appears to think forever, which is
+ * exactly the class of failure this repo keeps finding: a capability that reports nothing rather
+ * than failing.
+ *
+ * ⚠️ This does NOT answer permission requests. It carries them to the composition, which is the
+ * only layer that knows whether a human is reachable — a host serving an attached CLI can prompt
+ * through that client's elicitation channel; an unattended one must refuse rather than invent an
+ * answer. Deciding here would bake one of those choices in for both.
+ */
+/** The channels that require a human, and therefore a real route out of the host. */
+export declare const INTERACTIVE_AGENT_CHANNELS: readonly ["agent:permission-request", "agent:ask-user-request"];
+export type InteractiveAgentChannel = typeof INTERACTIVE_AGENT_CHANNELS[number];
+export declare function isInteractiveAgentChannel(channel: string): channel is InteractiveAgentChannel;
+export interface HeadlessAgentSurfaceOptions {
+    /**
+     * Called for every channel the loop emits, with `interactive` already classified so a
+     * composition cannot accidentally treat a permission prompt as a display update.
+     *
+     * Required, and deliberately not defaulted: see the note above on hangs.
+     *
+     * 🔴 Returns whether the message REACHED anyone. A headless host publishes to whatever clients
+     * are attached, and that set can be empty — a detached host running with nobody connected is a
+     * normal state, not an error.
+     */
+    onEvent(message: {
+        channel: string;
+        payload: Record<string, unknown> | undefined;
+        interactive: boolean;
+    }): HeadlessDelivery;
+    /**
+     * Called when an INTERACTIVE message reached nobody.
+     *
+     * 🔴 Required, because this is the difference between a safe headless host and one that wedges.
+     * `requestSurfacePermission` has NO TIMEOUT — measured, not assumed: it returns a promise that
+     * settles only when `grantSdkAccess` or `denySdkAccess` is called with the matching
+     * `permissionId`. Publish a prompt to zero subscribers and the turn waits forever, holding its
+     * tool call open, with the agent appearing to think.
+     *
+     * The loop already encodes the correct direction for the reachable-but-gone case:
+     * `if (!mainWindow || mainWindow.isDestroyed()) return false` — *a prompt nobody can answer
+     * must not resolve as an approval*. This extends the same rule to "nobody received it", which
+     * is the only version a headless host can actually be in.
+     *
+     * The composition performs the denial (it owns `denySdkAccess`), because this module must not
+     * import the loop it reports to.
+     */
+    onUnanswerableInteraction(message: {
+        channel: InteractiveAgentChannel;
+        payload: Record<string, unknown> | undefined;
+    }): void;
+    /**
+     * Whether the host still has anywhere to send. Defaults to "yes, always" — a headless host has
+     * no window to be destroyed, and its lifetime is the process's.
+     */
+    isGone?(): boolean;
+}
+/** Whether a forwarded message reached at least one recipient. */
+export interface HeadlessDelivery {
+    delivered: boolean;
+}
+/**
+ * Build a surface for a host with no renderer.
+ *
+ * Errors from `onEvent` are contained: the loop calls `send` from inside tool execution and
+ * streaming callbacks, where an exception would abort a turn that is otherwise fine. A broken
+ * consumer must not be able to kill the run it is merely observing — but it must not be silent
+ * either, so failures are reported through `onEventError` when supplied.
+ */
+export declare function createHeadlessAgentSurface(options: HeadlessAgentSurfaceOptions & {
+    onEventError?: (error: unknown, channel: string) => void;
+}): SdkAgentSurface;
+//# sourceMappingURL=headlessAgentSurface.d.ts.map

package/dist/headlessAgentSurface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"headlessAgentSurface.d.ts","sourceRoot":"","sources":["../src/headlessAgentSurface.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,qFAAqF;AACrF,eAAO,MAAM,0BAA0B,iEAG7B,CAAA;AAEV,MAAM,MAAM,uBAAuB,GAAG,OAAO,0BAA0B,CAAC,MAAM,CAAC,CAAA;AAE/E,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,IAAI,uBAAuB,CAE7F;AAED,MAAM,WAAW,2BAA2B;IAC1C;;;;;;;;;OASG;IACH,OAAO,CAAC,OAAO,EAAE;QACf,OAAO,EAAE,MAAM,CAAA;QACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;QAC5C,WAAW,EAAE,OAAO,CAAA;KACrB,GAAG,gBAAgB,CAAA;IAEpB;;;;;;;;;;;;;;;;OAgBG;IACH,yBAAyB,CAAC,OAAO,EAAE;QACjC,OAAO,EAAE,uBAAuB,CAAA;QAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;KAC7C,GAAG,IAAI,CAAA;IAER;;;OAGG;IACH,MAAM,CAAC,IAAI,OAAO,CAAA;CACnB;AAED,kEAAkE;AAClE,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,OAAO,CAAA;CACnB;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,2BAA2B,GAAG;IAAE,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GAClG,eAAe,CA0BjB"}

package/dist/headlessAgentSurface.js

@@ -0,0 +1,80 @@
+/**
+ * The SDK agent loop's surface for a host with no renderer.
+ *
+ * ## What this had to establish before it could be written
+ *
+ * The loop sends ten channels. It would be easy to assume a headless host must reimplement all
+ * ten, and wrong: measured at the emission site, `emitRuntimeEvent` **persists the event to the
+ * runtime store and calls `onPersistedRuntimeEvent` FIRST**, and only then forwards the same
+ * enriched event to the renderer. The window traffic is DERIVED from the runtime-event stream,
+ * not parallel to it.
+ *
+ * So a host that consumes `onPersistedRuntimeEvent` — which every composition already does —
+ * receives everything the renderer receives, for display purposes, with no window involved. The
+ * ten channels split cleanly:
+ *
+ * | channels | what a headless host owes them |
+ * |---|---|
+ * | `agent:runtime-event`, `agent:text-chunk`, `agent:done`, `agent:error`, `agent:tool-start`, `agent:tool-end`, `agent:task-event`, `workspaceStorage:changed` | **nothing** — the same facts already reached the host through the runtime-event stream |
+ * | `agent:permission-request`, `agent:ask-user-request` | **a real path to a human**, because nobody else can answer them |
+ *
+ * 🔴 That second row is why this class forwards rather than swallows, and why `onInteraction` is
+ * REQUIRED rather than optional. A permission request that goes nowhere does not degrade the
+ * turn — it hangs it, silently, because the loop is waiting for `grantSdkAccess` /
+ * `denySdkAccess` / `answerSdkAskUser` to be called by whoever displayed the prompt. A surface
+ * that quietly dropped those would produce an agent that appears to think forever, which is
+ * exactly the class of failure this repo keeps finding: a capability that reports nothing rather
+ * than failing.
+ *
+ * ⚠️ This does NOT answer permission requests. It carries them to the composition, which is the
+ * only layer that knows whether a human is reachable — a host serving an attached CLI can prompt
+ * through that client's elicitation channel; an unattended one must refuse rather than invent an
+ * answer. Deciding here would bake one of those choices in for both.
+ */
+/** The channels that require a human, and therefore a real route out of the host. */
+export const INTERACTIVE_AGENT_CHANNELS = [
+    'agent:permission-request',
+    'agent:ask-user-request',
+];
+export function isInteractiveAgentChannel(channel) {
+    return INTERACTIVE_AGENT_CHANNELS.includes(channel);
+}
+/**
+ * Build a surface for a host with no renderer.
+ *
+ * Errors from `onEvent` are contained: the loop calls `send` from inside tool execution and
+ * streaming callbacks, where an exception would abort a turn that is otherwise fine. A broken
+ * consumer must not be able to kill the run it is merely observing — but it must not be silent
+ * either, so failures are reported through `onEventError` when supplied.
+ */
+export function createHeadlessAgentSurface(options) {
+    return {
+        send(channel, payload) {
+            const interactive = isInteractiveAgentChannel(channel);
+            let delivered = false;
+            try {
+                delivered = options.onEvent({ channel, payload, interactive }).delivered;
+            }
+            catch (error) {
+                options.onEventError?.(error, channel);
+                // A consumer that threw did not deliver. Treating a failed send as delivered would let
+                // the very error path this guard exists for produce the hang it is preventing.
+                delivered = false;
+            }
+            if (!interactive || delivered)
+                return;
+            try {
+                options.onUnanswerableInteraction({ channel: channel, payload });
+            }
+            catch (error) {
+                // Nothing left to fall back to, so surface it rather than lose it: the turn is now very
+                // likely to hang and this is the only trace of why.
+                options.onEventError?.(error, channel);
+            }
+        },
+        isDestroyed() {
+            return options.isGone?.() ?? false;
+        },
+    };
+}
+//# sourceMappingURL=headlessAgentSurface.js.map

package/dist/headlessAgentSurface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"headlessAgentSurface.js","sourceRoot":"","sources":["../src/headlessAgentSurface.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,qFAAqF;AACrF,MAAM,CAAC,MAAM,0BAA0B,GAAG;IACxC,0BAA0B;IAC1B,wBAAwB;CAChB,CAAA;AAIV,MAAM,UAAU,yBAAyB,CAAC,OAAe;IACvD,OAAQ,0BAAgD,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAA;AAC5E,CAAC;AAqDD;;;;;;;GAOG;AACH,MAAM,UAAU,0BAA0B,CACxC,OAAmG;IAEnG,OAAO;QACL,IAAI,CAAC,OAAO,EAAE,OAAO;YACnB,MAAM,WAAW,GAAG,yBAAyB,CAAC,OAAO,CAAC,CAAA;YACtD,IAAI,SAAS,GAAG,KAAK,CAAA;YACrB,IAAI,CAAC;gBACH,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC,CAAC,SAAS,CAAA;YAC1E,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO,CAAC,YAAY,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,CAAA;gBACtC,uFAAuF;gBACvF,+EAA+E;gBAC/E,SAAS,GAAG,KAAK,CAAA;YACnB,CAAC;YACD,IAAI,CAAC,WAAW,IAAI,SAAS;gBAAE,OAAM;YACrC,IAAI,CAAC;gBACH,OAAO,CAAC,yBAAyB,CAAC,EAAE,OAAO,EAAE,OAAkC,EAAE,OAAO,EAAE,CAAC,CAAA;YAC7F,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,wFAAwF;gBACxF,oDAAoD;gBACpD,OAAO,CAAC,YAAY,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,CAAA;YACxC,CAAC;QACH,CAAC;QACD,WAAW;YACT,OAAO,OAAO,CAAC,MAAM,EAAE,EAAE,IAAI,KAAK,CAAA;QACpC,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export * from './sdkAgent.js';
+export * from './headlessAgentSurface.js';
+export * from './sdkNativeHeadlessRunner.js';
+/**
+ * The Electron IPC surface, split out of `sdkAgent.js` so the agent loop no longer value-imports
+ * `electron` and can therefore be loaded by a headless host. Re-exported here so every existing
+ * `setupPermissionIPC` import keeps working — the move is structural, not a contract change.
+ */
+export * from './permissionIpc.js';
+export * from './sdkNativeRunner.js';
+export * from './surfaceRuntimeBridge.js';
+export * from './workspaceStateBridge.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAA;AAC7B,cAAc,2BAA2B,CAAA;AACzC,cAAc,8BAA8B,CAAA;AAC5C;;;;GAIG;AACH,cAAc,oBAAoB,CAAA;AAClC,cAAc,sBAAsB,CAAA;AACpC,cAAc,2BAA2B,CAAA;AACzC,cAAc,2BAA2B,CAAA"}

package/dist/index.js

@@ -0,0 +1,13 @@
+export * from './sdkAgent.js';
+export * from './headlessAgentSurface.js';
+export * from './sdkNativeHeadlessRunner.js';
+/**
+ * The Electron IPC surface, split out of `sdkAgent.js` so the agent loop no longer value-imports
+ * `electron` and can therefore be loaded by a headless host. Re-exported here so every existing
+ * `setupPermissionIPC` import keeps working — the move is structural, not a contract change.
+ */
+export * from './permissionIpc.js';
+export * from './sdkNativeRunner.js';
+export * from './surfaceRuntimeBridge.js';
+export * from './workspaceStateBridge.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAA;AAC7B,cAAc,2BAA2B,CAAA;AACzC,cAAc,8BAA8B,CAAA;AAC5C;;;;GAIG;AACH,cAAc,oBAAoB,CAAA;AAClC,cAAc,sBAAsB,CAAA;AACpC,cAAc,2BAA2B,CAAA;AACzC,cAAc,2BAA2B,CAAA"}

package/dist/permissionIpc.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The Electron IPC surface for the SDK-native agent — split out of `sdkAgent.ts` 2026-08-17.
+ *
+ * 🔴 This exists so the AGENT LOOP can run without Electron.
+ *
+ * `sdkAgent.ts` is 6,000+ lines and looked deeply Electron-coupled. It was not: measured, the
+ * whole runtime dependency was `dialog` (imported, NEVER used), one `app.isPackaged` read, and
+ * these `ipcMain.handle` registrations — all of which lived in this single function at the
+ * bottom of the file. The loop itself uses `mainWindow` purely as an outbound event channel
+ * (`webContents.send`) plus a liveness check (`isDestroyed`).
+ *
+ * A module-level `import { ipcMain } from 'electron'` is enough to make the whole module
+ * unloadable in a plain Node process, so moving these 90 lines is what lets a headless host
+ * import the loop at all. That is the blocker for ADE step 5: `xeno-agent-cli` cannot become a
+ * pure surface while the only sdk-native lane needs a renderer window, and the CLI already runs
+ * this same loop headless today — so the work is RELOCATION, not new capability.
+ *
+ *
+ * @unwired-by-design Nothing in this repo calls it, and nothing ever has — verified against the
+ * pre-split tree, so this is not fallout from the 2026-08-17 refactor. It is a PUBLISHED export of
+ * `@xenosystem/agent-interface-electron-host` (0.1.2, ships `dist`) for an Electron composition
+ * that drives the SDK loop DIRECTLY over these `agent:*` channels.
+ *
+ * The standalone app deliberately does not: `apps/desktop/src/main/composeHost.ts` answers
+ * permissions through `sdkControlService`, i.e. over the host protocol, which is the direction
+ * the ADE spec takes every surface. Confirmed in the BUILT output as well as the source — the
+ * bundled chunk contains the declaration and the export, and no call.
+ *
+ * ⚠️ Do not read that as "superseded, delete it". Whether Hub adopts this repo through these
+ * channels or through the host protocol is an OPEN question owned by the Hub landing, and this is
+ * a published contract: removing an export is a breaking change to a package other compositions
+ * may already import. It stays until that adoption decides, and then it is retired deliberately
+ * with a major bump — not quietly, as tidying.
+ * ⚠️ What stays here is correctly Electron-resident: this is the renderer's IPC surface, and a
+ * headless host has no renderer to serve.
+ */
+export declare function setupPermissionIPC(): void;
+//# sourceMappingURL=permissionIpc.d.ts.map

package/dist/permissionIpc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissionIpc.d.ts","sourceRoot":"","sources":["../src/permissionIpc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAgBH,wBAAgB,kBAAkB,IAAI,IAAI,CAsFzC"}

package/dist/permissionIpc.js

@@ -0,0 +1,101 @@
+/**
+ * The Electron IPC surface for the SDK-native agent — split out of `sdkAgent.ts` 2026-08-17.
+ *
+ * 🔴 This exists so the AGENT LOOP can run without Electron.
+ *
+ * `sdkAgent.ts` is 6,000+ lines and looked deeply Electron-coupled. It was not: measured, the
+ * whole runtime dependency was `dialog` (imported, NEVER used), one `app.isPackaged` read, and
+ * these `ipcMain.handle` registrations — all of which lived in this single function at the
+ * bottom of the file. The loop itself uses `mainWindow` purely as an outbound event channel
+ * (`webContents.send`) plus a liveness check (`isDestroyed`).
+ *
+ * A module-level `import { ipcMain } from 'electron'` is enough to make the whole module
+ * unloadable in a plain Node process, so moving these 90 lines is what lets a headless host
+ * import the loop at all. That is the blocker for ADE step 5: `xeno-agent-cli` cannot become a
+ * pure surface while the only sdk-native lane needs a renderer window, and the CLI already runs
+ * this same loop headless today — so the work is RELOCATION, not new capability.
+ *
+ *
+ * @unwired-by-design Nothing in this repo calls it, and nothing ever has — verified against the
+ * pre-split tree, so this is not fallout from the 2026-08-17 refactor. It is a PUBLISHED export of
+ * `@xenosystem/agent-interface-electron-host` (0.1.2, ships `dist`) for an Electron composition
+ * that drives the SDK loop DIRECTLY over these `agent:*` channels.
+ *
+ * The standalone app deliberately does not: `apps/desktop/src/main/composeHost.ts` answers
+ * permissions through `sdkControlService`, i.e. over the host protocol, which is the direction
+ * the ADE spec takes every surface. Confirmed in the BUILT output as well as the source — the
+ * bundled chunk contains the declaration and the export, and no call.
+ *
+ * ⚠️ Do not read that as "superseded, delete it". Whether Hub adopts this repo through these
+ * channels or through the host protocol is an OPEN question owned by the Hub landing, and this is
+ * a published contract: removing an export is a breaking change to a package other compositions
+ * may already import. It stays until that adoption decides, and then it is retired deliberately
+ * with a major bump — not quietly, as tidying.
+ * ⚠️ What stays here is correctly Electron-resident: this is the renderer's IPC surface, and a
+ * headless host has no renderer to serve.
+ */
+import { ipcMain } from 'electron';
+import { answerChooseDirectoryRequest, answerWorkspacePlacementRequest, pendingChooseDirectoryRequestCount, pendingWorkspacePlacementRequestCount, } from '@xenosystem/agent-interface-host/node';
+import { answerSdkAskUser, createSdkNativeControlService, denySdkAccess, grantSdkAccess, logAgentDebug, } from './sdkAgent.js';
+export function setupPermissionIPC() {
+    const sdkControl = createSdkNativeControlService();
+    ipcMain.handle('agent:grant-access', async (_, params) => grantSdkAccess(params));
+    ipcMain.handle('agent:deny-access', async (_, params) => denySdkAccess(params));
+    ipcMain.handle('agent:answer-ask-user', async (_, params) => answerSdkAskUser(params));
+    ipcMain.handle('agent:answer-choose-directory', async (_, params) => {
+        const result = answerChooseDirectoryRequest(params);
+        if (!result.success) {
+            logAgentDebug('ChooseDirectory answer failed: no pending request', {
+                chooseDirectoryId: result.chooseDirectoryId || null,
+                requestId: result.requestId || null,
+                pendingCount: pendingChooseDirectoryRequestCount(),
+            });
+            return { success: false, error: result.error || 'No pending ChooseDirectory request found' };
+        }
+        logAgentDebug('ChooseDirectory answer resolved', {
+            chooseDirectoryId: result.chooseDirectoryId,
+            requestId: result.requestId,
+            cancelled: result.cancelled,
+            selectedDirectory: result.path || null,
+            error: result.responseError || null,
+        });
+        return { success: true };
+    });
+    ipcMain.handle('agent:answer-workspace-placement', async (_, params) => {
+        const result = answerWorkspacePlacementRequest(params);
+        if (!result.success) {
+            logAgentDebug('ChooseWorkspacePlacement answer failed: no pending request', {
+                workspacePlacementId: result.workspacePlacementId || null,
+                requestId: result.requestId || null,
+                pendingCount: pendingWorkspacePlacementRequestCount(),
+                error: result.error || null,
+            });
+            return { success: false, error: result.error || 'No pending ChooseWorkspacePlacement request found' };
+        }
+        logAgentDebug('ChooseWorkspacePlacement answer resolved', {
+            workspacePlacementId: result.workspacePlacementId,
+            requestId: result.requestId,
+            choice: result.response?.choice || null,
+            directory: result.response?.directory || null,
+            workspaceName: result.response?.workspaceName || null,
+            cancelled: result.response?.cancelled === true,
+            error: result.response?.error || null,
+        });
+        return { success: true };
+    });
+    ipcMain.handle('agent:sdk-session-list', async (_, params) => (sdkControl.listSessions(asSdkControlParams(params))));
+    ipcMain.handle('agent:sdk-session-show', async (_, params) => (sdkControl.showSession(asSdkControlParams(params))));
+    ipcMain.handle('agent:sdk-session-attach', async (_, params) => (sdkControl.attachSession(asSdkControlParams(params))));
+    ipcMain.handle('agent:sdk-session-detach', async (_, params) => (sdkControl.detachSession(asSdkControlParams(params))));
+    ipcMain.handle('agent:sdk-session-delete', async (_, params) => (sdkControl.deleteSession(asSdkControlParams(params))));
+    ipcMain.handle('agent:sdk-session-clean', async (_, params) => (sdkControl.cleanSessions(asSdkControlParams(params))));
+    ipcMain.handle('agent:sdk-checkpoint-list', async (_, params) => (sdkControl.listCheckpoints(asSdkControlParams(params))));
+    ipcMain.handle('agent:sdk-checkpoint-restore', async (_, params) => (sdkControl.restoreCheckpoint(asSdkControlParams(params))));
+    ipcMain.handle('agent:sdk-checkpoint-delete', async (_, params) => (sdkControl.deleteCheckpoint(asSdkControlParams(params))));
+    ipcMain.handle('agent:sdk-task-output', async (_, params) => (sdkControl.readTaskOutput(asSdkControlParams(params))));
+    ipcMain.handle('agent:sdk-task-stop', async (_, params) => (sdkControl.stopTask(asSdkControlParams(params))));
+}
+function asSdkControlParams(params) {
+    return (params && typeof params === 'object' ? params : {});
+}
+//# sourceMappingURL=permissionIpc.js.map

package/dist/permissionIpc.js.map

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