@xenosystem/agent-interface-host 0.1.3

package/dist/detachedHostService.d.ts

@@ -0,0 +1,77 @@
+import { type StartLocalAgentHostAuthorityOptions } from './localHostAuthority.js';
+/**
+ * DETACHED HOST SERVICE — ADE spec §9, build-order step 3.
+ *
+ * The lifecycle wrapper that lets the host own its own OS process instead of
+ * living inside the Electron main process.
+ *
+ * @unadopted-by-design ADE §9 step 3 — transport, election and lifecycle are done;
+ * the standalone app does not spawn or supervise this process yet, and cannot
+ * fully until the SDK-native lane stops threading a live `BrowserWindow` into
+ * its tool implementations (`electron-host/src/sdkAgent.ts`). Adopting it early
+ * for ACP + Cloud only IS possible — the adapter registry already refuses
+ * `sdk-native` by name — but that is a composition decision, not a wiring fix.
+ *
+ * 🔴 That marker is not decoration. `scripts/find-unwired-modules.mjs` flagged
+ * this module as the FOURTH instance of the "built, tested, unreachable" shape
+ * (after xeno-workflow's 76 node types, xeno-tools' `install`, and twice in this
+ * repo the same day), and it was right to: from outside, deliberately staged and
+ * accidentally orphaned are indistinguishable. The marker is what makes the
+ * difference visible, and it carries a reason so it can be argued with.
+ *
+ * Almost none of the hard work is here: `startLocalAgentHostAuthority` already
+ * elects a single local authority, serves it over an authenticated OS endpoint,
+ * and attaches every other process as a client. What was missing is a process
+ * whose ONLY job is to be that owner — and the lifecycle rules that make such a
+ * process safe to run unattended.
+ *
+ * ## Why this refuses to run as a client (§7.1, capability honesty)
+ *
+ * `startLocalAgentHostAuthority` is deliberately forgiving: if someone else owns
+ * the lease it hands back an attached client, because that is exactly right for
+ * a GUI that just wants to reach the host however it can.
+ *
+ * It is exactly wrong for a service whose purpose is to BE the host. Such a
+ * process, demoted to a client, would start cleanly, report healthy, hold an
+ * idle connection and serve nothing — the failure mode where a supervisor keeps
+ * restarting a process that is doing no work and saying nothing about it. So a
+ * demotion is a NAMED startup failure here, not a silent degradation.
+ *
+ * ## Why losing authority stops the process
+ *
+ * The lease can be lost — the heartbeat fails, or the file is taken over after a
+ * stall. Once that happens this process is no longer the authority, and the one
+ * thing it must not do is keep running as though it were: two writers to the
+ * same durable state is the split-brain the lease exists to prevent. It stops
+ * and reports why, leaving restart policy to whatever supervises it.
+ */
+export interface DetachedAgentHostOptions extends Omit<StartLocalAgentHostAuthorityOptions, 'onAuthorityLost'> {
+    /**
+     * Signals that trigger a graceful shutdown. Defaults to SIGINT/SIGTERM.
+     * Pass an empty array when the embedder owns signal handling.
+     */
+    shutdownSignals?: NodeJS.Signals[];
+    /** Called once the service is the elected owner and is serving requests. */
+    onReady?: (info: DetachedAgentHostReadyInfo) => void;
+    /** Called when the service stops, with the reason. */
+    onStopped?: (reason: DetachedAgentHostStopReason, error?: Error) => void;
+}
+export interface DetachedAgentHostReadyInfo {
+    endpoint: string;
+    instanceId: string;
+    protocolVersion: number;
+}
+export type DetachedAgentHostStopReason = 'requested' | 'signal' | 'authority-lost';
+export declare class DetachedAgentHostDemotedError extends Error {
+    readonly ownerInstanceId: string;
+    constructor(ownerInstanceId: string);
+}
+export interface DetachedAgentHostHandle {
+    readonly endpoint: string;
+    readonly instanceId: string;
+    /** Resolves when the service has stopped, with the reason it stopped. */
+    readonly stopped: Promise<DetachedAgentHostStopReason>;
+    stop(): Promise<void>;
+}
+export declare function runDetachedAgentHost(options: DetachedAgentHostOptions): Promise<DetachedAgentHostHandle>;
+//# sourceMappingURL=detachedHostService.d.ts.map

