@code-yeongyu/senpi 2026.7.4 → 2026.7.9-2

package/dist/modes/rpc/neo-daemon-mode.js

@@ -0,0 +1,267 @@
+/**
+ * Neo daemon mode: a JSONL-over-socket server that serves N neo clients sharing
+ * one cwd, each with its own runtime.
+ *
+ * ISOLATION MODEL (see task-15 spike, evidence/task-15-neo-go-tui.md §1):
+ * running N `createAgentSessionRuntime` instances concurrently in a SINGLE node
+ * process is NOT safe — pi-ai's process-global provider registry
+ * (`resetApiProviders`) and pi-agent-core's module-level UUIDv7 counter cause
+ * cross-talk, and both are out of scope to change. The daemon therefore uses the
+ * plan's documented contingency: the daemon process is a SUPERVISOR that runs
+ * ONE worker (its own child process) per connection. Each worker is a standard,
+ * already-proven single-connection `runRpcMode` runtime with its own module
+ * state and its own AuthStorage, so a connection's `--api-key` can never leak
+ * into another connection. Concurrency is real (separate processes).
+ *
+ * The worker factory is injectable so tests can drive the supervisor
+ * deterministically (handshake, registry, idle) without spawning real children,
+ * while production spawns `node <cli> --mode rpc` per connection.
+ *
+ * REGISTRY/RACE: the daemon binds the socket FIRST (bind is the mutex — the race
+ * loser gets EADDRINUSE and the client attaches to the winner), THEN atomically
+ * self-registers as the LAST listen step. Clients never write the registry.
+ *
+ * CONNECTION LIFECYCLE: a socket disconnect aborts that connection's in-flight
+ * turn and disposes its worker; sessions persist incrementally to disk so
+ * recovery is resume-from-file. Idle shutdown fires after a configurable
+ * no-connection period.
+ */
+import { createServer } from "node:net";
+import { attachJsonlLineReader, serializeJsonLine } from "./jsonl.js";
+import { parseHello, validateHello, } from "./neo-daemon-protocol.js";
+import { cleanupStaleNeoDaemon, NEO_DAEMON_PROTOCOL_VERSION, reassertNeoDaemonRecord, reclaimDeadSocketFile, removeNeoDaemonRecord, writeNeoDaemonRecord, } from "./neo-daemon-registry.js";
+const realClock = {
+    setTimeout: (handler, ms) => setTimeout(handler, ms),
+    clearTimeout: (handle) => clearTimeout(handle),
+};
+/** Raised when the socket path is already bound (a daemon already won the race). */
+export class NeoDaemonAddressInUseError extends Error {
+    constructor(listenPath) {
+        super(`Neo daemon socket already in use: ${listenPath}`);
+        this.name = "NeoDaemonAddressInUseError";
+    }
+}
+/**
+ * Start the neo daemon. Binds the socket (throws {@link NeoDaemonAddressInUseError}
+ * if the race is lost), registers, and serves connections until idle-shutdown or
+ * an explicit `shutdown()`.
+ */
+export async function runNeoDaemon(options) {
+    const version = options.version ?? NEO_DAEMON_PROTOCOL_VERSION;
+    const register = options.register ?? true;
+    const clock = options.clock ?? realClock;
+    const selfHealIntervalMs = options.selfHealIntervalMs ?? 2000;
+    // The record this daemon owns. It is written once as the last listen step and
+    // re-asserted (self-heal) whenever it is found missing/corrupt — carrying this
+    // daemon's real in-memory token so the healed record still authenticates.
+    const ownRecord = {
+        version,
+        socket: options.listenPath,
+        pid: process.pid,
+        token: options.token,
+    };
+    // Stale cleanup BEFORE bind so a dead daemon's leftover socket/record does
+    // not block the fresh bind.
+    cleanupStaleNeoDaemon(options.agentDir, options.cwd);
+    const connections = new Set();
+    let idleTimer;
+    let selfHealTimer;
+    let shuttingDown = false;
+    let resolveClosed;
+    const closed = new Promise((resolve) => {
+        resolveClosed = resolve;
+    });
+    const server = createServer();
+    // Re-assert the registry record iff it is missing or no longer matches this
+    // daemon. No-op when register is false (a bind-race loser never owns the slot)
+    // or the daemon is shutting down (it is about to remove its record).
+    const selfHeal = () => {
+        if (!register || shuttingDown)
+            return;
+        reassertNeoDaemonRecord(options.agentDir, options.cwd, ownRecord);
+    };
+    const clearSelfHealTimer = () => {
+        if (selfHealTimer !== undefined) {
+            clock.clearTimeout(selfHealTimer);
+            selfHealTimer = undefined;
+        }
+    };
+    // The clock only exposes one-shot setTimeout, so the recurring self-heal
+    // re-arms itself after each fire until shutdown clears it.
+    const armSelfHealTimer = () => {
+        if (!register || selfHealIntervalMs <= 0 || shuttingDown)
+            return;
+        selfHealTimer = clock.setTimeout(() => {
+            selfHeal();
+            selfHealTimer = undefined;
+            armSelfHealTimer();
+        }, selfHealIntervalMs);
+    };
+    const clearIdleTimer = () => {
+        if (idleTimer !== undefined) {
+            clock.clearTimeout(idleTimer);
+            idleTimer = undefined;
+        }
+    };
+    const armIdleTimer = () => {
+        clearIdleTimer();
+        if (options.idleShutdownMs <= 0)
+            return;
+        if (connections.size > 0)
+            return;
+        idleTimer = clock.setTimeout(() => {
+            void shutdown();
+        }, options.idleShutdownMs);
+    };
+    async function shutdown() {
+        if (shuttingDown)
+            return closed;
+        shuttingDown = true;
+        clearIdleTimer();
+        clearSelfHealTimer();
+        // Dispose all live connections (aborts each in-flight turn).
+        const disposals = [...connections].map((c) => c.teardown());
+        await Promise.allSettled(disposals);
+        connections.clear();
+        if (register) {
+            removeNeoDaemonRecord(options.agentDir, options.cwd);
+        }
+        await new Promise((resolve) => server.close(() => resolve()));
+        resolveClosed();
+        return closed;
+    }
+    server.on("connection", (socket) => {
+        void handleConnection(socket);
+    });
+    async function handleConnection(socket) {
+        clearIdleTimer();
+        // Self-heal on accept: a fresh client that found a lost/corrupt record but a
+        // LIVE deterministic socket pokes this daemon; re-asserting the record here
+        // lets that client's next poll find it and attach (closes the recovery wedge
+        // even before the recurring interval fires).
+        selfHeal();
+        socket.setNoDelay(true);
+        const abort = new AbortController();
+        const state = {
+            socket,
+            worker: undefined,
+            async teardown() {
+                abort.abort();
+                detach();
+                try {
+                    await this.worker?.dispose();
+                }
+                finally {
+                    if (!socket.destroyed)
+                        socket.destroy();
+                }
+            },
+        };
+        const writeToClient = (line) => {
+            if (!socket.destroyed)
+                socket.write(line);
+        };
+        const reply = (message) => {
+            writeToClient(serializeJsonLine(message));
+        };
+        let handshakeDone = false;
+        const onLine = (line) => {
+            if (handshakeDone) {
+                state.worker?.handleLine(line);
+                return;
+            }
+            handshakeDone = true;
+            void completeHandshake(line);
+        };
+        const detach = attachJsonlLineReader(socket, onLine);
+        const finalizeDrop = () => {
+            if (!connections.has(state))
+                return;
+            connections.delete(state);
+            void state.teardown();
+            armIdleTimer();
+        };
+        socket.on("close", finalizeDrop);
+        socket.on("error", finalizeDrop);
+        async function completeHandshake(firstLine) {
+            const hello = parseHello(firstLine);
+            if (!hello) {
+                reply({ type: "refuse", code: "malformed_hello", reason: "First line was not a valid hello message" });
+                socket.end();
+                return;
+            }
+            const refusal = validateHello(hello, { token: options.token, version });
+            if (refusal) {
+                reply(refusal);
+                socket.end();
+                return;
+            }
+            const runtimeOptions = hello.runtimeOptions ?? {};
+            const optionError = options.validateRuntimeOptions?.(runtimeOptions);
+            if (optionError) {
+                reply({ type: "refuse", code: "unsupported_options", reason: optionError });
+                socket.end();
+                return;
+            }
+            // Accepted: build the per-connection worker, then welcome.
+            try {
+                const worker = await options.workerFactory({
+                    runtimeOptions,
+                    capabilities: hello.capabilities ?? [],
+                    cwd: options.cwd,
+                    agentDir: options.agentDir,
+                    writeToClient,
+                    signal: abort.signal,
+                });
+                state.worker = worker;
+                connections.add(state);
+                reply({ type: "welcome", version, capabilities: hello.capabilities });
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                reply({ type: "refuse", code: "unsupported_options", reason: `Failed to start runtime: ${message}` });
+                socket.end();
+            }
+        }
+    }
+    // A deterministic socket path means a crashed daemon can leave a dead socket
+    // FILE behind with no registry record for cleanupStaleNeoDaemon to key off.
+    // Reclaim such a leftover before bind so we do not hit EADDRINUSE forever; a
+    // socket a LIVE daemon still serves is left intact so we lose the race to it.
+    await reclaimDeadSocketFile(options.listenPath);
+    // Bind FIRST (the mutex). Map EADDRINUSE to a typed error so the caller can
+    // attach to the winner.
+    await new Promise((resolve, reject) => {
+        const onError = (error) => {
+            server.off("listening", onListening);
+            if (error.code === "EADDRINUSE") {
+                reject(new NeoDaemonAddressInUseError(options.listenPath));
+            }
+            else {
+                reject(error);
+            }
+        };
+        const onListening = () => {
+            server.off("error", onError);
+            resolve();
+        };
+        server.once("error", onError);
+        server.once("listening", onListening);
+        server.listen(options.listenPath);
+    });
+    // Registry self-registration is the LAST listen step.
+    if (register) {
+        writeNeoDaemonRecord(options.agentDir, options.cwd, ownRecord);
+    }
+    // No connections yet: arm the idle timer immediately. Also start the recurring
+    // self-heal so a lost/corrupt record repairs itself even with no new connection.
+    armIdleTimer();
+    armSelfHealTimer();
+    return {
+        listenPath: options.listenPath,
+        closed,
+        connectionCount: () => connections.size,
+        shutdown,
+    };
+}
+//# sourceMappingURL=neo-daemon-mode.js.map

