@xenosystem/agent-interface-runtime 0.1.12

package/dist/hostServices.js

@@ -0,0 +1,74 @@
+/**
+ * The host services every composition must build the same way.
+ *
+ * ## 🔴 Why this module exists
+ *
+ * `composeHost.ts` is the shared composition ADE §9 step 3 is heading for, and
+ * `index.ts` — the Electron main the user actually launches — still builds its
+ * own `AgentHostCoordinator`. That fork is real and is being closed in one
+ * deliberate commit, not as a side effect of feature work.
+ *
+ * Meanwhile the four §5 services were mounted in `composeHost` only, which
+ * meant they reached the DETACHED host and nobody who starts the app. The gate
+ * in `packages/host/src/serviceMounting.test.ts` now asks the sharper question
+ * — "does this reach the SHIPPED app" — and named them as an adoption gap.
+ *
+ * Closing that gap by pasting the constructions into `index.ts` would answer
+ * the gate and create a worse defect: two spellings of the same decision, in
+ * the two files least likely to be read together. The ecosystem rule is that a
+ * rule belongs in the shared callee and there must be exactly ONE spelling of
+ * it, so the decisions live here and both compositions call this.
+ *
+ * ## What is a decision, and what is glue
+ *
+ * Only choices that must not diverge are here. `onRunActivity` is NOT: it binds
+ * to the coordinator that composition builds, so the two are genuinely
+ * different values rather than one rule written twice.
+ */
+import { AgentSessionService, CoordinationService, InMemoryWorkspaceKnowledgeStore, IntakeService, WorkspaceKnowledgeService, WorkspaceTodoIntakeSource, } from '@xenosystem/agent-interface-host/node';
+export function createSharedHostServices(options) {
+    /**
+     * Workspace knowledge — ADE §5.8.
+     *
+     * 🔴 `durable: false` is the TRUTH, not a placeholder. The only store that
+     * exists is in-memory, so facts are lost on quit — and the panel's first line
+     * says so. Claiming durability here would make the surface lie on our behalf;
+     * the honest warning is what makes the feature safe to use at all.
+     */
+    const knowledgeService = new WorkspaceKnowledgeService({
+        store: new InMemoryWorkspaceKnowledgeStore(),
+        durable: false,
+    });
+    /**
+     * Intake — ADE §5.1.
+     *
+     * A repository-TODO source needs the user's project, and the only tree the
+     * host may read is one granted through a native dialog — which is why the
+     * roots are resolved at POLL time, not here.
+     *
+     * With no grants yet this reports an empty inbox rather than a failure:
+     * correct for a fresh install, and different from "the source could not be
+     * read", which §5.1 requires to surface as an INCOMPLETE inbox.
+     */
+    const intakeService = new IntakeService({
+        sources: [new WorkspaceTodoIntakeSource({ resolveRoots: options.resolveIntakeRoots })],
+    });
+    /**
+     * Sessions — ADE §2.8.
+     *
+     * No native module is involved, which is why this is constructed here rather
+     * than behind a surface capability: `node-pty` becomes necessary only when
+     * the `native-tui` lane exists, and it does not.
+     */
+    const sessionService = new AgentSessionService();
+    /** Coordination — ADE §5.2b. */
+    const coordinationService = new CoordinationService();
+    const coordinationPort = {
+        send: (input) => coordinationService.send(input),
+        peers: (callerRunId) => coordinationService.peers(callerRunId),
+        runSummary: (callerRunId, targetRunId) => coordinationService.runSummary(callerRunId, targetRunId),
+        acquireClaim: (scope, runId) => coordinationService.acquireClaim(scope, runId),
+    };
+    return { knowledgeService, intakeService, sessionService, coordinationService, coordinationPort };
+}
+//# sourceMappingURL=hostServices.js.map