package/dist/detachedHostService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detachedHostService.d.ts","sourceRoot":"","sources":["../src/detachedHostService.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,mCAAmC,EACzC,MAAM,yBAAyB,CAAA;AAEhC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,MAAM,WAAW,wBACf,SAAQ,IAAI,CAAC,mCAAmC,EAAE,iBAAiB,CAAC;IACpE;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC,OAAO,EAAE,CAAA;IAClC,4EAA4E;IAC5E,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,0BAA0B,KAAK,IAAI,CAAA;IACpD,sDAAsD;IACtD,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,2BAA2B,EAAE,KAAK,CAAC,EAAE,KAAK,KAAK,IAAI,CAAA;CACzE;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;IAClB,eAAe,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,MAAM,2BAA2B,GAAG,WAAW,GAAG,QAAQ,GAAG,gBAAgB,CAAA;AAEnF,qBAAa,6BAA8B,SAAQ,KAAK;IACtD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;gBAEpB,eAAe,EAAE,MAAM;CASpC;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,2BAA2B,CAAC,CAAA;IACtD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACtB;AAED,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,uBAAuB,CAAC,CA2DlC"}

package/dist/detachedHostService.js

@@ -0,0 +1,66 @@
+import { startLocalAgentHostAuthority, } from './localHostAuthority.js';
+export class DetachedAgentHostDemotedError extends Error {
+    ownerInstanceId;
+    constructor(ownerInstanceId) {
+        super('Another process already owns the local Agent host authority '
+            + `(instance ${ownerInstanceId}). A detached host service must be the owner; `
+            + 'stop the existing owner or run this service against a different endpoint scope.');
+        this.name = 'DetachedAgentHostDemotedError';
+        this.ownerInstanceId = ownerInstanceId;
+    }
+}
+export async function runDetachedAgentHost(options) {
+    const { shutdownSignals, onReady, onStopped, ...authorityOptions } = options;
+    let session;
+    let settleStopped = () => { };
+    const stopped = new Promise((resolve) => {
+        settleStopped = resolve;
+    });
+    let stopping = false;
+    const registeredSignals = [];
+    const finish = async (reason, error) => {
+        if (stopping)
+            return;
+        stopping = true;
+        for (const { signal, handler } of registeredSignals.splice(0)) {
+            process.off(signal, handler);
+        }
+        // A lost authority has already closed the session from underneath us, and
+        // closing twice would try to release a lease we no longer hold.
+        if (reason !== 'authority-lost')
+            await session?.close().catch(() => undefined);
+        onStopped?.(reason, error);
+        settleStopped(reason);
+    };
+    session = await startLocalAgentHostAuthority({
+        ...authorityOptions,
+        onAuthorityLost: (error) => {
+            void finish('authority-lost', error);
+        },
+    });
+    if (session.role !== 'owner') {
+        const ownerInstanceId = session.descriptor.instanceId;
+        // Release the client connection before reporting: a failed startup must not
+        // leave a socket attached to someone else's host.
+        await session.close().catch(() => undefined);
+        throw new DetachedAgentHostDemotedError(ownerInstanceId);
+    }
+    for (const signal of shutdownSignals ?? ['SIGINT', 'SIGTERM']) {
+        const handler = () => { void finish('signal'); };
+        process.on(signal, handler);
+        registeredSignals.push({ signal, handler });
+    }
+    const ready = {
+        endpoint: session.descriptor.endpoint,
+        instanceId: session.descriptor.instanceId,
+        protocolVersion: session.descriptor.protocolVersion,
+    };
+    onReady?.(ready);
+    return {
+        endpoint: ready.endpoint,
+        instanceId: ready.instanceId,
+        stopped,
+        stop: async () => { await finish('requested'); },
+    };
+}
+//# sourceMappingURL=detachedHostService.js.map

package/dist/detachedHostService.js.map

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

