@apnex/network-adapter 0.1.2 → 0.1.6

package/dist/kernel/build-identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-identity.js","sourceRoot":"","sources":["../../src/kernel/build-identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,6EAA6E;AAC7E,MAAM,UAAU,kBAAkB,CAAC,WAAmB,EAAE,QAAgB;IACtE,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC;QAC3D,OAAO,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC;IAClE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,QAAQ,CAAC;IAClB,CAAC;AACH,CAAC;AAUD,MAAM,CAAC,MAAM,kBAAkB,GAAc;IAC3C,SAAS,EAAE,SAAS;IACpB,KAAK,EAAE,KAAK;IACZ,SAAS,EAAE,IAAI;IACf,MAAM,EAAE,SAAS;CAClB,CAAC;AAEF,kFAAkF;AAClF,MAAM,UAAU,aAAa,CAAC,aAAqB;IACjD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC,CAAC;QAC7D,OAAO;YACL,SAAS,EAAE,OAAO,GAAG,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS;YACxE,KAAK,EAAE,CAAC,CAAC,GAAG,CAAC,KAAK;YAClB,SAAS,EAAE,OAAO,GAAG,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI;YACnE,MAAM,EAAE,OAAO,GAAG,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS;SAChE,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,kBAAkB,CAAC;IAC5B,CAAC;AACH,CAAC"}

package/dist/kernel/event-router.d.ts

@@ -6,6 +6,7 @@
  * from this module and only implement their own dispatch mechanisms
  * (Push-to-LLM for the Plugin, Sandwich pattern for the Architect).
  */
+import type { DrainedPendingAction } from "./state-sync.js";
 /** All known Hub event types */
 export type HubEventType = "task_issued" | "directive_acknowledged" | "report_submitted" | "review_completed" | "revision_required" | "proposal_submitted" | "proposal_decided" | "clarification_requested" | "clarification_answered" | "thread_opened" | "thread_message" | "thread_convergence_finalized" | "thread_abandoned" | "idea_submitted" | "mission_created" | "mission_activated" | "turn_created" | "turn_updated" | "tele_defined" | "director_attention_required" | "cascade_failure" | "message_arrived" | "agent_state_changed";
 /** Parsed, typed event envelope */
@@ -24,7 +25,27 @@ export type EventDisposition = "actionable" | "informational" | "unhandled";
  * "informational" if it's FYI only, or "unhandled" if the event
  * is not recognized for this role.
  */
-export declare function classifyEvent(event: string, role: "engineer" | "architect"): EventDisposition;
+export declare function classifyEvent(event: string, role: "engineer" | "architect" | "verifier"): EventDisposition;
+/** Pulse-kind discriminators that route to informational level (Mission-57 W3). */
+export declare const PULSE_KINDS: ReadonlySet<string>;
+/**
+ * Detect whether an event is a pulse Message (status_check or
+ * missed_threshold_escalation): a `message_arrived` event whose
+ * `data.message.payload.pulseKind` ∈ PULSE_KINDS.
+ */
+export declare function isPulseEvent(eventType: string, eventData?: Record<string, unknown>): boolean;
+export interface DrainedActionReconstruction {
+    /** {event,data} — structurally an AgentEvent for the host wake to consume. */
+    agentEvent: {
+        event: string;
+        data: Record<string, unknown>;
+    };
+    /** Diagnostic-log action hint (identical across both shims). */
+    actionHint: string;
+    /** Notification level — pulse Messages downgrade to informational. */
+    level: "actionable" | "informational";
+}
+export declare function reconstructDrainedAction(item: DrainedPendingAction): DrainedActionReconstruction;
 /**
  * Parse raw eventData from the ConnectionManager into a typed HubEvent.
  */

package/dist/kernel/event-router.js

@@ -76,13 +76,51 @@ export function classifyEvent(event, role) {
             return "informational";
         return "unhandled";
     }
-    else {
-        if (ARCHITECT_ACTIONABLE.has(event))
-            return "actionable";
-        if (ARCHITECT_INFORMATIONAL.has(event))
-            return "informational";
-        return "unhandled";
-    }
+    // architect + verifier (mission-93): the verifier's directed-wake surface
+    // ≈ the architect's (thread_message / review_requested / pulse / directed
+    // notifications per verifier-role.md §2.1), so it shares the architect
+    // classification set rather than mis-falling through an engineer path.
+    if (ARCHITECT_ACTIONABLE.has(event))
+        return "actionable";
+    if (ARCHITECT_INFORMATIONAL.has(event))
+        return "informational";
+    return "unhandled";
+}
+// ── Pulse detection (M-OpenCode-Shim-Sovereign-Dedup, idea-331) ──────
+//
+// Hoisted to core from the two shims (claude-plugin/src/source-attribute.ts
+// + the opencode shim's inlined mirror — its own comment admitted the dup).
+// Sibling to classifyEvent: both shims call isPulseEvent to downgrade a
+// pulse Message's notification level from "actionable" to "informational"
+// (Mission-57 W3 / Design v1.0 §4 — S3 noise reduction during high-activity
+// sub-PR cascades). `eventData` is OPTIONAL (Claude's signature) so the one
+// core impl serves both shims behavior-preservingly.
+/** Pulse-kind discriminators that route to informational level (Mission-57 W3). */
+export const PULSE_KINDS = new Set([
+    "status_check",
+    "missed_threshold_escalation",
+]);
+/**
+ * Detect whether an event is a pulse Message (status_check or
+ * missed_threshold_escalation): a `message_arrived` event whose
+ * `data.message.payload.pulseKind` ∈ PULSE_KINDS.
+ */
+export function isPulseEvent(eventType, eventData) {
+    if (eventType !== "message_arrived" || !eventData)
+        return false;
+    const message = eventData.message;
+    const payload = message?.payload;
+    return typeof payload?.pulseKind === "string" && PULSE_KINDS.has(payload.pulseKind);
+}
+export function reconstructDrainedAction(item) {
+    const agentEvent = { event: item.dispatchType, data: item.payload };
+    const actionHint = item.dispatchType === "thread_message"
+        ? `Reply with create_thread_reply to thread ${item.entityRef}`
+        : `Owed: ${item.dispatchType} on ${item.entityRef}`;
+    const level = isPulseEvent(agentEvent.event, agentEvent.data)
+        ? "informational"
+        : "actionable";
+    return { agentEvent, actionHint, level };
 }
 // ── Event Parsing ────────────────────────────────────────────────────
 /**

package/dist/kernel/event-router.js.map

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

package/dist/kernel/handshake.d.ts

@@ -5,8 +5,9 @@
  * (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).
+ *   1. Re-calls `register_role` with full payload (name, clientMetadata,
+ *      advisoryTags). idea-251 D-prime Phase 2: name IS identity (was
+ *      globalInstanceId pre-D-prime; that field RETIRED).
  *   2. Parses the response for `agentId`/`sessionEpoch`/`wasCreated`.
  *   3. Tracks epoch displacement across reconnects.
  *   4. Halts on fatal codes (`agent_thrashing_detected`, `role_mismatch`).
@@ -27,6 +28,10 @@ export interface HandshakeClientMetadata {
     hostname?: string;
     platform?: string;
     pid?: number;
+    proxyCommitSha?: string;
+    proxyDirty?: boolean;
+    sdkCommitSha?: string;
+    sdkDirty?: boolean;
 }
 export interface HandshakeAdvisoryTags {
     /** Best-effort, drift-prone. Hub MUST NOT route on this. */
