@canonmsg/backend-contracts 1.9.0 → 2.1.0

package/dist/restEndpoints.js

@@ -1,234 +0,0 @@
-// Wire contract v1 — request/response schemas for the agent-facing "Canon op"
-// REST surface the bridge proxies (bridge-local-api.md §B).
-//
-// Grounded in the Functions handlers (functions/src/api/*) and the canonical
-// consumer (@canonmsg/core CanonClient) — request bodies mirror what clients
-// send today, response schemas mirror what the handlers emit. This is a
-// re-expression of current behavior, not a redesign.
-import { z } from 'zod';
-import { MediaAttachmentSchema } from './media.js';
-import { SerializedContentTypeSchema, SerializedMessageSchema, SerializedReactionsSchema, } from './message.js';
-import { InboundDispositionSchema } from './turnProtocol.js';
-// ── Shared fragments ───────────────────────────────────────────────────
-export const RestOkResponseSchema = z.looseObject({
-    success: z.boolean().optional(),
-});
-/** GET …/messages items — the serialized message plus the soft-delete flag. */
-export const RestMessageSchema = SerializedMessageSchema.extend({
-    deleted: z.boolean().optional(),
-});
-/**
- * STRICT WRITES, TOLERANT READS: this is a READ schema over live production
- * data, so it must describe what Firestore actually holds — not what today's
- * writers produce. The GET /conversations serializer
- * (functions/src/api/getConversations.ts) passes `lastMessage` fields through
- * from the conversation doc, and legacy rows (pre-refactor writes,
- * deleted-message repair) hold explicit nulls:
- * - `text` is serialized `?? null` and `timestamp` as
- *   `?.toDate?.()?.toISOString() ?? null` — both emit null by construction.
- * - `senderId` / `senderType` / `contentType` are raw pass-throughs; live
- *   rows exist with all three null (the getConversations "ghost fix" comment
- *   acknowledges null senderId).
- * - conversation `createdAt` is also serialized `?? null`.
- * Writers (onMessageCreated / deletedMessageRepair) stay strict — they always
- * produce the full shape; only the read contract admits the legacy nulls.
- */
-export const RestConversationLastMessageSchema = z.looseObject({
-    text: z.string().nullable(),
-    messageId: z.string().optional(),
-    senderId: z.string().nullable().optional(),
-    senderType: z.enum(['human', 'ai_agent']).nullable().optional(),
-    contentType: SerializedContentTypeSchema.nullable().optional(),
-    timestamp: z.string().nullable(),
-});
-export const RestConversationSchema = z.looseObject({
-    id: z.string(),
-    type: z.enum(['direct', 'group']),
-    name: z.string().nullable().optional(),
-    topic: z.string().nullable().optional(),
-    memberIds: z.array(z.string()),
-    isAgentChat: z.boolean().optional(),
-    /** Resolved agent behavior policy — opaque pass-through. */
-    behavior: z.record(z.string(), z.unknown()).optional(),
-    hasUnread: z.boolean().optional(),
-    lastMessage: RestConversationLastMessageSchema.nullable(),
-    createdAt: z.string().nullable().optional(),
-});
-export const RestContactSchema = z.object({
-    id: z.string(),
-    source: z.string(),
-    addedAt: z.string().nullable(),
-    displayNameOverride: z.string().nullable(),
-});
-export const RestSessionSelectionSchema = z.union([
-    z.object({ mode: z.enum(['new', 'continue_latest', 'continue_or_create']) }),
-    z.object({ mode: z.literal('specific'), conversationId: z.string() }),
-]);
-// ── POST /messages/send ────────────────────────────────────────────────
-export const SendMessageRequestSchema = z.object({
-    conversationId: z.string(),
-    text: z.string().optional(),
-    /** Client-supplied idempotency id. */
-    messageId: z.string().optional(),
-    contentType: SerializedContentTypeSchema.optional(),
-    replyTo: z.string().optional(),
-    replyToPosition: z.number().optional(),
-    attachments: z.array(MediaAttachmentSchema).optional(),
-    contactCardUserId: z.string().optional(),
-    mentions: z.array(z.string()).optional(),
-    selfContextId: z.string().nullable().optional(),
-    /** Structured metadata (turn protocol, approval cards, …). */
-    metadata: z.record(z.string(), z.unknown()).optional(),
-});
-export const SendMessageResponseSchema = z.object({
-    messageId: z.string(),
-});
-// ── POST /messages/react ───────────────────────────────────────────────
-export const ReactRequestSchema = z.object({
-    conversationId: z.string(),
-    messageId: z.string(),
-    emoji: z.string(),
-});
-export const ReactResponseSchema = z.object({
-    success: z.boolean(),
-    action: z.enum(['added', 'removed']),
-    reactions: SerializedReactionsSchema,
-});
-// ── POST /messages/forward ─────────────────────────────────────────────
-export const ForwardMessageRequestSchema = z.object({
-    sourceConversationId: z.string(),
-    targetConversationId: z.string(),
-    messageId: z.string(),
-    text: z.string().optional(),
-});
-export const ForwardMessageResponseSchema = z.object({
-    messageId: z.string(),
-    targetConversationId: z.string(),
-    forwardedFrom: z.object({
-        sourceConversationId: z.string(),
-        messageId: z.string(),
-    }),
-});
-// ── DELETE /conversations/:id/messages/:id, POST …/read, PATCH …/disposition ──
-export const DeleteMessageResponseSchema = RestOkResponseSchema;
-export const MarkReadResponseSchema = RestOkResponseSchema;
-export const UpdateDispositionRequestSchema = z.object({
-    inboundDisposition: InboundDispositionSchema,
-});
-// ── GET /conversations + GET …/messages ────────────────────────────────
-export const ConversationsResponseSchema = z.object({
-    conversations: z.array(RestConversationSchema),
-});
-/** Query params: limit, before, includeBehavior. */
-export const GetMessagesQuerySchema = z.object({
-    limit: z.string().optional(),
-    before: z.string().optional(),
-    includeBehavior: z.string().optional(),
-});
-export const MessagesPageResponseSchema = z.looseObject({
-    messages: z.array(RestMessageSchema),
-    /** Present with includeBehavior=1. */
-    behavior: z.record(z.string(), z.unknown()).optional(),
-    activeSelfContextIdByMessageId: z.record(z.string(), z.string()).optional(),
-    selfContexts: z.array(z.record(z.string(), z.unknown())).optional(),
-});
-// ── POST /conversations/create ─────────────────────────────────────────
-export const CreateConversationRequestSchema = z.object({
-    type: z.enum(['direct', 'group']),
-    targetUserId: z.string().optional(),
-    memberIds: z.array(z.string()).optional(),
-    name: z.string().optional(),
-    /** Initial session config for first-party coding agents — opaque pass-through. */
-    sessionConfig: z.record(z.string(), z.unknown()).nullable().optional(),
-    sessionSelection: RestSessionSelectionSchema.optional(),
-});
-export const CreateConversationResponseSchema = z.object({
-    conversationId: z.string(),
-    created: z.boolean().optional(),
-    reused: z.boolean().optional(),
-    sessionSelection: z.enum(['new', 'continue_latest', 'continue_or_create', 'specific']).optional(),
-});
-// ── Contacts / admission ───────────────────────────────────────────────
-export const CreateContactRequestRequestSchema = z.object({
-    targetId: z.string(),
-    message: z.string().optional(),
-});
-export const CreateContactRequestResponseSchema = z.union([
-    z.looseObject({ status: z.literal('open') }),
-    z.looseObject({ status: z.enum(['created', 'duplicate']), requestId: z.string() }),
-    /** Legacy "already a contact" body. */
-    z.looseObject({ message: z.string() }),
-]);
-export const ContactsResponseSchema = z.object({
-    contacts: z.array(RestContactSchema),
-});
-export const ResolveAdmissionRequestSchema = z.union([
-    z.object({ targetUserId: z.string() }),
-    z.object({ canonContactId: z.string() }),
-]);
-export const ResolveAdmissionResponseSchema = z.looseObject({
-    resolvedTargetUserId: z.string().nullable().optional(),
-    target: z.looseObject({
-        id: z.string(),
-        canonContactId: z.string().optional(),
-        displayName: z.string().optional(),
-        avatarUrl: z.string().nullable().optional(),
-        about: z.string().optional(),
-        userType: z.enum(['human', 'ai_agent']).optional(),
-        discoverable: z.boolean().optional(),
-        inboundPolicy: z.enum(['open', 'approval-required', 'owner-only']).optional(),
-        groupJoinPolicy: z.enum(['open', 'approval-required', 'owner-only']).optional(),
-    }).nullable(),
-    admission: z.looseObject({
-        state: z.enum([
-            'self',
-            'not-found',
-            'allowed',
-            'request-required',
-            'pending-outbound',
-            'blocked',
-            'inactive',
-            'owner-only',
-        ]),
-        canMessage: z.boolean(),
-        canRequestContact: z.boolean(),
-        isContact: z.boolean(),
-        pendingRequestId: z.string().optional(),
-        blockedByViewer: z.boolean().optional(),
-        blockedByTarget: z.boolean().optional(),
-    }),
-});
-// ── Typing / streaming ─────────────────────────────────────────────────
-export const SetTypingRequestSchema = z.object({
-    conversationId: z.string(),
-    typing: z.boolean(),
-    status: z.enum(['thinking', 'typing']).optional(),
-});
-/** POST /streaming — the legacy REST facade over the RTDB streaming bubble. */
-export const SetStreamingRequestSchema = z.union([
-    z.object({
-        conversationId: z.string(),
-        text: z.string(),
-        status: z.string(),
-        messageId: z.string(),
-        turnId: z.string().nullable().optional(),
-        /** TurnOutputBlock[] — opaque pass-through. */
-        blocks: z.array(z.record(z.string(), z.unknown())).optional(),
-    }),
-    z.object({
-        conversationId: z.string(),
-        streaming: z.literal(false),
-    }),
-]);
-// ── Media upload ───────────────────────────────────────────────────────
-export const UploadMediaRequestSchema = z.object({
-    conversationId: z.string(),
-    mimeType: z.string(),
-    /** Base64-encoded file content. */
-    data: z.string(),
-    fileName: z.string().optional(),
-});
-export const UploadMediaResponseSchema = z.object({
-    url: z.string(),
-    attachment: MediaAttachmentSchema,
-});