package/dist/modes/rpc/neo-daemon-mode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"neo-daemon-mode.js","sourceRoot":"","sources":["../../../src/modes/rpc/neo-daemon-mode.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Neo daemon mode: a JSONL-over-socket server that serves N neo clients sharing\n * one cwd, each with its own runtime.\n *\n * ISOLATION MODEL (see task-15 spike, evidence/task-15-neo-go-tui.md §1):\n * running N `createAgentSessionRuntime` instances concurrently in a SINGLE node\n * process is NOT safe — pi-ai's process-global provider registry\n * (`resetApiProviders`) and pi-agent-core's module-level UUIDv7 counter cause\n * cross-talk, and both are out of scope to change. The daemon therefore uses the\n * plan's documented contingency: the daemon process is a SUPERVISOR that runs\n * ONE worker (its own child process) per connection. Each worker is a standard,\n * already-proven single-connection `runRpcMode` runtime with its own module\n * state and its own AuthStorage, so a connection's `--api-key` can never leak\n * into another connection. Concurrency is real (separate processes).\n *\n * The worker factory is injectable so tests can drive the supervisor\n * deterministically (handshake, registry, idle) without spawning real children,\n * while production spawns `node <cli> --mode rpc` per connection.\n *\n * REGISTRY/RACE: the daemon binds the socket FIRST (bind is the mutex — the race\n * loser gets EADDRINUSE and the client attaches to the winner), THEN atomically\n * self-registers as the LAST listen step. Clients never write the registry.\n *\n * CONNECTION LIFECYCLE: a socket disconnect aborts that connection's in-flight\n * turn and disposes its worker; sessions persist incrementally to disk so\n * recovery is resume-from-file. Idle shutdown fires after a configurable\n * no-connection period.\n */\n\nimport { createServer, type Server, type Socket } from \"node:net\";\nimport { attachJsonlLineReader, serializeJsonLine } from \"./jsonl.ts\";\nimport {\n\ttype NeoDaemonHandshakeReply,\n\ttype NeoHelloMessage,\n\tparseHello,\n\tvalidateHello,\n} from \"./neo-daemon-protocol.ts\";\nimport {\n\tcleanupStaleNeoDaemon,\n\tNEO_DAEMON_PROTOCOL_VERSION,\n\ttype NeoDaemonRecord,\n\treassertNeoDaemonRecord,\n\treclaimDeadSocketFile,\n\tremoveNeoDaemonRecord,\n\twriteNeoDaemonRecord,\n} from \"./neo-daemon-registry.ts\";\nimport type { NeoRuntimeOptions } from \"./neo-runtime-options.ts\";\n\n/** A live worker serving exactly one connection. */\nexport interface NeoDaemonWorker {\n\t/** Feed one inbound JSONL line from the client to the worker. */\n\thandleLine(line: string): void;\n\t/** Called when the connection drops; abort the in-flight turn and dispose. */\n\tdispose(): Promise<void>;\n}\n\n/**\n * Build a worker for one accepted connection. `writeToClient` sends a\n * (LF-terminated) JSONL line back to the client. `runtimeOptions` are the\n * per-connection options from the handshake. `signal` aborts when the\n * connection drops or the daemon shuts down.\n */\nexport type NeoDaemonWorkerFactory = (args: {\n\treadonly runtimeOptions: NeoRuntimeOptions;\n\treadonly capabilities: readonly string[];\n\treadonly cwd: string;\n\treadonly agentDir: string;\n\treadonly writeToClient: (line: string) => void;\n\treadonly signal: AbortSignal;\n}) => Promise<NeoDaemonWorker>;\n\n/** Minimal injectable clock so idle-shutdown timing is testable. */\nexport interface NeoDaemonClock {\n\tsetTimeout(handler: () => void, ms: number): unknown;\n\tclearTimeout(handle: unknown): void;\n}\n\nconst realClock: NeoDaemonClock = {\n\tsetTimeout: (handler, ms) => setTimeout(handler, ms),\n\tclearTimeout: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>),\n};\n\nexport interface NeoDaemonOptions {\n\t/** Unix socket path (POSIX) or named-pipe path (Windows) to bind. */\n\treadonly listenPath: string;\n\t/** Absolute cwd this daemon serves. */\n\treadonly cwd: string;\n\t/** Agent dir (holds the registry). */\n\treadonly agentDir: string;\n\t/** Self-register into the registry as the last listen step. Default true. */\n\treadonly register?: boolean;\n\t/** Idle shutdown period in ms; 0 disables. Default 30 min (caller supplies). */\n\treadonly idleShutdownMs: number;\n\t/**\n\t * Registry self-heal interval in ms; 0 disables the recurring re-assert (the\n\t * on-accept re-assert still runs). The daemon periodically re-writes its own\n\t * registry record if it went missing/corrupt, so a lost record repairs itself\n\t * even before the next connection. Default 2000ms (caller may override).\n\t */\n\treadonly selfHealIntervalMs?: number;\n\t/** Handshake token clients must present. */\n\treadonly token: string;\n\t/** Protocol version this daemon speaks. Default NEO_DAEMON_PROTOCOL_VERSION. */\n\treadonly version?: number;\n\t/** Worker factory (injected in tests; production spawns a child process). */\n\treadonly workerFactory: NeoDaemonWorkerFactory;\n\t/** Injectable clock for idle-shutdown timing. */\n\treadonly clock?: NeoDaemonClock;\n\t/**\n\t * Validate connection runtimeOptions; return a human reason to refuse, or\n\t * undefined to accept. Lets the host reject options it cannot honor.\n\t */\n\treadonly validateRuntimeOptions?: (options: NeoRuntimeOptions) => string | undefined;\n}\n\nexport interface NeoDaemonHandle {\n\t/** The bound socket path. */\n\treadonly listenPath: string;\n\t/** Resolves when the daemon has fully shut down. */\n\treadonly closed: Promise<void>;\n\t/** Current live connection count (for tests/observability). */\n\tconnectionCount(): number;\n\t/** Trigger a graceful shutdown. */\n\tshutdown(): Promise<void>;\n}\n\n/** Raised when the socket path is already bound (a daemon already won the race). */\nexport class NeoDaemonAddressInUseError extends Error {\n\tconstructor(listenPath: string) {\n\t\tsuper(`Neo daemon socket already in use: ${listenPath}`);\n\t\tthis.name = \"NeoDaemonAddressInUseError\";\n\t}\n}\n\n/**\n * Start the neo daemon. Binds the socket (throws {@link NeoDaemonAddressInUseError}\n * if the race is lost), registers, and serves connections until idle-shutdown or\n * an explicit `shutdown()`.\n */\nexport async function runNeoDaemon(options: NeoDaemonOptions): Promise<NeoDaemonHandle> {\n\tconst version = options.version ?? NEO_DAEMON_PROTOCOL_VERSION;\n\tconst register = options.register ?? true;\n\tconst clock = options.clock ?? realClock;\n\tconst selfHealIntervalMs = options.selfHealIntervalMs ?? 2000;\n\n\t// The record this daemon owns. It is written once as the last listen step and\n\t// re-asserted (self-heal) whenever it is found missing/corrupt — carrying this\n\t// daemon's real in-memory token so the healed record still authenticates.\n\tconst ownRecord: NeoDaemonRecord = {\n\t\tversion,\n\t\tsocket: options.listenPath,\n\t\tpid: process.pid,\n\t\ttoken: options.token,\n\t};\n\n\t// Stale cleanup BEFORE bind so a dead daemon's leftover socket/record does\n\t// not block the fresh bind.\n\tcleanupStaleNeoDaemon(options.agentDir, options.cwd);\n\n\tconst connections = new Set<ConnectionState>();\n\tlet idleTimer: unknown;\n\tlet selfHealTimer: unknown;\n\tlet shuttingDown = false;\n\tlet resolveClosed!: () => void;\n\tconst closed = new Promise<void>((resolve) => {\n\t\tresolveClosed = resolve;\n\t});\n\n\tconst server: Server = createServer();\n\n\t// Re-assert the registry record iff it is missing or no longer matches this\n\t// daemon. No-op when register is false (a bind-race loser never owns the slot)\n\t// or the daemon is shutting down (it is about to remove its record).\n\tconst selfHeal = (): void => {\n\t\tif (!register || shuttingDown) return;\n\t\treassertNeoDaemonRecord(options.agentDir, options.cwd, ownRecord);\n\t};\n\n\tconst clearSelfHealTimer = (): void => {\n\t\tif (selfHealTimer !== undefined) {\n\t\t\tclock.clearTimeout(selfHealTimer);\n\t\t\tselfHealTimer = undefined;\n\t\t}\n\t};\n\n\t// The clock only exposes one-shot setTimeout, so the recurring self-heal\n\t// re-arms itself after each fire until shutdown clears it.\n\tconst armSelfHealTimer = (): void => {\n\t\tif (!register || selfHealIntervalMs <= 0 || shuttingDown) return;\n\t\tselfHealTimer = clock.setTimeout(() => {\n\t\t\tselfHeal();\n\t\t\tselfHealTimer = undefined;\n\t\t\tarmSelfHealTimer();\n\t\t}, selfHealIntervalMs);\n\t};\n\n\tconst clearIdleTimer = (): void => {\n\t\tif (idleTimer !== undefined) {\n\t\t\tclock.clearTimeout(idleTimer);\n\t\t\tidleTimer = undefined;\n\t\t}\n\t};\n\n\tconst armIdleTimer = (): void => {\n\t\tclearIdleTimer();\n\t\tif (options.idleShutdownMs <= 0) return;\n\t\tif (connections.size > 0) return;\n\t\tidleTimer = clock.setTimeout(() => {\n\t\t\tvoid shutdown();\n\t\t}, options.idleShutdownMs);\n\t};\n\n\tasync function shutdown(): Promise<void> {\n\t\tif (shuttingDown) return closed;\n\t\tshuttingDown = true;\n\t\tclearIdleTimer();\n\t\tclearSelfHealTimer();\n\t\t// Dispose all live connections (aborts each in-flight turn).\n\t\tconst disposals = [...connections].map((c) => c.teardown());\n\t\tawait Promise.allSettled(disposals);\n\t\tconnections.clear();\n\t\tif (register) {\n\t\t\tremoveNeoDaemonRecord(options.agentDir, options.cwd);\n\t\t}\n\t\tawait new Promise<void>((resolve) => server.close(() => resolve()));\n\t\tresolveClosed();\n\t\treturn closed;\n\t}\n\n\tserver.on(\"connection\", (socket: Socket) => {\n\t\tvoid handleConnection(socket);\n\t});\n\n\tasync function handleConnection(socket: Socket): Promise<void> {\n\t\tclearIdleTimer();\n\t\t// Self-heal on accept: a fresh client that found a lost/corrupt record but a\n\t\t// LIVE deterministic socket pokes this daemon; re-asserting the record here\n\t\t// lets that client's next poll find it and attach (closes the recovery wedge\n\t\t// even before the recurring interval fires).\n\t\tselfHeal();\n\t\tsocket.setNoDelay(true);\n\t\tconst abort = new AbortController();\n\t\tconst state: ConnectionState = {\n\t\t\tsocket,\n\t\t\tworker: undefined,\n\t\t\tasync teardown() {\n\t\t\t\tabort.abort();\n\t\t\t\tdetach();\n\t\t\t\ttry {\n\t\t\t\t\tawait this.worker?.dispose();\n\t\t\t\t} finally {\n\t\t\t\t\tif (!socket.destroyed) socket.destroy();\n\t\t\t\t}\n\t\t\t},\n\t\t};\n\n\t\tconst writeToClient = (line: string): void => {\n\t\t\tif (!socket.destroyed) socket.write(line);\n\t\t};\n\n\t\tconst reply = (message: NeoDaemonHandshakeReply): void => {\n\t\t\twriteToClient(serializeJsonLine(message));\n\t\t};\n\n\t\tlet handshakeDone = false;\n\n\t\tconst onLine = (line: string): void => {\n\t\t\tif (handshakeDone) {\n\t\t\t\tstate.worker?.handleLine(line);\n\t\t\t\treturn;\n\t\t\t}\n\t\t\thandshakeDone = true;\n\t\t\tvoid completeHandshake(line);\n\t\t};\n\n\t\tconst detach = attachJsonlLineReader(socket, onLine);\n\n\t\tconst finalizeDrop = (): void => {\n\t\t\tif (!connections.has(state)) return;\n\t\t\tconnections.delete(state);\n\t\t\tvoid state.teardown();\n\t\t\tarmIdleTimer();\n\t\t};\n\t\tsocket.on(\"close\", finalizeDrop);\n\t\tsocket.on(\"error\", finalizeDrop);\n\n\t\tasync function completeHandshake(firstLine: string): Promise<void> {\n\t\t\tconst hello = parseHello(firstLine);\n\t\t\tif (!hello) {\n\t\t\t\treply({ type: \"refuse\", code: \"malformed_hello\", reason: \"First line was not a valid hello message\" });\n\t\t\t\tsocket.end();\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tconst refusal = validateHello(hello, { token: options.token, version });\n\t\t\tif (refusal) {\n\t\t\t\treply(refusal);\n\t\t\t\tsocket.end();\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tconst runtimeOptions = hello.runtimeOptions ?? {};\n\t\t\tconst optionError = options.validateRuntimeOptions?.(runtimeOptions);\n\t\t\tif (optionError) {\n\t\t\t\treply({ type: \"refuse\", code: \"unsupported_options\", reason: optionError });\n\t\t\t\tsocket.end();\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\t// Accepted: build the per-connection worker, then welcome.\n\t\t\ttry {\n\t\t\t\tconst worker = await options.workerFactory({\n\t\t\t\t\truntimeOptions,\n\t\t\t\t\tcapabilities: hello.capabilities ?? [],\n\t\t\t\t\tcwd: options.cwd,\n\t\t\t\t\tagentDir: options.agentDir,\n\t\t\t\t\twriteToClient,\n\t\t\t\t\tsignal: abort.signal,\n\t\t\t\t});\n\t\t\t\tstate.worker = worker;\n\t\t\t\tconnections.add(state);\n\t\t\t\treply({ type: \"welcome\", version, capabilities: hello.capabilities });\n\t\t\t} catch (error) {\n\t\t\t\tconst message = error instanceof Error ? error.message : String(error);\n\t\t\t\treply({ type: \"refuse\", code: \"unsupported_options\", reason: `Failed to start runtime: ${message}` });\n\t\t\t\tsocket.end();\n\t\t\t}\n\t\t}\n\t}\n\n\t// A deterministic socket path means a crashed daemon can leave a dead socket\n\t// FILE behind with no registry record for cleanupStaleNeoDaemon to key off.\n\t// Reclaim such a leftover before bind so we do not hit EADDRINUSE forever; a\n\t// socket a LIVE daemon still serves is left intact so we lose the race to it.\n\tawait reclaimDeadSocketFile(options.listenPath);\n\n\t// Bind FIRST (the mutex). Map EADDRINUSE to a typed error so the caller can\n\t// attach to the winner.\n\tawait new Promise<void>((resolve, reject) => {\n\t\tconst onError = (error: NodeJS.ErrnoException): void => {\n\t\t\tserver.off(\"listening\", onListening);\n\t\t\tif (error.code === \"EADDRINUSE\") {\n\t\t\t\treject(new NeoDaemonAddressInUseError(options.listenPath));\n\t\t\t} else {\n\t\t\t\treject(error);\n\t\t\t}\n\t\t};\n\t\tconst onListening = (): void => {\n\t\t\tserver.off(\"error\", onError);\n\t\t\tresolve();\n\t\t};\n\t\tserver.once(\"error\", onError);\n\t\tserver.once(\"listening\", onListening);\n\t\tserver.listen(options.listenPath);\n\t});\n\n\t// Registry self-registration is the LAST listen step.\n\tif (register) {\n\t\twriteNeoDaemonRecord(options.agentDir, options.cwd, ownRecord);\n\t}\n\n\t// No connections yet: arm the idle timer immediately. Also start the recurring\n\t// self-heal so a lost/corrupt record repairs itself even with no new connection.\n\tarmIdleTimer();\n\tarmSelfHealTimer();\n\n\treturn {\n\t\tlistenPath: options.listenPath,\n\t\tclosed,\n\t\tconnectionCount: () => connections.size,\n\t\tshutdown,\n\t};\n}\n\ninterface ConnectionState {\n\tsocket: Socket;\n\tworker: NeoDaemonWorker | undefined;\n\tteardown(): Promise<void>;\n}\n\nexport type { NeoHelloMessage };\n"]}

