@xenosystem/agent-interface-electron-host 0.1.32 → 0.1.33

package/dist/desktopDocumentConnections.d.ts

@@ -0,0 +1,30 @@
+import type { AgentHostClientIdentity, AgentHostEvent, AgentHostTransport } from '@xenosystem/agent-interface-contract';
+export interface DesktopAttachedSession {
+    role: string;
+    descriptor: {
+        instanceId: string;
+        endpoint: string;
+    };
+    transport: AgentHostTransport;
+    close(): Promise<void>;
+}
+/** Each document owns a client socket, never the shared host authority. Socket
+ * loss then reaches the existing canonical server releaseClient path exactly. */
+export declare class DesktopDocumentConnections {
+    private readonly options;
+    private readonly entries;
+    private closing;
+    constructor(options: {
+        attach: () => Promise<DesktopAttachedSession>;
+        expectedAuthority: () => {
+            instanceId: string;
+            endpoint: string;
+        };
+        onEvent: (identity: AgentHostClientIdentity, event: AgentHostEvent) => void;
+    });
+    request(identity: AgentHostClientIdentity, dispatch: (transport: AgentHostTransport) => Promise<unknown>): Promise<unknown>;
+    retire(identity: Pick<AgentHostClientIdentity, 'instanceId'>): Promise<void>;
+    close(): Promise<void>;
+    private create;
+}
+//# sourceMappingURL=desktopDocumentConnections.d.ts.map

package/dist/desktopDocumentConnections.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"desktopDocumentConnections.d.ts","sourceRoot":"","sources":["../src/desktopDocumentConnections.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAA;AAEvH,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAA;IACpD,SAAS,EAAE,kBAAkB,CAAA;IAC7B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACvB;AAGD;iFACiF;AACjF,qBAAa,0BAA0B;IAGzB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2B;IACnD,OAAO,CAAC,OAAO,CAAQ;gBACM,OAAO,EAAE;QACpC,MAAM,EAAE,MAAM,OAAO,CAAC,sBAAsB,CAAC,CAAA;QAC7C,iBAAiB,EAAE,MAAM;YAAE,UAAU,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAA;SAAE,CAAA;QACjE,OAAO,EAAE,CAAC,QAAQ,EAAE,uBAAuB,EAAE,KAAK,EAAE,cAAc,KAAK,IAAI,CAAA;KAC5E;IAEK,OAAO,CAAC,QAAQ,EAAE,uBAAuB,EAAE,QAAQ,EAAE,CAAC,SAAS,EAAE,kBAAkB,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;IAYjI,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,uBAAuB,EAAE,YAAY,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBtE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5B,OAAO,CAAC,MAAM;CAyBf"}

package/dist/desktopDocumentConnections.js

