@apnex/network-adapter 0.1.0

package/dist/kernel/handshake.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Enriched register_role handshake.
+ *
+ * After the bare `register_role({role})` call in `McpAgentClient.runHandshake`
+ * (which proves the wire is alive and the session is bound), the agent
+ * performs this enriched handshake on entry to the `synchronizing` state. It:
+ *
+ *   1. Re-calls `register_role` with full payload (globalInstanceId,
+ *      clientMetadata, advisoryTags).
+ *   2. Parses the response for `agentId`/`sessionEpoch`/`wasCreated`.
+ *   3. Tracks epoch displacement across reconnects.
+ *   4. Halts on fatal codes (`agent_thrashing_detected`, `role_mismatch`).
+ *
+ * Fatal halt is delegated to a caller-provided `onFatalHalt` callback so
+ * each engineer can implement its own shutdown path (Claude: stdio drain +
+ * `process.exit(2)`; OpenCode: OpenCode lifecycle shutdown).
+ */
+import type { ILogger, LegacyStringLogger } from "../logger.js";
+export declare const FATAL_CODES: ReadonlySet<string>;
+export interface HandshakeClientMetadata {
+    clientName: string;
+    clientVersion: string;
+    proxyName: string;
+    proxyVersion: string;
+    transport: string;
+    sdkVersion: string;
+    hostname?: string;
+    platform?: string;
+    pid?: number;
+}
+export interface HandshakeAdvisoryTags {
+    /** Best-effort, drift-prone. Hub MUST NOT route on this. */
+    llmModel?: string;
+    [key: string]: unknown;
+}
+export interface HandshakePayload {
+    role: string;
+    globalInstanceId: string;
+    clientMetadata: HandshakeClientMetadata;
+    advisoryTags: HandshakeAdvisoryTags;
+    labels?: Record<string, string>;
+}
+export interface HandshakeResponse {
+    agentId: string;
+    sessionEpoch: number;
+    wasCreated: boolean;
+}
+export interface HandshakeFatalError {
+    code: string;
+    message: string;
+}
+/**
+ * Parse an MCP CallTool result for a structured handshake error payload.
+ * Returns the fatal error if the result matches `{isError:true, content:[{text: <json>}]}`
+ * and the JSON body has a `code` in `FATAL_CODES`. Returns null otherwise.
+ */
+export declare function parseHandshakeError(result: unknown): HandshakeFatalError | null;
+/**
+ * Parse a successful handshake response. The adapter's executeTool returns
+ * parsed JSON directly, but some code paths deliver the raw `{content:[{text}]}`
+ * envelope — handle both.
+ *
+ * mission-63 W3: reads canonical envelope per Design v1.0 §3.1 + ADR-028 —
+ * `body.agent.id` + `body.session.epoch` (not `body.agentId` + `body.sessionEpoch`).
+ * The Hub-side flat-field shape is gone post-mission-63 W1+W2 (anti-goal §8.1
+ * clean cutover). Adapter parses the canonical shape only.
+ */
+export declare function parseHandshakeResponse(result: unknown): HandshakeResponse | null;
+export interface HandshakeConfig {
+    role: string;
+    globalInstanceId: string;
+    clientInfo: {
+        name: string;
+        version: string;
+    };
+    proxyName: string;
+    proxyVersion: string;
+    transport: string;
+    sdkVersion: string;
+    llmModel?: string;
+    /**
+     * Mission-19 routing labels. Forwarded as the `labels` arg on the
+     * enriched register_role call. Hub persists them on the Agent entity
+     * (immutable after first create — INV-AG1), and subsequent
+     * `task.labels` / dispatch selectors inherit from the Agent. Omit to
+     * keep legacy broadcast semantics (labels = {}).
+     */
+    labels?: Record<string, string>;
+    /**
+     * ADR-017: optional durable-wake HTTP endpoint. When set, the Hub
+     * POSTs here on queue-deadline miss to cold-start scaled-to-zero
+     * agents. For Cloud Run architects, this is the service URL. Absent
+     * for interactive CLI agents — watchdog skips Stage 1 re-dispatch and
+     * escalates directly to Director notification.
+     */
+    wakeEndpoint?: string;
+    /**
+     * ADR-017: optional per-agent receipt-SLA override in milliseconds.
+     * When omitted, Hub uses DEFAULT_AGENT_RECEIPT_SLA_MS (30000).
+     */
+    receiptSla?: number;
+}
+export interface HandshakeContext {
+    /** Tool executor — typically `transport.request.bind(transport)`. */
+    executeTool: (name: string, args: Record<string, unknown>) => Promise<unknown>;
+    config: HandshakeConfig;
+    /** Previous session epoch for displacement detection. 0 if unknown. */
+    previousEpoch: number;
+    /**
+     * Structured logger for diagnostics + the canonical `[Handshake] Registered as …`
+     * line. A legacy `(msg: string) => void` is auto-bridged for tests and
+     * shims that haven't migrated to `ILogger` yet.
+     */
+    log: ILogger | LegacyStringLogger;
+    /** Invoked on fatal codes. Implementations should terminate the process. */
+    onFatalHalt?: (err: HandshakeFatalError) => void;
+}
+export interface HandshakeResult {
+    /** Parsed response, or null if the handshake failed (non-fatally). */
+    response: HandshakeResponse | null;
+    /** New epoch to persist for the next reconnect's displacement check. */
+    epoch: number;
+}
+/**
+ * bug-17 fix: resolve clientName / clientVersion with proxy-fallback.
+ *
+ * The MCP `initialize` handshake is supposed to carry the host's `clientInfo`
+ * (name + version), but some hosts — notably the claude-plugin dev-channel
+ * load path (`claude --dangerously-load-development-channels`) — don't
+ * forward clientInfo through the stdio transport. The Hub then persists
+ * `clientName: "unknown"` + `clientVersion: "0.0.0"` into the Agent record,
+ * losing the identity signal entirely.
+ *
+ * Fallback policy: when either field is missing/empty/sentinel, substitute
+ * the proxy identity (`@apnex/claude-plugin` / `@apnex/vertex-cloudrun` / etc.)
+ * which is authoritative at the adapter layer. The Agent record then
+ * surfaces a meaningful identity even when MCP clientInfo is absent.
+ *
+ * Exported for unit-test access.
+ */
+export declare function resolveClientName(raw: string | undefined, proxyName: string): string;
+export declare function resolveClientVersion(raw: string | undefined, proxyVersion: string): string;
+/**
+ * Build the enriched register_role payload.
+ */
+export declare function buildHandshakePayload(config: HandshakeConfig): HandshakePayload;
+/**
+ * Perform the enriched handshake. Never throws on tool-call failure — a
+ * transport or session error is logged and returned as
+ * `{response:null, epoch:previousEpoch}` so the caller can continue state
+ * sync. A fatal code (`agent_thrashing_detected`, `role_mismatch`) triggers
+ * `onFatalHalt` and then also returns null.
+ */
+export declare function performHandshake(ctx: HandshakeContext): Promise<HandshakeResult>;
+/**
+ * Build a fatal-halt function with a stdio drain delay. Engineers that use
+ * stdio transports (Claude) MUST use this to avoid losing the halt message
+ * to an unflushed buffer. Engineers that do not (OpenCode) can implement
+ * their own `onFatalHalt` directly.
+ */
+export declare function makeStdioFatalHalt(log: (msg: string) => void, exit?: (code: number) => void, drainMs?: number): (err: HandshakeFatalError) => void;