package/dist/hostServices.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hostServices.js","sourceRoot":"","sources":["../src/hostServices.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,+BAA+B,EAC/B,aAAa,EACb,yBAAyB,EACzB,yBAAyB,GAE1B,MAAM,uCAAuC,CAAA;AA8B9C,MAAM,UAAU,wBAAwB,CACtC,OAAiC;IAEjC;;;;;;;OAOG;IACH,MAAM,gBAAgB,GAAG,IAAI,yBAAyB,CAAC;QACrD,KAAK,EAAE,IAAI,+BAA+B,EAAE;QAC5C,OAAO,EAAE,KAAK;KACf,CAAC,CAAA;IAEF;;;;;;;;;;OAUG;IACH,MAAM,aAAa,GAAG,IAAI,aAAa,CAAC;QACtC,OAAO,EAAE,CAAC,IAAI,yBAAyB,CAAC,EAAE,YAAY,EAAE,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAC;KACvF,CAAC,CAAA;IAEF;;;;;;OAMG;IACH,MAAM,cAAc,GAAG,IAAI,mBAAmB,EAAE,CAAA;IAEhD,gCAAgC;IAChC,MAAM,mBAAmB,GAAG,IAAI,mBAAmB,EAAE,CAAA;IACrD,MAAM,gBAAgB,GAAyB;QAC7C,IAAI,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,mBAAmB,CAAC,IAAI,CAAC,KAAK,CAAC;QAChD,KAAK,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC,mBAAmB,CAAC,KAAK,CAAC,WAAW,CAAC;QAC9D,UAAU,EAAE,CAAC,WAAW,EAAE,WAAW,EAAE,EAAE,CAAC,mBAAmB,CAAC,UAAU,CAAC,WAAW,EAAE,WAAW,CAAC;QAClG,YAAY,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,mBAAmB,CAAC,YAAY,CAAC,KAAK,EAAE,KAAK,CAAC;KAC/E,CAAA;IAED,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,cAAc,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,CAAA;AACnG,CAAC"}

package/dist/hostSupervisorAdapter.d.ts

@@ -0,0 +1,31 @@
+import { attachToLocalAgentHost, type LocalAgentHostAuthoritySession } from '@xenosystem/agent-interface-client/local';
+import { superviseDetachedHost, type DetachedHostSupervisorHandle } from '@xenosystem/agent-interface-host/node';
+export interface EnsureSharedAgentHostOptions {
+    homeDirectory: string;
+    hostVersion: string;
+    launcherInstanceId: string;
+    execPath: string;
+    entryPath: string;
+    hostRootDirectory?: string;
+    env?: NodeJS.ProcessEnv;
+    readyTimeoutMs?: number;
+    attachAttempts?: number;
+    attachRetryDelayMs?: number;
+    /** Test seam. Production callers leave this absent. */
+    attachFn?: typeof attachToLocalAgentHost;
+    /** Test seam. Production callers leave this absent. */
+    superviseFn?: typeof superviseDetachedHost;
+}
+export interface SharedAgentHostAttachment {
+    session: LocalAgentHostAuthoritySession;
+    /** True only when this launcher won the race to start the canonical host. */
+    launched: boolean;
+    /** Present for the launcher that started the host; ordinary surface disposal leaves it alive. */
+    supervisor?: DetachedHostSupervisorHandle;
+}
+/**
+ * Attach to the one per-user Agent host, starting the canonical detached runtime when absent.
+ * Two products may race here: the lease chooses one host and every loser joins that winner.
+ */
+export declare function ensureSharedAgentHost(options: EnsureSharedAgentHostOptions): Promise<SharedAgentHostAttachment>;
+//# sourceMappingURL=hostSupervisorAdapter.d.ts.map

package/dist/hostSupervisorAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hostSupervisorAdapter.d.ts","sourceRoot":"","sources":["../src/hostSupervisorAdapter.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EAEtB,KAAK,8BAA8B,EACpC,MAAM,0CAA0C,CAAA;AACjD,OAAO,EACL,qBAAqB,EACrB,KAAK,4BAA4B,EAElC,MAAM,uCAAuC,CAAA;AAE9C,MAAM,WAAW,4BAA4B;IAC3C,aAAa,EAAE,MAAM,CAAA;IACrB,WAAW,EAAE,MAAM,CAAA;IACnB,kBAAkB,EAAE,MAAM,CAAA;IAC1B,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;IACvB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,uDAAuD;IACvD,QAAQ,CAAC,EAAE,OAAO,sBAAsB,CAAA;IACxC,uDAAuD;IACvD,WAAW,CAAC,EAAE,OAAO,qBAAqB,CAAA;CAC3C;AAED,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,8BAA8B,CAAA;IACvC,6EAA6E;IAC7E,QAAQ,EAAE,OAAO,CAAA;IACjB,iGAAiG;IACjG,UAAU,CAAC,EAAE,4BAA4B,CAAA;CAC1C;AAED;;;GAGG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,4BAA4B,GACpC,OAAO,CAAC,yBAAyB,CAAC,CAqDpC"}

package/dist/hostSupervisorAdapter.js