@@ -0,0 +1,81 @@
+/** Each document owns a client socket, never the shared host authority. Socket
+ * loss then reaches the existing canonical server releaseClient path exactly. */
+export class DesktopDocumentConnections {
+    options;
+    entries = new Map();
+    closing = false;
+    constructor(options) {
+        this.options = options;
+    }
+    async request(identity, dispatch) {
+        if (this.closing)
+            throw new Error('Desktop document connections are closing.');
+        const entry = this.entries.get(identity.instanceId) || this.create(identity);
+        if (entry.retired)
+            throw new Error('Desktop document connection was retired.');
+        const session = await entry.ready;
+        if (entry.retired || this.closing) {
+            await this.retire(identity);
+            throw new Error('Desktop document connection was retired while attaching.');
+        }
+        return dispatch(session.transport);
+    }
+    retire(identity) {
+        const entry = this.entries.get(identity.instanceId);
+        if (!entry)
+            return Promise.resolve();
+        entry.retired = true;
+        entry.unsubscribe?.();
+        delete entry.unsubscribe;
+        if (entry.retirement)
+            return entry.retirement;
+        const retirement = (async () => {
+            try {
+                await entry.ready;
+            }
+            catch { /* An attached session, if any, is retained below. */ }
+            if (entry.session)
+                await entry.session.close();
+            if (this.entries.get(identity.instanceId) === entry)
+                this.entries.delete(identity.instanceId);
+        })();
+        entry.retirement = retirement;
+        void retirement.finally(() => { if (entry.retirement === retirement)
+            delete entry.retirement; }).catch(() => { });
+        return retirement;
+    }
+    async close() {
+        this.closing = true;
+        await Promise.all([...this.entries.keys()].map(instanceId => this.retire({ instanceId })));
+    }
+    create(identity) {
+        const expected = this.options.expectedAuthority();
+        const entry = { retired: false, ready: Promise.resolve(undefined) };
+        this.entries.set(identity.instanceId, entry);
+        entry.ready = Promise.resolve().then(async () => {
+            if (entry.retired)
+                throw new Error('Desktop document retired before attachment.');
+            const session = await this.options.attach();
+            // Never close an owner session from this client-only pool, even if an
+            // erroneous injected factory hands one back.
+            if (session.role !== 'attached-client')
+                throw new Error('Desktop documents may only attach to an existing authority.');
+            entry.session = session;
+            if (session.descriptor.instanceId !== expected.instanceId || session.descriptor.endpoint !== expected.endpoint) {
+                entry.retired = true;
+                await session.close();
+                delete entry.session;
+                throw new Error('Desktop shared authority changed during document attachment.');
+            }
+            if (!entry.retired)
+                entry.unsubscribe = session.transport.subscribe(event => {
+                    if (!entry.retired && this.entries.get(identity.instanceId) === entry)
+                        this.options.onEvent(identity, event);
+                });
+            return session;
+        });
+        void entry.ready.catch(() => { });
+        return entry;
+    }
+}
+//# sourceMappingURL=desktopDocumentConnections.js.map

package/dist/desktopDocumentConnections.js.map

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

package/dist/desktopSenderAuthority.d.ts

@@ -0,0 +1,45 @@
+import { type AgentHostClientIdentity } from '@xenosystem/agent-interface-contract';
+export declare const DESKTOP_BOOTSTRAP_CHANNEL = "xeno-agent-host:bootstrap";
+/** The two other channel names a product must agree on with its preload. */
+export declare const AGENT_HOST_REQUEST_CHANNEL = "xeno-agent-host:request";
+export declare const AGENT_HOST_EVENT_CHANNEL = "xeno-agent-host:event";
+export interface DesktopDocumentReceipt {
+    identity: AgentHostClientIdentity;
+    token: string;
+}
+export declare function sameDesktopDocumentUrl(actual: string, expected: string): boolean;
+/**
+ * Which product this authority mints identities for.
+ *
+ * Parameters rather than constants because this class is the ONLY safe way for an Electron
+ * product to mint a client identity, and every product needs its own. Hard-coding
+ * `xeno-agent-desktop`/`standalone-desktop` here is what kept it app-private, and the
+ * alternative — each product writing its own copy — is a second implementation of the check
+ * that decides whether a renderer may speak to the agent host at all.
+ */
+export interface DocumentAuthorityProduct {
+    /** Stable product id, e.g. `xeno-agent-desktop`, `xeno-canvas`. */
+    clientId: string;
+    /** The surface the host will see. The embed layer refuses a client whose surface disagrees
+     *  with its mount, so this is not cosmetic. */
+    surface: AgentHostClientIdentity['surface'];
+}
+/** Main-process authority. Renderer claims never create a client identity. */
+export declare class DesktopSenderAuthority {
+    private readonly version;
+    private readonly uuid;
+    private readonly onRetire;
+    private readonly senders;
+    private readonly product;
+    constructor(version: string, uuid?: () => string, onRetire?: (identity: AgentHostClientIdentity) => void, product?: DocumentAuthorityProduct);
+    register(sender: object, allowedUrl: string): void;
+    remove(sender: object): void;
+    invalidate(sender: object): void;
+    committed(sender: object, url: string, sameDocument?: boolean): void;
+    bootstrap(sender: object, isMainFrame: boolean, url: string): DesktopDocumentReceipt;
+    assert(sender: object, isMainFrame: boolean, url: string, token: unknown, handshake?: boolean): AgentHostClientIdentity;
+    canReceive(sender: object, url: string): boolean;
+    request(sender: object, isMainFrame: boolean, url: string, token: unknown, method: string, input: unknown, dispatch: (input: unknown) => Promise<unknown>): Promise<unknown>;
+    private document;
+}
+//# sourceMappingURL=desktopSenderAuthority.d.ts.map