@@ -35,10 +40,16 @@ export interface HandshakeAdvisoryTags {
 }
 export interface HandshakePayload {
     role: string;
-    globalInstanceId: string;
     clientMetadata: HandshakeClientMetadata;
     advisoryTags: HandshakeAdvisoryTags;
     labels?: Record<string, string>;
+    /**
+     * idea-251 D-prime Phase 2: name IS identity. REQUIRED. Sourced from the
+     * `OIS_AGENT_NAME` env var by the host process; passed through here. Drives
+     * agentId derivation `agent-{8-hex-of-sha256(name)}` on the Hub side.
+     * (`globalInstanceId` field RETIRED in D-prime — name replaces it.)
+     */
+    name: string;
 }
 export interface HandshakeResponse {
     agentId: string;
@@ -68,7 +79,6 @@ export declare function parseHandshakeError(result: unknown): HandshakeFatalErro
 export declare function parseHandshakeResponse(result: unknown): HandshakeResponse | null;
 export interface HandshakeConfig {
     role: string;
-    globalInstanceId: string;
     clientInfo: {
         name: string;
         version: string;
@@ -77,6 +87,10 @@ export interface HandshakeConfig {
     proxyVersion: string;
     transport: string;
     sdkVersion: string;
+    proxyCommitSha?: string;
+    proxyDirty?: boolean;
+    sdkCommitSha?: string;
+    sdkDirty?: boolean;
     llmModel?: string;
     /**
      * Mission-19 routing labels. Forwarded as the `labels` arg on the
@@ -99,6 +113,12 @@ export interface HandshakeConfig {
      * When omitted, Hub uses DEFAULT_AGENT_RECEIPT_SLA_MS (30000).
      */
     receiptSla?: number;
+    /**
+     * idea-251 D-prime Phase 2: name IS identity. REQUIRED. Operator sets via
+     * `OIS_AGENT_NAME` env var; host shim passes through. Hub derives
+     * `agent-{8-hex-of-sha256(name)}` agentId from this.
+     */
+    name: string;
 }
 export interface HandshakeContext {
     /** Tool executor — typically `transport.request.bind(transport)`. */
@@ -120,6 +140,13 @@ export interface HandshakeResult {
     response: HandshakeResponse | null;
     /** New epoch to persist for the next reconnect's displacement check. */
     epoch: number;
+    /**
+     * True when register_role was REJECTED by a structured fatal error
+     * (FATAL_CODES — e.g. role_mismatch). The caller MUST HALT, not silently
+     * degrade to streaming with a fallback role. mission-93 cutover: that
+     * silent degrade masked a role-change rejection for an hour.
+     */
+    fatal?: boolean;
 }
 /**
  * bug-17 fix: resolve clientName / clientVersion with proxy-fallback.
@@ -140,6 +167,15 @@ export interface HandshakeResult {
  */
 export declare function resolveClientName(raw: string | undefined, proxyName: string): string;
 export declare function resolveClientVersion(raw: string | undefined, proxyVersion: string): string;
+/**
+ * idea-251 D-prime Phase 2 + idea-355 SLICE-1 dedup: read the REQUIRED
+ * OIS_AGENT_NAME identity (name IS identity per idea-251). Reads + trims +
+ * loud-errors if absent (returns null) so misconfiguration surfaces at startup
+ * rather than a silent Hub-side identity collision. The caller keeps the
+ * one-line host-specific abort (claude `process.exit(2)`; opencode `return` —
+ * it can't kill the TUI).
+ */
+export declare function readRequiredAgentName(log: (m: string) => void): string | null;
 /**
  * Build the enriched register_role payload.
  */

package/dist/kernel/handshake.js

@@ -5,8 +5,9 @@
  * (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).
+ *   1. Re-calls `register_role` with full payload (name, clientMetadata,
+ *      advisoryTags). idea-251 D-prime Phase 2: name IS identity (was
+ *      globalInstanceId pre-D-prime; that field RETIRED).
  *   2. Parses the response for `agentId`/`sessionEpoch`/`wasCreated`.
  *   3. Tracks epoch displacement across reconnects.
  *   4. Halts on fatal codes (`agent_thrashing_detected`, `role_mismatch`).
@@ -29,11 +30,25 @@ export const FATAL_CODES = new Set([
 export function parseHandshakeError(result) {
     try {
         const r = result;
-        if (!r || r.isError !== true || !Array.isArray(r.content) || !r.content[0]?.text) {
+        if (!r || typeof r !== "object")
             return null;
+        let body;
+        let envelopeError = false;
+        if (Array.isArray(r.content) && r.content[0]?.text) {
+            // {content:[{text:<json>}], isError} envelope shape.
+            body = JSON.parse(r.content[0].text);
+            envelopeError = r.isError === true;
         }
-        const body = JSON.parse(r.content[0].text);
-        if (body && typeof body.code === "string" && FATAL_CODES.has(body.code)) {
+        else {
+            // Parsed-body-directly shape: executeTool unwraps the envelope on some
+            // transports (e.g. bun-serve-proxy / opencode), dropping the isError
+            // flag — so the body-level `ok:false` is the failure signal. mission-93:
+            // this unwrapped path is exactly why a role_mismatch rejection fell
+            // through to parse_failed + silent engineer/offline degrade for Steve.
+            body = r;
+        }
+        const isFailure = envelopeError || body.ok === false;
+        if (isFailure && typeof body.code === "string" && FATAL_CODES.has(body.code)) {
             return { code: body.code, message: String(body.message ?? "") };
         }
     }
@@ -108,13 +123,30 @@ export function resolveClientVersion(raw, proxyVersion) {
         return proxyVersion;
     return raw;
 }
+/**
+ * idea-251 D-prime Phase 2 + idea-355 SLICE-1 dedup: read the REQUIRED
+ * OIS_AGENT_NAME identity (name IS identity per idea-251). Reads + trims +
+ * loud-errors if absent (returns null) so misconfiguration surfaces at startup
+ * rather than a silent Hub-side identity collision. The caller keeps the
+ * one-line host-specific abort (claude `process.exit(2)`; opencode `return` —
+ * it can't kill the TUI).
+ */
+export function readRequiredAgentName(log) {
+    const agentName = process.env.OIS_AGENT_NAME?.trim();
+    if (!agentName) {
+        log("[Handshake] FATAL: OIS_AGENT_NAME env var required (idea-251 D-prime). Set in ~/.config/apnex-agents/{name}.env.");
+        return null;
+    }
+    log(`[Handshake] OIS_AGENT_NAME=${agentName}`);
+    return agentName;
+}
 /**
  * Build the enriched register_role payload.
  */
 export function buildHandshakePayload(config) {
     const payload = {
         role: config.role,
-        globalInstanceId: config.globalInstanceId,
+        name: config.name,
         clientMetadata: {
             clientName: resolveClientName(config.clientInfo.name, config.proxyName),
             clientVersion: resolveClientVersion(config.clientInfo.version, config.proxyVersion),
@@ -125,6 +157,13 @@ export function buildHandshakePayload(config) {
             hostname: hostname(),
             platform: osPlatform(),
             pid: process.pid,
+            // M-Build-Identity-AdvisoryTag (idea-256): forward build-identity
+            // when host provided it; omit otherwise (Hub gracefully treats
+            // absent as legacy / unknown).
+            ...(config.proxyCommitSha !== undefined && { proxyCommitSha: config.proxyCommitSha }),
+            ...(config.proxyDirty !== undefined && { proxyDirty: config.proxyDirty }),
+            ...(config.sdkCommitSha !== undefined && { sdkCommitSha: config.sdkCommitSha }),
+            ...(config.sdkDirty !== undefined && { sdkDirty: config.sdkDirty }),
         },
         advisoryTags: {
             llmModel: config.llmModel ?? "unknown",
@@ -161,7 +200,7 @@ export async function performHandshake(ctx) {
         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 };
+        return { response: null, epoch: ctx.previousEpoch, fatal: true };
     }
     const response = parseHandshakeResponse(result);
     if (!response) {

package/dist/kernel/handshake.js.map

@@ -1 +1 @@
-{"version":3,"file":"handshake.js","sourceRoot":"","sources":["../../src/kernel/handshake.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,QAAQ,EAAE,QAAQ,IAAI,UAAU,EAAE,MAAM,SAAS,CAAC;AAE3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAElD,MAAM,CAAC,MAAM,WAAW,GAAwB,IAAI,GAAG,CAAC;IACtD,0BAA0B;IAC1B,eAAe;CAChB,CAAC,CAAC;AAuCH;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAe;IACjD,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,MAAmE,CAAC;QAC9E,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;YACjF,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAC3C,IAAI,IAAI,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACxE,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC,EAAE,CAAC;QAClE,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,2CAA2C;IAC7C,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAAe;IACpD,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,MAA0E,CAAC;QACrF,IAAI,IAA6B,CAAC;QAClC,IAAI,KAAK,CAAC,OAAO,CAAE,CAA6B,CAAC,OAAO,CAAC,EAAE,CAAC;YAC1D,MAAM,IAAI,GAAI,CAA2C,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC;YAC3E,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACtC,CAAC;aAAM,CAAC;YACN,IAAI,GAAG,CAA4B,CAAC;QACtC,CAAC;QACD,MAAM,KAAK,GAAG,IAAI,CAAC,KAA4C,CAAC;QAChE,MAAM,OAAO,GAAG,IAAI,CAAC,OAA8C,CAAC;QACpE,IACE,KAAK;YACL,OAAO,KAAK,CAAC,EAAE,KAAK,QAAQ;YAC5B,OAAO;YACP,OAAO,OAAO,CAAC,KAAK,KAAK,QAAQ,EACjC,CAAC;YACD,OAAO;gBACL,OAAO,EAAE,KAAK,CAAC,EAAE;gBACjB,YAAY,EAAE,OAAO,CAAC,KAAK;gBAC3B,UAAU,EAAE,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC;aACrC,CAAC;QACJ,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,kBAAkB;IACpB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAyDD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAuB,EAAE,SAAiB;IAC1E,IAAI,CAAC,GAAG,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAChD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,GAAuB,EAAE,YAAoB;IAChF,IAAI,CAAC,GAAG,IAAI,GAAG,KAAK,OAAO;QAAE,OAAO,YAAY,CAAC;IACjD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAuB;IAC3D,MAAM,OAAO,GAAqB;QAChC,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,gBAAgB,EAAE,MAAM,CAAC,gBAAgB;QACzC,cAAc,EAAE;YACd,UAAU,EAAE,iBAAiB,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,SAAS,CAAC;YACvE,aAAa,EAAE,oBAAoB,CAAC,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC,YAAY,CAAC;YACnF,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,YAAY,EAAE,MAAM,CAAC,YAAY;YACjC,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,QAAQ,EAAE,QAAQ,EAAE;YACpB,QAAQ,EAAE,UAAU,EAAE;YACtB,GAAG,EAAE,OAAO,CAAC,GAAG;SACjB;QACD,YAAY,EAAE;YACZ,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,SAAS;SACvC;KACF,CAAC;IACF,IAAI,MAAM,CAAC,MAAM;QAAE,OAAO,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAClD,IAAI,MAAM,CAAC,YAAY;QAAG,OAA8C,CAAC,YAAY,GAAG,MAAM,CAAC,YAAY,CAAC;IAC5G,IAAI,OAAO,MAAM,CAAC,UAAU,KAAK,QAAQ;QAAG,OAA8C,CAAC,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC;IAC1H,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,GAAqB;IAErB,MAAM,GAAG,GAAG,kBAAkB,CAAC,GAAG,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;IACrD,MAAM,OAAO,GAAG,qBAAqB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAElD,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,GAAG,CAAC,WAAW,CAAC,eAAe,EAAE,OAA6C,CAAC,CAAC;IACjG,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,GAAG,CAAC,GAAG,CACL,kCAAkC,EAClC,EAAE,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,EACtB,iEAAiE,GAAG,EAAE,CACvE,CAAC;QACF,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,aAAa,EAAE,CAAC;IACtD,CAAC;IAED,MAAM,KAAK,GAAG,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAC1C,IAAI,KAAK,EAAE,CAAC;QACV,GAAG,CAAC,GAAG,CACL,uBAAuB,EACvB,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,EAC5C,qBAAqB,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE,CACpD,CAAC;QACF,IAAI,GAAG,CAAC,WAAW;YAAE,GAAG,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;QAC5C,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,aAAa,EAAE,CAAC;IACtD,CAAC;IAED,MAAM,QAAQ,GAAG,sBAAsB,CAAC,MAAM,CAAC,CAAC;IAChD,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,qEAAqE;QACrE,qEAAqE;QACrE,8EAA8E;QAC9E,sEAAsE;QACtE,IAAI,QAAQ,GAAG,SAAS,CAAC;QACzB,IAAI,QAAQ,GAAG,MAAM,CAAC;QACtB,IAAI,eAAe,GAAG,MAAM,CAAC;QAC7B,IAAI,iBAAiB,GAAG,MAAM,CAAC;QAC/B,IAAI,iBAAiB,GAAG,QAAQ,CAAC;QACjC,IAAI,sBAAsB,GAAG,QAAQ,CAAC;QACtC,IAAI,CAAC;YACH,MAAM,CAAC,GAAG,MAEiB,CAAC;YAC5B,IAAI,IAAI,GAA4B,EAAE,CAAC;YACvC,IAAI,KAAK,CAAC,OAAO,CAAE,CAA6B,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC1D,QAAQ,GAAG,eAAe,CAAC;gBAC3B,MAAM,IAAI,GAAI,CAA2C,CAAC,OAAO,CAAC,CAAC,CAAC;oBAClE,EAAE,IAAI,CAAC;gBACT,IAAI,GAAG,IAAI,CAAC,CAAC,CAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAA6B,CAAC,CAAC,CAAC,EAAE,CAAC;YACnE,CAAC;iBAAM,CAAC;gBACN,QAAQ,GAAG,YAAY,CAAC;gBACxB,IAAI,GAAG,CAA4B,CAAC;YACtC,CAAC;YACD,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAC9C,IAAI,IAAI,CAAC,KAAK,IAAI,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,IAAI,IAAI,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;gBACxE,eAAe,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAgC,CAAC;qBACjE,IAAI,EAAE;qBACN,IAAI,CAAC,GAAG,CAAC,CAAC;YACf,CAAC;YACD,IAAI,IAAI,CAAC,OAAO,IAAI,OAAO,IAAI,CAAC,OAAO,KAAK,QAAQ,IAAI,IAAI,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;gBAC9E,iBAAiB,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,OAAkC,CAAC;qBACrE,IAAI,EAAE;qBACN,IAAI,CAAC,GAAG,CAAC,CAAC;YACf,CAAC;YACD,iBAAiB;gBACf,IAAI,CAAC,OAAO,KAAK,SAAS;oBACxB,CAAC,CAAC,WAAW;oBACb,CAAC,CAAC,IAAI,CAAC,OAAO,KAAK,IAAI;wBACrB,CAAC,CAAC,MAAM;wBACR,CAAC,CAAC,OAAO,IAAI,CAAC,OAAO,CAAC;YAC5B,sBAAsB;gBACpB,IAAI,CAAC,YAAY,KAAK,SAAS;oBAC7B,CAAC,CAAC,WAAW;oBACb,CAAC,CAAC,IAAI,CAAC,YAAY,KAAK,IAAI;wBAC1B,CAAC,CAAC,MAAM;wBACR,CAAC,CAAC,OAAO,IAAI,CAAC,YAAY,CAAC;QACnC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,QAAQ,GAAG,eAAgB,GAAa,EAAE,OAAO,IAAI,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;QACrE,CAAC;QACD,GAAG,CAAC,GAAG,CACL,8BAA8B,EAC9B,EAAE,QAAQ,EAAE,QAAQ,EAAE,eAAe,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,EACrG,+CAA+C,CAChD,CAAC;QACF,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,aAAa,EAAE,CAAC;IACtD,CAAC;IAED,0EAA0E;IAC1E,oEAAoE;IACpE,sEAAsE;IACtE,oEAAoE;IACpE,mEAAmE;IACnE,oEAAoE;IACpE,yEAAyE;IACzE,sEAAsE;IACtE,uDAAuD;IACvD,EAAE;IACF,wEAAwE;IACxE,gEAAgE;IAChE,2CAA2C;IAC3C,IAAI,GAAG,CAAC,aAAa,GAAG,CAAC,IAAI,QAAQ,CAAC,YAAY,GAAG,GAAG,CAAC,aAAa,GAAG,CAAC,EAAE,CAAC;QAC3E,GAAG,CAAC,GAAG,CACL,4BAA4B,EAC5B,EAAE,IAAI,EAAE,GAAG,CAAC,aAAa,EAAE,EAAE,EAAE,QAAQ,CAAC,YAAY,EAAE,EACtD,0CAA0C,GAAG,CAAC,aAAa,OAAO,QAAQ,CAAC,YAAY,4IAA4I,CACpO,CAAC;IACJ,CAAC;IACD,GAAG,CAAC,GAAG,CACL,4BAA4B,EAC5B;QACE,OAAO,EAAE,QAAQ,CAAC,OAAO;QACzB,KAAK,EAAE,QAAQ,CAAC,YAAY;QAC5B,UAAU,EAAE,QAAQ,CAAC,UAAU;KAChC,EACD,6BAA6B,QAAQ,CAAC,OAAO,WAAW,QAAQ,CAAC,YAAY,GAAG,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,EAAE,GAAG,CAChI,CAAC;IAEF,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,CAAC,YAAY,EAAE,CAAC;AACpD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAChC,GAA0B,EAC1B,OAA+B,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAA2B,EACnF,OAAO,GAAG,GAAG;IAEb,OAAO,CAAC,GAAG,EAAE,EAAE;QACb,MAAM,IAAI,GAAG,UAAU,GAAG,CAAC,IAAI,KAAK,GAAG,CAAC,OAAO,EAAE,CAAC;QAClD,GAAG,CAAC,IAAI,CAAC,CAAC;QACV,UAAU,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IACrC,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"handshake.js","sourceRoot":"","sources":["../../src/kernel/handshake.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,QAAQ,EAAE,QAAQ,IAAI,UAAU,EAAE,MAAM,SAAS,CAAC;AAE3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAElD,MAAM,CAAC,MAAM,WAAW,GAAwB,IAAI,GAAG,CAAC;IACtD,0BAA0B;IAC1B,eAAe;CAChB,CAAC,CAAC;AAqDH;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAe;IACjD,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,MAA6F,CAAC;QACxG,IAAI,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QAC7C,IAAI,IAA6B,CAAC;QAClC,IAAI,aAAa,GAAG,KAAK,CAAC;QAC1B,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;YACnD,qDAAqD;YACrD,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;YACrC,aAAa,GAAG,CAAC,CAAC,OAAO,KAAK,IAAI,CAAC;QACrC,CAAC;aAAM,CAAC;YACN,uEAAuE;YACvE,qEAAqE;YACrE,yEAAyE;YACzE,oEAAoE;YACpE,uEAAuE;YACvE,IAAI,GAAG,CAAC,CAAC;QACX,CAAC;QACD,MAAM,SAAS,GAAG,aAAa,IAAI,IAAI,CAAC,EAAE,KAAK,KAAK,CAAC;QACrD,IAAI,SAAS,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAC7E,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC,EAAE,CAAC;QAClE,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,2CAA2C;IAC7C,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAAe;IACpD,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,MAA0E,CAAC;QACrF,IAAI,IAA6B,CAAC;QAClC,IAAI,KAAK,CAAC,OAAO,CAAE,CAA6B,CAAC,OAAO,CAAC,EAAE,CAAC;YAC1D,MAAM,IAAI,GAAI,CAA2C,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC;YAC3E,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACtC,CAAC;aAAM,CAAC;YACN,IAAI,GAAG,CAA4B,CAAC;QACtC,CAAC;QACD,MAAM,KAAK,GAAG,IAAI,CAAC,KAA4C,CAAC;QAChE,MAAM,OAAO,GAAG,IAAI,CAAC,OAA8C,CAAC;QACpE,IACE,KAAK;YACL,OAAO,KAAK,CAAC,EAAE,KAAK,QAAQ;YAC5B,OAAO;YACP,OAAO,OAAO,CAAC,KAAK,KAAK,QAAQ,EACjC,CAAC;YACD,OAAO;gBACL,OAAO,EAAE,KAAK,CAAC,EAAE;gBACjB,YAAY,EAAE,OAAO,CAAC,KAAK;gBAC3B,UAAU,EAAE,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC;aACrC,CAAC;QACJ,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,kBAAkB;IACpB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AA6ED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAuB,EAAE,SAAiB;IAC1E,IAAI,CAAC,GAAG,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAChD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,GAAuB,EAAE,YAAoB;IAChF,IAAI,CAAC,GAAG,IAAI,GAAG,KAAK,OAAO;QAAE,OAAO,YAAY,CAAC;IACjD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAwB;IAC5D,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE,IAAI,EAAE,CAAC;IACrD,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,GAAG,CACD,kHAAkH,CACnH,CAAC;QACF,OAAO,IAAI,CAAC;IACd,CAAC;IACD,GAAG,CAAC,8BAA8B,SAAS,EAAE,CAAC,CAAC;IAC/C,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAuB;IAC3D,MAAM,OAAO,GAAqB;QAChC,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,cAAc,EAAE;YACd,UAAU,EAAE,iBAAiB,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,SAAS,CAAC;YACvE,aAAa,EAAE,oBAAoB,CAAC,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC,YAAY,CAAC;YACnF,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,YAAY,EAAE,MAAM,CAAC,YAAY;YACjC,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,QAAQ,EAAE,QAAQ,EAAE;YACpB,QAAQ,EAAE,UAAU,EAAE;YACtB,GAAG,EAAE,OAAO,CAAC,GAAG;YAChB,kEAAkE;YAClE,+DAA+D;YAC/D,+BAA+B;YAC/B,GAAG,CAAC,MAAM,CAAC,cAAc,KAAK,SAAS,IAAI,EAAE,cAAc,EAAE,MAAM,CAAC,cAAc,EAAE,CAAC;YACrF,GAAG,CAAC,MAAM,CAAC,UAAU,KAAK,SAAS,IAAI,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,CAAC;YACzE,GAAG,CAAC,MAAM,CAAC,YAAY,KAAK,SAAS,IAAI,EAAE,YAAY,EAAE,MAAM,CAAC,YAAY,EAAE,CAAC;YAC/E,GAAG,CAAC,MAAM,CAAC,QAAQ,KAAK,SAAS,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC;SACpE;QACD,YAAY,EAAE;YACZ,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,SAAS;SACvC;KACF,CAAC;IACF,IAAI,MAAM,CAAC,MAAM;QAAE,OAAO,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAClD,IAAI,MAAM,CAAC,YAAY;QAAG,OAA8C,CAAC,YAAY,GAAG,MAAM,CAAC,YAAY,CAAC;IAC5G,IAAI,OAAO,MAAM,CAAC,UAAU,KAAK,QAAQ;QAAG,OAA8C,CAAC,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC;IAC1H,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,GAAqB;IAErB,MAAM,GAAG,GAAG,kBAAkB,CAAC,GAAG,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;IACrD,MAAM,OAAO,GAAG,qBAAqB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAElD,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,GAAG,CAAC,WAAW,CAAC,eAAe,EAAE,OAA6C,CAAC,CAAC;IACjG,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,GAAG,CAAC,GAAG,CACL,kCAAkC,EAClC,EAAE,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,EACtB,iEAAiE,GAAG,EAAE,CACvE,CAAC;QACF,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,aAAa,EAAE,CAAC;IACtD,CAAC;IAED,MAAM,KAAK,GAAG,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAC1C,IAAI,KAAK,EAAE,CAAC;QACV,GAAG,CAAC,GAAG,CACL,uBAAuB,EACvB,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,EAC5C,qBAAqB,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE,CACpD,CAAC;QACF,IAAI,GAAG,CAAC,WAAW;YAAE,GAAG,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;QAC5C,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,aAAa,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACnE,CAAC;IAED,MAAM,QAAQ,GAAG,sBAAsB,CAAC,MAAM,CAAC,CAAC;IAChD,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,qEAAqE;QACrE,qEAAqE;QACrE,8EAA8E;QAC9E,sEAAsE;QACtE,IAAI,QAAQ,GAAG,SAAS,CAAC;QACzB,IAAI,QAAQ,GAAG,MAAM,CAAC;QACtB,IAAI,eAAe,GAAG,MAAM,CAAC;QAC7B,IAAI,iBAAiB,GAAG,MAAM,CAAC;QAC/B,IAAI,iBAAiB,GAAG,QAAQ,CAAC;QACjC,IAAI,sBAAsB,GAAG,QAAQ,CAAC;QACtC,IAAI,CAAC;YACH,MAAM,CAAC,GAAG,MAEiB,CAAC;YAC5B,IAAI,IAAI,GAA4B,EAAE,CAAC;YACvC,IAAI,KAAK,CAAC,OAAO,CAAE,CAA6B,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC1D,QAAQ,GAAG,eAAe,CAAC;gBAC3B,MAAM,IAAI,GAAI,CAA2C,CAAC,OAAO,CAAC,CAAC,CAAC;oBAClE,EAAE,IAAI,CAAC;gBACT,IAAI,GAAG,IAAI,CAAC,CAAC,CAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAA6B,CAAC,CAAC,CAAC,EAAE,CAAC;YACnE,CAAC;iBAAM,CAAC;gBACN,QAAQ,GAAG,YAAY,CAAC;gBACxB,IAAI,GAAG,CAA4B,CAAC;YACtC,CAAC;YACD,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAC9C,IAAI,IAAI,CAAC,KAAK,IAAI,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,IAAI,IAAI,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;gBACxE,eAAe,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAgC,CAAC;qBACjE,IAAI,EAAE;qBACN,IAAI,CAAC,GAAG,CAAC,CAAC;YACf,CAAC;YACD,IAAI,IAAI,CAAC,OAAO,IAAI,OAAO,IAAI,CAAC,OAAO,KAAK,QAAQ,IAAI,IAAI,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;gBAC9E,iBAAiB,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,OAAkC,CAAC;qBACrE,IAAI,EAAE;qBACN,IAAI,CAAC,GAAG,CAAC,CAAC;YACf,CAAC;YACD,iBAAiB;gBACf,IAAI,CAAC,OAAO,KAAK,SAAS;oBACxB,CAAC,CAAC,WAAW;oBACb,CAAC,CAAC,IAAI,CAAC,OAAO,KAAK,IAAI;wBACrB,CAAC,CAAC,MAAM;wBACR,CAAC,CAAC,OAAO,IAAI,CAAC,OAAO,CAAC;YAC5B,sBAAsB;gBACpB,IAAI,CAAC,YAAY,KAAK,SAAS;oBAC7B,CAAC,CAAC,WAAW;oBACb,CAAC,CAAC,IAAI,CAAC,YAAY,KAAK,IAAI;wBAC1B,CAAC,CAAC,MAAM;wBACR,CAAC,CAAC,OAAO,IAAI,CAAC,YAAY,CAAC;QACnC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,QAAQ,GAAG,eAAgB,GAAa,EAAE,OAAO,IAAI,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;QACrE,CAAC;QACD,GAAG,CAAC,GAAG,CACL,8BAA8B,EAC9B,EAAE,QAAQ,EAAE,QAAQ,EAAE,eAAe,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,EACrG,+CAA+C,CAChD,CAAC;QACF,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,aAAa,EAAE,CAAC;IACtD,CAAC;IAED,0EAA0E;IAC1E,oEAAoE;IACpE,sEAAsE;IACtE,oEAAoE;IACpE,mEAAmE;IACnE,oEAAoE;IACpE,yEAAyE;IACzE,sEAAsE;IACtE,uDAAuD;IACvD,EAAE;IACF,wEAAwE;IACxE,gEAAgE;IAChE,2CAA2C;IAC3C,IAAI,GAAG,CAAC,aAAa,GAAG,CAAC,IAAI,QAAQ,CAAC,YAAY,GAAG,GAAG,CAAC,aAAa,GAAG,CAAC,EAAE,CAAC;QAC3E,GAAG,CAAC,GAAG,CACL,4BAA4B,EAC5B,EAAE,IAAI,EAAE,GAAG,CAAC,aAAa,EAAE,EAAE,EAAE,QAAQ,CAAC,YAAY,EAAE,EACtD,0CAA0C,GAAG,CAAC,aAAa,OAAO,QAAQ,CAAC,YAAY,4IAA4I,CACpO,CAAC;IACJ,CAAC;IACD,GAAG,CAAC,GAAG,CACL,4BAA4B,EAC5B;QACE,OAAO,EAAE,QAAQ,CAAC,OAAO;QACzB,KAAK,EAAE,QAAQ,CAAC,YAAY;QAC5B,UAAU,EAAE,QAAQ,CAAC,UAAU;KAChC,EACD,6BAA6B,QAAQ,CAAC,OAAO,WAAW,QAAQ,CAAC,YAAY,GAAG,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,EAAE,GAAG,CAChI,CAAC;IAEF,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,CAAC,YAAY,EAAE,CAAC;AACpD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAChC,GAA0B,EAC1B,OAA+B,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAA2B,EACnF,OAAO,GAAG,GAAG;IAEb,OAAO,CAAC,GAAG,EAAE,EAAE;QACb,MAAM,IAAI,GAAG,UAAU,GAAG,CAAC,IAAI,KAAK,GAAG,CAAC,OAAO,EAAE,CAAC;QAClD,GAAG,CAAC,IAAI,CAAC,CAAC;QACV,UAAU,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IACrC,CAAC,CAAC;AACJ,CAAC"}

package/dist/kernel/harness-manifest.d.ts

@@ -0,0 +1,51 @@
+/** A 3-valued capability cell (scion-steelman: yes/partial/no + REASON + per-capability unevenness). */
+export interface HarnessCapability {
+    value: "yes" | "partial" | "no";
+    reason: string;
+}
+export interface HarnessManifest {
+    /** Schema version (forward-compat). */
+    manifestVersion: 1;
+    /** Harness id, e.g. "claude" | "opencode". */
+    harness: string;
+    /** npm package name of the shim, e.g. "@apnex/claude-plugin". */
+    proxyName: string;
+    /** Transport id reported on handshake, e.g. "stdio-mcp-proxy". */
+    transport: string;
+    /** MCP server name, e.g. "proxy". */
+    serverName: string;
+    /** Tool-prefix / dialect the host sees, e.g. "mcp__plugin_agent-adapter_proxy__". */
+    toolPrefix: string;
+    /**
+     * Last-hop injection mechanism (capability-matrix seed). For claude this is the
+     * MCP server-notification method exposed as an experimental server capability
+     * (e.g. "claude/channel"); the shim builds serverCapabilities from it.
+     */
+    injectionChannel: string;
+    /** Free-form mechanism descriptor, e.g. "mcp-server-notification". */
+    injectionMechanism: string;
+    /** Optional protocol dialect descriptor (e.g. "mcp"). (P1e A8 — folds the manifest's dialect field.) */
+    dialect?: string;
+    /** The 3-valued per-capability matrix (capability-name -> cell). */
+    capabilityMatrix: Record<string, HarnessCapability>;
+    /** Credential resolution order, e.g. ["defaults","file","env"]. */
+    authOrder: string[];
+    /** Per-agent ENV var NAMES (instance config); values live in the environment, never here. */
+    envTemplate: string[];
+}
+/**
+ * Validate + parse a raw object into a HarnessManifest. Throws a field-named
+ * Error on any violation (fail-closed). Returns the typed manifest on success.
+ */
+export declare function parseHarnessManifest(raw: unknown): HarnessManifest;
+/** Read + validate a manifest JSON file. Throws on read or validation failure (fail-closed). */
+export declare function loadHarnessManifest(path: string): HarnessManifest;
+/**
+ * Build the MCP serverCapabilities object from a manifest's injectionChannel —
+ * the experimental server-notification capability the host negotiates (e.g.
+ * { tools: {}, experimental: { "claude/channel": {} } }).
+ */
+export declare function serverCapabilitiesFromManifest(m: HarnessManifest): {
+    tools: Record<string, never>;
+    experimental: Record<string, Record<string, never>>;
+};

package/dist/kernel/harness-manifest.js

@@ -0,0 +1,96 @@
+/**
+ * Harness manifest — the per-harness STANDARD config as schema-validated DATA
+ * (M-Adapter-Modernization Design §3, P1b — the #1 shim-audit structural gap).
+ *
+ * The per-harness config (proxyName, transport, serverName, tool-prefix/dialect,
+ * injection-mechanism, the 3-valued capability-matrix, auth-order, env-template)
+ * was hardcoded inline in each shim. This single-homes it as a schema-validated
+ * JSON manifest the shim LOADS, so per-harness variation is DATA (references, not
+ * topology) and a new harness is a manifest + thin glue. Per-AGENT INSTANCE values
+ * (hubUrl/token/name/labels) stay in ENV — the manifest lists only the var NAMES
+ * (envTemplate), never the values.
+ *
+ * Validation is HAND-ROLLED (no zod — it is a dev-dep only; the kernel's existing
+ * validators — parseLabels, parseHandshakeResponse — are hand-rolled too) so the
+ * published package carries no extra runtime dep. parseHarnessManifest throws a
+ * field-named error on any violation (fail-closed; a malformed manifest must not
+ * boot a mis-shaped adapter).
+ */
+import { readFileSync } from "node:fs";
+function fail(msg) {
+    throw new Error(`harness-manifest: ${msg}`);
+}
+function str(obj, key) {
+    const v = obj[key];
+    if (typeof v !== "string" || v.length === 0)
+        fail(`field '${key}' must be a non-empty string`);
+    return v;
+}
+function strArray(obj, key) {
+    const v = obj[key];
+    if (!Array.isArray(v) || !v.every((x) => typeof x === "string"))
+        fail(`field '${key}' must be a string[]`);
+    return v;
+}
+/**
+ * Validate + parse a raw object into a HarnessManifest. Throws a field-named
+ * Error on any violation (fail-closed). Returns the typed manifest on success.
+ */
+export function parseHarnessManifest(raw) {
+    if (typeof raw !== "object" || raw === null)
+        fail("manifest must be a JSON object");
+    const o = raw;
+    if (o.manifestVersion !== 1)
+        fail("manifestVersion must be 1");
+    const cmRaw = o.capabilityMatrix;
+    if (typeof cmRaw !== "object" || cmRaw === null || Array.isArray(cmRaw)) {
+        fail("field 'capabilityMatrix' must be an object map");
+    }
+    const capabilityMatrix = {};
+    for (const [name, cell] of Object.entries(cmRaw)) {
+        if (typeof cell !== "object" || cell === null)
+            fail(`capability '${name}' must be an object`);
+        const c = cell;
+        if (c.value !== "yes" && c.value !== "partial" && c.value !== "no") {
+            fail(`capability '${name}'.value must be one of yes|partial|no (got ${JSON.stringify(c.value)})`);
+        }
+        if (typeof c.reason !== "string" || c.reason.length === 0) {
+            fail(`capability '${name}'.reason must be a non-empty string (the per-capability unevenness rationale)`);
+        }
+        capabilityMatrix[name] = { value: c.value, reason: c.reason };
+    }
+    return {
+        manifestVersion: 1,
+        harness: str(o, "harness"),
+        proxyName: str(o, "proxyName"),
+        transport: str(o, "transport"),
+        serverName: str(o, "serverName"),
+        toolPrefix: str(o, "toolPrefix"),
+        injectionChannel: str(o, "injectionChannel"),
+        injectionMechanism: str(o, "injectionMechanism"),
+        ...(typeof o.dialect === "string" ? { dialect: o.dialect } : {}),
+        capabilityMatrix,
+        authOrder: strArray(o, "authOrder"),
+        envTemplate: strArray(o, "envTemplate"),
+    };
+}
+/** Read + validate a manifest JSON file. Throws on read or validation failure (fail-closed). */
+export function loadHarnessManifest(path) {
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch (err) {
+        fail(`cannot read/parse manifest at ${path}: ${err?.message ?? String(err)}`);
+    }
+    return parseHarnessManifest(raw);
+}
+/**
+ * Build the MCP serverCapabilities object from a manifest's injectionChannel —
+ * the experimental server-notification capability the host negotiates (e.g.
+ * { tools: {}, experimental: { "claude/channel": {} } }).
+ */
+export function serverCapabilitiesFromManifest(m) {
+    return { tools: {}, experimental: { [m.injectionChannel]: {} } };
+}
+//# sourceMappingURL=harness-manifest.js.map

package/dist/kernel/harness-manifest.js.map

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

package/dist/kernel/liveness-signal.d.ts

@@ -0,0 +1,35 @@
+/** EX_TEMPFAIL — the wedged-restart container-exit code the P1e supervisor uses. */
+export declare const WEDGED_RESTART_EXIT_CODE = 75;
+/** Default sentinel path PID-1 watches. Override via OIS_LIVENESS_SENTINEL (P1e mounts /run). */
+export declare const DEFAULT_LIVENESS_SENTINEL = "/run/adapter-wedged";
+export interface LivenessLostSignalPayload {
+    reason: "session-wedged";
+    consecutiveFailures: number;
+    /** The code PID-1 should exit the CONTAINER with (NOT the shim's exit code). */
+    exitCode: number;
+    emittedAt: string;
+    pid: number;
+    lastError?: string;
+}
+export interface EmitLivenessLostOptions {
+    sentinelPath?: string;
+    consecutiveFailures: number;
+    lastError?: unknown;
+    now?: () => string;
+    /** Injectable writer (tests). Default writes the file, mkdir-p the parent dir. */
+    writeFile?: (path: string, data: string) => void;
+    log?: (msg: string) => void;
+}
+/**
+ * Resolve the sentinel path: explicit opt > OIS_LIVENESS_SENTINEL env > default.
+ */
+export declare function resolveSentinelPath(explicit?: string): string;
+/**
+ * Emit the liveness-lost sentinel (the kernel->PID-1 signal). Writes the JSON
+ * payload durably and returns it. Does NOT itself exit the process — the caller
+ * chains the in-process self-exit AFTER this returns, so the sentinel is on disk
+ * before the shim dies and the supervisor can read it. Never throws out: a write
+ * failure is logged (the self-exit still proceeds; L3 lease-reclaim is the final
+ * backstop) but does not mask the wedge.
+ */
+export declare function emitLivenessLostSignal(opts: EmitLivenessLostOptions): LivenessLostSignalPayload;

package/dist/kernel/liveness-signal.js

@@ -0,0 +1,61 @@
+/**
+ * Liveness-lost signal-contract — the kernel->supervisor seam (Design §4 P1c,
+ * the EMBEDDED exit-propagation seam).
+ *
+ * In the EMBEDDED topology (PID-1 supervisor -> CLI -> kernel-shim GRANDCHILD)
+ * the kernel CANNOT exit the container by itself: `process.exit` kills only the
+ * shim, the CLI swallows its exit code, and PID-1 (the supervisor) never sees it.
+ * So liveness-loss is signalled to PID-1 DIRECTLY + OUT-OF-BAND via a SENTINEL
+ * file. P1c (here) EMITS the sentinel; P1e's PID-1 supervisor CONSUMES it -> exits
+ * the container with WEDGED_RESTART_EXIT_CODE -> docker-L2 restart-on-exit fires
+ * -> a fresh container re-handshakes + re-claims.
+ *
+ * The distinct code (75 / EX_TEMPFAIL) carries "wedged — restart me" semantics
+ * (vs a clean exit 0). It is the SIGNAL payload's code + the code PID-1 exits the
+ * CONTAINER with — NOT the grandchild shim's exit code (which the CLI discards).
+ */
+import { writeFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+/** EX_TEMPFAIL — the wedged-restart container-exit code the P1e supervisor uses. */
+export const WEDGED_RESTART_EXIT_CODE = 75;
+/** Default sentinel path PID-1 watches. Override via OIS_LIVENESS_SENTINEL (P1e mounts /run). */
+export const DEFAULT_LIVENESS_SENTINEL = "/run/adapter-wedged";
+/**
+ * Resolve the sentinel path: explicit opt > OIS_LIVENESS_SENTINEL env > default.
+ */
+export function resolveSentinelPath(explicit) {
+    return explicit ?? process.env.OIS_LIVENESS_SENTINEL ?? DEFAULT_LIVENESS_SENTINEL;
+}
+/**
+ * Emit the liveness-lost sentinel (the kernel->PID-1 signal). Writes the JSON
+ * payload durably and returns it. Does NOT itself exit the process — the caller
+ * chains the in-process self-exit AFTER this returns, so the sentinel is on disk
+ * before the shim dies and the supervisor can read it. Never throws out: a write
+ * failure is logged (the self-exit still proceeds; L3 lease-reclaim is the final
+ * backstop) but does not mask the wedge.
+ */
+export function emitLivenessLostSignal(opts) {
+    const path = resolveSentinelPath(opts.sentinelPath);
+    const payload = {
+        reason: "session-wedged",
+        consecutiveFailures: opts.consecutiveFailures,
+        exitCode: WEDGED_RESTART_EXIT_CODE,
+        emittedAt: (opts.now ?? (() => new Date().toISOString()))(),
+        pid: process.pid,
+        ...(opts.lastError !== undefined ? { lastError: String(opts.lastError) } : {}),
+    };
+    const write = opts.writeFile ??
+        ((p, d) => {
+            mkdirSync(dirname(p), { recursive: true });
+            writeFileSync(p, d);
+        });
+    try {
+        write(path, JSON.stringify(payload, null, 2) + "\n");
+        opts.log?.(`[LivenessSignal] wrote wedged-restart sentinel ${path} (exitCode ${WEDGED_RESTART_EXIT_CODE}, ${opts.consecutiveFailures} failures); PID-1 supervisor consumes -> container-exit -> docker-L2 restart`);
+    }
+    catch (err) {
+        opts.log?.(`[LivenessSignal] FAILED to write sentinel ${path}: ${err} — self-exit proceeds; L3 lease-reclaim is the backstop`);
+    }
+    return payload;
+}
+//# sourceMappingURL=liveness-signal.js.map

package/dist/kernel/liveness-signal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"liveness-signal.js","sourceRoot":"","sources":["../../src/kernel/liveness-signal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,oFAAoF;AACpF,MAAM,CAAC,MAAM,wBAAwB,GAAG,EAAE,CAAC;AAE3C,iGAAiG;AACjG,MAAM,CAAC,MAAM,yBAAyB,GAAG,qBAAqB,CAAC;AAsB/D;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAAiB;IACnD,OAAO,QAAQ,IAAI,OAAO,CAAC,GAAG,CAAC,qBAAqB,IAAI,yBAAyB,CAAC;AACpF,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAA6B;IAClE,MAAM,IAAI,GAAG,mBAAmB,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IACpD,MAAM,OAAO,GAA8B;QACzC,MAAM,EAAE,gBAAgB;QACxB,mBAAmB,EAAE,IAAI,CAAC,mBAAmB;QAC7C,QAAQ,EAAE,wBAAwB;QAClC,SAAS,EAAE,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC,EAAE;QAC3D,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,GAAG,CAAC,IAAI,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC/E,CAAC;IACF,MAAM,KAAK,GACT,IAAI,CAAC,SAAS;QACd,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;YACR,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAC3C,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACtB,CAAC,CAAC,CAAC;IACL,IAAI,CAAC;QACH,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;QACrD,IAAI,CAAC,GAAG,EAAE,CACR,kDAAkD,IAAI,cAAc,wBAAwB,KAAK,IAAI,CAAC,mBAAmB,8EAA8E,CACxM,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,GAAG,EAAE,CAAC,6CAA6C,IAAI,KAAK,GAAG,yDAAyD,CAAC,CAAC;IACjI,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}