@canonmsg/backend-contracts 1.7.0 → 1.8.0

package/dist/sseEvents.js

@@ -0,0 +1,295 @@
+// 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.
+import { z } from 'zod';
+import { SerializedContactRequestSchema } from './contactRequest.js';
+import { SerializedMessageSchema, SerializedReactionsSchema } from './message.js';
+export const SseAccessPolicySchema = z.enum(['open', 'approval-required', 'owner-only']);
+// ── Lifecycle events ───────────────────────────────────────────────────
+export const SseConnectedPayloadSchema = z.object({
+    connectionId: z.string(),
+    agentId: z.string(),
+});
+/** Trusted, server-injected identity & access info (stream.ts `agent.context`). */
+export const SseAgentContextPayloadSchema = z.looseObject({
+    agentId: z.string(),
+    canonContactId: z.string().optional(),
+    clientType: z.string().optional(),
+    ownerId: z.string(),
+    ownerName: z.string(),
+    /** Resolved agent behavior policy — passed through opaquely. */
+    defaultBehavior: z.record(z.string(), z.unknown()).optional(),
+    inboundPolicy: SseAccessPolicySchema,
+    groupJoinPolicy: SseAccessPolicySchema,
+    discoverable: z.boolean(),
+});
+export const SseHeartbeatPayloadSchema = z.object({
+    timestamp: z.string(),
+});
+export const SseReplayExpiredPayloadSchema = z.looseObject({
+    lastAvailableId: z.string().nullable().optional(),
+    message: z.string().optional(),
+});
+export const SseErrorPayloadSchema = z.looseObject({
+    code: z.string().optional(),
+    message: z.string().optional(),
+    retryAfterMs: z.number().optional(),
+    activeConnections: z.number().optional(),
+    maxConnections: z.number().optional(),
+});
+// ── Messages family ────────────────────────────────────────────────────
+export const SseSelfContextSchema = z.object({
+    id: z.string(),
+    type: z.literal('cross_session'),
+    context: z.string(),
+    createdAt: z.string().nullable(),
+    updatedAt: z.string().nullable(),
+});
+export const SseTurnDispatchSchema = z.looseObject({
+    kind: z.enum(['run_turn', 'observe_only']),
+    reason: z.string(),
+    addressed: z.boolean(),
+    policyVersion: z.string().optional(),
+});
+export const SseProvenanceSchema = z.looseObject({
+    conversation: z.looseObject({
+        id: z.string(),
+        type: z.enum(['direct', 'group', 'unknown']),
+    }),
+    sender: z.looseObject({
+        id: z.string(),
+        name: z.string().optional(),
+        type: z.enum(['human', 'ai_agent']),
+        isOwner: z.boolean(),
+    }),
+    mentionedAgent: z.boolean(),
+});
+/**
+ * `message.created` — the inbound message envelope. `message` is exactly the
+ * SerializedMessage the shared serializer emits (the E2EE S1 slot).
+ */
+export const SseMessageCreatedPayloadSchema = z.looseObject({
+    conversationId: z.string(),
+    /** Resolved agent behavior policy — passed through opaquely. */
+    behavior: z.record(z.string(), z.unknown()).optional(),
+    activeSelfContextId: z.string().nullable().optional(),
+    selfContexts: z.array(SseSelfContextSchema).optional(),
+    provenance: SseProvenanceSchema.optional(),
+    turnDispatch: SseTurnDispatchSchema.optional(),
+    message: SerializedMessageSchema,
+});
+export const SseMessageUpdatedPayloadSchema = z.object({
+    conversationId: z.string(),
+    messageId: z.string(),
+    actorId: z.string().optional(),
+    updatedAt: z.string().optional(),
+    changes: z.looseObject({
+        reactions: SerializedReactionsSchema,
+    }),
+});
+export const SseMessageDeletedPayloadSchema = z.object({
+    conversationId: z.string(),
+    messageId: z.string(),
+});
+export const SseMembershipChangeSchema = z.object({
+    addedMemberIds: z.array(z.string()),
+    removedMemberIds: z.array(z.string()),
+    memberCount: z.number(),
+});
+export const SseConversationUpdatedPayloadSchema = z.object({
+    conversationId: z.string(),
+    changes: z.record(z.string(), z.unknown()),
+    membershipChange: SseMembershipChangeSchema.optional(),
+});
+// ── Contacts family ────────────────────────────────────────────────────
+/** `contact.request` / `contact.approved` carry the serialized contact request. */
+export const SseContactRequestPayloadSchema = 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.
+ */
+export const SseContactPayloadSchema = z.object({
+    id: z.string(),
+    source: z.string(),
+    addedAt: z.string().nullable(),
+    displayNameOverride: z.string().nullable(),
+});
+export const SseContactRemovedPayloadSchema = z.object({
+    id: z.string(),
+});
+// ── Typing / presence family ───────────────────────────────────────────
+export const SseTypingPayloadSchema = z.object({
+    conversationId: z.string(),
+    userId: z.string(),
+    isTyping: z.boolean(),
+    status: z.enum(['thinking', 'typing']).optional(),
+    timestamp: z.number().optional(),
+});
+export const SsePresencePayloadSchema = z.object({
+    userId: z.string(),
+    online: z.boolean(),
+    lastSeen: z.string().optional(),
+});
+// ── Runtime / turn family ──────────────────────────────────────────────
+/** Aggregated RTDB runtime snapshot — nodes are passed through opaquely. */
+export const SseRuntimeUpdatedPayloadSchema = z.object({
+    conversationId: z.string(),
+    agentId: z.string(),
+    runtime: z.record(z.string(), z.unknown()).nullable(),
+    runtimeInfo: z.record(z.string(), z.unknown()).nullable(),
+    sessionState: z.record(z.string(), z.unknown()).nullable(),
+    sessionConfig: z.record(z.string(), z.unknown()).nullable(),
+});
+export const SseTurnUpdatedPayloadSchema = z.object({
+    conversationId: z.string(),
+    agentId: z.string(),
+    turn: z.record(z.string(), z.unknown()).nullable(),
+});
+export const SseRuntimeControlKindSchema = z.enum([
+    'session',
+    'signal',
+    'primitive',
+    'runtimeInput',
+    'runtimeCard',
+    'runtimeApproval',
+]);
+export const SseRuntimeControlPayloadSchema = z.object({
+    conversationId: z.string(),
+    agentId: z.string(),
+    kind: SseRuntimeControlKindSchema,
+    requestId: z.string().optional(),
+    updatedAt: z.number().optional(),
+    value: z.record(z.string(), z.unknown()),
+});
+// ── Voice family ───────────────────────────────────────────────────────
+export const SseVoiceSessionSchema = z.looseObject({
+    id: z.string(),
+    conversationId: z.string(),
+    roomName: z.string(),
+    mode: z.enum(['human', 'runtime_voice']),
+    status: z.enum(['active', 'ended', 'error']),
+    createdBy: z.string(),
+    participantIds: z.array(z.string()),
+    participants: z.array(z.looseObject({
+        userId: z.string(),
+        userType: z.enum(['human', 'ai_agent', 'system']),
+        displayName: z.string().nullable(),
+        joinedAt: z.string().nullable(),
+        leftAt: z.string().nullable(),
+    })).optional(),
+    targetAgentId: z.string().nullable().optional(),
+    createdAt: z.string().nullable().optional(),
+    updatedAt: z.string().nullable().optional(),
+    endedAt: z.string().nullable().optional(),
+    error: z.string().nullable().optional(),
+});
+export const SseVoiceSessionEventPayloadSchema = z.object({
+    conversationId: z.string(),
+    session: 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.
+ */
+export const 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',
+];
+export const SseEventTypeSchema = z.enum(SSE_EVENT_TYPES);
+/** Payload schema for every event type — the machine-readable event registry. */
+export const SSE_EVENT_PAYLOAD_SCHEMAS = {
+    'connected': SseConnectedPayloadSchema,
+    'agent.context': SseAgentContextPayloadSchema,
+    'heartbeat': SseHeartbeatPayloadSchema,
+    'message.created': SseMessageCreatedPayloadSchema,
+    'message.updated': SseMessageUpdatedPayloadSchema,
+    'message.deleted': SseMessageDeletedPayloadSchema,
+    'conversation.updated': SseConversationUpdatedPayloadSchema,
+    'contact.request': SseContactRequestPayloadSchema,
+    'contact.approved': SseContactRequestPayloadSchema,
+    'contact.added': SseContactPayloadSchema,
+    'contact.updated': SseContactPayloadSchema,
+    'contact.removed': SseContactRemovedPayloadSchema,
+    'typing': SseTypingPayloadSchema,
+    'presence': SsePresencePayloadSchema,
+    'runtime.updated': SseRuntimeUpdatedPayloadSchema,
+    'turn.updated': SseTurnUpdatedPayloadSchema,
+    'runtime.control': SseRuntimeControlPayloadSchema,
+    'voice.session.started': SseVoiceSessionEventPayloadSchema,
+    'voice.session.ended': SseVoiceSessionEventPayloadSchema,
+    'replay.expired': SseReplayExpiredPayloadSchema,
+    'error': SseErrorPayloadSchema,
+};
+/**
+ * Subscription families (`?events=` filter). Lifecycle events (`connected`,
+ * `agent.context`, `heartbeat`, `replay.expired`, `error`) are always sent.
+ */
+export const SSE_EVENT_FAMILIES = [
+    'messages',
+    'contacts',
+    'typing_presence',
+    'runtime_turn',
+    'voice',
+];
+export const SseEventFamilySchema = z.enum(SSE_EVENT_FAMILIES);
+export const 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].
+ */
+export const SseEventEnvelopeSchema = z.object({
+    id: z.string().optional(),
+    event: SseEventTypeSchema,
+    data: z.unknown(),
+});