package/dist/desktopSenderAuthority.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"desktopSenderAuthority.d.ts","sourceRoot":"","sources":["../src/desktopSenderAuthority.ts"],"names":[],"mappings":"AACA,OAAO,EAAmD,KAAK,uBAAuB,EAAE,MAAM,sCAAsC,CAAA;AAEpI,eAAO,MAAM,yBAAyB,8BAA8B,CAAA;AACpE,4EAA4E;AAC5E,eAAO,MAAM,0BAA0B,4BAA4B,CAAA;AACnE,eAAO,MAAM,wBAAwB,0BAA0B,CAAA;AAC/D,MAAM,WAAW,sBAAsB;IAAG,QAAQ,EAAE,uBAAuB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE;AAK5F,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAMhF;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,wBAAwB;IACvC,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAA;IAChB;mDAC+C;IAC/C,OAAO,EAAE,uBAAuB,CAAC,SAAS,CAAC,CAAA;CAC5C;AAED,8EAA8E;AAC9E,qBAAa,sBAAsB;IAGrB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAAU,OAAO,CAAC,QAAQ,CAAC,IAAI;IACjE,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAH3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;IAC1D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;gBACrB,OAAO,EAAE,MAAM,EAAmB,IAAI,GAAE,MAAM,MAAmB,EAC3E,QAAQ,GAAE,CAAC,QAAQ,EAAE,uBAAuB,KAAK,IAAe,EACjF,OAAO,GAAE,wBAA4F;IAIvG,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAIlD,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAC5B,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAOhC,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,UAAQ,GAAG,IAAI;IAgBlE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,sBAAsB;IAKpF,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,UAAQ,GAAG,uBAAuB;IAMrH,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO;IAI1C,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;IAgClL,OAAO,CAAC,QAAQ;CAKjB"}

package/dist/desktopSenderAuthority.js