package/dist/kernel/handshake.js

@@ -0,0 +1,257 @@
+/**
+ * Enriched register_role handshake.
+ *
+ * After the bare `register_role({role})` call in `McpAgentClient.runHandshake`
+ * (which proves the wire is alive and the session is bound), the agent
+ * performs this enriched handshake on entry to the `synchronizing` state. It:
+ *
+ *   1. Re-calls `register_role` with full payload (globalInstanceId,
+ *      clientMetadata, advisoryTags).
+ *   2. Parses the response for `agentId`/`sessionEpoch`/`wasCreated`.
+ *   3. Tracks epoch displacement across reconnects.
+ *   4. Halts on fatal codes (`agent_thrashing_detected`, `role_mismatch`).
+ *
+ * Fatal halt is delegated to a caller-provided `onFatalHalt` callback so
+ * each engineer can implement its own shutdown path (Claude: stdio drain +
+ * `process.exit(2)`; OpenCode: OpenCode lifecycle shutdown).
+ */
+import { hostname, platform as osPlatform } from "node:os";
+import { normalizeToILogger } from "../logger.js";
+export const FATAL_CODES = new Set([
+    "agent_thrashing_detected",
+    "role_mismatch",
+]);
+/**
+ * Parse an MCP CallTool result for a structured handshake error payload.
+ * Returns the fatal error if the result matches `{isError:true, content:[{text: <json>}]}`
+ * and the JSON body has a `code` in `FATAL_CODES`. Returns null otherwise.
+ */
+export function parseHandshakeError(result) {
+    try {
+        const r = result;
+        if (!r || r.isError !== true || !Array.isArray(r.content) || !r.content[0]?.text) {
+            return null;
+        }
+        const body = JSON.parse(r.content[0].text);
+        if (body && typeof body.code === "string" && FATAL_CODES.has(body.code)) {
+            return { code: body.code, message: String(body.message ?? "") };
+        }
+    }
+    catch {
+        /* not a structured error — fall through */
+    }
+    return null;
+}
+/**
+ * Parse a successful handshake response. The adapter's executeTool returns
+ * parsed JSON directly, but some code paths deliver the raw `{content:[{text}]}`
+ * envelope — handle both.
+ *
+ * mission-63 W3: reads canonical envelope per Design v1.0 §3.1 + ADR-028 —
+ * `body.agent.id` + `body.session.epoch` (not `body.agentId` + `body.sessionEpoch`).
+ * The Hub-side flat-field shape is gone post-mission-63 W1+W2 (anti-goal §8.1
+ * clean cutover). Adapter parses the canonical shape only.
+ */
+export function parseHandshakeResponse(result) {
+    try {
+        const r = result;
+        let body;
+        if (Array.isArray(r.content)) {
+            const text = r.content[0]?.text;
+            body = text ? JSON.parse(text) : {};
+        }
+        else {
+            body = r;
+        }
+        const agent = body.agent;
+        const session = body.session;
+        if (agent &&
+            typeof agent.id === "string" &&
+            session &&
+            typeof session.epoch === "number") {
+            return {
+                agentId: agent.id,
+                sessionEpoch: session.epoch,
+                wasCreated: Boolean(body.wasCreated),
+            };
+        }
+    }
+    catch {
+        /* fall through */
+    }
+    return null;
+}
+/**
+ * bug-17 fix: resolve clientName / clientVersion with proxy-fallback.
+ *
+ * The MCP `initialize` handshake is supposed to carry the host's `clientInfo`
+ * (name + version), but some hosts — notably the claude-plugin dev-channel
+ * load path (`claude --dangerously-load-development-channels`) — don't
+ * forward clientInfo through the stdio transport. The Hub then persists
+ * `clientName: "unknown"` + `clientVersion: "0.0.0"` into the Agent record,
+ * losing the identity signal entirely.
+ *
+ * Fallback policy: when either field is missing/empty/sentinel, substitute
+ * the proxy identity (`@apnex/claude-plugin` / `@apnex/vertex-cloudrun` / etc.)
+ * which is authoritative at the adapter layer. The Agent record then
+ * surfaces a meaningful identity even when MCP clientInfo is absent.
+ *
+ * Exported for unit-test access.
+ */
+export function resolveClientName(raw, proxyName) {
+    if (!raw || raw === "unknown")
+        return proxyName;
+    return raw;
+}
+export function resolveClientVersion(raw, proxyVersion) {
+    if (!raw || raw === "0.0.0")
+        return proxyVersion;
+    return raw;
+}
+/**
+ * Build the enriched register_role payload.
+ */
+export function buildHandshakePayload(config) {
+    const payload = {
+        role: config.role,
+        globalInstanceId: config.globalInstanceId,
+        clientMetadata: {
+            clientName: resolveClientName(config.clientInfo.name, config.proxyName),
+            clientVersion: resolveClientVersion(config.clientInfo.version, config.proxyVersion),
+            proxyName: config.proxyName,
+            proxyVersion: config.proxyVersion,
+            transport: config.transport,
+            sdkVersion: config.sdkVersion,
+            hostname: hostname(),
+            platform: osPlatform(),
+            pid: process.pid,
+        },
+        advisoryTags: {
+            llmModel: config.llmModel ?? "unknown",
+        },
+    };
+    if (config.labels)
+        payload.labels = config.labels;
+    if (config.wakeEndpoint)
+        payload.wakeEndpoint = config.wakeEndpoint;
+    if (typeof config.receiptSla === "number")
+        payload.receiptSla = config.receiptSla;
+    return payload;
+}
+/**
+ * Perform the enriched handshake. Never throws on tool-call failure — a
+ * transport or session error is logged and returned as
+ * `{response:null, epoch:previousEpoch}` so the caller can continue state
+ * sync. A fatal code (`agent_thrashing_detected`, `role_mismatch`) triggers
+ * `onFatalHalt` and then also returns null.
+ */
+export async function performHandshake(ctx) {
+    const log = normalizeToILogger(ctx.log, "Handshake");
+    const payload = buildHandshakePayload(ctx.config);
+    let result;
+    try {
+        result = await ctx.executeTool("register_role", payload);
+    }
+    catch (err) {
+        log.log("agent.handshake.tool_call_failed", { error: String(err) }, `[Handshake] tool-call failed (non-fatal, retry on reconnect): ${err}`);
+        return { response: null, epoch: ctx.previousEpoch };
+    }
+    const fatal = parseHandshakeError(result);
+    if (fatal) {
+        log.log("agent.handshake.fatal", { code: fatal.code, message: fatal.message }, `[Handshake] FATAL ${fatal.code}: ${fatal.message}`);
+        if (ctx.onFatalHalt)
+            ctx.onFatalHalt(fatal);
+        return { response: null, epoch: ctx.previousEpoch };
+    }
+    const response = parseHandshakeResponse(result);
+    if (!response) {
+        // mission-63 W3 diagnostic — capture envelope + body shape for parse
+        // failures. Post-mission-63 the canonical shape is `body.agent.id` +
+        // `body.session.epoch`; legacy flat fields (body.agentId + body.sessionEpoch)
+        // surfacing here would indicate the Hub is on a pre-mission-63 build.
+        let envelope = "unknown";
+        let bodyKeys = "none";
+        let nestedAgentKeys = "none";
+        let nestedSessionKeys = "none";
+        let legacyAgentIdType = "absent";
+        let legacySessionEpochType = "absent";
+        try {
+            const r = result;
+            let body = {};
+            if (Array.isArray(r.content)) {
+                envelope = "content-array";
+                const text = r.content[0]
+                    ?.text;
+                body = text ? JSON.parse(text) : {};
+            }
+            else {
+                envelope = "raw-object";
+                body = r;
+            }
+            bodyKeys = Object.keys(body).sort().join(",");
+            if (body.agent && typeof body.agent === "object" && body.agent !== null) {
+                nestedAgentKeys = Object.keys(body.agent)
+                    .sort()
+                    .join(",");
+            }
+            if (body.session && typeof body.session === "object" && body.session !== null) {
+                nestedSessionKeys = Object.keys(body.session)
+                    .sort()
+                    .join(",");
+            }
+            legacyAgentIdType =
+                body.agentId === undefined
+                    ? "undefined"
+                    : body.agentId === null
+                        ? "null"
+                        : typeof body.agentId;
+            legacySessionEpochType =
+                body.sessionEpoch === undefined
+                    ? "undefined"
+                    : body.sessionEpoch === null
+                        ? "null"
+                        : typeof body.sessionEpoch;
+        }
+        catch (err) {
+            envelope = `parse-error:${err?.message ?? String(err)}`;
+        }
+        log.log("agent.handshake.parse_failed", { envelope, bodyKeys, nestedAgentKeys, nestedSessionKeys, legacyAgentIdType, legacySessionEpochType }, "[Handshake] response parse failed (non-fatal)");
+        return { response: null, epoch: ctx.previousEpoch };
+    }
+    // M-Session-Claim-Separation (mission-40) T3 HC #1: post-T2 register_role
+    // is pure identity assertion — does NOT increment sessionEpoch. The
+    // previousEpoch vs response.sessionEpoch comparison no longer detects
+    // "I just took over" (that signal lives on claim_session's response
+    // shape: sessionClaimed + displacedPriorSession). It still detects
+    // "someone else claimed our identity between our last register_role
+    // and this one": any positive delta means an out-of-band claim happened.
+    // Pre-T2 the threshold was `> 1` (because register_role itself bumped
+    // by 1 on every call). Post-T2 the threshold is `> 0`.
+    //
+    // Takeover detection inside the adapter (claude-plugin shim.ts T3) keys
+    // on the claim_session response fields, NOT on this delta — see
+    // mission-40 brief §3 T3 + anti-goal §7.5.
+    if (ctx.previousEpoch > 0 && response.sessionEpoch - ctx.previousEpoch > 0) {
+        log.log("agent.handshake.epoch_jump", { from: ctx.previousEpoch, to: response.sessionEpoch }, `[Handshake] sessionEpoch advanced from ${ctx.previousEpoch} to ${response.sessionEpoch} between register_role calls — an external claim_session has displaced our prior session; in-flight RPCs from prior epoch may be abandoned`);
+    }
+    log.log("agent.handshake.registered", {
+        agentId: response.agentId,
+        epoch: response.sessionEpoch,
+        wasCreated: response.wasCreated,
+    }, `[Handshake] Registered as ${response.agentId} (epoch=${response.sessionEpoch}${response.wasCreated ? ", newly created" : ""})`);
+    return { response, epoch: response.sessionEpoch };
+}
+/**
+ * Build a fatal-halt function with a stdio drain delay. Engineers that use
+ * stdio transports (Claude) MUST use this to avoid losing the halt message
+ * to an unflushed buffer. Engineers that do not (OpenCode) can implement
+ * their own `onFatalHalt` directly.
+ */
+export function makeStdioFatalHalt(log, exit = process.exit.bind(process), drainMs = 100) {
+    return (err) => {
+        const text = `[FATAL:${err.code}] ${err.message}`;
+        log(text);
+        setTimeout(() => exit(2), drainMs);
+    };
+}
+//# sourceMappingURL=handshake.js.map