package/dist/modes/rpc/neo-daemon-protocol.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Neo daemon handshake protocol.
+ *
+ * A connection begins with a single `hello` line from the client. The daemon
+ * replies with exactly one `welcome` or `refuse` line, then (on welcome) the
+ * connection carries the ordinary JSONL RPC protocol for that connection's
+ * runtime. The handshake is additive and lives entirely on the socket — it does
+ * not touch the existing stdio RPC command shapes.
+ */
+import type { NeoRuntimeOptions } from "./neo-runtime-options.ts";
+/** First line a client sends on a fresh connection. */
+export interface NeoHelloMessage {
+    readonly type: "hello";
+    /** Must match the daemon's registry token. */
+    readonly token: string;
+    /** Client's protocol version; must equal the daemon's. */
+    readonly version: number;
+    /** Optional client capability flags (e.g. custom_unsupported opt-in). */
+    readonly capabilities?: readonly string[];
+    /** Per-connection runtime options used to build THIS connection's runtime. */
+    readonly runtimeOptions?: NeoRuntimeOptions;
+}
+/** Accepted-handshake reply. */
+export interface NeoWelcomeMessage {
+    readonly type: "welcome";
+    readonly version: number;
+    /** Capabilities the daemon acknowledges for this connection. */
+    readonly capabilities?: readonly string[];
+}
+/** Rejected-handshake reply. The client then falls back to isolated transport. */
+export interface NeoRefuseMessage {
+    readonly type: "refuse";
+    readonly reason: string;
+    readonly code: NeoRefuseCode;
+}
+export type NeoRefuseCode = "bad_token" | "version_mismatch" | "unsupported_options" | "malformed_hello";
+export type NeoDaemonHandshakeReply = NeoWelcomeMessage | NeoRefuseMessage;
+/** Parse an inbound first line as a hello message, or return undefined. */
+export declare function parseHello(line: string): NeoHelloMessage | undefined;
+/**
+ * Validate a hello against the daemon's token/version. Returns a refuse reply
+ * on mismatch, or undefined when the handshake is acceptable. `runtimeOptions`
+ * validation (unsupported/incompatible flags) is delegated to the caller since
+ * it depends on which options the daemon can honor.
+ */
+export declare function validateHello(hello: NeoHelloMessage, expected: {
+    token: string;
+    version?: number;
+}): NeoRefuseMessage | undefined;
+//# sourceMappingURL=neo-daemon-protocol.d.ts.map