package/dist/schemas/agent-behavior-settings-record.schema.json

@@ -1,48 +0,0 @@
-{
-  "$id": "canon:AgentBehaviorSettingsRecordSchema",
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "type": "object",
-  "properties": {
-    "participationStyle": {
-      "type": "string",
-      "enum": [
-        "natural",
-        "collaborative",
-        "mention-first",
-        "approval-gated",
-        "handoff-only",
-        "observer"
-      ]
-    },
-    "allowAgentToAgent": {
-      "type": "boolean"
-    },
-    "allowLongRunningCollaboration": {
-      "type": "boolean"
-    },
-    "requireMentionForGroupReplies": {
-      "type": "boolean"
-    },
-    "maxConsecutiveAgentTurns": {
-      "anyOf": [
-        {
-          "type": "number"
-        },
-        {
-          "type": "null"
-        }
-      ]
-    },
-    "instructions": {
-      "anyOf": [
-        {
-          "type": "string"
-        },
-        {
-          "type": "null"
-        }
-      ]
-    }
-  },
-  "additionalProperties": false
-}

package/dist/schemas/bridge-connection-state-notification.schema.json

@@ -1,19 +0,0 @@
-{
-  "$id": "canon:BridgeConnectionStateNotificationSchema",
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "type": "object",
-  "properties": {
-    "upstream": {
-      "type": "string",
-      "enum": [
-        "connected",
-        "reconnecting",
-        "down"
-      ]
-    }
-  },
-  "required": [
-    "upstream"
-  ],
-  "additionalProperties": false
-}

