@canonmsg/backend-contracts 1.9.0 → 2.1.0

package/dist/bridgeLocal.js

@@ -1,744 +0,0 @@
-// Bridge ⇄ runtime-adapter LOCAL JSON-RPC contract v1 (types + schemas ONLY —
-// no runtime, no transport; Phase 4 builds the bridge against these).
-//
-// Source spec: docs/design/bridge-local-api.md §A–§C. Where that draft
-// conflicts with code-grounded wire shapes (event names, REST payloads), the
-// code-grounded schemas in this package win — payload slots below COMPOSE
-// restEndpoints.ts / hitl.ts / sseEvents.ts / controlSignals.ts so every
-// shape is defined once.
-//
-// Protocol: JSON-RPC 2.0 over one duplex channel (stdio pipe or unix
-// socket / named pipe), NDJSON framing. Requests adapter→bridge (replied),
-// notifications bridge→adapter (never awaited). `hello` carries
-// protocolVersion — the local contract is version-guarded from v1.
-import { z } from 'zod';
-import { SerializedContactRequestSchema } from './contactRequest.js';
-import { DeliveryIntentSchema, TurnLifecycleStateSchema } from './turnProtocol.js';
-import { ControlPrimitiveEventSchema, ControlSessionEventSchema, ControlSignalEventSchema, } from './controlSignals.js';
-import { HitlApprovalCategorySchema, HitlApprovalDetailSchema, HitlApprovalRiskSchema, HitlInputKindSchema, HitlInputQuestionSchema, HitlPendingSchema, HitlRequestAcceptedSchema, HitlResolutionSchema, HitlResolutionStatusSchema, } from './hitl.js';
-import { ContactsResponseSchema, ConversationsResponseSchema, CreateContactRequestRequestSchema, CreateContactRequestResponseSchema, CreateConversationRequestSchema, CreateConversationResponseSchema, ForwardMessageRequestSchema, ForwardMessageResponseSchema, MessagesPageResponseSchema, ReactRequestSchema, ReactResponseSchema, ResolveAdmissionRequestSchema, ResolveAdmissionResponseSchema, RestContactSchema, RestSessionSelectionSchema, SendMessageRequestSchema, SendMessageResponseSchema, UpdateDispositionRequestSchema, UploadMediaResponseSchema, } from './restEndpoints.js';
-import { SendContextualRequestSchema, SendContextualResponseSchema, } from './sendContextual.js';
-import { SseAgentContextPayloadSchema, SseConversationUpdatedPayloadSchema, SseEventFamilySchema, SseMessageCreatedPayloadSchema, SseMessageDeletedPayloadSchema, SseMessageUpdatedPayloadSchema, SsePresencePayloadSchema, SseTypingPayloadSchema, SseVoiceSessionEventPayloadSchema, } from './sseEvents.js';
-export const BRIDGE_LOCAL_PROTOCOL_VERSION = 1;
-const OkResultSchema = z.object({ ok: z.literal(true) });
-export { OkResultSchema as BridgeOkResultSchema };
-// ── §A Session lifecycle ───────────────────────────────────────────────
-export const BridgeHelloParamsSchema = z.object({
-    protocolVersion: z.number(),
-    /** Adapter self-identification (claude-code | codex | openclaw | hermes | …). */
-    clientType: z.string(),
-    /** Event families to deliver; [] = pure-request adapter, no C-notifications. */
-    wantFamilies: z.array(SseEventFamilySchema),
-    /** Replay C-notifications missed while disconnected. */
-    resumeCursor: z.string().optional(),
-    /** Publish the runtime descriptor in the same round trip. */
-    runtimeDescriptor: z.record(z.string(), z.unknown()).optional(),
-});
-// ── §G resume cursor / resync ───────────────────────────────────────────
-//
-// The bridge keeps a bounded, locally-sequenced event log. Every replayable
-// §C event notification carries the OPAQUE `cursor` token that produced it;
-// adapters persist the last cursor they fully processed and present it as
-// `hello.resumeCursor` on reconnect to replay exactly the gap. When the
-// cursor cannot be honored the hello result answers `sinceCursor: null`
-// PLUS a `resync` field — the adapter must treat the gap as lost locally and
-// recover out-of-band (REST backfill / state refresh). Never silent loss.
-export const BridgeResyncReasonSchema = z.enum([
-    /** Cursor was valid but its events were evicted from the bounded log. */
-    'cursor-expired',
-    /** Cursor was never issued by this bridge run (restart or corruption). */
-    'unknown-cursor',
-]);
-export const BridgeResyncSchema = z.object({
-    reason: BridgeResyncReasonSchema,
-});
-/**
- * Shape mixin for replayable §C notification params (`.extend(...)` onto the
- * payload schema). `cursor` is optional in the schema for compatibility, but
- * the bridge always sends it on log-delivered notifications. `ready` and
- * `connectionState` are connection-scoped (never replayed) and carry none.
- */
-export const BRIDGE_EVENT_CURSOR_SHAPE = {
-    cursor: z.string().optional(),
-};
-export const BridgeHelloResultSchema = z.object({
-    protocolVersion: z.number(),
-    agentId: z.string(),
-    agentName: z.string(),
-    agentContext: SseAgentContextPayloadSchema,
-    /** Cursor the delivered replay starts from; null = no replay. */
-    sinceCursor: z.string().nullable(),
-    /**
-     * Present when resumeCursor could not be honored (§G): delivery starts at
-     * the live head and the adapter must recover the gap out-of-band.
-     */
-    resync: BridgeResyncSchema.optional(),
-});
-export const BridgeUpstreamStateSchema = z.enum(['connected', 'reconnecting', 'down']);
-export const BridgeReadyNotificationSchema = z.object({
-    agentId: z.string(),
-    agentContext: SseAgentContextPayloadSchema,
-    upstreamState: BridgeUpstreamStateSchema,
-});
-export const BridgeConnectionStateNotificationSchema = z.object({
-    upstream: BridgeUpstreamStateSchema,
-});
-/**
- * `status` result (B4.6 observability): a live snapshot of the daemon
- * process, its upstream health, and the B4.2 hub counters. Additive to
- * contract v1 — served by the daemon and rendered by `canon-bridge status`.
- */
-export const BridgeStatusResultSchema = z.object({
-    /** Daemon process id. */
-    pid: z.number(),
-    /** canon-bridge binary (package) version. */
-    version: z.string(),
-    /** bridgeLocal contract version the daemon speaks. */
-    protocolVersion: z.number(),
-    /** ISO timestamp of daemon start. */
-    startedAt: z.string(),
-    uptimeMs: z.number(),
-    /** Lifecycle profile served (one identity per daemon). */
-    profile: z.string(),
-    /** Socket / named-pipe path; null in stdio (spawned-child) mode. */
-    socketPath: z.string().nullable(),
-    agentId: z.string(),
-    agentName: z.string(),
-    upstream: BridgeUpstreamStateSchema,
-    /** Adapter connections currently subscribed to the fan-out. */
-    connectedClients: z.number(),
-    /** Non-zero B4.2 hub counters (upstream.* / fanout.*). */
-    counters: z.record(z.string(), z.number()),
-});
-// ── §B7 HITL state (durable; resolution arrives via onHitlResolved) ────
-export const BridgeHitlStateSchema = z.object({
-    status: z.union([z.literal('pending'), HitlResolutionStatusSchema]),
-    answer: z.record(z.string(), z.unknown()).optional(),
-    expiresAt: z.string(),
-});
-// ── §B8 media (named schemas so the bridge + Framework share the types) ──
-//
-// Byte transfer is bridge-owned (adapter-interface §1): adapters hand the
-// bridge a {path} (streamed from disk — preferred for anything big) or
-// inline {bytes} (base64, size-capped so a frame never breaches the NDJSON
-// line limit). getAttachment returns the bridge-cached materialization.
-export const BridgeUploadMediaParamsSchema = z.object({
-    /** Absolute file path — the bridge streams it (exactly one of path | bytes). */
-    path: z.string().optional(),
-    /** Base64 bytes — size-capped by the bridge; prefer `path` for large files. */
-    bytes: z.string().optional(),
-    mime: z.string(),
-    fileName: z.string(),
-    conversationId: z.string(),
-});
-export const BridgeGetAttachmentParamsSchema = z.object({
-    /** Storage download URL from a MediaAttachment (exactly one of url | attachmentId). */
-    url: z.string().optional(),
-    attachmentId: z.string().optional(),
-    as: z.enum(['path', 'bytes']),
-});
-export const BridgeGetAttachmentResultSchema = z.object({
-    /** Stable bridge-cache path — present when as:'path'. */
-    path: z.string().optional(),
-    /** Base64 — present when as:'bytes'; capped by the bridge's bytes ceiling. */
-    bytes: z.string().optional(),
-    mime: z.string(),
-});
-const conversationScoped = z.object({ conversationId: z.string() });
-const messageScoped = z.object({ conversationId: z.string(), messageId: z.string() });
-/**
- * RTDB server-timestamp sentinel — code-grounded pass-through (hosts write
- * `{'.sv':'timestamp'}` for openedAt/completedAt today; the bridge forwards
- * it to the RTDB REST API untouched).
- */
-const ServerTimestampSentinelSchema = z.object({ '.sv': z.literal('timestamp') });
-const EpochOrServerTimestampSchema = z.union([z.number(), ServerTimestampSentinelSchema]);
-// ─────────────────────────────────────────────────────────────────────────
-// W2-A4 REGION START — bridge-owned streaming assembly (raw event surface).
-// ADDITIVE: `publishStreamingEvent` lets a channel adapter forward RAW turn
-// events (a text segment begin/append/replace, a tool-trail item, a thinking
-// tick, a final compose, or a clear). The BRIDGE owns snapshot assembly, the
-// single write cadence, thinking keepalive, final compose, and node clear —
-// so adapters stop reimplementing turn-output-controller + a keepalive loop
-// (T1: they also stop swallowing the write failure). The pre-existing
-// snapshot `publishStreaming` (below) is UNTOUCHED — coding hosts still call
-// it via agent-host/runtime-writers.
-// ─────────────────────────────────────────────────────────────────────────
-/** A single tool-trail item forwarded raw; the bridge folds it into `blocks`. */
-export const BridgeStreamToolEventSchema = z.object({
-    kind: z.literal('tool'),
-    /** Stable block id (adapter-scoped, e.g. `tool:{turnId}`). */
-    id: z.string(),
-    status: z.enum(['running', 'completed', 'failed']).optional(),
-    title: z.string().optional(),
-    summary: z.string().optional(),
-    detail: z.string().optional(),
-});
-/**
- * A visible-text segment. `mode:'append'` concatenates onto the segment's
- * running text; `mode:'replace'` overwrites it (the adapter already holds the
- * full segment). The bridge rebuilds the bubble text from its text segments in
- * sequence order, exactly as the core turn-output-controller does today.
- */
-export const BridgeStreamTextEventSchema = z.object({
-    kind: z.literal('text'),
-    /** Segment id (adapter-scoped, e.g. `text:{turnId}:{n}`). */
-    id: z.string(),
-    mode: z.enum(['append', 'replace']),
-    text: z.string(),
-});
-/** A thinking tick (onset or keepalive) — no content; keeps the bubble warm. */
-export const BridgeStreamThinkingEventSchema = z.object({
-    kind: z.literal('thinking'),
-});
-/**
- * Final compose: the assembled reply text is written one last time (status
- * settles to `streaming`) and the node is LEFT in place for the final-message
- * handoff. Clearing is a separate `clear` event / `clearStreaming`.
- */
-export const BridgeStreamFinalEventSchema = z.object({
-    kind: z.literal('final'),
-    text: z.string(),
-});
-/** Clear the streaming node (turn ended / interrupted). */
-export const BridgeStreamClearEventSchema = z.object({
-    kind: z.literal('clear'),
-});
-export const BridgeStreamEventSchema = z.discriminatedUnion('kind', [
-    BridgeStreamTextEventSchema,
-    BridgeStreamToolEventSchema,
-    BridgeStreamThinkingEventSchema,
-    BridgeStreamFinalEventSchema,
-    BridgeStreamClearEventSchema,
-]);
-export const BridgePublishStreamingEventParamsSchema = conversationScoped.extend({
-    /** New turnId resets the bridge's accumulation for this conversation. */
-    turnId: z.string().nullable().optional(),
-    messageId: z.string().optional(),
-    event: BridgeStreamEventSchema,
-});
-// W2-A4 REGION END — bridge-owned streaming assembly.
-export const BRIDGE_LOCAL_METHODS = {
-    // §A lifecycle
-    hello: { params: BridgeHelloParamsSchema, result: BridgeHelloResultSchema },
-    /** Liveness probe — the bridge answers without touching upstream. */
-    ping: { params: z.object({}), result: OkResultSchema },
-    shutdown: { params: z.object({}), result: OkResultSchema },
-    /** Daemon snapshot (B4.6): process, upstream health, hub counters. */
-    status: { params: z.object({}), result: BridgeStatusResultSchema },
-    // §B1 messaging (outbound)
-    sendMessage: {
-        params: SendMessageRequestSchema,
-        // B4.3 additive: the bridge chunks oversized text (core retry/chunking);
-        // messageId is the FINAL chunk (carries the caller's metadata/turn
-        // semantics), messageIds lists every part in send order.
-        result: SendMessageResponseSchema.extend({
-            messageIds: z.array(z.string()).optional(),
-        }),
-    },
-    sendContextualMessage: {
-        params: SendContextualRequestSchema,
-        result: SendContextualResponseSchema,
-    },
-    reactToMessage: { params: ReactRequestSchema, result: ReactResponseSchema },
-    forwardMessage: { params: ForwardMessageRequestSchema, result: ForwardMessageResponseSchema },
-    deleteMessage: { params: messageScoped, result: OkResultSchema },
-    markRead: { params: conversationScoped, result: OkResultSchema },
-    setDisposition: {
-        params: messageScoped.extend(UpdateDispositionRequestSchema.shape),
-        result: OkResultSchema,
-    },
-    // §B2 reading / history
-    getMessages: {
-        params: z.object({
-            conversationId: z.string(),
-            limit: z.number().optional(),
-            before: z.string().optional(),
-            includeBehavior: z.boolean().optional(),
-        }),
-        // B4.3 additive: nextCursor is the bridge-derived `before` token for the
-        // next page (oldest returned message id), present when the page filled
-        // the requested limit. The REST surface itself emits no cursor.
-        result: MessagesPageResponseSchema.extend({
-            nextCursor: z.string().optional(),
-        }),
-    },
-    getConversations: { params: z.object({}), result: ConversationsResponseSchema },
-    // §B3 conversation / group management
-    createConversation: {
-        params: CreateConversationRequestSchema,
-        result: CreateConversationResponseSchema,
-    },
-    updateTopic: {
-        params: conversationScoped.extend({ topic: z.string() }),
-        result: OkResultSchema,
-    },
-    updateName: {
-        params: conversationScoped.extend({ name: z.string() }),
-        result: OkResultSchema,
-    },
-    updateAvatar: {
-        params: conversationScoped.extend({ avatarUrl: z.string().nullable().optional() }),
-        result: OkResultSchema,
-    },
-    addMember: {
-        params: conversationScoped.extend({ userId: z.string() }),
-        result: z.union([
-            z.object({ status: z.literal('added') }),
-            z.object({ status: z.literal('pending'), requestId: z.string() }),
-        ]),
-    },
-    removeMember: {
-        params: conversationScoped.extend({ userId: z.string() }),
-        result: OkResultSchema,
-    },
-    leaveConversation: { params: conversationScoped, result: OkResultSchema },
-    muteConversation: {
-        params: conversationScoped.extend({ until: z.number().optional() }),
-        result: OkResultSchema,
-    },
-    unmuteConversation: { params: conversationScoped, result: OkResultSchema },
-    hideConversation: { params: conversationScoped, result: OkResultSchema },
-    // §B4 contacts / admission / blocking
-    createContactRequest: {
-        params: CreateContactRequestRequestSchema,
-        result: CreateContactRequestResponseSchema,
-    },
-    listContacts: { params: z.object({}), result: ContactsResponseSchema },
-    getContact: {
-        params: z.object({ contactId: z.string() }),
-        result: RestContactSchema.nullable(),
-    },
-    removeContact: { params: z.object({ contactId: z.string() }), result: OkResultSchema },
-    listContactRequests: {
-        params: z.object({}),
-        result: z.object({ requests: z.array(SerializedContactRequestSchema) }),
-    },
-    resolveAdmission: {
-        params: ResolveAdmissionRequestSchema,
-        result: ResolveAdmissionResponseSchema,
-    },
-    reachOut: {
-        // B6.1 additive (P6 openclaw): the optional fields mirror core
-        // reachOutToCanonContact options — contact-request message, agent
-        // session config/selection, and SendMessageOptions passthrough — so
-        // channel adapters keep today's reach-out fidelity through the bridge.
-        params: z.object({
-            targetId: z.string(),
-            /**
-             * Optional (B6.1): core reach-out treats a missing text as
-             * "resolve/open the conversation only" — the openclaw media path
-             * reaches out first and sends the uploaded attachment separately.
-             */
-            text: z.string().optional(),
-            selfContext: z.string().optional(),
-            /** Contact-request message when admission requires approval. */
-            requestMessage: z.string().optional(),
-            /** Initial agent session config — opaque pass-through. */
-            sessionConfig: z.record(z.string(), z.unknown()).nullable().optional(),
-            /** Same union as the REST send surfaces (incl. mode: 'specific'). */
-            sessionSelection: RestSessionSelectionSchema.optional(),
-            /** SendMessageOptions passthrough (replyTo, selfContextId, metadata, …). */
-            sendMessageOptions: z.record(z.string(), z.unknown()).optional(),
-        }),
-        result: z.record(z.string(), z.unknown()),
-    },
-    blockUser: { params: z.object({ userId: z.string() }), result: OkResultSchema },
-    unblockUser: { params: z.object({ userId: z.string() }), result: OkResultSchema },
-    // §B5 live presence / streaming (bridge throttles internally)
-    setTyping: {
-        params: conversationScoped.extend({ state: z.enum(['typing', 'thinking', 'clear']) }),
-        result: OkResultSchema,
-    },
-    publishStreaming: {
-        params: conversationScoped.extend({
-            turnId: z.string().nullable().optional(),
-            messageId: z.string().optional(),
-            text: z.string().optional(),
-            delta: z.string().optional(),
-            /** TurnOutputBlock[] — opaque pass-through. */
-            blocks: z.array(z.record(z.string(), z.unknown())).optional(),
-            /**
-             * Explicit bubble/presentation status override (union of B6.1 openclaw
-             * + P6 host surface): 'tool' / 'waiting_input' cannot be derived from
-             * text/blocks. Omitted: the bridge derives thinking/streaming from
-             * content as before.
-             */
-            status: z.enum(['thinking', 'streaming', 'tool', 'waiting_input']).optional(),
-            done: z.boolean().optional(),
-        }),
-        result: OkResultSchema,
-    },
-    clearStreaming: { params: conversationScoped, result: OkResultSchema },
-    // W2-A4 additive: raw streaming events (bridge owns assembly/cadence/
-    // keepalive/final/clear). Coexists with the snapshot publishStreaming above.
-    publishStreamingEvent: {
-        params: BridgePublishStreamingEventParamsSchema,
-        result: OkResultSchema,
-    },
-    // §B6 runtime presentation (adapter owns content, bridge publishes)
-    publishRuntimeDescriptor: {
-        params: z.object({
-            descriptor: z.record(z.string(), z.unknown()),
-            /**
-             * B6.1 additive (P6 openclaw): rides into the published /agent-runtime
-             * payload — hosts and host-mode channel plugins publish hostMode: true
-             * today and the field is app-visible. Latched for subsequent publishes;
-             * defaults to false (bridge-adapter split is not a host process).
-             */
-            hostMode: z.boolean().optional(),
-        }),
-        result: OkResultSchema,
-    },
-    publishRuntimeStatus: {
-        // Code-grounded correction (B4.3): RTDB runtime-info lives per
-        // conversation (/runtime-info/{convoId}/{agentId}), so the publish is
-        // conversation-scoped. `presentation` carries the remaining
-        // RuntimeInfoPayload fields (surfaceMode, facts, inventories, notes, …)
-        // as an opaque pass-through.
-        params: conversationScoped.extend({
-            statusItems: z.array(z.record(z.string(), z.unknown())).optional(),
-            presentation: z.record(z.string(), z.unknown()).optional(),
-        }),
-        result: OkResultSchema,
-    },
-    publishTurnState: {
-        // B6.1 additive (P6 openclaw): the remaining CanonTurnStatePayload
-        // fields hosts publish today. `completedAt: true` asks the bridge to
-        // stamp the server timestamp (the RTDB sentinel is bridge-owned).
-        params: conversationScoped.extend({
-            turnId: z.string().nullable().optional(),
-            state: TurnLifecycleStateSchema,
-            queueDepth: z.number().optional(),
-            capabilities: z.record(z.string(), z.unknown()).optional(),
-            // Union of B6.1 (openclaw) + P6 host surface — the remaining
-            // code-grounded TurnStatePayload fields (rtdb-rest.ts).
-            currentSpeakerId: z.string().nullable().optional(),
-            lastAcceptedIntent: DeliveryIntentSchema.nullable().optional(),
-            activeMessageIds: z.array(z.string()).optional(),
-            openedAt: EpochOrServerTimestampSchema.optional(),
-            turnUpdatedAt: EpochOrServerTimestampSchema.nullable().optional(),
-            // `true` (B6.1 openclaw) asks the bridge to stamp the server-timestamp
-            // sentinel; hosts (P6) pass an epoch or the sentinel through directly.
-            completedAt: z
-                .union([z.boolean(), EpochOrServerTimestampSchema])
-                .nullable()
-                .optional(),
-        }),
-        result: OkResultSchema,
-    },
-    clearTurnState: { params: conversationScoped, result: OkResultSchema },
-    publishActivity: {
-        params: conversationScoped.extend({
-            activityItems: z.array(z.record(z.string(), z.unknown())),
-        }),
-        result: OkResultSchema,
-    },
-    clearActivity: {
-        // B6.1 additive (P6 openclaw): remove activity blocks. `all` wipes the
-        // conversation's node; `itemIds` removes specific blocks; neither falls
-        // back to the publisher's terminal-only sweep semantics.
-        params: conversationScoped.extend({
-            all: z.boolean().optional(),
-            itemIds: z.array(z.string()).optional(),
-        }),
-        result: OkResultSchema,
-    },
-    /** B6.1 additive: clear the per-conversation runtime-info node. */
-    clearRuntimeStatus: { params: conversationScoped, result: OkResultSchema },
-    /**
-     * B6.1 additive: clear /agent-runtime for this identity (preserves
-     * descriptor-bearing payloads with updatedAt: 0, like hosts do today).
-     */
-    clearRuntimeDescriptor: { params: z.object({}), result: OkResultSchema },
-    // §B7 HITL (durable; returns requestId, resolves via onHitlResolved).
-    //
-    // P6 host surface (additive): process-executing hosts publish the SAME
-    // rich records channel runtimes create today (approval cards with
-    // diff/details/native handles, titled input cards, card ids the runtime
-    // correlates on). All new fields are optional — the narrow Phase-4 shape
-    // still parses. `requestId`/`inputId`/`cardId`-style explicit ids become
-    // the bridge record's requestId so adapters keep their own correlation.
-    // `responseUserId: null` means "let the server pick a reachable responder"
-    // (codex cards today); absent keeps the Phase-4 default (agent owner).
-    requestApproval: {
-        // B6.1 additive (P6 openclaw): optional approval-card fidelity fields
-        // (core createRuntimeApprovalRequest passthrough) so native runtime
-        // approvals keep their tool name, detail rows, correlation handles and
-        // allow-always affordance through the bridge.
-        params: conversationScoped.extend({
-            detail: z.string(),
-            risk: HitlApprovalRiskSchema,
-            category: HitlApprovalCategorySchema,
-            expiresAt: z.string().optional(),
-            approvalId: z.string().optional(),
-            /** Card header tool name; defaults to the category. */
-            toolName: z.string().optional(),
-            riskLevel: z.enum(['normal', 'destructive']).optional(),
-            details: z.array(HitlApprovalDetailSchema).optional(),
-            /** File-change preview (CanonUnifiedDiff) — opaque pass-through. */
-            diff: z.record(z.string(), z.unknown()).optional(),
-            /** Native runtime correlation handles — opaque pass-through. */
-            native: z.record(z.string(), z.unknown()).optional(),
-            turnId: z.string().optional(),
-            runtimeId: z.string().optional(),
-            /** Offer the "always allow" session-rule affordance on the card. */
-            allowSessionRule: z.boolean().optional(),
-            responseUserId: z.string().nullable().optional(),
-        }),
-        result: HitlRequestAcceptedSchema,
-    },
-    requestInput: {
-        params: conversationScoped.extend({
-            questions: z.array(HitlInputQuestionSchema),
-            expiresAt: z.string().optional(),
-            inputId: z.string().optional(),
-            title: z.string().optional(),
-            prompt: z.string().optional(),
-            kind: HitlInputKindSchema.optional(),
-            sensitive: z.boolean().optional(),
-            native: z.record(z.string(), z.unknown()).optional(),
-            turnId: z.string().optional(),
-            responseUserId: z.string().nullable().optional(),
-        }),
-        result: HitlRequestAcceptedSchema,
-    },
-    requestCard: {
-        params: conversationScoped.extend({
-            /** canon.card.v1 content — opaque pass-through. */
-            card: z.record(z.string(), z.unknown()),
-            expiresAt: z.string().optional(),
-            cardId: z.string().optional(),
-            native: z.record(z.string(), z.unknown()).optional(),
-            turnId: z.string().optional(),
-            responseUserId: z.string().nullable().optional(),
-        }),
-        result: HitlRequestAcceptedSchema,
-    },
-    getHitlState: {
-        params: z.object({ requestId: z.string() }),
-        result: BridgeHitlStateSchema,
-    },
-    cancelHitl: { params: z.object({ requestId: z.string() }), result: OkResultSchema },
-    // §B8 media (named schemas above — the bridge + Framework share them)
-    uploadMedia: {
-        params: BridgeUploadMediaParamsSchema,
-        result: UploadMediaResponseSchema,
-    },
-    getAttachment: {
-        params: BridgeGetAttachmentParamsSchema,
-        result: BridgeGetAttachmentResultSchema,
-    },
-    // §B9 voice (media stays client↔LiveKit; bridge brokers the token).
-    // Code-grounded correction (B4.3): every /voice/sessions/:id REST op
-    // requires the conversationId (body or query) — the session doc lives
-    // under the conversation — so the session-scoped methods carry it too.
-    createVoiceSession: {
-        params: conversationScoped.extend({ targetAgentId: z.string().optional() }),
-        result: z.looseObject({ sessionId: z.string() }),
-    },
-    joinVoiceSession: {
-        params: z.object({ sessionId: z.string(), conversationId: z.string() }),
-        result: z.looseObject({ url: z.string(), token: z.string() }),
-    },
-    endVoiceSession: {
-        params: z.object({ sessionId: z.string(), conversationId: z.string() }),
-        result: OkResultSchema,
-    },
-    getVoiceSession: {
-        params: z.object({ sessionId: z.string(), conversationId: z.string() }),
-        result: SseVoiceSessionEventPayloadSchema,
-    },
-    // §B10 registration / identity
-    getAgent: {
-        params: z.object({}),
-        result: z.object({
-            agentId: z.string(),
-            agentName: z.string(),
-            context: SseAgentContextPayloadSchema,
-        }),
-    },
-    register: {
-        params: z.record(z.string(), z.unknown()),
-        // pollToken (when issued) authorizes subsequent status polls.
-        result: z.object({ requestId: z.string(), pollToken: z.string().optional() }),
-    },
-    getRegistrationStatus: {
-        // `baseUrl` (B6.1 additive) supports the pre-identity bootstrap: the
-        // registration statics are unauthenticated, so a stub-identity bridge
-        // can serve them with an explicit endpoint.
-        params: z.object({
-            requestId: z.string(),
-            pollToken: z.string().optional(),
-            baseUrl: z.string().optional(),
-        }),
-        result: z.looseObject({ status: z.string() }),
-    },
-    /**
-     * Acknowledge one-time API-key delivery after an approved registration
-     * (POST /agents/status/:id/ack). Best-effort on the wire; failures surface
-     * as upstream-band errors. Additive union of Phase 5 + P6 openclaw: the
-     * Hermes port consumed it through the GENERIC Python escape hatch first
-     * (a bridge-side method addition with zero framework-py release), and
-     * `baseUrl` (B6.1) supports the wizard's per-call pre-identity bootstrap.
-     */
-    ackRegistrationStatus: {
-        params: z.object({
-            requestId: z.string(),
-            pollToken: z.string().optional(),
-            baseUrl: z.string().optional(),
-        }),
-        result: OkResultSchema,
-    },
-    // §5b host-profile surface (bridge-execution-plan Phase 4 step 5b) —
-    // additive methods for process-executing (host-mode) adapters, beyond §B.
-    // Shapes mirror @canonmsg/core host-runtime-wire.ts; runtime payloads are
-    // opaque pass-through (AgentRuntime).
-    publishHostAgentRuntime: {
-        params: z.object({
-            /** Defaults to the hello clientType. */
-            clientType: z.string().optional(),
-            /** AgentRuntime — opaque pass-through. */
-            runtime: z.record(z.string(), z.unknown()),
-        }),
-        result: OkResultSchema,
-    },
-    publishHostSessionSnapshots: {
-        params: z.object({
-            conversationIds: z.array(z.string()),
-            /** Defaults to the hello clientType. */
-            clientType: z.string().optional(),
-            /** AgentRuntime — opaque pass-through. */
-            runtime: z.record(z.string(), z.unknown()),
-            workspaceOptions: z.array(z.object({ id: z.string(), cwd: z.string() })).optional(),
-            defaultCwd: z.string().optional(),
-            extraSessionConfigFields: z.array(z.string()).optional(),
-            /** conversationId → live session-config overrides (JSON'd Map). */
-            liveSessionConfigByConversation: z
-                .record(z.string(), z.record(z.string(), z.unknown()))
-                .optional(),
-        }),
-        result: OkResultSchema,
-    },
-    // §5b host-profile surface, P6 additions (bridge-execution-plan Phase 6) —
-    // the remaining RTDB planes the process-executing hosts touched directly
-    // until now: the per-conversation session-state node, its config read, and
-    // the terminal clears. Payloads mirror @canonmsg/core rtdb-rest.ts shapes
-    // as opaque pass-through; the bridge executes them through the core
-    // runtime-state publisher (hostMode) over its single RTDB handle.
-    getSessionConfig: {
-        params: conversationScoped,
-        /** Raw `/session-config/{convoId}/{agentId}` node; adapters parse locally. */
-        result: z.record(z.string(), z.unknown()).nullable(),
-    },
-    publishSessionState: {
-        params: conversationScoped.extend({
-            /** SessionStatePayload minus updatedAt — opaque pass-through. */
-            state: z.record(z.string(), z.unknown()),
-        }),
-        result: OkResultSchema,
-    },
-    clearSessionState: { params: conversationScoped, result: OkResultSchema },
-    // clearTurnState is defined once under §B6 above (both legs added it; the
-    // clear is publisher-agnostic so channel adapters and hosts share it).
-    /**
-     * Terminal /agent-runtime clear through the HOST publisher. Same RTDB
-     * effect as §B6.1 clearRuntimeDescriptor (preserve descriptor-bearing
-     * payloads with updatedAt: 0) — kept as a distinct §5b name because host
-     * consumers correlate it with the publishHostAgentRuntime plane.
-     */
-    clearAgentRuntime: { params: z.object({}), result: OkResultSchema },
-};
-export const BRIDGE_LOCAL_METHOD_NAMES = Object.keys(BRIDGE_LOCAL_METHODS);
-// ── §C Notification registry (bridge → adapter, one-way) ───────────────
-export const BRIDGE_LOCAL_NOTIFICATIONS = {
-    // §A — connection-scoped, never replayed, no cursor
-    ready: BridgeReadyNotificationSchema,
-    connectionState: BridgeConnectionStateNotificationSchema,
-    // §C1 inbound messages (pre-filtered: deduped, self/control stripped)
-    onMessage: SseMessageCreatedPayloadSchema.extend(BRIDGE_EVENT_CURSOR_SHAPE),
-    onMessageUpdated: SseMessageUpdatedPayloadSchema.extend(BRIDGE_EVENT_CURSOR_SHAPE),
-    onMessageDeleted: SseMessageDeletedPayloadSchema.extend(BRIDGE_EVENT_CURSOR_SHAPE),
-    onConversationUpdated: SseConversationUpdatedPayloadSchema.extend(BRIDGE_EVENT_CURSOR_SHAPE),
-    // §C2 control (bridge consumed from RTDB — adapters never poll)
-    onControlSignal: ControlSignalEventSchema.extend(BRIDGE_EVENT_CURSOR_SHAPE),
-    onSessionControl: ControlSessionEventSchema.extend(BRIDGE_EVENT_CURSOR_SHAPE),
-    // §C2 addition (P6, both legs): `/control/.../primitive` runtime command
-    // dispatch (/status, /compact, …) consumed by the bridge poller — adapters
-    // (openclaw handlers, codex compact) never poll RTDB themselves.
-    onControlPrimitive: ControlPrimitiveEventSchema.extend(BRIDGE_EVENT_CURSOR_SHAPE),
-    // §C6 HITL resolution (durable; matches a §B7 requestId)
-    onHitlResolved: HitlResolutionSchema.extend(BRIDGE_EVENT_CURSOR_SHAPE),
-    onHitlPending: HitlPendingSchema.extend(BRIDGE_EVENT_CURSOR_SHAPE),
-    /**
-     * §C6 addition (P6 host surface): a stripped HITL control-reply message
-     * (metadata.type approval_reply / plan_approval_reply) that matched NO
-     * bridge-owned HITL record fans out here instead of being dropped —
-     * process-executing hosts run reply flows the bridge did not raise
-     * (claude plan approval is a plain sendMessage + metadata-reply waiter).
-     * `message` is the serialized Canon message, opaque pass-through.
-     */
-    onControlReply: z.object({
-        conversationId: z.string(),
-        message: z.record(z.string(), z.unknown()),
-    }).extend(BRIDGE_EVENT_CURSOR_SHAPE),
-    // §C3 contacts
-    onContactChanged: z.object({
-        kind: z.enum(['request', 'approved', 'added', 'updated', 'removed']),
-        contact: z.record(z.string(), z.unknown()),
-    }).extend(BRIDGE_EVENT_CURSOR_SHAPE),
-    // §C4 typing / presence
-    onTyping: SseTypingPayloadSchema.extend(BRIDGE_EVENT_CURSOR_SHAPE),
-    onPresence: SsePresencePayloadSchema.extend(BRIDGE_EVENT_CURSOR_SHAPE),
-    // §C5 voice
-    onVoiceSessionStarted: SseVoiceSessionEventPayloadSchema.extend(BRIDGE_EVENT_CURSOR_SHAPE),
-    onVoiceSessionEnded: SseVoiceSessionEventPayloadSchema.extend(BRIDGE_EVENT_CURSOR_SHAPE),
-};
-export const BRIDGE_LOCAL_NOTIFICATION_NAMES = Object.keys(BRIDGE_LOCAL_NOTIFICATIONS);
-/**
- * Event family per §C notification, mirroring SSE_EVENT_FAMILY_BY_TYPE.
- * `lifecycle` notifications are connection-scoped and delivered to every
- * client; family notifications are filtered by `hello.wantFamilies`
- * (`wantFamilies: []` = pure-request adapter, no §C events at all).
- */
-export const BRIDGE_LOCAL_NOTIFICATION_FAMILIES = {
-    ready: 'lifecycle',
-    connectionState: 'lifecycle',
-    onMessage: 'messages',
-    onMessageUpdated: 'messages',
-    onMessageDeleted: 'messages',
-    onConversationUpdated: 'messages',
-    onControlSignal: 'runtime_turn',
-    onSessionControl: 'runtime_turn',
-    onControlPrimitive: 'runtime_turn',
-    onHitlResolved: 'runtime_turn',
-    onHitlPending: 'runtime_turn',
-    onControlReply: 'runtime_turn',
-    onContactChanged: 'contacts',
-    onTyping: 'typing_presence',
-    onPresence: 'typing_presence',
-    onVoiceSessionStarted: 'voice',
-    onVoiceSessionEnded: 'voice',
-};
-// ── JSON-RPC 2.0 framing ───────────────────────────────────────────────
-export const BridgeRpcIdSchema = z.union([z.string(), z.number()]);
-export const BridgeRpcRequestSchema = z.object({
-    jsonrpc: z.literal('2.0'),
-    id: BridgeRpcIdSchema,
-    method: z.string(),
-    params: z.unknown().optional(),
-});
-export const BridgeRpcNotificationSchema = z.object({
-    jsonrpc: z.literal('2.0'),
-    method: z.string(),
-    params: z.unknown().optional(),
-});
-export const BridgeRpcErrorSchema = z.object({
-    code: z.number(),
-    message: z.string(),
-    data: z.unknown().optional(),
-});
-export const BridgeRpcResponseSchema = z.union([
-    z.object({ jsonrpc: z.literal('2.0'), id: BridgeRpcIdSchema, result: z.unknown() }),
-    z.object({ jsonrpc: z.literal('2.0'), id: BridgeRpcIdSchema.nullable(), error: BridgeRpcErrorSchema }),
-]);