package/dist/modes/rpc/neo-daemon-protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"neo-daemon-protocol.d.ts","sourceRoot":"","sources":["../../../src/modes/rpc/neo-daemon-protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAElE,uDAAuD;AACvD,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yEAAyE;IACzE,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,8EAA8E;IAC9E,QAAQ,CAAC,cAAc,CAAC,EAAE,iBAAiB,CAAC;CAC5C;AAED,gCAAgC;AAChC,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,gEAAgE;IAChE,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAED,kFAAkF;AAClF,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;CAC7B;AAED,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,kBAAkB,GAAG,qBAAqB,GAAG,iBAAiB,CAAC;AAEzG,MAAM,MAAM,uBAAuB,GAAG,iBAAiB,GAAG,gBAAgB,CAAC;AAE3E,2EAA2E;AAC3E,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CA0BpE;AAMD;;;;;GAKG;AACH,wBAAgB,aAAa,CAC5B,KAAK,EAAE,eAAe,EACtB,QAAQ,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAC3C,gBAAgB,GAAG,SAAS,CAa9B"}

package/dist/modes/rpc/neo-daemon-protocol.js

@@ -0,0 +1,66 @@
+/**
+ * Neo daemon handshake protocol.
+ *
+ * A connection begins with a single `hello` line from the client. The daemon
+ * replies with exactly one `welcome` or `refuse` line, then (on welcome) the
+ * connection carries the ordinary JSONL RPC protocol for that connection's
+ * runtime. The handshake is additive and lives entirely on the socket — it does
+ * not touch the existing stdio RPC command shapes.
+ */
+import { NEO_DAEMON_PROTOCOL_VERSION } from "./neo-daemon-registry.js";
+/** Parse an inbound first line as a hello message, or return undefined. */
+export function parseHello(line) {
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return undefined;
+    const record = parsed;
+    if (record.type !== "hello")
+        return undefined;
+    if (typeof record.token !== "string")
+        return undefined;
+    if (typeof record.version !== "number")
+        return undefined;
+    if (record.capabilities !== undefined && !isStringArray(record.capabilities))
+        return undefined;
+    if (record.runtimeOptions !== undefined &&
+        (typeof record.runtimeOptions !== "object" || record.runtimeOptions === null)) {
+        return undefined;
+    }
+    return {
+        type: "hello",
+        token: record.token,
+        version: record.version,
+        capabilities: record.capabilities,
+        runtimeOptions: record.runtimeOptions,
+    };
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+/**
+ * Validate a hello against the daemon's token/version. Returns a refuse reply
+ * on mismatch, or undefined when the handshake is acceptable. `runtimeOptions`
+ * validation (unsupported/incompatible flags) is delegated to the caller since
+ * it depends on which options the daemon can honor.
+ */
+export function validateHello(hello, expected) {
+    const version = expected.version ?? NEO_DAEMON_PROTOCOL_VERSION;
+    if (hello.version !== version) {
+        return {
+            type: "refuse",
+            code: "version_mismatch",
+            reason: `Protocol version mismatch: daemon speaks ${version}, client sent ${hello.version}`,
+        };
+    }
+    if (hello.token !== expected.token) {
+        return { type: "refuse", code: "bad_token", reason: "Invalid handshake token" };
+    }
+    return undefined;
+}
+//# sourceMappingURL=neo-daemon-protocol.js.map

package/dist/modes/rpc/neo-daemon-protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"neo-daemon-protocol.js","sourceRoot":"","sources":["../../../src/modes/rpc/neo-daemon-protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AAmCvE,2EAA2E;AAC3E,MAAM,UAAU,UAAU,CAAC,IAAY;IACtC,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACJ,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,SAAS,CAAC;IAClB,CAAC;IACD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IACpE,MAAM,MAAM,GAAG,MAAiC,CAAC;IACjD,IAAI,MAAM,CAAC,IAAI,KAAK,OAAO;QAAE,OAAO,SAAS,CAAC;IAC9C,IAAI,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IACvD,IAAI,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IACzD,IAAI,MAAM,CAAC,YAAY,KAAK,SAAS,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,YAAY,CAAC;QAAE,OAAO,SAAS,CAAC;IAC/F,IACC,MAAM,CAAC,cAAc,KAAK,SAAS;QACnC,CAAC,OAAO,MAAM,CAAC,cAAc,KAAK,QAAQ,IAAI,MAAM,CAAC,cAAc,KAAK,IAAI,CAAC,EAC5E,CAAC;QACF,OAAO,SAAS,CAAC;IAClB,CAAC;IACD,OAAO;QACN,IAAI,EAAE,OAAO;QACb,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,YAAY,EAAE,MAAM,CAAC,YAAoC;QACzD,cAAc,EAAE,MAAM,CAAC,cAA+C;KACtE,CAAC;AACH,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACpC,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC;AAChF,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAC5B,KAAsB,EACtB,QAA6C;IAE7C,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,IAAI,2BAA2B,CAAC;IAChE,IAAI,KAAK,CAAC,OAAO,KAAK,OAAO,EAAE,CAAC;QAC/B,OAAO;YACN,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,kBAAkB;YACxB,MAAM,EAAE,4CAA4C,OAAO,iBAAiB,KAAK,CAAC,OAAO,EAAE;SAC3F,CAAC;IACH,CAAC;IACD,IAAI,KAAK,CAAC,KAAK,KAAK,QAAQ,CAAC,KAAK,EAAE,CAAC;QACpC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,yBAAyB,EAAE,CAAC;IACjF,CAAC;IACD,OAAO,SAAS,CAAC;AAClB,CAAC","sourcesContent":["/**\n * Neo daemon handshake protocol.\n *\n * A connection begins with a single `hello` line from the client. The daemon\n * replies with exactly one `welcome` or `refuse` line, then (on welcome) the\n * connection carries the ordinary JSONL RPC protocol for that connection's\n * runtime. The handshake is additive and lives entirely on the socket — it does\n * not touch the existing stdio RPC command shapes.\n */\n\nimport { NEO_DAEMON_PROTOCOL_VERSION } from \"./neo-daemon-registry.ts\";\nimport type { NeoRuntimeOptions } from \"./neo-runtime-options.ts\";\n\n/** First line a client sends on a fresh connection. */\nexport interface NeoHelloMessage {\n\treadonly type: \"hello\";\n\t/** Must match the daemon's registry token. */\n\treadonly token: string;\n\t/** Client's protocol version; must equal the daemon's. */\n\treadonly version: number;\n\t/** Optional client capability flags (e.g. custom_unsupported opt-in). */\n\treadonly capabilities?: readonly string[];\n\t/** Per-connection runtime options used to build THIS connection's runtime. */\n\treadonly runtimeOptions?: NeoRuntimeOptions;\n}\n\n/** Accepted-handshake reply. */\nexport interface NeoWelcomeMessage {\n\treadonly type: \"welcome\";\n\treadonly version: number;\n\t/** Capabilities the daemon acknowledges for this connection. */\n\treadonly capabilities?: readonly string[];\n}\n\n/** Rejected-handshake reply. The client then falls back to isolated transport. */\nexport interface NeoRefuseMessage {\n\treadonly type: \"refuse\";\n\treadonly reason: string;\n\treadonly code: NeoRefuseCode;\n}\n\nexport type NeoRefuseCode = \"bad_token\" | \"version_mismatch\" | \"unsupported_options\" | \"malformed_hello\";\n\nexport type NeoDaemonHandshakeReply = NeoWelcomeMessage | NeoRefuseMessage;\n\n/** Parse an inbound first line as a hello message, or return undefined. */\nexport function parseHello(line: string): NeoHelloMessage | undefined {\n\tlet parsed: unknown;\n\ttry {\n\t\tparsed = JSON.parse(line);\n\t} catch {\n\t\treturn undefined;\n\t}\n\tif (typeof parsed !== \"object\" || parsed === null) return undefined;\n\tconst record = parsed as Record<string, unknown>;\n\tif (record.type !== \"hello\") return undefined;\n\tif (typeof record.token !== \"string\") return undefined;\n\tif (typeof record.version !== \"number\") return undefined;\n\tif (record.capabilities !== undefined && !isStringArray(record.capabilities)) return undefined;\n\tif (\n\t\trecord.runtimeOptions !== undefined &&\n\t\t(typeof record.runtimeOptions !== \"object\" || record.runtimeOptions === null)\n\t) {\n\t\treturn undefined;\n\t}\n\treturn {\n\t\ttype: \"hello\",\n\t\ttoken: record.token,\n\t\tversion: record.version,\n\t\tcapabilities: record.capabilities as string[] | undefined,\n\t\truntimeOptions: record.runtimeOptions as NeoRuntimeOptions | undefined,\n\t};\n}\n\nfunction isStringArray(value: unknown): value is string[] {\n\treturn Array.isArray(value) && value.every((item) => typeof item === \"string\");\n}\n\n/**\n * Validate a hello against the daemon's token/version. Returns a refuse reply\n * on mismatch, or undefined when the handshake is acceptable. `runtimeOptions`\n * validation (unsupported/incompatible flags) is delegated to the caller since\n * it depends on which options the daemon can honor.\n */\nexport function validateHello(\n\thello: NeoHelloMessage,\n\texpected: { token: string; version?: number },\n): NeoRefuseMessage | undefined {\n\tconst version = expected.version ?? NEO_DAEMON_PROTOCOL_VERSION;\n\tif (hello.version !== version) {\n\t\treturn {\n\t\t\ttype: \"refuse\",\n\t\t\tcode: \"version_mismatch\",\n\t\t\treason: `Protocol version mismatch: daemon speaks ${version}, client sent ${hello.version}`,\n\t\t};\n\t}\n\tif (hello.token !== expected.token) {\n\t\treturn { type: \"refuse\", code: \"bad_token\", reason: \"Invalid handshake token\" };\n\t}\n\treturn undefined;\n}\n"]}

package/dist/modes/rpc/neo-daemon-registry.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Neo daemon registry: the on-disk record clients use to find a running daemon
+ * for a given cwd.
+ *
+ * Layout: `<agentDir>/neo-daemon/<cwd-key>.json`, mode 0600, containing
+ * `{ version, socket, pid, token }`. The daemon is the ONLY writer — clients
+ * only read. Writes are atomic (temp file + rename) so a client never observes a
+ * half-written record.
+ *
+ * `cwd-key` uses the same safe-path scheme as the session manager
+ * (session-manager.ts getDefaultSessionDirPath) so one cwd maps to exactly one
+ * daemon record.
+ */
+/** Bump when the wire protocol or handshake changes incompatibly. */
+export declare const NEO_DAEMON_PROTOCOL_VERSION = 1;
+export interface NeoDaemonRecord {
+    /** Protocol version the daemon speaks; clients refuse on mismatch. */
+    readonly version: number;
+    /** Absolute unix socket path (or Windows named-pipe path) the daemon listens on. */
+    readonly socket: string;
+    /** Daemon process id, used for stale-record detection. */
+    readonly pid: number;
+    /** Handshake token; a client must present it in `hello`. */
+    readonly token: string;
+}
+/**
+ * Compute the safe registry-key for a cwd. Mirrors the session-manager
+ * safe-path scheme so both derive the same key from the same cwd.
+ */
+export declare function neoDaemonCwdKey(cwd: string): string;
+/** Directory holding all neo daemon registry records. */
+export declare function neoDaemonRegistryDir(agentDir: string): string;
+/** Absolute path to the registry record for a cwd. */
+export declare function neoDaemonRegistryPath(agentDir: string, cwd: string): string;
+/**
+ * Read the registry record for a cwd. Returns undefined when the file is
+ * missing, unreadable, or malformed (all non-fatal — the caller then spawns).
+ */
+export declare function readNeoDaemonRecord(agentDir: string, cwd: string): NeoDaemonRecord | undefined;
+/**
+ * Atomically write the registry record (temp file + rename, mode 0600). The
+ * daemon calls this as the LAST listen step, after the socket is bound and
+ * listening.
+ */
+export declare function writeNeoDaemonRecord(agentDir: string, cwd: string, record: NeoDaemonRecord): void;
+/**
+ * Re-assert the daemon's own registry record iff it is missing or does not match
+ * this daemon (version/socket/pid/token). Returns true when a (re-)write happened.
+ *
+ * This is the self-heal that closes the "live daemon owns the deterministic
+ * socket, but its registry record was lost/corrupted (or a SIGKILL left it
+ * missing)" recovery wedge: a fresh client cannot bind a new daemon (the live one
+ * owns the socket) and, with no record, cannot find the live one either. The
+ * daemon calls this on every accepted connection and on a short recurring
+ * interval, so a lost record repairs itself inside the client's attach-poll
+ * window. It NEVER clobbers an already-correct record (idempotent, no write when
+ * the record already points at this daemon), and because there is exactly one
+ * daemon per cwd (the bind mutex), it can never fight another live daemon. The
+ * re-asserted record carries the daemon's real in-memory token, so token auth is
+ * preserved — the client authenticates with the healed token exactly as it would
+ * with the original.
+ */
+export declare function reassertNeoDaemonRecord(agentDir: string, cwd: string, record: NeoDaemonRecord): boolean;
+/** Remove the registry record for a cwd (best-effort; missing is fine). */
+export declare function removeNeoDaemonRecord(agentDir: string, cwd: string): void;
+/**
+ * Whether a pid is alive. `process.kill(pid, 0)` throws ESRCH for a dead pid and
+ * EPERM for a live pid we cannot signal (which still means "alive").
+ */
+export declare function isPidAlive(pid: number): boolean;
+/**
+ * Clean up a stale record + its socket file for a cwd BEFORE a fresh daemon
+ * binds. A record is stale when its pid is dead. Returns true when something was
+ * cleaned. The bound socket path is unlinked so the fresh bind does not hit a
+ * leftover socket file.
+ */
+export declare function cleanupStaleNeoDaemon(agentDir: string, cwd: string): boolean;
+/**
+ * Reclaim a leftover unix-socket file at `listenPath` when NO live daemon is
+ * serving it, so a fresh bind() does not hit EADDRINUSE forever.
+ *
+ * This is the safety net that makes the DETERMINISTIC socket path safe: a daemon
+ * SIGKILLed without a clean shutdown leaves the socket file on disk with its
+ * registry record gone (so {@link cleanupStaleNeoDaemon}, which keys off the
+ * record, misses it). bind() on a leftover unix-socket file throws EADDRINUSE
+ * whether or not anyone is listening, so the fresh daemon must probe the path and
+ * unlink it when it is dead.
+ *
+ * A LIVE daemon serving the socket accepts a connection; we must NOT unlink that
+ * one — the caller then loses the bind race (EADDRINUSE) and attaches to the
+ * winner, which is the intended "bind is the mutex" outcome. We only unlink when
+ * connecting is refused/errors (a dead socket) or the path is a plain file.
+ *
+ * No-op on Windows named pipes (not filesystem paths; the OS reclaims a pipe when
+ * its owner dies) and when nothing exists at the path.
+ */
+export declare function reclaimDeadSocketFile(listenPath: string): Promise<void>;
+//# sourceMappingURL=neo-daemon-registry.d.ts.map

package/dist/modes/rpc/neo-daemon-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"neo-daemon-registry.d.ts","sourceRoot":"","sources":["../../../src/modes/rpc/neo-daemon-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAOH,qEAAqE;AACrE,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAE7C,MAAM,WAAW,eAAe;IAC/B,sEAAsE;IACtE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,oFAAoF;IACpF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,0DAA0D;IAC1D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,4DAA4D;IAC5D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGnD;AAED,yDAAyD;AACzD,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED,sDAAsD;AACtD,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAE3E;AAaD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAe9F;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI,CAOjG;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,OAAO,CAavG;AAED,2EAA2E;AAC3E,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAOzE;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAS/C;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAmB5E;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAU7E"}