@canonmsg/backend-contracts 1.7.1 → 1.8.1

package/dist/cjs/sseEvents.js

@@ -0,0 +1,298 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SseEventEnvelopeSchema = exports.SSE_EVENT_FAMILY_BY_TYPE = exports.SseEventFamilySchema = exports.SSE_EVENT_FAMILIES = exports.SSE_EVENT_PAYLOAD_SCHEMAS = exports.SseEventTypeSchema = exports.SSE_EVENT_TYPES = exports.SseVoiceSessionEventPayloadSchema = exports.SseVoiceSessionSchema = exports.SseRuntimeControlPayloadSchema = exports.SseRuntimeControlKindSchema = exports.SseTurnUpdatedPayloadSchema = exports.SseRuntimeUpdatedPayloadSchema = exports.SsePresencePayloadSchema = exports.SseTypingPayloadSchema = exports.SseContactRemovedPayloadSchema = exports.SseContactPayloadSchema = exports.SseContactRequestPayloadSchema = exports.SseConversationUpdatedPayloadSchema = exports.SseMembershipChangeSchema = exports.SseMessageDeletedPayloadSchema = exports.SseMessageUpdatedPayloadSchema = exports.SseMessageCreatedPayloadSchema = exports.SseProvenanceSchema = exports.SseTurnDispatchSchema = exports.SseSelfContextSchema = exports.SseErrorPayloadSchema = exports.SseReplayExpiredPayloadSchema = exports.SseHeartbeatPayloadSchema = exports.SseAgentContextPayloadSchema = exports.SseConnectedPayloadSchema = exports.SseAccessPolicySchema = void 0;
+// Wire contract v1 — SSE event envelope + per-family payload schemas.
+//
+// Grounded in what stream-service ACTUALLY emits (stream-service/src/stream.ts
+// + listeners.ts) and what @canonmsg/core's CanonStream consumes — not in
+// design-doc prose. Payload slots that stream-service passes through opaquely
+// (behavior policies, runtime snapshots, raw RTDB values) stay loose objects;
+// slots stream-service constructs field-by-field are closed.
+//
+// The golden fixtures in @canonmsg/test-fixtures parse under these schemas;
+// the future Python framework must pass the same fixtures.
+const zod_1 = require("zod");
+const contactRequest_js_1 = require("./contactRequest.js");
+const message_js_1 = require("./message.js");
+exports.SseAccessPolicySchema = zod_1.z.enum(['open', 'approval-required', 'owner-only']);
+// ── Lifecycle events ───────────────────────────────────────────────────
+exports.SseConnectedPayloadSchema = zod_1.z.object({
+    connectionId: zod_1.z.string(),
+    agentId: zod_1.z.string(),
+});
+/** Trusted, server-injected identity & access info (stream.ts `agent.context`). */
+exports.SseAgentContextPayloadSchema = zod_1.z.looseObject({
+    agentId: zod_1.z.string(),
+    canonContactId: zod_1.z.string().optional(),
+    clientType: zod_1.z.string().optional(),
+    ownerId: zod_1.z.string(),
+    ownerName: zod_1.z.string(),
+    /** Resolved agent behavior policy — passed through opaquely. */
+    defaultBehavior: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
+    inboundPolicy: exports.SseAccessPolicySchema,
+    groupJoinPolicy: exports.SseAccessPolicySchema,
+    discoverable: zod_1.z.boolean(),
+});
+exports.SseHeartbeatPayloadSchema = zod_1.z.object({
+    timestamp: zod_1.z.string(),
+});
+exports.SseReplayExpiredPayloadSchema = zod_1.z.looseObject({
+    lastAvailableId: zod_1.z.string().nullable().optional(),
+    message: zod_1.z.string().optional(),
+});
+exports.SseErrorPayloadSchema = zod_1.z.looseObject({
+    code: zod_1.z.string().optional(),
+    message: zod_1.z.string().optional(),
+    retryAfterMs: zod_1.z.number().optional(),
+    activeConnections: zod_1.z.number().optional(),
+    maxConnections: zod_1.z.number().optional(),
+});
+// ── Messages family ────────────────────────────────────────────────────
+exports.SseSelfContextSchema = zod_1.z.object({
+    id: zod_1.z.string(),
+    type: zod_1.z.literal('cross_session'),
+    context: zod_1.z.string(),
+    createdAt: zod_1.z.string().nullable(),
+    updatedAt: zod_1.z.string().nullable(),
+});
+exports.SseTurnDispatchSchema = zod_1.z.looseObject({
+    kind: zod_1.z.enum(['run_turn', 'observe_only']),
+    reason: zod_1.z.string(),
+    addressed: zod_1.z.boolean(),
+    policyVersion: zod_1.z.string().optional(),
+});
+exports.SseProvenanceSchema = zod_1.z.looseObject({
+    conversation: zod_1.z.looseObject({
+        id: zod_1.z.string(),
+        type: zod_1.z.enum(['direct', 'group', 'unknown']),
+    }),
+    sender: zod_1.z.looseObject({
+        id: zod_1.z.string(),
+        name: zod_1.z.string().optional(),
+        type: zod_1.z.enum(['human', 'ai_agent']),
+        isOwner: zod_1.z.boolean(),
+    }),
+    mentionedAgent: zod_1.z.boolean(),
+});
+/**
+ * `message.created` — the inbound message envelope. `message` is exactly the
+ * SerializedMessage the shared serializer emits (the E2EE S1 slot).
+ */
+exports.SseMessageCreatedPayloadSchema = zod_1.z.looseObject({
+    conversationId: zod_1.z.string(),
+    /** Resolved agent behavior policy — passed through opaquely. */
+    behavior: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
+    activeSelfContextId: zod_1.z.string().nullable().optional(),
+    selfContexts: zod_1.z.array(exports.SseSelfContextSchema).optional(),
+    provenance: exports.SseProvenanceSchema.optional(),
+    turnDispatch: exports.SseTurnDispatchSchema.optional(),
+    message: message_js_1.SerializedMessageSchema,
+});
+exports.SseMessageUpdatedPayloadSchema = zod_1.z.object({
+    conversationId: zod_1.z.string(),
+    messageId: zod_1.z.string(),
+    actorId: zod_1.z.string().optional(),
+    updatedAt: zod_1.z.string().optional(),
+    changes: zod_1.z.looseObject({
+        reactions: message_js_1.SerializedReactionsSchema,
+    }),
+});
+exports.SseMessageDeletedPayloadSchema = zod_1.z.object({
+    conversationId: zod_1.z.string(),
+    messageId: zod_1.z.string(),
+});
+exports.SseMembershipChangeSchema = zod_1.z.object({
+    addedMemberIds: zod_1.z.array(zod_1.z.string()),
+    removedMemberIds: zod_1.z.array(zod_1.z.string()),
+    memberCount: zod_1.z.number(),
+});
+exports.SseConversationUpdatedPayloadSchema = zod_1.z.object({
+    conversationId: zod_1.z.string(),
+    changes: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()),
+    membershipChange: exports.SseMembershipChangeSchema.optional(),
+});
+// ── Contacts family ────────────────────────────────────────────────────
+/** `contact.request` / `contact.approved` carry the serialized contact request. */
+exports.SseContactRequestPayloadSchema = contactRequest_js_1.SerializedContactRequestSchema;
+/**
+ * `contact.added` / `contact.updated`. `source` is a pass-through string —
+ * canonical values today: direct_add, phone_book, contact_request, link, qr,
+ * group, open_inbound_message, unknown.
+ */
+exports.SseContactPayloadSchema = zod_1.z.object({
+    id: zod_1.z.string(),
+    source: zod_1.z.string(),
+    addedAt: zod_1.z.string().nullable(),
+    displayNameOverride: zod_1.z.string().nullable(),
+});
+exports.SseContactRemovedPayloadSchema = zod_1.z.object({
+    id: zod_1.z.string(),
+});
+// ── Typing / presence family ───────────────────────────────────────────
+exports.SseTypingPayloadSchema = zod_1.z.object({
+    conversationId: zod_1.z.string(),
+    userId: zod_1.z.string(),
+    isTyping: zod_1.z.boolean(),
+    status: zod_1.z.enum(['thinking', 'typing']).optional(),
+    timestamp: zod_1.z.number().optional(),
+});
+exports.SsePresencePayloadSchema = zod_1.z.object({
+    userId: zod_1.z.string(),
+    online: zod_1.z.boolean(),
+    lastSeen: zod_1.z.string().optional(),
+});
+// ── Runtime / turn family ──────────────────────────────────────────────
+/** Aggregated RTDB runtime snapshot — nodes are passed through opaquely. */
+exports.SseRuntimeUpdatedPayloadSchema = zod_1.z.object({
+    conversationId: zod_1.z.string(),
+    agentId: zod_1.z.string(),
+    runtime: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).nullable(),
+    runtimeInfo: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).nullable(),
+    sessionState: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).nullable(),
+    sessionConfig: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).nullable(),
+});
+exports.SseTurnUpdatedPayloadSchema = zod_1.z.object({
+    conversationId: zod_1.z.string(),
+    agentId: zod_1.z.string(),
+    turn: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).nullable(),
+});
+exports.SseRuntimeControlKindSchema = zod_1.z.enum([
+    'session',
+    'signal',
+    'primitive',
+    'runtimeInput',
+    'runtimeCard',
+    'runtimeApproval',
+]);
+exports.SseRuntimeControlPayloadSchema = zod_1.z.object({
+    conversationId: zod_1.z.string(),
+    agentId: zod_1.z.string(),
+    kind: exports.SseRuntimeControlKindSchema,
+    requestId: zod_1.z.string().optional(),
+    updatedAt: zod_1.z.number().optional(),
+    value: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()),
+});
+// ── Voice family ───────────────────────────────────────────────────────
+exports.SseVoiceSessionSchema = zod_1.z.looseObject({
+    id: zod_1.z.string(),
+    conversationId: zod_1.z.string(),
+    roomName: zod_1.z.string(),
+    mode: zod_1.z.enum(['human', 'runtime_voice']),
+    status: zod_1.z.enum(['active', 'ended', 'error']),
+    createdBy: zod_1.z.string(),
+    participantIds: zod_1.z.array(zod_1.z.string()),
+    participants: zod_1.z.array(zod_1.z.looseObject({
+        userId: zod_1.z.string(),
+        userType: zod_1.z.enum(['human', 'ai_agent', 'system']),
+        displayName: zod_1.z.string().nullable(),
+        joinedAt: zod_1.z.string().nullable(),
+        leftAt: zod_1.z.string().nullable(),
+    })).optional(),
+    targetAgentId: zod_1.z.string().nullable().optional(),
+    createdAt: zod_1.z.string().nullable().optional(),
+    updatedAt: zod_1.z.string().nullable().optional(),
+    endedAt: zod_1.z.string().nullable().optional(),
+    error: zod_1.z.string().nullable().optional(),
+});
+exports.SseVoiceSessionEventPayloadSchema = zod_1.z.object({
+    conversationId: zod_1.z.string(),
+    session: exports.SseVoiceSessionSchema,
+});
+// ── Envelope + registry ────────────────────────────────────────────────
+/**
+ * Every SSE `event:` name stream-service emits today (stream.ts + listeners.ts;
+ * mirrored by CanonStream's dispatch switch in core). NOTE: `contact.updated`
+ * is emitted by stream-service but not yet consumed by CanonStream.
+ */
+exports.SSE_EVENT_TYPES = [
+    'connected',
+    'agent.context',
+    'heartbeat',
+    'message.created',
+    'message.updated',
+    'message.deleted',
+    'conversation.updated',
+    'contact.request',
+    'contact.approved',
+    'contact.added',
+    'contact.updated',
+    'contact.removed',
+    'typing',
+    'presence',
+    'runtime.updated',
+    'turn.updated',
+    'runtime.control',
+    'voice.session.started',
+    'voice.session.ended',
+    'replay.expired',
+    'error',
+];
+exports.SseEventTypeSchema = zod_1.z.enum(exports.SSE_EVENT_TYPES);
+/** Payload schema for every event type — the machine-readable event registry. */
+exports.SSE_EVENT_PAYLOAD_SCHEMAS = {
+    'connected': exports.SseConnectedPayloadSchema,
+    'agent.context': exports.SseAgentContextPayloadSchema,
+    'heartbeat': exports.SseHeartbeatPayloadSchema,
+    'message.created': exports.SseMessageCreatedPayloadSchema,
+    'message.updated': exports.SseMessageUpdatedPayloadSchema,
+    'message.deleted': exports.SseMessageDeletedPayloadSchema,
+    'conversation.updated': exports.SseConversationUpdatedPayloadSchema,
+    'contact.request': exports.SseContactRequestPayloadSchema,
+    'contact.approved': exports.SseContactRequestPayloadSchema,
+    'contact.added': exports.SseContactPayloadSchema,
+    'contact.updated': exports.SseContactPayloadSchema,
+    'contact.removed': exports.SseContactRemovedPayloadSchema,
+    'typing': exports.SseTypingPayloadSchema,
+    'presence': exports.SsePresencePayloadSchema,
+    'runtime.updated': exports.SseRuntimeUpdatedPayloadSchema,
+    'turn.updated': exports.SseTurnUpdatedPayloadSchema,
+    'runtime.control': exports.SseRuntimeControlPayloadSchema,
+    'voice.session.started': exports.SseVoiceSessionEventPayloadSchema,
+    'voice.session.ended': exports.SseVoiceSessionEventPayloadSchema,
+    'replay.expired': exports.SseReplayExpiredPayloadSchema,
+    'error': exports.SseErrorPayloadSchema,
+};
+/**
+ * Subscription families (`?events=` filter). Lifecycle events (`connected`,
+ * `agent.context`, `heartbeat`, `replay.expired`, `error`) are always sent.
+ */
+exports.SSE_EVENT_FAMILIES = [
+    'messages',
+    'contacts',
+    'typing_presence',
+    'runtime_turn',
+    'voice',
+];
+exports.SseEventFamilySchema = zod_1.z.enum(exports.SSE_EVENT_FAMILIES);
+exports.SSE_EVENT_FAMILY_BY_TYPE = {
+    'connected': 'lifecycle',
+    'agent.context': 'lifecycle',
+    'heartbeat': 'lifecycle',
+    'message.created': 'messages',
+    'message.updated': 'messages',
+    'message.deleted': 'messages',
+    'conversation.updated': 'messages',
+    'contact.request': 'contacts',
+    'contact.approved': 'contacts',
+    'contact.added': 'contacts',
+    'contact.updated': 'contacts',
+    'contact.removed': 'contacts',
+    'typing': 'typing_presence',
+    'presence': 'typing_presence',
+    'runtime.updated': 'runtime_turn',
+    'turn.updated': 'runtime_turn',
+    'runtime.control': 'runtime_turn',
+    'voice.session.started': 'voice',
+    'voice.session.ended': 'voice',
+    'replay.expired': 'lifecycle',
+    'error': 'lifecycle',
+};
+/**
+ * A parsed SSE frame: `id:` (replay cursor), `event:`, and the JSON-decoded
+ * `data:` payload. Validate `data` with SSE_EVENT_PAYLOAD_SCHEMAS[event].
+ */
+exports.SseEventEnvelopeSchema = zod_1.z.object({
+    id: zod_1.z.string().optional(),
+    event: exports.SseEventTypeSchema,
+    data: zod_1.z.unknown(),
+});