package/dist/kernel/handshake.js.map

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

package/dist/kernel/instance.d.ts

@@ -0,0 +1,40 @@
+/**
+ * globalInstanceId bootstrap.
+ *
+ * Identity is decoupled from authentication: the Hub token grants *access*
+ * and *role*; the globalInstanceId grants *identity*. This lets tokens be
+ * rotated without orphaning Agent entities.
+ *
+ * Storage: ~/.ois/instance.json (owner-private, 0600). NOT workspace-local —
+ * workspace scoping fails on multi-terminal, clone, and accidental git commit.
+ *
+ * First call generates a new UUID v4. Subsequent calls read it. If the file
+ * is deleted or corrupted, a new UUID is generated → new fingerprint → Hub
+ * creates a new Agent. The old Agent remains append-only with its queue
+ * intact; use `migrate_agent_queue` to recover pending work.
+ */
+export interface LoadInstanceOptions {
+    /** Override the default ~/.ois/instance.json location (for tests). */
+    instanceFile?: string;
+    /** Optional logger for diagnostics (regeneration on corruption, etc.). */
+    log?: (msg: string) => void;
+}
+/**
+ * Load an existing globalInstanceId from disk or create a new one.
+ * Returns the UUID (or the env-provided string override). Idempotent
+ * across calls within a process.
+ *
+ * Precedence: `OIS_INSTANCE_ID` env var wins outright — used when the
+ * operator wants a stable, human-meaningful identity (e.g. "greg" or
+ * "kate") and is responsible for uniqueness themselves. Absent that,
+ * falls back to the file-persisted UUID (original behaviour). The env
+ * path does NOT touch the file, so the two schemes coexist cleanly:
+ * toggling the env var off restores the file-derived UUID untouched.
+ *
+ * This is a pragmatic escape hatch that unblocks multi-agent
+ * co-location on a single user account (two Claude instances on one
+ * laptop). A richer design — separate agentName metadata plus an
+ * agentId derived from multiple inputs — is queued for the Entity
+ * Registry SSOT mission.
+ */
+export declare function loadOrCreateGlobalInstanceId(opts?: LoadInstanceOptions): string;