@@ -0,0 +1,133 @@
+import { randomUUID } from 'node:crypto';
+import { isAgentHostClientIdentity, isAgentHostHandshake } from '@xenosystem/agent-interface-contract';
+export const DESKTOP_BOOTSTRAP_CHANNEL = 'xeno-agent-host:bootstrap';
+/** The two other channel names a product must agree on with its preload. */
+export const AGENT_HOST_REQUEST_CHANNEL = 'xeno-agent-host:request';
+export const AGENT_HOST_EVENT_CHANNEL = 'xeno-agent-host:event';
+const record = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+export function sameDesktopDocumentUrl(actual, expected) {
+    try {
+        const left = new URL(actual), right = new URL(expected);
+        left.hash = '';
+        right.hash = '';
+        return !left.username && !left.password && left.href === right.href;
+    }
+    catch {
+        return false;
+    }
+}
+/** Main-process authority. Renderer claims never create a client identity. */
+export class DesktopSenderAuthority {
+    version;
+    uuid;
+    onRetire;
+    senders = new Map();
+    product;
+    constructor(version, uuid = randomUUID, onRetire = () => { }, product = { clientId: 'xeno-agent-desktop', surface: 'standalone-desktop' }) {
+        this.version = version;
+        this.uuid = uuid;
+        this.onRetire = onRetire;
+        this.product = product;
+    }
+    register(sender, allowedUrl) {
+        if (this.senders.has(sender))
+            throw new Error('Desktop sender is already registered.');
+        this.senders.set(sender, { allowedUrl });
+    }
+    remove(sender) { this.invalidate(sender); this.senders.delete(sender); }
+    invalidate(sender) {
+        const registration = this.senders.get(sender);
+        const prior = registration?.document;
+        if (registration)
+            delete registration.document;
+        if (prior)
+            this.onRetire({ ...prior.identity });
+    }
+    committed(sender, url, sameDocument = false) {
+        const registration = this.senders.get(sender);
+        if (!registration)
+            return;
+        if (sameDocument)
+            return;
+        const prior = registration.document;
+        // A foreign committed document must not retain the old page's authority.
+        this.invalidate(sender);
+        if (!sameDesktopDocumentUrl(url, registration.allowedUrl))
+            return;
+        const instanceId = this.uuid(), token = this.uuid();
+        if (!instanceId || !token || instanceId === token || instanceId === prior?.identity.instanceId || token === prior?.token
+            || [...this.senders.values()].some(item => item.document?.identity.instanceId === instanceId || item.document?.token === token)) {
+            throw new Error('Duplicate desktop document identity refused.');
+        }
+        registration.document = { identity: { clientId: this.product.clientId, clientVersion: this.version, instanceId, surface: this.product.surface }, token, acknowledged: false };
+    }
+    bootstrap(sender, isMainFrame, url) {
+        const document = this.document(sender, isMainFrame, url);
+        return { identity: { ...document.identity }, token: document.token };
+    }
+    assert(sender, isMainFrame, url, token, handshake = false) {
+        const document = this.document(sender, isMainFrame, url);
+        if (token !== document.token || (handshake && !document.acknowledged))
+            throw new Error('Desktop document authority refused.');
+        return { ...document.identity };
+    }
+    canReceive(sender, url) {
+        try {
+            return this.document(sender, true, url).acknowledged;
+        }
+        catch {
+            return false;
+        }
+    }
+    async request(sender, isMainFrame, url, token, method, input, dispatch) {
+        const identity = this.assert(sender, isMainFrame, url, token, method !== 'host.handshake');
+        const document = this.senders.get(sender).document;
+        if (!record(input))
+            throw new Error('Desktop request input is invalid.');
+        const matches = (value) => isAgentHostClientIdentity(value)
+            && value.clientId === identity.clientId && value.clientVersion === identity.clientVersion
+            && value.surface === identity.surface && value.instanceId === identity.instanceId
+            && Object.keys(value).every(key => ['clientId', 'clientVersion', 'surface', 'instanceId'].includes(key));
+        if ((method === 'host.handshake' && !matches(input.identity))
+            || ('identity' in input && !matches(input.identity))
+            || ('client' in input && !matches(input.client))
+            || (record(input.command) && !matches(input.command.client)))
+            throw new Error('Desktop request client identity refused.');
+        const current = () => this.senders.get(sender)?.document === document;
+        if (method === 'host.handshake') {
+            const fingerprint = JSON.stringify(input);
+            if (document.handshake && document.handshake !== fingerprint)
+                throw new Error('Desktop handshake changed within the document.');
+            if (document.pending)
+                return document.pending;
+            document.handshake = fingerprint;
+            const pending = dispatch(structuredClone(input)).then(result => {
+                if (!current())
+                    throw new Error('Desktop document changed during handshake.');
+                if (!isAgentHostHandshake(result) || !matches(result.surface))
+                    throw new Error('Desktop host handshake was not acknowledged.');
+                document.acknowledged = true;
+                return result;
+            });
+            document.pending = pending;
+            try {
+                return await pending;
+            }
+            finally {
+                if (current())
+                    delete document.pending;
+            }
+        }
+        const result = await dispatch(structuredClone(input));
+        if (!current())
+            throw new Error('Desktop document changed during request.');
+        return result;
+    }
+    document(sender, isMainFrame, url) {
+        const registration = this.senders.get(sender);
+        if (!isMainFrame || !registration?.document || !sameDesktopDocumentUrl(url, registration.allowedUrl))
+            throw new Error('Desktop sender is not an authorized main document.');
+        return registration.document;
+    }
+}
+//# sourceMappingURL=desktopSenderAuthority.js.map