package/dist/detachedHostSupervisor.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Spawns and watches the detached host process — ADE §9 build-order step 3.
+ *
+ * `runDetachedAgentHost` is the process's own lifecycle: it elects itself owner,
+ * refuses to run demoted, and stops when it loses the lease. This is the other
+ * half — the parent that starts it, learns when it is actually serving, and
+ * notices when it dies.
+ *
+ * ## 🔴 Readiness is a SIGNAL, never a sleep
+ *
+ * The parent has to attach as a client, and attaching before the child owns the
+ * lease means the parent wins the election instead. The two processes then both
+ * believe they are the host, which is the split-brain the lease exists to
+ * prevent — reached by way of a race that only shows up on a slow machine.
+ *
+ * So the child prints one line of JSON when it is serving, and this waits for
+ * that line. A fixed sleep would be either flaky or slow, and usually both.
+ *
+ * ## An exit is reported, never retried in a loop
+ *
+ * A supervisor that restarts unconditionally turns a permanent failure — a bad
+ * endpoint, a corrupt state directory, another owner already holding the lease —
+ * into an infinite loop that looks like activity. This reports the exit and the
+ * child's own words, and lets the caller decide. `DetachedAgentHostDemotedError`
+ * exists precisely so "someone else is already the host" arrives as a named
+ * failure rather than as a crash to retry.
+ *
+ * @unadopted-by-design ADE §9 step 3 — the child ENTRY POINT now EXISTS
+ * (`apps/desktop/src/main/detachedHostEntry.ts`) and this supervisor is proven
+ * to spawn it: `detachedHostEntry.test.ts` starts the BUILT entry through this
+ * code, connects a real client to the endpoint it publishes, and asserts a
+ * second one refuses rather than demoting. What is still missing is the app
+ * calling it — `index.ts` remains its own in-process host. The app SAYS SO when
+ * the flag is set rather than ignoring it; a requested capability that silently
+ * does nothing is the defect this marker exists to keep visible.
+ *
+ * 🔴 CORRECTED 2026-08-14. This said extracting a headless entry was "a
+ * refactor rather than a wiring step" because the composition is "written
+ * against Electron". It was not: `HostSurfaceCapabilities` has no required
+ * fields, so `surface: {}` composes a working host. The one REAL Electron
+ * coupling was a static import of the electron-host package pulling `electron`
+ * into the shared bundle chunk — invisible to every in-process test, fatal to
+ * the built entry, and now a dynamic import gated on a window.
+ */
+import { spawn } from 'node:child_process';
+/** The line the child prints once it owns the lease and is serving. */
+export interface DetachedHostReadySignal {
+    type: 'xeno-agent-detached-host-ready';
+    endpoint: string;
+    instanceId: string;
+    protocolVersion: number;
+}
+export interface DetachedHostSupervisorOptions {
+    /**
+     * Executable to run the child with.
+     *
+     * In a packaged Electron app this is `process.execPath` — the Electron binary
+     * — run with `ELECTRON_RUN_AS_NODE=1`. There is no separate node binary in the
+     * bundle, and it is the right choice rather than a workaround: the host loads
+     * `better-sqlite3`, which is rebuilt for Electron's ABI, and Electron's own
+     * Node is the runtime that ABI matches. A system `node` would fail to load it.
+     */
+    execPath: string;
+    /** Entry script for the child. */
+    entryPath: string;
+    /** Extra environment for the child, merged over the parent's. */
+    env?: Record<string, string | undefined>;
+    cwd?: string;
+    /**
+     * How long to wait for the ready line.
+     *
+     * Bounded because the failure it guards is silent: a child that starts, prints
+     * nothing and hangs would otherwise leave the app waiting forever with no
+     * window and no error.
+     */
+    readyTimeoutMs?: number;
+    /** Called when the child exits, however it exits. */
+    onExit?: (info: {
+        code: number | null;
+        signal: NodeJS.Signals | null;
+        output: string;
+    }) => void;
+    /** Injected for tests. */
+    spawnFn?: typeof spawn;
+}
+export declare class DetachedHostStartError extends Error {
+    /** Everything the child said, so a failure is diagnosable from one message. */
+    readonly childOutput: string;
+    constructor(message: string, childOutput: string);
+}
+export interface DetachedHostSupervisorHandle {
+    readonly ready: DetachedHostReadySignal;
+    readonly pid: number | undefined;
+    /** Resolves when the child has exited. */
+    readonly exited: Promise<{
+        code: number | null;
+        signal: NodeJS.Signals | null;
+    }>;
+    stop(): Promise<void>;
+}
+export declare function superviseDetachedHost(options: DetachedHostSupervisorOptions): Promise<DetachedHostSupervisorHandle>;
+//# sourceMappingURL=detachedHostSupervisor.d.ts.map