@@ -0,0 +1,59 @@
+import { attachToLocalAgentHost, resolveLocalAgentHostRoot, } from '@xenosystem/agent-interface-client/local';
+import { superviseDetachedHost, } from '@xenosystem/agent-interface-host/node';
+/**
+ * Attach to the one per-user Agent host, starting the canonical detached runtime when absent.
+ * Two products may race here: the lease chooses one host and every loser joins that winner.
+ */
+export async function ensureSharedAgentHost(options) {
+    const attach = options.attachFn ?? attachToLocalAgentHost;
+    const supervise = options.superviseFn ?? superviseDetachedHost;
+    const rootDirectory = resolveLocalAgentHostRoot({
+        homeDirectory: options.homeDirectory,
+        ...(options.hostRootDirectory ? { hostRootDirectory: options.hostRootDirectory } : {}),
+    });
+    const existing = await attach({ rootDirectory });
+    if (existing.attached)
+        return { session: existing.session, launched: false };
+    let supervisor;
+    let launchError;
+    try {
+        const launchOptions = {
+            execPath: options.execPath,
+            entryPath: options.entryPath,
+            env: {
+                ...options.env,
+                XENO_AGENT_DETACHED_HOME: options.homeDirectory,
+                XENO_AGENT_DETACHED_VERSION: options.hostVersion,
+                XENO_AGENT_DETACHED_INSTANCE: `${options.launcherInstanceId}-host`,
+                ...(options.hostRootDirectory ? { XENO_AGENT_HOST_ROOT: options.hostRootDirectory } : {}),
+            },
+            ...(options.readyTimeoutMs === undefined ? {} : { readyTimeoutMs: options.readyTimeoutMs }),
+        };
+        supervisor = await supervise(launchOptions);
+    }
+    catch (error) {
+        // Another product may have won between our first attachment attempt and spawn.
+        launchError = error;
+    }
+    const attempts = Math.max(1, options.attachAttempts ?? 20);
+    const retryDelay = Math.max(0, options.attachRetryDelayMs ?? 100);
+    let detail = existing.detail;
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+        const result = await attach({ rootDirectory });
+        if (result.attached) {
+            return {
+                session: result.session,
+                launched: supervisor !== undefined,
+                ...(supervisor ? { supervisor } : {}),
+            };
+        }
+        detail = result.detail;
+        if (attempt + 1 < attempts && retryDelay > 0) {
+            await new Promise((resolve) => setTimeout(resolve, retryDelay));
+        }
+    }
+    await supervisor?.stop().catch(() => undefined);
+    const reason = launchError instanceof Error ? launchError.message : String(launchError ?? detail);
+    throw new Error(`The canonical XENO Agent host could not be started or attached: ${reason}`);
+}
+//# sourceMappingURL=hostSupervisorAdapter.js.map

package/dist/hostSupervisorAdapter.js.map

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

package/dist/node.d.ts

@@ -0,0 +1,7 @@
+export * from './composeHost.js';
+export * from './cloudOptions.js';
+export * from './hostLanePolicy.js';
+export * from './hostServices.js';
+export * from './hostSupervisorAdapter.js';
+export * from './observationConfig.js';
+//# sourceMappingURL=node.d.ts.map

package/dist/node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAA;AAChC,cAAc,mBAAmB,CAAA;AACjC,cAAc,qBAAqB,CAAA;AACnC,cAAc,mBAAmB,CAAA;AACjC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,wBAAwB,CAAA"}

package/dist/node.js

@@ -0,0 +1,7 @@
+export * from './composeHost.js';
+export * from './cloudOptions.js';
+export * from './hostLanePolicy.js';
+export * from './hostServices.js';
+export * from './hostSupervisorAdapter.js';
+export * from './observationConfig.js';
+//# sourceMappingURL=node.js.map

package/dist/node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.js","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAA;AAChC,cAAc,mBAAmB,CAAA;AACjC,cAAc,qBAAqB,CAAA;AACnC,cAAc,mBAAmB,CAAA;AACjC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,wBAAwB,CAAA"}