package/dist/kernel/instance.js

@@ -0,0 +1,79 @@
+/**
+ * globalInstanceId bootstrap.
+ *
+ * Identity is decoupled from authentication: the Hub token grants *access*
+ * and *role*; the globalInstanceId grants *identity*. This lets tokens be
+ * rotated without orphaning Agent entities.
+ *
+ * Storage: ~/.ois/instance.json (owner-private, 0600). NOT workspace-local —
+ * workspace scoping fails on multi-terminal, clone, and accidental git commit.
+ *
+ * First call generates a new UUID v4. Subsequent calls read it. If the file
+ * is deleted or corrupted, a new UUID is generated → new fingerprint → Hub
+ * creates a new Agent. The old Agent remains append-only with its queue
+ * intact; use `migrate_agent_queue` to recover pending work.
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { randomUUID } from "node:crypto";
+const DEFAULT_INSTANCE_DIR = join(homedir(), ".ois");
+const DEFAULT_INSTANCE_FILE = join(DEFAULT_INSTANCE_DIR, "instance.json");
+/**
+ * Load an existing globalInstanceId from disk or create a new one.
+ * Returns the UUID (or the env-provided string override). Idempotent
+ * across calls within a process.
+ *
+ * Precedence: `OIS_INSTANCE_ID` env var wins outright — used when the
+ * operator wants a stable, human-meaningful identity (e.g. "greg" or
+ * "kate") and is responsible for uniqueness themselves. Absent that,
+ * falls back to the file-persisted UUID (original behaviour). The env
+ * path does NOT touch the file, so the two schemes coexist cleanly:
+ * toggling the env var off restores the file-derived UUID untouched.
+ *
+ * This is a pragmatic escape hatch that unblocks multi-agent
+ * co-location on a single user account (two Claude instances on one
+ * laptop). A richer design — separate agentName metadata plus an
+ * agentId derived from multiple inputs — is queued for the Entity
+ * Registry SSOT mission.
+ */
+export function loadOrCreateGlobalInstanceId(opts = {}) {
+    const log = opts.log ?? (() => { });
+    const envOverride = process.env.OIS_INSTANCE_ID?.trim();
+    if (envOverride) {
+        log(`[instance] Using OIS_INSTANCE_ID from env: ${envOverride}`);
+        return envOverride;
+    }
+    const file = opts.instanceFile ?? DEFAULT_INSTANCE_FILE;
+    const dir = file.substring(0, file.lastIndexOf("/")) || DEFAULT_INSTANCE_DIR;
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    if (existsSync(file)) {
+        try {
+            const raw = JSON.parse(readFileSync(file, "utf-8"));
+            if (raw.globalInstanceId && typeof raw.globalInstanceId === "string") {
+                return raw.globalInstanceId;
+            }
+            log(`[instance] ${file} missing globalInstanceId — regenerating`);
+        }
+        catch (err) {
+            log(`[instance] Failed to parse ${file}: ${err} — regenerating`);
+        }
+    }
+    const globalInstanceId = randomUUID();
+    const body = {
+        globalInstanceId,
+        createdAt: new Date().toISOString(),
+    };
+    writeFileSync(file, JSON.stringify(body, null, 2), { mode: 0o600 });
+    try {
+        chmodSync(file, 0o600);
+    }
+    catch {
+        /* best effort — filesystem may not support chmod */
+    }
+    log(`[instance] Generated new globalInstanceId → ${file}`);
+    return globalInstanceId;
+}
+//# sourceMappingURL=instance.js.map