package/dist/detachedHostSupervisor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detachedHostSupervisor.d.ts","sourceRoot":"","sources":["../src/detachedHostSupervisor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,OAAO,EAAE,KAAK,EAAqB,MAAM,oBAAoB,CAAA;AAE7D,uEAAuE;AACvE,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,gCAAgC,CAAA;IACtC,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;IAClB,eAAe,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,WAAW,6BAA6B;IAC5C;;;;;;;;OAQG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB,kCAAkC;IAClC,SAAS,EAAE,MAAM,CAAA;IACjB,iEAAiE;IACjE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;IACxC,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,qDAAqD;IACrD,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAA;IAC/F,0BAA0B;IAC1B,OAAO,CAAC,EAAE,OAAO,KAAK,CAAA;CACvB;AAED,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,+EAA+E;IAC/E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;gBAEhB,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM;CAKjD;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,KAAK,EAAE,uBAAuB,CAAA;IACvC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,0CAA0C;IAC1C,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAA;KAAE,CAAC,CAAA;IAChF,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACtB;AAID,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,4BAA4B,CAAC,CAiGvC"}

package/dist/detachedHostSupervisor.js

@@ -0,0 +1,168 @@
+/**
+ * Spawns and watches the detached host process — ADE §9 build-order step 3.
+ *
+ * `runDetachedAgentHost` is the process's own lifecycle: it elects itself owner,
+ * refuses to run demoted, and stops when it loses the lease. This is the other
+ * half — the parent that starts it, learns when it is actually serving, and
+ * notices when it dies.
+ *
+ * ## 🔴 Readiness is a SIGNAL, never a sleep
+ *
+ * The parent has to attach as a client, and attaching before the child owns the
+ * lease means the parent wins the election instead. The two processes then both
+ * believe they are the host, which is the split-brain the lease exists to
+ * prevent — reached by way of a race that only shows up on a slow machine.
+ *
+ * So the child prints one line of JSON when it is serving, and this waits for
+ * that line. A fixed sleep would be either flaky or slow, and usually both.
+ *
+ * ## An exit is reported, never retried in a loop
+ *
+ * A supervisor that restarts unconditionally turns a permanent failure — a bad
+ * endpoint, a corrupt state directory, another owner already holding the lease —
+ * into an infinite loop that looks like activity. This reports the exit and the
+ * child's own words, and lets the caller decide. `DetachedAgentHostDemotedError`
+ * exists precisely so "someone else is already the host" arrives as a named
+ * failure rather than as a crash to retry.
+ *
+ * @unadopted-by-design ADE §9 step 3 — the child ENTRY POINT now EXISTS
+ * (`apps/desktop/src/main/detachedHostEntry.ts`) and this supervisor is proven
+ * to spawn it: `detachedHostEntry.test.ts` starts the BUILT entry through this
+ * code, connects a real client to the endpoint it publishes, and asserts a
+ * second one refuses rather than demoting. What is still missing is the app
+ * calling it — `index.ts` remains its own in-process host. The app SAYS SO when
+ * the flag is set rather than ignoring it; a requested capability that silently
+ * does nothing is the defect this marker exists to keep visible.
+ *
+ * 🔴 CORRECTED 2026-08-14. This said extracting a headless entry was "a
+ * refactor rather than a wiring step" because the composition is "written
+ * against Electron". It was not: `HostSurfaceCapabilities` has no required
+ * fields, so `surface: {}` composes a working host. The one REAL Electron
+ * coupling was a static import of the electron-host package pulling `electron`
+ * into the shared bundle chunk — invisible to every in-process test, fatal to
+ * the built entry, and now a dynamic import gated on a window.
+ */
+import { spawn } from 'node:child_process';
+export class DetachedHostStartError extends Error {
+    /** Everything the child said, so a failure is diagnosable from one message. */
+    childOutput;
+    constructor(message, childOutput) {
+        super(childOutput ? `${message} The host process said: ${childOutput.trim()}` : message);
+        this.name = 'DetachedHostStartError';
+        this.childOutput = childOutput;
+    }
+}
+const DEFAULT_READY_TIMEOUT_MS = 30_000;
+export async function superviseDetachedHost(options) {
+    const spawnImpl = options.spawnFn ?? spawn;
+    const child = spawnImpl(options.execPath, [options.entryPath], {
+        ...(options.cwd ? { cwd: options.cwd } : {}),
+        env: {
+            ...process.env,
+            // Runs the Electron binary as plain Node. Without it the child would try
+            // to start a second Electron app: a GUI process, an app lock, and no host.
+            ELECTRON_RUN_AS_NODE: '1',
+            ...options.env,
+        },
+        // `pipe` on both, so the ready line is readable AND a failure is quotable.
+        // `ignore` would make a child that dies on startup indistinguishable from
+        // one that never started.
+        stdio: ['ignore', 'pipe', 'pipe'],
+        // NOT detached. A truly detached child survives the parent, which sounds
+        // like the goal and is not: the point is that runs survive a WINDOW, and the
+        // host is still owned by this app. An orphan holding the lease with nobody
+        // to stop it is how the next launch finds itself permanently demoted.
+        detached: false,
+    });
+    let output = '';
+    const collect = (chunk) => { output += String(chunk); };
+    child.stdout?.on('data', collect);
+    child.stderr?.on('data', collect);
+    let settleExit = () => { };
+    const exited = new Promise((resolve) => {
+        settleExit = resolve;
+    });
+    let hasExited = false;
+    child.on('exit', (code, signal) => {
+        hasExited = true;
+        options.onExit?.({ code, signal, output });
+        settleExit({ code, signal });
+    });
+    const ready = await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            finish();
+            // Killed rather than left running: a child that never reported ready may
+            // still be holding the lease, and leaving it would demote every future
+            // launch of this app.
+            child.kill();
+            reject(new DetachedHostStartError(`The Agent host process did not report ready within ${options.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS}ms.`, output));
+        }, options.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS);
+        let buffer = '';
+        const onData = (chunk) => {
+            buffer += String(chunk);
+            // Line-delimited: the child may print other things, and a JSON.parse of
+            // the whole buffer would fail on the first log line it happened to emit.
+            let index = buffer.indexOf('\n');
+            while (index >= 0) {
+                const line = buffer.slice(0, index).trim();
+                buffer = buffer.slice(index + 1);
+                const signal = parseReady(line);
+                if (signal) {
+                    finish();
+                    clearTimeout(timer);
+                    resolve(signal);
+                    return;
+                }
+                index = buffer.indexOf('\n');
+            }
+        };
+        const onExit = () => {
+            finish();
+            clearTimeout(timer);
+            reject(new DetachedHostStartError('The Agent host process exited before it was ready.', output));
+        };
+        function finish() {
+            child.stdout?.off('data', onData);
+            child.off('exit', onExit);
+        }
+        child.stdout?.on('data', onData);
+        child.on('exit', onExit);
+    });
+    return {
+        ready,
+        pid: child.pid,
+        exited,
+        stop: async () => {
+            if (hasExited)
+                return;
+            // SIGTERM, which `runDetachedAgentHost` handles as a graceful stop — it
+            // releases the lease. Killing hard would leave a lease file whose owner is
+            // gone, and the next launch would wait out its stall timeout for nothing.
+            child.kill('SIGTERM');
+            await exited;
+        },
+    };
+}
+function parseReady(line) {
+    if (!line.startsWith('{'))
+        return null;
+    try {
+        const parsed = JSON.parse(line);
+        if (parsed.type !== 'xeno-agent-detached-host-ready')
+            return null;
+        if (typeof parsed.endpoint !== 'string' || typeof parsed.instanceId !== 'string')
+            return null;
+        return {
+            type: 'xeno-agent-detached-host-ready',
+            endpoint: parsed.endpoint,
+            instanceId: parsed.instanceId,
+            protocolVersion: typeof parsed.protocolVersion === 'number' ? parsed.protocolVersion : 1,
+        };
+    }
+    catch {
+        // A line that is not our signal is not an error — the child is allowed to
+        // print. Only the absence of the signal within the timeout is.
+        return null;
+    }
+}
+//# sourceMappingURL=detachedHostSupervisor.js.map