package/dist/desktopSenderAuthority.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"desktopSenderAuthority.js","sourceRoot":"","sources":["../src/desktopSenderAuthority.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EAAE,yBAAyB,EAAE,oBAAoB,EAAgC,MAAM,sCAAsC,CAAA;AAEpI,MAAM,CAAC,MAAM,yBAAyB,GAAG,2BAA2B,CAAA;AACpE,4EAA4E;AAC5E,MAAM,CAAC,MAAM,0BAA0B,GAAG,yBAAyB,CAAA;AACnE,MAAM,CAAC,MAAM,wBAAwB,GAAG,uBAAuB,CAAA;AAI/D,MAAM,MAAM,GAAG,CAAC,KAAc,EAAoC,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;AAEzI,MAAM,UAAU,sBAAsB,CAAC,MAAc,EAAE,QAAgB;IACrE,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,EAAE,KAAK,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAA;QACvD,IAAI,CAAC,IAAI,GAAG,EAAE,CAAC;QAAC,KAAK,CAAC,IAAI,GAAG,EAAE,CAAA;QAC/B,OAAO,CAAC,IAAI,CAAC,QAAQ,IAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,IAAI,KAAK,KAAK,CAAC,IAAI,CAAA;IACrE,CAAC;IAAC,MAAM,CAAC;QAAC,OAAO,KAAK,CAAA;IAAC,CAAC;AAC1B,CAAC;AAmBD,8EAA8E;AAC9E,MAAM,OAAO,sBAAsB;IAGJ;IAAkC;IAC5C;IAHF,OAAO,GAAG,IAAI,GAAG,EAAwB,CAAA;IACzC,OAAO,CAA0B;IAClD,YAA6B,OAAe,EAAmB,OAAqB,UAAU,EAC3E,WAAwD,GAAG,EAAE,GAAE,CAAC,EACjF,UAAoC,EAAE,QAAQ,EAAE,oBAAoB,EAAE,OAAO,EAAE,oBAAoB,EAAE;QAF1E,YAAO,GAAP,OAAO,CAAQ;QAAmB,SAAI,GAAJ,IAAI,CAA2B;QAC3E,aAAQ,GAAR,QAAQ,CAAwD;QAEjF,IAAI,CAAC,OAAO,GAAG,OAAO,CAAA;IACxB,CAAC;IAED,QAAQ,CAAC,MAAc,EAAE,UAAkB;QACzC,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAA;QACtF,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,UAAU,EAAE,CAAC,CAAA;IAC1C,CAAC;IACD,MAAM,CAAC,MAAc,IAAU,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA,CAAC,CAAC;IACrF,UAAU,CAAC,MAAc;QACvB,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;QAC7C,MAAM,KAAK,GAAG,YAAY,EAAE,QAAQ,CAAA;QACpC,IAAI,YAAY;YAAE,OAAO,YAAY,CAAC,QAAQ,CAAA;QAC9C,IAAI,KAAK;YAAE,IAAI,CAAC,QAAQ,CAAC,EAAE,GAAG,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAA;IACjD,CAAC;IAED,SAAS,CAAC,MAAc,EAAE,GAAW,EAAE,YAAY,GAAG,KAAK;QACzD,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;QAC7C,IAAI,CAAC,YAAY;YAAE,OAAM;QACzB,IAAI,YAAY;YAAE,OAAM;QACxB,MAAM,KAAK,GAAG,YAAY,CAAC,QAAQ,CAAA;QACnC,yEAAyE;QACzE,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAA;QACvB,IAAI,CAAC,sBAAsB,CAAC,GAAG,EAAE,YAAY,CAAC,UAAU,CAAC;YAAE,OAAM;QACjE,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,EAAE,EAAE,KAAK,GAAG,IAAI,CAAC,IAAI,EAAE,CAAA;QACnD,IAAI,CAAC,UAAU,IAAI,CAAC,KAAK,IAAI,UAAU,KAAK,KAAK,IAAI,UAAU,KAAK,KAAK,EAAE,QAAQ,CAAC,UAAU,IAAI,KAAK,KAAK,KAAK,EAAE,KAAK;eACnH,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,UAAU,KAAK,UAAU,IAAI,IAAI,CAAC,QAAQ,EAAE,KAAK,KAAK,KAAK,CAAC,EAAE,CAAC;YAClI,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAA;QACjE,CAAC;QACD,YAAY,CAAC,QAAQ,GAAG,EAAE,QAAQ,EAAE,EAAE,QAAQ,EAAE,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,aAAa,EAAE,IAAI,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,CAAA;IAC/K,CAAC;IAED,SAAS,CAAC,MAAc,EAAE,WAAoB,EAAE,GAAW;QACzD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,CAAC,CAAA;QACxD,OAAO,EAAE,QAAQ,EAAE,EAAE,GAAG,QAAQ,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAA;IACtE,CAAC;IAED,MAAM,CAAC,MAAc,EAAE,WAAoB,EAAE,GAAW,EAAE,KAAc,EAAE,SAAS,GAAG,KAAK;QACzF,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,CAAC,CAAA;QACxD,IAAI,KAAK,KAAK,QAAQ,CAAC,KAAK,IAAI,CAAC,SAAS,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAA;QAC7H,OAAO,EAAE,GAAG,QAAQ,CAAC,QAAQ,EAAE,CAAA;IACjC,CAAC;IAED,UAAU,CAAC,MAAc,EAAE,GAAW;QACpC,IAAI,CAAC;YAAC,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC,YAAY,CAAA;QAAC,CAAC;QAAC,MAAM,CAAC;YAAC,OAAO,KAAK,CAAA;QAAC,CAAC;IACrF,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,MAAc,EAAE,WAAoB,EAAE,GAAW,EAAE,KAAc,EAAE,MAAc,EAAE,KAAc,EAAE,QAA8C;QAC7J,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,KAAK,gBAAgB,CAAC,CAAA;QAC1F,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAE,CAAC,QAAS,CAAA;QACpD,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAA;QACxE,MAAM,OAAO,GAAG,CAAC,KAAc,EAAE,EAAE,CAAC,yBAAyB,CAAC,KAAK,CAAC;eAC/D,KAAK,CAAC,QAAQ,KAAK,QAAQ,CAAC,QAAQ,IAAI,KAAK,CAAC,aAAa,KAAK,QAAQ,CAAC,aAAa;eACtF,KAAK,CAAC,OAAO,KAAK,QAAQ,CAAC,OAAO,IAAI,KAAK,CAAC,UAAU,KAAK,QAAQ,CAAC,UAAU;eAC9E,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,UAAU,EAAE,eAAe,EAAE,SAAS,EAAE,YAAY,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAA;QAC1G,IAAI,CAAC,MAAM,KAAK,gBAAgB,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;eACxD,CAAC,UAAU,IAAI,KAAK,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;eACjD,CAAC,QAAQ,IAAI,KAAK,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;eAC7C,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAA;QAC3H,MAAM,OAAO,GAAG,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,QAAQ,KAAK,QAAQ,CAAA;QACrE,IAAI,MAAM,KAAK,gBAAgB,EAAE,CAAC;YAChC,MAAM,WAAW,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAA;YACzC,IAAI,QAAQ,CAAC,SAAS,IAAI,QAAQ,CAAC,SAAS,KAAK,WAAW;gBAAE,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAA;YAC/H,IAAI,QAAQ,CAAC,OAAO;gBAAE,OAAO,QAAQ,CAAC,OAAO,CAAA;YAC7C,QAAQ,CAAC,SAAS,GAAG,WAAW,CAAA;YAChC,MAAM,OAAO,GAAG,QAAQ,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE;gBAC7D,IAAI,CAAC,OAAO,EAAE;oBAAE,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAA;gBAC7E,IAAI,CAAC,oBAAoB,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC;oBAAE,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAA;gBAC9H,QAAQ,CAAC,YAAY,GAAG,IAAI,CAAA;gBAC5B,OAAO,MAAM,CAAA;YACf,CAAC,CAAC,CAAA;YACF,QAAQ,CAAC,OAAO,GAAG,OAAO,CAAA;YAC1B,IAAI,CAAC;gBAAC,OAAO,MAAM,OAAO,CAAA;YAAC,CAAC;oBAAS,CAAC;gBAAC,IAAI,OAAO,EAAE;oBAAE,OAAO,QAAQ,CAAC,OAAO,CAAA;YAAC,CAAC;QACjF,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,CAAA;QACrD,IAAI,CAAC,OAAO,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAA;QAC3E,OAAO,MAAM,CAAA;IACf,CAAC;IAEO,QAAQ,CAAC,MAAc,EAAE,WAAoB,EAAE,GAAW;QAChE,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;QAC7C,IAAI,CAAC,WAAW,IAAI,CAAC,YAAY,EAAE,QAAQ,IAAI,CAAC,sBAAsB,CAAC,GAAG,EAAE,YAAY,CAAC,UAAU,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAA;QAC3K,OAAO,YAAY,CAAC,QAAQ,CAAA;IAC9B,CAAC;CACF"}

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+export * from './desktopSenderAuthority.js';
+export * from './desktopDocumentConnections.js';
 export * from './sdkAgent.js';
 export * from './headlessAgentSurface.js';
 export * from './sdkNativeHeadlessRunner.js';