package/dist/kernel/instance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance.js","sourceRoot":"","sources":["../../src/kernel/instance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACxF,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,MAAM,oBAAoB,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,MAAM,CAAC,CAAC;AACrD,MAAM,qBAAqB,GAAG,IAAI,CAAC,oBAAoB,EAAE,eAAe,CAAC,CAAC;AAc1E;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,4BAA4B,CAC1C,OAA4B,EAAE;IAE9B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,GAAgB,CAAC,CAAC,CAAC;IAEjD,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,IAAI,EAAE,CAAC;IACxD,IAAI,WAAW,EAAE,CAAC;QAChB,GAAG,CAAC,8CAA8C,WAAW,EAAE,CAAC,CAAC;QACjE,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,MAAM,IAAI,GAAG,IAAI,CAAC,YAAY,IAAI,qBAAqB,CAAC;IACxD,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,IAAI,oBAAoB,CAAC;IAE7E,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACrB,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACnD,CAAC;IAED,IAAI,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACrB,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAiB,CAAC;YACpE,IAAI,GAAG,CAAC,gBAAgB,IAAI,OAAO,GAAG,CAAC,gBAAgB,KAAK,QAAQ,EAAE,CAAC;gBACrE,OAAO,GAAG,CAAC,gBAAgB,CAAC;YAC9B,CAAC;YACD,GAAG,CAAC,cAAc,IAAI,0CAA0C,CAAC,CAAC;QACpE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,GAAG,CAAC,8BAA8B,IAAI,KAAK,GAAG,iBAAiB,CAAC,CAAC;QACnE,CAAC;IACH,CAAC;IAED,MAAM,gBAAgB,GAAG,UAAU,EAAE,CAAC;IACtC,MAAM,IAAI,GAAiB;QACzB,gBAAgB;QAChB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACpC,CAAC;IACF,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACpE,IAAI,CAAC;QACH,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACzB,CAAC;IAAC,MAAM,CAAC;QACP,oDAAoD;IACtD,CAAC;IACD,GAAG,CAAC,+CAA+C,IAAI,EAAE,CAAC,CAAC;IAC3D,OAAO,gBAAgB,CAAC;AAC1B,CAAC"}