package/dist/schemas/bridge-get-attachment-params.schema.json

@@ -1,24 +0,0 @@
-{
-  "$id": "canon:BridgeGetAttachmentParamsSchema",
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "type": "object",
-  "properties": {
-    "url": {
-      "type": "string"
-    },
-    "attachmentId": {
-      "type": "string"
-    },
-    "as": {
-      "type": "string",
-      "enum": [
-        "path",
-        "bytes"
-      ]
-    }
-  },
-  "required": [
-    "as"
-  ],
-  "additionalProperties": false
-}

package/dist/schemas/bridge-get-attachment-result.schema.json

@@ -1,20 +0,0 @@
-{
-  "$id": "canon:BridgeGetAttachmentResultSchema",
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "type": "object",
-  "properties": {
-    "path": {
-      "type": "string"
-    },
-    "bytes": {
-      "type": "string"
-    },
-    "mime": {
-      "type": "string"
-    }
-  },
-  "required": [
-    "mime"
-  ],
-  "additionalProperties": false
-}

package/dist/schemas/bridge-hello-params.schema.json

@@ -1,42 +0,0 @@
-{
-  "$id": "canon:BridgeHelloParamsSchema",
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "type": "object",
-  "properties": {
-    "protocolVersion": {
-      "type": "number"
-    },
-    "clientType": {
-      "type": "string"
-    },
-    "wantFamilies": {
-      "type": "array",
-      "items": {
-        "type": "string",
-        "enum": [
-          "messages",
-          "contacts",
-          "typing_presence",
-          "runtime_turn",
-          "voice"
-        ]
-      }
-    },
-    "resumeCursor": {
-      "type": "string"
-    },
-    "runtimeDescriptor": {
-      "type": "object",
-      "propertyNames": {
-        "type": "string"
-      },
-      "additionalProperties": {}
-    }
-  },
-  "required": [
-    "protocolVersion",
-    "clientType",
-    "wantFamilies"
-  ],
-  "additionalProperties": false
-}