package/dist/cjs/turnProtocol.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WAITING_INPUT_STALE_THRESHOLD_MS = exports.ACTIVE_TURN_STALE_THRESHOLD_MS = void 0;
+exports.WAITING_INPUT_STALE_THRESHOLD_MS = exports.ACTIVE_TURN_STALE_THRESHOLD_MS = exports.TurnStateLikeSchema = exports.TriggerDecisionSchema = exports.TurnMetadataSchema = exports.InboundDispositionSchema = exports.DeliveryIntentSchema = exports.TurnMessageSemanticsSchema = exports.TurnLifecycleStateSchema = exports.SenderTypeSchema = void 0;
 exports.normalizeTurnMetadata = normalizeTurnMetadata;
 exports.isTurnOpen = isTurnOpen;
 exports.getTurnStateStaleThresholdMs = getTurnStateStaleThresholdMs;
@@ -9,6 +9,46 @@ exports.resolveTurnMessageSemantics = resolveTurnMessageSemantics;
 exports.shouldPromoteConversationMessage = shouldPromoteConversationMessage;
 exports.shouldTriggerAgentTurn = shouldTriggerAgentTurn;
 exports.normalizeRuntimeTurnState = normalizeRuntimeTurnState;
+const zod_1 = require("zod");
+exports.SenderTypeSchema = zod_1.z.enum(['human', 'ai_agent']);
+exports.TurnLifecycleStateSchema = zod_1.z.enum([
+    'idle',
+    'thinking',
+    'streaming',
+    'tool',
+    'waiting_input',
+    'completed',
+    'interrupted',
+]);
+exports.TurnMessageSemanticsSchema = zod_1.z.enum(['progress', 'turn_complete', 'control']);
+exports.DeliveryIntentSchema = zod_1.z.enum(['queue', 'interrupt', 'interleave', 'stop']);
+exports.InboundDispositionSchema = zod_1.z.enum([
+    'queued',
+    'accepted_now',
+    'interleaved',
+    'trigger_suppressed',
+    'rejected',
+    'cancelled',
+]);
+exports.TurnMetadataSchema = zod_1.z.object({
+    turnId: zod_1.z.string().nullable().optional(),
+    turnSemantics: exports.TurnMessageSemanticsSchema.optional(),
+    deliveryIntent: exports.DeliveryIntentSchema.optional(),
+    replyBehavior: zod_1.z.enum(['allow_auto_reply', 'suppress_auto_reply']).optional(),
+    inboundDisposition: exports.InboundDispositionSchema.optional(),
+    requestedTurnMode: zod_1.z.string().optional(),
+});
+exports.TriggerDecisionSchema = zod_1.z.object({
+    allow: zod_1.z.boolean(),
+    semantics: exports.TurnMessageSemanticsSchema,
+    reason: zod_1.z.string(),
+});
+exports.TurnStateLikeSchema = zod_1.z.object({
+    state: exports.TurnLifecycleStateSchema,
+    openedAt: zod_1.z.number().optional(),
+    updatedAt: zod_1.z.number().optional(),
+    turnUpdatedAt: zod_1.z.number().nullable().optional(),
+});
 exports.ACTIVE_TURN_STALE_THRESHOLD_MS = 30 * 60 * 1000;
 exports.WAITING_INPUT_STALE_THRESHOLD_MS = 12 * 60 * 60 * 1000;
 const TURN_SEMANTICS = [

package/dist/contactRequest.d.ts

@@ -1,24 +1,43 @@
-export type SerializedContactRequestStatus = 'pending' | 'approved' | 'rejected' | 'expired';
-export interface SerializedContactRequest {
-    id: string;
-    requesterId: string;
-    requesterName: string;
-    requesterAvatarUrl: string | null;
-    targetId: string;
-    targetName: string;
-    targetAvatarUrl: string | null;
-    targetUserType: 'human' | 'ai_agent';
-    targetOwnerId?: string | null;
-    approverId: string;
-    message: string | null;
-    status: SerializedContactRequestStatus;
-    kind: 'dm' | 'group_invite';
-    groupContext?: {
-        conversationId: string;
-        groupName: string | null;
-    };
-    createdAt: string | null;
-    resolvedAt?: string | null;
-    expiresAt?: string | null;
-}
+import { z } from 'zod';
+export declare const SerializedContactRequestStatusSchema: z.ZodEnum<{
+    rejected: "rejected";
+    pending: "pending";
+    approved: "approved";
+    expired: "expired";
+}>;
+export type SerializedContactRequestStatus = z.infer<typeof SerializedContactRequestStatusSchema>;
+export declare const SerializedContactRequestSchema: z.ZodObject<{
+    id: z.ZodString;
+    requesterId: z.ZodString;
+    requesterName: z.ZodString;
+    requesterAvatarUrl: z.ZodNullable<z.ZodString>;
+    targetId: z.ZodString;
+    targetName: z.ZodString;
+    targetAvatarUrl: z.ZodNullable<z.ZodString>;
+    targetUserType: z.ZodEnum<{
+        human: "human";
+        ai_agent: "ai_agent";
+    }>;
+    targetOwnerId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    approverId: z.ZodString;
+    message: z.ZodNullable<z.ZodString>;
+    status: z.ZodEnum<{
+        rejected: "rejected";
+        pending: "pending";
+        approved: "approved";
+        expired: "expired";
+    }>;
+    kind: z.ZodEnum<{
+        dm: "dm";
+        group_invite: "group_invite";
+    }>;
+    groupContext: z.ZodOptional<z.ZodObject<{
+        conversationId: z.ZodString;
+        groupName: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    createdAt: z.ZodNullable<z.ZodString>;
+    resolvedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    expiresAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type SerializedContactRequest = z.infer<typeof SerializedContactRequestSchema>;
 export declare function serializeContactRequest(requestId: string, data: Record<string, unknown>): SerializedContactRequest | null;

package/dist/contactRequest.js

@@ -1,3 +1,32 @@
+import { z } from 'zod';
+export const SerializedContactRequestStatusSchema = z.enum([
+    'pending',
+    'approved',
+    'rejected',
+    'expired',
+]);
+export const SerializedContactRequestSchema = z.object({
+    id: z.string(),
+    requesterId: z.string(),
+    requesterName: z.string(),
+    requesterAvatarUrl: z.string().nullable(),
+    targetId: z.string(),
+    targetName: z.string(),
+    targetAvatarUrl: z.string().nullable(),
+    targetUserType: z.enum(['human', 'ai_agent']),
+    targetOwnerId: z.string().nullable().optional(),
+    approverId: z.string(),
+    message: z.string().nullable(),
+    status: SerializedContactRequestStatusSchema,
+    kind: z.enum(['dm', 'group_invite']),
+    groupContext: z.object({
+        conversationId: z.string(),
+        groupName: z.string().nullable(),
+    }).optional(),
+    createdAt: z.string().nullable(),
+    resolvedAt: z.string().nullable().optional(),
+    expiresAt: z.string().nullable().optional(),
+});
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }

package/dist/controlSignals.d.ts

@@ -0,0 +1,55 @@
+import { z } from 'zod';
+export declare const ControlSignalTypeSchema: z.ZodEnum<{
+    interrupt: "interrupt";
+    stop_and_drop: "stop_and_drop";
+    new_session: "new_session";
+}>;
+export type ControlSignalType = z.infer<typeof ControlSignalTypeSchema>;
+export declare const ControlChannelKeySchema: z.ZodEnum<{
+    session: "session";
+    signal: "signal";
+    primitive: "primitive";
+}>;
+export type ControlChannelKey = z.infer<typeof ControlChannelKeySchema>;
+/** `/control/{convo}/{agent}/signal` node. Consumed by writing null. */
+export declare const ControlSignalNodeSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        interrupt: "interrupt";
+        stop_and_drop: "stop_and_drop";
+        new_session: "new_session";
+    }>;
+    updatedAt: z.ZodOptional<z.ZodNumber>;
+}, z.core.$loose>;
+export type ControlSignalNode = z.infer<typeof ControlSignalNodeSchema>;
+/** `/control/{convo}/{agent}/session` node — the session-control primitive record. */
+export declare const ControlSessionNodeSchema: z.ZodObject<{
+    updatedAt: z.ZodOptional<z.ZodNumber>;
+}, z.core.$loose>;
+export type ControlSessionNode = z.infer<typeof ControlSessionNodeSchema>;
+/** `/control/{convo}/{agent}/primitive` — map of requestId → request value. */
+export declare const ControlPrimitiveMapSchema: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+export type ControlPrimitiveMap = z.infer<typeof ControlPrimitiveMapSchema>;
+export declare const ControlSignalEventSchema: z.ZodObject<{
+    conversationId: z.ZodString;
+    type: z.ZodEnum<{
+        interrupt: "interrupt";
+        stop_and_drop: "stop_and_drop";
+        new_session: "new_session";
+    }>;
+    updatedAt: z.ZodNumber;
+    raw: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+export type ControlSignalEventRecord = z.infer<typeof ControlSignalEventSchema>;
+export declare const ControlSessionEventSchema: z.ZodObject<{
+    conversationId: z.ZodString;
+    updatedAt: z.ZodNumber;
+    control: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+export type ControlSessionEventRecord = z.infer<typeof ControlSessionEventSchema>;
+export declare const ControlPrimitiveEventSchema: z.ZodObject<{
+    conversationId: z.ZodString;
+    requestId: z.ZodString;
+    updatedAt: z.ZodNumber;
+    value: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+export type ControlPrimitiveEventRecord = z.infer<typeof ControlPrimitiveEventSchema>;

package/dist/controlSignals.js

@@ -0,0 +1,41 @@
+// Wire contract v1 — RTDB control-channel signal + session-control records.
+//
+// Grounded in @canonmsg/core's ControlChannelPoller (the consumer every host
+// uses for `/control/{conversationId}/{agentId}` reads) and stream-service's
+// `runtime.control` mirror. Three channel keys, read in order:
+//   session   — human changed a runtime control (model/effort/permission …)
+//   signal    — interrupt / stop_and_drop / new_session
+//   primitive — keyed request map (requestId → value)
+import { z } from 'zod';
+export const ControlSignalTypeSchema = z.enum(['interrupt', 'stop_and_drop', 'new_session']);
+export const ControlChannelKeySchema = z.enum(['session', 'signal', 'primitive']);
+// ── RTDB node records (what is written at /control/{convo}/{agent}/…) ──
+/** `/control/{convo}/{agent}/signal` node. Consumed by writing null. */
+export const ControlSignalNodeSchema = z.looseObject({
+    type: ControlSignalTypeSchema,
+    updatedAt: z.number().optional(),
+});
+/** `/control/{convo}/{agent}/session` node — the session-control primitive record. */
+export const ControlSessionNodeSchema = z.looseObject({
+    updatedAt: z.number().optional(),
+});
+/** `/control/{convo}/{agent}/primitive` — map of requestId → request value. */
+export const ControlPrimitiveMapSchema = z.record(z.string(), z.record(z.string(), z.unknown()));
+// ── Dispatched events (what a runtime's handler receives) ──────────────
+export const ControlSignalEventSchema = z.object({
+    conversationId: z.string(),
+    type: ControlSignalTypeSchema,
+    updatedAt: z.number(),
+    raw: z.record(z.string(), z.unknown()),
+});
+export const ControlSessionEventSchema = z.object({
+    conversationId: z.string(),
+    updatedAt: z.number(),
+    control: z.record(z.string(), z.unknown()),
+});
+export const ControlPrimitiveEventSchema = z.object({
+    conversationId: z.string(),
+    requestId: z.string(),
+    updatedAt: z.number(),
+    value: z.record(z.string(), z.unknown()),
+});

package/dist/endpointRegistry.d.ts

@@ -0,0 +1,13 @@
+import type { z } from 'zod';
+export type CanonEndpointSection = 'identity' | 'messaging' | 'conversations' | 'contacts';
+export interface CanonEndpointDescriptor {
+    method: 'GET' | 'POST' | 'PATCH' | 'DELETE';
+    path: string;
+    section: CanonEndpointSection;
+    /** Public one-line contract note (rendered into docs/agents/contracts.md). */
+    note: string;
+    request?: z.ZodType;
+    response?: z.ZodType;
+}
+export declare const CANON_REST_ENDPOINTS: CanonEndpointDescriptor[];
+export declare const CANON_MEDIA_UPLOAD_ENDPOINT: CanonEndpointDescriptor;