package/dist/observationConfig.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Whether this shared runtime observes runs, and against what.
+ *
+ * Pure and side-effect free, for the same reason `updaterPolicy.ts` is: the
+ * decision rules are the part worth testing, and a rule that lives inside the
+ * composition root can only be tested by booting Electron.
+ *
+ * ## Absent configuration means NO OBSERVATION — never a fake one
+ *
+ * Tier-1 observation needs a running `xeno-use`. Most installations do not have
+ * one, and the honest answer there is that review is unavailable: the host
+ * mounts no observation service, `capabilityFor` drops below tier 1, and
+ * `mayLand` refuses for want of a diff. Every one of those behaviours already
+ * exists and is correct.
+ *
+ * The tempting alternative — mount the service anyway so the wiring is "always
+ * there" — produces a service that is registered and permanently empty, which
+ * is indistinguishable from a run that changed nothing. That is the false-clean
+ * diff the whole path exists to prevent, arrived at by way of tidiness.
+ *
+ * ## Half-configured is DISABLED, and says so
+ *
+ * A URL with no token authenticates nothing, so every call would 401 and every
+ * run would go unobserved anyway — but silently, one failure per run, with no
+ * hint that the cause was configuration. Resolving it to `disabled` with a
+ * reason turns a recurring runtime mystery into one line at startup. This is
+ * the same failure electron-builder has with `CSC_LINK` set and
+ * `CSC_KEY_PASSWORD` missing, and the same answer: a half-configured route must
+ * fail loudly rather than quietly produce the wrong thing.
+ */
+export interface ObservationConfig {
+    enabled: boolean;
+    baseUrl?: string;
+    token?: string;
+    image?: string;
+    /** Present whenever observation is off for a reason worth telling an operator. */
+    reason?: string;
+}
+export interface ObservationEnv {
+    XENO_AGENT_USE_URL?: string | undefined;
+    XENO_AGENT_USE_TOKEN?: string | undefined;
+    XENO_AGENT_USE_IMAGE?: string | undefined;
+}
+export declare function resolveObservationConfig(env: ObservationEnv): ObservationConfig;
+//# sourceMappingURL=observationConfig.d.ts.map

package/dist/observationConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observationConfig.d.ts","sourceRoot":"","sources":["../src/observationConfig.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,OAAO,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,kFAAkF;IAClF,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC,oBAAoB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACzC,oBAAoB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC1C;AAED,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,cAAc,GAAG,iBAAiB,CA4C/E"}

package/dist/observationConfig.js

@@ -0,0 +1,78 @@
+/**
+ * Whether this shared runtime observes runs, and against what.
+ *
+ * Pure and side-effect free, for the same reason `updaterPolicy.ts` is: the
+ * decision rules are the part worth testing, and a rule that lives inside the
+ * composition root can only be tested by booting Electron.
+ *
+ * ## Absent configuration means NO OBSERVATION — never a fake one
+ *
+ * Tier-1 observation needs a running `xeno-use`. Most installations do not have
+ * one, and the honest answer there is that review is unavailable: the host
+ * mounts no observation service, `capabilityFor` drops below tier 1, and
+ * `mayLand` refuses for want of a diff. Every one of those behaviours already
+ * exists and is correct.
+ *
+ * The tempting alternative — mount the service anyway so the wiring is "always
+ * there" — produces a service that is registered and permanently empty, which
+ * is indistinguishable from a run that changed nothing. That is the false-clean
+ * diff the whole path exists to prevent, arrived at by way of tidiness.
+ *
+ * ## Half-configured is DISABLED, and says so
+ *
+ * A URL with no token authenticates nothing, so every call would 401 and every
+ * run would go unobserved anyway — but silently, one failure per run, with no
+ * hint that the cause was configuration. Resolving it to `disabled` with a
+ * reason turns a recurring runtime mystery into one line at startup. This is
+ * the same failure electron-builder has with `CSC_LINK` set and
+ * `CSC_KEY_PASSWORD` missing, and the same answer: a half-configured route must
+ * fail loudly rather than quietly produce the wrong thing.
+ */
+export function resolveObservationConfig(env) {
+    const baseUrl = (env.XENO_AGENT_USE_URL ?? '').trim();
+    const token = (env.XENO_AGENT_USE_TOKEN ?? '').trim();
+    const image = (env.XENO_AGENT_USE_IMAGE ?? '').trim();
+    // Nothing configured is the ordinary case and not a problem, so it carries no
+    // reason: an operator who never asked for observation should not be told
+    // every startup that they do not have it.
+    if (!baseUrl && !token)
+        return { enabled: false };
+    if (!baseUrl) {
+        return { enabled: false, reason: 'XENO_AGENT_USE_TOKEN is set but XENO_AGENT_USE_URL is not, so run observation is off.' };
+    }
+    if (!token) {
+        return { enabled: false, reason: 'XENO_AGENT_USE_URL is set but XENO_AGENT_USE_TOKEN is not, so run observation is off.' };
+    }
+    let parsed;
+    try {
+        parsed = new URL(baseUrl);
+    }
+    catch {
+        return { enabled: false, reason: `XENO_AGENT_USE_URL is not a valid URL, so run observation is off.` };
+    }
+    // 🔴 http: is allowed ONLY on the loopback interface. `xeno-use` is designed
+    // as a local sidecar, and its bearer token is the whole authorization — over
+    // plaintext to another host that token is readable by anything on the path,
+    // and it authorizes creating containers with host directories mounted into
+    // them. A remote endpoint must be https.
+    if (parsed.protocol === 'http:' && !isLoopback(parsed.hostname)) {
+        return {
+            enabled: false,
+            reason: 'XENO_AGENT_USE_URL uses http: to a non-loopback host, which would send the bearer token in plaintext. Use https:, so run observation is off.',
+        };
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        return { enabled: false, reason: `XENO_AGENT_USE_URL must be http: or https:, so run observation is off.` };
+    }
+    return {
+        enabled: true,
+        baseUrl: baseUrl.replace(/\/+$/, ''),
+        token,
+        ...(image ? { image } : {}),
+    };
+}
+function isLoopback(hostname) {
+    const host = hostname.replace(/^\[|\]$/g, '').toLowerCase();
+    return host === 'localhost' || host === '127.0.0.1' || host === '::1' || host.startsWith('127.');
+}
+//# sourceMappingURL=observationConfig.js.map