package/dist/schemas/bridge-hello-result.schema.json

@@ -1,105 +0,0 @@
-{
-  "$id": "canon:BridgeHelloResultSchema",
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "type": "object",
-  "properties": {
-    "protocolVersion": {
-      "type": "number"
-    },
-    "agentId": {
-      "type": "string"
-    },
-    "agentName": {
-      "type": "string"
-    },
-    "agentContext": {
-      "type": "object",
-      "properties": {
-        "agentId": {
-          "type": "string"
-        },
-        "canonContactId": {
-          "type": "string"
-        },
-        "clientType": {
-          "type": "string"
-        },
-        "ownerId": {
-          "type": "string"
-        },
-        "ownerName": {
-          "type": "string"
-        },
-        "defaultBehavior": {
-          "type": "object",
-          "propertyNames": {
-            "type": "string"
-          },
-          "additionalProperties": {}
-        },
-        "inboundPolicy": {
-          "type": "string",
-          "enum": [
-            "open",
-            "approval-required",
-            "owner-only"
-          ]
-        },
-        "groupJoinPolicy": {
-          "type": "string",
-          "enum": [
-            "open",
-            "approval-required",
-            "owner-only"
-          ]
-        },
-        "discoverable": {
-          "type": "boolean"
-        }
-      },
-      "required": [
-        "agentId",
-        "ownerId",
-        "ownerName",
-        "inboundPolicy",
-        "groupJoinPolicy",
-        "discoverable"
-      ],
-      "additionalProperties": {}
-    },
-    "sinceCursor": {
-      "anyOf": [
-        {
-          "type": "string"
-        },
-        {
-          "type": "null"
-        }
-      ]
-    },
-    "resync": {
-      "type": "object",
-      "properties": {
-        "reason": {
-          "type": "string",
-          "enum": [
-            "cursor-expired",
-            "unknown-cursor"
-          ]
-        }
-      },
-      "required": [
-        "reason"
-      ],
-      "additionalProperties": false
-    }
-  },
-  "required": [
-    "protocolVersion",
-    "agentId",
-    "agentName",
-    "agentContext",
-    "sinceCursor"
-  ],
-  "additionalProperties": false
-}