package/dist/detachedHostSupervisor.js.map

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

package/dist/durableRuntimeEventStore.d.ts

@@ -0,0 +1,49 @@
+import { type AgentRuntimeEventDraft, type AgentRuntimeEventEnvelope, type AgentRuntimeEventListRequest, type AgentRuntimeEventListResult } from '@xenosystem/agent-interface-contract';
+export interface DurableRuntimeEventStoreOptions {
+    rootDirectory: string;
+    syncWrites?: boolean;
+    maxEventBytes?: number;
+    maxListLimit?: number;
+}
+export interface DurableRuntimeEventAppendResult {
+    inserted: boolean;
+    event: AgentRuntimeEventEnvelope;
+}
+export interface DurableRuntimeEventRepairReport {
+    conversationId: string;
+    streamPath: string;
+    repaired: boolean;
+    truncatedBytes: number;
+    retainedEvents: number;
+}
+export declare class DurableRuntimeEventStoreCorruptionError extends Error {
+    readonly streamPath: string;
+    readonly line: number;
+    constructor(streamPath: string, line: number, message: string);
+}
+/**
+ * Append-only runtime-event journal used by the single Agent host authority.
+ * Writes are serialized per conversation and fsynced by default. A partial
+ * final line is repaired on reopen; corruption before the tail fails closed.
+ */
+export declare class DurableRuntimeEventStore {
+    private readonly rootDirectory;
+    private readonly streamDirectory;
+    private readonly syncWrites;
+    private readonly maxEventBytes;
+    private readonly maxListLimit;
+    private readonly loaded;
+    private readonly queues;
+    constructor(options: DurableRuntimeEventStoreOptions);
+    initialize(): Promise<void>;
+    append(event: AgentRuntimeEventEnvelope): Promise<DurableRuntimeEventAppendResult>;
+    appendGenerated(event: AgentRuntimeEventDraft): Promise<DurableRuntimeEventAppendResult>;
+    appendGeneratedBatch(events: AgentRuntimeEventDraft[]): Promise<DurableRuntimeEventAppendResult[]>;
+    list(input: AgentRuntimeEventListRequest): Promise<AgentRuntimeEventListResult>;
+    repairReport(conversationId: string): Promise<DurableRuntimeEventRepairReport>;
+    streamPath(conversationId: string): string;
+    private loadStream;
+    private withConversationLock;
+    private appendToLoadedStream;
+}
+//# sourceMappingURL=durableRuntimeEventStore.d.ts.map