package/dist/observationConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observationConfig.js","sourceRoot":"","sources":["../src/observationConfig.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAiBH,MAAM,UAAU,wBAAwB,CAAC,GAAmB;IAC1D,MAAM,OAAO,GAAG,CAAC,GAAG,CAAC,kBAAkB,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAA;IACrD,MAAM,KAAK,GAAG,CAAC,GAAG,CAAC,oBAAoB,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAA;IACrD,MAAM,KAAK,GAAG,CAAC,GAAG,CAAC,oBAAoB,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAA;IAErD,8EAA8E;IAC9E,yEAAyE;IACzE,0CAA0C;IAC1C,IAAI,CAAC,OAAO,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAA;IAEjD,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,uFAAuF,EAAE,CAAA;IAC5H,CAAC;IACD,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,uFAAuF,EAAE,CAAA;IAC5H,CAAC;IAED,IAAI,MAAW,CAAA;IACf,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAA;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,mEAAmE,EAAE,CAAA;IACxG,CAAC;IACD,6EAA6E;IAC7E,6EAA6E;IAC7E,4EAA4E;IAC5E,2EAA2E;IAC3E,yCAAyC;IACzC,IAAI,MAAM,CAAC,QAAQ,KAAK,OAAO,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;QAChE,OAAO;YACL,OAAO,EAAE,KAAK;YACd,MAAM,EAAE,8IAA8I;SACvJ,CAAA;IACH,CAAC;IACD,IAAI,MAAM,CAAC,QAAQ,KAAK,OAAO,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAChE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,wEAAwE,EAAE,CAAA;IAC7G,CAAC;IAED,OAAO;QACL,OAAO,EAAE,IAAI;QACb,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;QACpC,KAAK;QACL,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC5B,CAAA;AACH,CAAC;AAED,SAAS,UAAU,CAAC,QAAgB;IAClC,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,WAAW,EAAE,CAAA;IAC3D,OAAO,IAAI,KAAK,WAAW,IAAI,IAAI,KAAK,WAAW,IAAI,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAA;AAClG,CAAC"}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@xenosystem/agent-interface-runtime",
+  "version": "0.1.12",
+  "license": "UNLICENSED",
+  "description": "Canonical XENO Agent host composition and launchable detached runtime.",
+  "type": "module",
+  "main": "./dist/node.js",
+  "types": "./dist/node.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/node.d.ts",
+      "import": "./dist/node.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "import": "./dist/node.js"
+    },
+    "./detached-entry": {
+      "types": "./dist/detachedHostEntry.d.ts",
+      "import": "./dist/detachedHostEntry.js",
+      "default": "./dist/detachedHostEntry.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/XENO-CORPORATION/xeno-agent-interface.git",
+    "directory": "packages/runtime"
+  },
+  "dependencies": {
+    "@xenosystem/acp-agent": "0.2.6",
+    "@xenosystem/agent-interface-client": "0.1.12",
+    "@xenosystem/agents-client": "0.1.12",
+    "@xenosystem/agent-interface-electron-host": "0.1.12",
+    "@xenosystem/agent-interface-host": "0.1.12",
+    "@xenosystem/agent-interface-contract": "0.1.12"
+  },
+  "scripts": {}
+}