package/dist/turnProtocol.d.ts

@@ -1,27 +1,94 @@
-export type SenderType = 'human' | 'ai_agent';
-export type TurnLifecycleState = 'idle' | 'thinking' | 'streaming' | 'tool' | 'waiting_input' | 'completed' | 'interrupted';
-export type TurnMessageSemantics = 'progress' | 'turn_complete' | 'control';
-export type DeliveryIntent = 'queue' | 'interrupt' | 'interleave' | 'stop';
-export type InboundDisposition = 'queued' | 'accepted_now' | 'interleaved' | 'trigger_suppressed' | 'rejected' | 'cancelled';
-export interface TurnMetadata {
-    turnId?: string | null;
-    turnSemantics?: TurnMessageSemantics;
-    deliveryIntent?: DeliveryIntent;
-    replyBehavior?: 'allow_auto_reply' | 'suppress_auto_reply';
-    inboundDisposition?: InboundDisposition;
-    requestedTurnMode?: string;
-}
-export interface TriggerDecision {
-    allow: boolean;
-    semantics: TurnMessageSemantics;
-    reason: string;
-}
-export interface TurnStateLike {
-    state: TurnLifecycleState;
-    openedAt?: number;
-    updatedAt?: number;
-    turnUpdatedAt?: number | null;
-}
+import { z } from 'zod';
+export declare const SenderTypeSchema: z.ZodEnum<{
+    human: "human";
+    ai_agent: "ai_agent";
+}>;
+export type SenderType = z.infer<typeof SenderTypeSchema>;
+export declare const TurnLifecycleStateSchema: z.ZodEnum<{
+    idle: "idle";
+    thinking: "thinking";
+    streaming: "streaming";
+    tool: "tool";
+    waiting_input: "waiting_input";
+    completed: "completed";
+    interrupted: "interrupted";
+}>;
+export type TurnLifecycleState = z.infer<typeof TurnLifecycleStateSchema>;
+export declare const TurnMessageSemanticsSchema: z.ZodEnum<{
+    progress: "progress";
+    turn_complete: "turn_complete";
+    control: "control";
+}>;
+export type TurnMessageSemantics = z.infer<typeof TurnMessageSemanticsSchema>;
+export declare const DeliveryIntentSchema: z.ZodEnum<{
+    queue: "queue";
+    interrupt: "interrupt";
+    interleave: "interleave";
+    stop: "stop";
+}>;
+export type DeliveryIntent = z.infer<typeof DeliveryIntentSchema>;
+export declare const InboundDispositionSchema: z.ZodEnum<{
+    queued: "queued";
+    accepted_now: "accepted_now";
+    interleaved: "interleaved";
+    trigger_suppressed: "trigger_suppressed";
+    rejected: "rejected";
+    cancelled: "cancelled";
+}>;
+export type InboundDisposition = z.infer<typeof InboundDispositionSchema>;
+export declare const TurnMetadataSchema: z.ZodObject<{
+    turnId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    turnSemantics: z.ZodOptional<z.ZodEnum<{
+        progress: "progress";
+        turn_complete: "turn_complete";
+        control: "control";
+    }>>;
+    deliveryIntent: z.ZodOptional<z.ZodEnum<{
+        queue: "queue";
+        interrupt: "interrupt";
+        interleave: "interleave";
+        stop: "stop";
+    }>>;
+    replyBehavior: z.ZodOptional<z.ZodEnum<{
+        allow_auto_reply: "allow_auto_reply";
+        suppress_auto_reply: "suppress_auto_reply";
+    }>>;
+    inboundDisposition: z.ZodOptional<z.ZodEnum<{
+        queued: "queued";
+        accepted_now: "accepted_now";
+        interleaved: "interleaved";
+        trigger_suppressed: "trigger_suppressed";
+        rejected: "rejected";
+        cancelled: "cancelled";
+    }>>;
+    requestedTurnMode: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type TurnMetadata = z.infer<typeof TurnMetadataSchema>;
+export declare const TriggerDecisionSchema: z.ZodObject<{
+    allow: z.ZodBoolean;
+    semantics: z.ZodEnum<{
+        progress: "progress";
+        turn_complete: "turn_complete";
+        control: "control";
+    }>;
+    reason: z.ZodString;
+}, z.core.$strip>;
+export type TriggerDecision = z.infer<typeof TriggerDecisionSchema>;
+export declare const TurnStateLikeSchema: z.ZodObject<{
+    state: z.ZodEnum<{
+        idle: "idle";
+        thinking: "thinking";
+        streaming: "streaming";
+        tool: "tool";
+        waiting_input: "waiting_input";
+        completed: "completed";
+        interrupted: "interrupted";
+    }>;
+    openedAt: z.ZodOptional<z.ZodNumber>;
+    updatedAt: z.ZodOptional<z.ZodNumber>;
+    turnUpdatedAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+}, z.core.$strip>;
+export type TurnStateLike = z.infer<typeof TurnStateLikeSchema>;
 export declare const ACTIVE_TURN_STALE_THRESHOLD_MS: number;
 export declare const WAITING_INPUT_STALE_THRESHOLD_MS: number;
 export declare function normalizeTurnMetadata(metadata: unknown): TurnMetadata | null;

package/dist/turnProtocol.js

@@ -1,3 +1,43 @@
+import { z } from 'zod';
+export const SenderTypeSchema = z.enum(['human', 'ai_agent']);
+export const TurnLifecycleStateSchema = z.enum([
+    'idle',
+    'thinking',
+    'streaming',
+    'tool',
+    'waiting_input',
+    'completed',
+    'interrupted',
+]);
+export const TurnMessageSemanticsSchema = z.enum(['progress', 'turn_complete', 'control']);
+export const DeliveryIntentSchema = z.enum(['queue', 'interrupt', 'interleave', 'stop']);
+export const InboundDispositionSchema = z.enum([
+    'queued',
+    'accepted_now',
+    'interleaved',
+    'trigger_suppressed',
+    'rejected',
+    'cancelled',
+]);
+export const TurnMetadataSchema = z.object({
+    turnId: z.string().nullable().optional(),
+    turnSemantics: TurnMessageSemanticsSchema.optional(),
+    deliveryIntent: DeliveryIntentSchema.optional(),
+    replyBehavior: z.enum(['allow_auto_reply', 'suppress_auto_reply']).optional(),
+    inboundDisposition: InboundDispositionSchema.optional(),
+    requestedTurnMode: z.string().optional(),
+});
+export const TriggerDecisionSchema = z.object({
+    allow: z.boolean(),
+    semantics: TurnMessageSemanticsSchema,
+    reason: z.string(),
+});
+export const TurnStateLikeSchema = z.object({
+    state: TurnLifecycleStateSchema,
+    openedAt: z.number().optional(),
+    updatedAt: z.number().optional(),
+    turnUpdatedAt: z.number().nullable().optional(),
+});
 export const ACTIVE_TURN_STALE_THRESHOLD_MS = 30 * 60 * 1000;
 export const WAITING_INPUT_STALE_THRESHOLD_MS = 12 * 60 * 60 * 1000;
 const TURN_SEMANTICS = [
@@ -19,7 +59,6 @@ function isHiddenRuntimeCardMetadata(metadata) {
         return false;
     return metadata.type === 'approval_reply'
         || metadata.type === 'approval_outcome'
-        || metadata.type === 'question_reply'
         || metadata.type === 'plan_approval_reply'
         || metadata.type === 'runtime_input_reply'
         || metadata.type === 'runtime_input_outcome'

package/package.json

@@ -1,22 +1,22 @@
 {
   "name": "@canonmsg/backend-contracts",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Canon backend contract helpers shared by Functions and stream-service",
   "type": "module",
   "main": "dist/cjs/index.js",
   "types": "dist/index.d.ts",
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
-      "require": "./dist/cjs/index.js",
-      "types": "./dist/index.d.ts"
+      "require": "./dist/cjs/index.js"
     }
   },
   "files": [
     "dist"
   ],
   "scripts": {
-    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json && tsc -p tsconfig.cjs.json && node -e \"require('fs').mkdirSync('dist/cjs',{recursive:true}); require('fs').writeFileSync('dist/cjs/package.json', JSON.stringify({type:'commonjs'}))\"",
+    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json && tsc -p tsconfig.cjs.json && node -e \"require('fs').mkdirSync('dist/cjs',{recursive:true}); require('fs').writeFileSync('dist/cjs/package.json', JSON.stringify({type:'commonjs'}))\" && node scripts/emit-json-schema.mjs",
     "dev": "tsc -p tsconfig.json --watch",
     "test": "vitest run",
     "prepack": "npm run build"
@@ -44,5 +44,8 @@
     "typescript": "~5.7.0",
     "vitest": "^4.1.8"
   },
-  "license": "MIT"
+  "license": "MIT",
+  "dependencies": {
+    "zod": "^4.4.3"
+  }
 }