package/dist/durableRuntimeEventStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"durableRuntimeEventStore.d.ts","sourceRoot":"","sources":["../src/durableRuntimeEventStore.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,sBAAsB,EAC3B,KAAK,yBAAyB,EAC9B,KAAK,4BAA4B,EACjC,KAAK,2BAA2B,EACjC,MAAM,sCAAsC,CAAA;AAE7C,MAAM,WAAW,+BAA+B;IAC9C,aAAa,EAAE,MAAM,CAAA;IACrB,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,EAAE,OAAO,CAAA;IACjB,KAAK,EAAE,yBAAyB,CAAA;CACjC;AAED,MAAM,WAAW,+BAA+B;IAC9C,cAAc,EAAE,MAAM,CAAA;IACtB,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,OAAO,CAAA;IACjB,cAAc,EAAE,MAAM,CAAA;IACtB,cAAc,EAAE,MAAM,CAAA;CACvB;AAED,qBAAa,uCAAwC,SAAQ,KAAK;IAChE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;gBAET,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAM9D;AAYD;;;;GAIG;AACH,qBAAa,wBAAwB;IACnC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAQ;IACtC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAQ;IACxC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAQ;IACtC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAQ;IACrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkC;IACzD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmC;gBAE9C,OAAO,EAAE,+BAA+B;IAS9C,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B,MAAM,CAAC,KAAK,EAAE,yBAAyB,GAAG,OAAO,CAAC,+BAA+B,CAAC;IASlF,eAAe,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,+BAA+B,CAAC;IA8BxF,oBAAoB,CAAC,MAAM,EAAE,sBAAsB,EAAE,GAAG,OAAO,CAAC,+BAA+B,EAAE,CAAC;IA+DlG,IAAI,CAAC,KAAK,EAAE,4BAA4B,GAAG,OAAO,CAAC,2BAA2B,CAAC;IAqB/E,YAAY,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,+BAA+B,CAAC;IAKpF,UAAU,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM;YAM5B,UAAU;YA2DV,oBAAoB;YAepB,oBAAoB;CAmCnC"}