package/dist/schemas/bridge-hitl-state.schema.json

@@ -1,38 +0,0 @@
-{
-  "$id": "canon:BridgeHitlStateSchema",
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "type": "object",
-  "properties": {
-    "status": {
-      "anyOf": [
-        {
-          "type": "string",
-          "const": "pending"
-        },
-        {
-          "type": "string",
-          "enum": [
-            "submitted",
-            "cancelled",
-            "timeout"
-          ]
-        }
-      ]
-    },
-    "answer": {
-      "type": "object",
-      "propertyNames": {
-        "type": "string"
-      },
-      "additionalProperties": {}
-    },
-    "expiresAt": {
-      "type": "string"
-    }
-  },
-  "required": [
-    "status",
-    "expiresAt"
-  ],
-  "additionalProperties": false
-}

package/dist/schemas/bridge-ok-result.schema.json

@@ -1,15 +0,0 @@
-{
-  "$id": "canon:BridgeOkResultSchema",
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "type": "object",
-  "properties": {
-    "ok": {
-      "type": "boolean",
-      "const": true
-    }
-  },
-  "required": [
-    "ok"
-  ],
-  "additionalProperties": false
-}

package/dist/schemas/bridge-publish-streaming-event-params.schema.json

@@ -1,138 +0,0 @@
-{
-  "$id": "canon:BridgePublishStreamingEventParamsSchema",
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "type": "object",
-  "properties": {
-    "conversationId": {
-      "type": "string"
-    },
-    "turnId": {
-      "anyOf": [
-        {
-          "type": "string"
-        },
-        {
-          "type": "null"
-        }
-      ]
-    },
-    "messageId": {
-      "type": "string"
-    },
-    "event": {
-      "oneOf": [
-        {
-          "type": "object",
-          "properties": {
-            "kind": {
-              "type": "string",
-              "const": "text"
-            },
-            "id": {
-              "type": "string"
-            },
-            "mode": {
-              "type": "string",
-              "enum": [
-                "append",
-                "replace"
-              ]
-            },
-            "text": {
-              "type": "string"
-            }
-          },
-          "required": [
-            "kind",
-            "id",
-            "mode",
-            "text"
-          ],
-          "additionalProperties": false
-        },
-        {
-          "type": "object",
-          "properties": {
-            "kind": {
-              "type": "string",
-              "const": "tool"
-            },
-            "id": {
-              "type": "string"
-            },
-            "status": {
-              "type": "string",
-              "enum": [
-                "running",
-                "completed",
-                "failed"
-              ]
-            },
-            "title": {
-              "type": "string"
-            },
-            "summary": {
-              "type": "string"
-            },
-            "detail": {
-              "type": "string"
-            }
-          },
-          "required": [
-            "kind",
-            "id"
-          ],
-          "additionalProperties": false
-        },
-        {
-          "type": "object",
-          "properties": {
-            "kind": {
-              "type": "string",
-              "const": "thinking"
-            }
-          },
-          "required": [
-            "kind"
-          ],
-          "additionalProperties": false
-        },
-        {
-          "type": "object",
-          "properties": {
-            "kind": {
-              "type": "string",
-              "const": "final"
-            },
-            "text": {
-              "type": "string"
-            }
-          },
-          "required": [
-            "kind",
-            "text"
-          ],
-          "additionalProperties": false
-        },
-        {
-          "type": "object",
-          "properties": {
-            "kind": {
-              "type": "string",
-              "const": "clear"
-            }
-          },
-          "required": [
-            "kind"
-          ],
-          "additionalProperties": false
-        }
-      ]
-    }
-  },
-  "required": [
-    "conversationId",
-    "event"
-  ],
-  "additionalProperties": false
-}