package/dist/index.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAaA,cAAc,6BAA6B,CAAA;AAC3C,cAAc,iCAAiC,CAAA;AAC/C,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

@@ -1,3 +1,18 @@
+/*
+ * The Electron main-process boundary a product needs to host the Agent panel.
+ *
+ * 🔴 These two modules lived in `apps/desktop/src/main/` and were therefore UNPUBLISHED, which
+ * meant the standalone app was the only product that could mount the interface at all: the
+ * panel is installable from npm, and the code that decides whether a renderer may speak to the
+ * agent host was not. Any other product had to reimplement per-document identity minting,
+ * sender validation and connection pooling — a second copy of a security boundary, which is
+ * exactly the failure `XENO AGENT PANEL - SPEC.md` D7d refuses.
+ *
+ * Moved rather than ported: `apps/desktop` consumes these, so there is one implementation and
+ * its existing tests still guard it.
+ */
+export * from './desktopSenderAuthority.js';
+export * from './desktopDocumentConnections.js';
 export * from './sdkAgent.js';
 export * from './headlessAgentSurface.js';
 export * from './sdkNativeHeadlessRunner.js';

package/dist/index.js.map

@@ -1 +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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,cAAc,6BAA6B,CAAA;AAC3C,cAAc,iCAAiC,CAAA;AAC/C,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xenosystem/agent-interface-electron-host",
-  "version": "0.1.32",
+  "version": "0.1.33",
   "license": "UNLICENSED",
   "type": "module",
   "main": "./dist/index.js",
@@ -29,7 +29,9 @@
   "dependencies": {
     "@xenosystem/agent-sdk": "0.9.27",
     "@xenosystem/web-context-client": "0.1.1",
-    "@xenosystem/agent-interface-host": "0.1.32"
+    "@xenosystem/agent-interface-client": "0.1.33",
+    "@xenosystem/agent-interface-host": "0.1.33",
+    "@xenosystem/agent-interface-contract": "0.1.33"
   },
   "peerDependencies": {
     "electron": ">=44"