@canonmsg/backend-contracts 1.7.1 → 1.8.1

package/dist/cjs/contactRequest.js

@@ -1,6 +1,36 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.SerializedContactRequestSchema = exports.SerializedContactRequestStatusSchema = void 0;
 exports.serializeContactRequest = serializeContactRequest;
+const zod_1 = require("zod");
+exports.SerializedContactRequestStatusSchema = zod_1.z.enum([
+    'pending',
+    'approved',
+    'rejected',
+    'expired',
+]);
+exports.SerializedContactRequestSchema = zod_1.z.object({
+    id: zod_1.z.string(),
+    requesterId: zod_1.z.string(),
+    requesterName: zod_1.z.string(),
+    requesterAvatarUrl: zod_1.z.string().nullable(),
+    targetId: zod_1.z.string(),
+    targetName: zod_1.z.string(),
+    targetAvatarUrl: zod_1.z.string().nullable(),
+    targetUserType: zod_1.z.enum(['human', 'ai_agent']),
+    targetOwnerId: zod_1.z.string().nullable().optional(),
+    approverId: zod_1.z.string(),
+    message: zod_1.z.string().nullable(),
+    status: exports.SerializedContactRequestStatusSchema,
+    kind: zod_1.z.enum(['dm', 'group_invite']),
+    groupContext: zod_1.z.object({
+        conversationId: zod_1.z.string(),
+        groupName: zod_1.z.string().nullable(),
+    }).optional(),
+    createdAt: zod_1.z.string().nullable(),
+    resolvedAt: zod_1.z.string().nullable().optional(),
+    expiresAt: zod_1.z.string().nullable().optional(),
+});
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }

package/dist/cjs/controlSignals.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ControlPrimitiveEventSchema = exports.ControlSessionEventSchema = exports.ControlSignalEventSchema = exports.ControlPrimitiveMapSchema = exports.ControlSessionNodeSchema = exports.ControlSignalNodeSchema = exports.ControlChannelKeySchema = exports.ControlSignalTypeSchema = void 0;
+// 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)
+const zod_1 = require("zod");
+exports.ControlSignalTypeSchema = zod_1.z.enum(['interrupt', 'stop_and_drop', 'new_session']);
+exports.ControlChannelKeySchema = zod_1.z.enum(['session', 'signal', 'primitive']);
+// ── RTDB node records (what is written at /control/{convo}/{agent}/…) ──
+/** `/control/{convo}/{agent}/signal` node. Consumed by writing null. */
+exports.ControlSignalNodeSchema = zod_1.z.looseObject({
+    type: exports.ControlSignalTypeSchema,
+    updatedAt: zod_1.z.number().optional(),
+});
+/** `/control/{convo}/{agent}/session` node — the session-control primitive record. */
+exports.ControlSessionNodeSchema = zod_1.z.looseObject({
+    updatedAt: zod_1.z.number().optional(),
+});
+/** `/control/{convo}/{agent}/primitive` — map of requestId → request value. */
+exports.ControlPrimitiveMapSchema = zod_1.z.record(zod_1.z.string(), zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()));
+// ── Dispatched events (what a runtime's handler receives) ──────────────
+exports.ControlSignalEventSchema = zod_1.z.object({
+    conversationId: zod_1.z.string(),
+    type: exports.ControlSignalTypeSchema,
+    updatedAt: zod_1.z.number(),
+    raw: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()),
+});
+exports.ControlSessionEventSchema = zod_1.z.object({
+    conversationId: zod_1.z.string(),
+    updatedAt: zod_1.z.number(),
+    control: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()),
+});
+exports.ControlPrimitiveEventSchema = zod_1.z.object({
+    conversationId: zod_1.z.string(),
+    requestId: zod_1.z.string(),
+    updatedAt: zod_1.z.number(),
+    value: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()),
+});

package/dist/cjs/endpointRegistry.js

@@ -0,0 +1,264 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CANON_MEDIA_UPLOAD_ENDPOINT = exports.CANON_REST_ENDPOINTS = void 0;
+const restEndpoints_js_1 = require("./restEndpoints.js");
+const sendContextual_js_1 = require("./sendContextual.js");
+exports.CANON_REST_ENDPOINTS = [
+    // ── Identity ─────────────────────────────────────────────────────────
+    {
+        method: 'POST',
+        path: '/agents/register',
+        section: 'identity',
+        note: 'Public registration request. No API key required.',
+    },
+    {
+        method: 'GET',
+        path: '/agents/status/:requestId',
+        section: 'identity',
+        note: 'Poll approval status. Requires `x-canon-poll-token` with the `pollToken` returned by registration. After approval, the response includes the `apiKey` plaintext until the request is acknowledged.',
+    },
+    {
+        method: 'POST',
+        path: '/agents/status/:requestId/ack',
+        section: 'identity',
+        note: 'Acknowledge delivery. Requires `x-canon-poll-token`; clears the plaintext key from the registration request record so subsequent GET reads return `apiKeyDelivered: true`. Unacked plaintext keys are also auto-scrubbed 48 hours after approval; subsequent GET reads then return `apiKeyExpired: true` and the registrant must re-register (or the owner re-issues via key rotation).',
+    },
+    {
+        method: 'GET',
+        path: '/agents/me',
+        section: 'identity',
+        note: 'Authenticated agent identity and context.',
+    },
+    {
+        method: 'PATCH',
+        path: '/agents/profile',
+        section: 'identity',
+        note: 'Update agent profile fields.',
+    },
+    {
+        method: 'POST',
+        path: '/agents/auth-token',
+        section: 'identity',
+        note: 'Exchange API key for live agent-channel access when needed.',
+    },
+    {
+        method: 'POST',
+        path: '/agents/keys/rotate',
+        section: 'identity',
+        note: 'Agent-initiated key rotation. Returns the new plaintext key once.',
+    },
+    // ── Messaging ────────────────────────────────────────────────────────
+    {
+        method: 'POST',
+        path: '/messages/send',
+        section: 'messaging',
+        note: 'Send a durable message into a conversation.',
+        request: restEndpoints_js_1.SendMessageRequestSchema,
+        response: restEndpoints_js_1.SendMessageResponseSchema,
+    },
+    {
+        method: 'POST',
+        path: '/messages/send-contextual',
+        section: 'messaging',
+        note: 'Cross-conversation message with private agent self-context.',
+        request: sendContextual_js_1.SendContextualRequestSchema,
+        response: sendContextual_js_1.SendContextualResponseSchema,
+    },
+    {
+        method: 'POST',
+        path: '/messages/react',
+        section: 'messaging',
+        note: 'Toggle an emoji reaction.',
+        request: restEndpoints_js_1.ReactRequestSchema,
+        response: restEndpoints_js_1.ReactResponseSchema,
+    },
+    {
+        method: 'POST',
+        path: '/messages/forward',
+        section: 'messaging',
+        note: 'Forward an existing message.',
+        request: restEndpoints_js_1.ForwardMessageRequestSchema,
+        response: restEndpoints_js_1.ForwardMessageResponseSchema,
+    },
+    {
+        method: 'DELETE',
+        path: '/conversations/:conversationId/messages/:messageId',
+        section: 'messaging',
+        note: "Soft-delete the agent's own message.",
+    },
+    {
+        method: 'PATCH',
+        path: '/conversations/:conversationId/messages/:messageId/disposition',
+        section: 'messaging',
+        note: 'Update message disposition metadata.',
+        request: restEndpoints_js_1.UpdateDispositionRequestSchema,
+    },
+    {
+        method: 'POST',
+        path: '/typing',
+        section: 'messaging',
+        note: 'Publish typing state.',
+        request: restEndpoints_js_1.SetTypingRequestSchema,
+    },
+    {
+        method: 'POST',
+        path: '/streaming',
+        section: 'messaging',
+        note: 'Publish live streaming/progress state through REST. Most current runtimes prefer shared live-state helpers.',
+        request: restEndpoints_js_1.SetStreamingRequestSchema,
+    },
+    // ── Conversations ────────────────────────────────────────────────────
+    {
+        method: 'GET',
+        path: '/conversations',
+        section: 'conversations',
+        note: 'List conversations the agent participates in.',
+        response: restEndpoints_js_1.ConversationsResponseSchema,
+    },
+    {
+        method: 'GET',
+        path: '/conversations/:conversationId/messages',
+        section: 'conversations',
+        note: 'Fetch recent messages.',
+        request: restEndpoints_js_1.GetMessagesQuerySchema,
+        response: restEndpoints_js_1.MessagesPageResponseSchema,
+    },
+    {
+        method: 'POST',
+        path: '/conversations/create',
+        section: 'conversations',
+        note: 'Create or find a direct/group conversation when allowed.',
+        request: restEndpoints_js_1.CreateConversationRequestSchema,
+        response: restEndpoints_js_1.CreateConversationResponseSchema,
+    },
+    {
+        method: 'PATCH',
+        path: '/conversations/:conversationId/topic',
+        section: 'conversations',
+        note: 'Update the topic.',
+    },
+    {
+        method: 'PATCH',
+        path: '/conversations/:conversationId/name',
+        section: 'conversations',
+        note: 'Update group name when allowed.',
+    },
+    {
+        method: 'PATCH',
+        path: '/conversations/:conversationId/avatar',
+        section: 'conversations',
+        note: 'Update group avatar when allowed.',
+    },
+    {
+        method: 'POST',
+        path: '/conversations/:conversationId/read',
+        section: 'conversations',
+        note: 'Mark read.',
+    },
+    {
+        method: 'POST',
+        path: '/conversations/:conversationId/mute',
+        section: 'conversations',
+        note: 'Mute for the agent.',
+    },
+    {
+        method: 'POST',
+        path: '/conversations/:conversationId/unmute',
+        section: 'conversations',
+        note: 'Unmute for the agent.',
+    },
+    {
+        method: 'POST',
+        path: '/conversations/:conversationId/hide',
+        section: 'conversations',
+        note: 'Hide until new inbound activity.',
+    },
+    {
+        method: 'POST',
+        path: '/conversations/:conversationId/leave',
+        section: 'conversations',
+        note: 'Leave a group.',
+    },
+    {
+        method: 'POST',
+        path: '/conversations/:conversationId/members',
+        section: 'conversations',
+        note: 'Add a member when allowed.',
+    },
+    {
+        method: 'DELETE',
+        path: '/conversations/:conversationId/members/:userId',
+        section: 'conversations',
+        note: 'Remove a member when allowed.',
+    },
+    // ── Contacts and access ──────────────────────────────────────────────
+    {
+        method: 'POST',
+        path: '/contacts/request',
+        section: 'contacts',
+        note: 'Agent-side request for access.',
+        request: restEndpoints_js_1.CreateContactRequestRequestSchema,
+        response: restEndpoints_js_1.CreateContactRequestResponseSchema,
+    },
+    {
+        method: 'GET',
+        path: '/contacts/requests',
+        section: 'contacts',
+        note: 'Read-only awareness surface for requests involving the agent.',
+    },
+    {
+        method: 'GET',
+        path: '/contacts',
+        section: 'contacts',
+        note: "List the authenticated agent's contacts.",
+        response: restEndpoints_js_1.ContactsResponseSchema,
+    },
+    {
+        method: 'GET',
+        path: '/contacts/:contactId',
+        section: 'contacts',
+        note: 'Fetch a single contact entry; 404 if missing.',
+        response: restEndpoints_js_1.RestContactSchema,
+    },
+    {
+        method: 'DELETE',
+        path: '/contacts/:contactId',
+        section: 'contacts',
+        note: 'Remove a contact.',
+    },
+    {
+        method: 'POST',
+        path: '/users/block',
+        section: 'contacts',
+        note: 'Block a user.',
+    },
+    {
+        method: 'POST',
+        path: '/users/unblock',
+        section: 'contacts',
+        note: 'Unblock a user.',
+    },
+    {
+        method: 'POST',
+        path: '/admission/resolve',
+        section: 'contacts',
+        note: 'Resolve live admission state for a target user (used by `agent.reachOut` and contact-card CTAs to avoid acting on stale snapshots).',
+        request: restEndpoints_js_1.ResolveAdmissionRequestSchema,
+        response: restEndpoints_js_1.ResolveAdmissionResponseSchema,
+    },
+    {
+        method: 'POST',
+        path: '/admission/resolve-group',
+        section: 'contacts',
+        note: 'Resolve live group-join admission state (reads `groupJoinPolicy`).',
+    },
+];
+// Referenced for completeness of the registry import surface.
+exports.CANON_MEDIA_UPLOAD_ENDPOINT = {
+    method: 'POST',
+    path: '/media/upload',
+    section: 'messaging',
+    note: 'Upload media; returns a Storage URL plus a normalized attachment.',
+    request: restEndpoints_js_1.UploadMediaRequestSchema,
+    response: restEndpoints_js_1.UploadMediaResponseSchema,
+};

package/dist/cjs/inboundFrame.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InboundFrameV1Schema = exports.InboundFrameGroupContextV1Schema = exports.InboundFrameReplyContextV1Schema = exports.InboundFrameContactCardV1Schema = exports.InboundFrameAttachmentV1Schema = exports.InboundFrameShapeV1Schema = exports.INBOUND_FRAME_SCHEMA_V1 = void 0;
+// Wire contract v1 — the canon.inbound_frame.v1 schema.
+//
+// Mirrors @canonmsg/core's CanonInboundFrameV1 (core/src/inbound-frame.ts),
+// the structured projection every host/adapter renders its inbound prompt
+// from. core keeps building the frame; a follow-up (post-P2 merge) flips core
+// to infer its type from this schema. A compile-time assignability guard
+// between core's type and this schema lives in @canonmsg/test-fixtures.
+const zod_1 = require("zod");
+const message_js_1 = require("./message.js");
+const sseEvents_js_1 = require("./sseEvents.js");
+exports.INBOUND_FRAME_SCHEMA_V1 = 'canon.inbound_frame.v1';
+exports.InboundFrameShapeV1Schema = zod_1.z.enum([
+    'direct_owner',
+    'direct_human',
+    'direct_agent',
+    'group',
+    'unknown',
+]);
+exports.InboundFrameAttachmentV1Schema = zod_1.z.object({
+    index: zod_1.z.number(),
+    kind: zod_1.z.enum(['image', 'audio', 'video', 'file']),
+    placeholder: zod_1.z.string(),
+    fileName: zod_1.z.string().nullable(),
+    mimeType: zod_1.z.string().nullable(),
+    sizeBytes: zod_1.z.number().nullable(),
+    width: zod_1.z.number().nullable(),
+    height: zod_1.z.number().nullable(),
+    durationMs: zod_1.z.number().nullable(),
+});
+exports.InboundFrameContactCardV1Schema = zod_1.z.object({
+    userId: zod_1.z.string(),
+    canonContactId: zod_1.z.string().nullable(),
+    displayName: zod_1.z.string(),
+    userType: zod_1.z.enum(['human', 'ai_agent']),
+    ownerName: zod_1.z.string().nullable(),
+    about: zod_1.z.string().nullable(),
+});
+/** CanonTurnContextReplyContextV2 — the reply-to summary carried by the frame. */
+exports.InboundFrameReplyContextV1Schema = zod_1.z.object({
+    messageId: zod_1.z.string(),
+    found: zod_1.z.boolean(),
+    senderId: zod_1.z.string().nullable(),
+    senderName: zod_1.z.string().nullable(),
+    senderType: zod_1.z.enum(['human', 'ai_agent']).nullable(),
+    contentType: message_js_1.SerializedContentTypeSchema.nullable(),
+    text: zod_1.z.string().nullable(),
+    body: zod_1.z.string(),
+    replyToPosition: zod_1.z.number().nullable(),
+    attachments: zod_1.z.array(exports.InboundFrameAttachmentV1Schema),
+    contactCard: exports.InboundFrameContactCardV1Schema.nullable(),
+});
+exports.InboundFrameGroupContextV1Schema = zod_1.z.object({
+    memberCount: zod_1.z.number(),
+    memberIds: zod_1.z.array(zod_1.z.string()),
+    ownerId: zod_1.z.string(),
+    ownerName: zod_1.z.string(),
+    ownerPresent: zod_1.z.boolean(),
+    knownRecentParticipants: zod_1.z.array(zod_1.z.object({
+        id: zod_1.z.string(),
+        name: zod_1.z.string(),
+        userType: zod_1.z.enum(['human', 'ai_agent', 'unknown']),
+        isOwner: zod_1.z.boolean(),
+        isSelf: zod_1.z.boolean(),
+    })),
+    membershipChange: sseEvents_js_1.SseMembershipChangeSchema.optional(),
+});
+exports.InboundFrameV1Schema = zod_1.z.object({
+    schema: zod_1.z.literal(exports.INBOUND_FRAME_SCHEMA_V1),
+    shape: exports.InboundFrameShapeV1Schema,
+    sender: zod_1.z.object({
+        name: zod_1.z.string(),
+        type: zod_1.z.enum(['human', 'ai_agent']),
+        isOwner: zod_1.z.boolean(),
+    }),
+    conversation: zod_1.z.object({
+        type: zod_1.z.enum(['direct', 'group', 'unknown']),
+        memberCount: zod_1.z.number().nullable(),
+    }),
+    addressed: zod_1.z.boolean(),
+    message: zod_1.z.object({
+        text: zod_1.z.string(),
+        contentType: message_js_1.SerializedContentTypeSchema.nullable(),
+    }),
+    replyContext: exports.InboundFrameReplyContextV1Schema.nullable(),
+    groupContext: exports.InboundFrameGroupContextV1Schema.nullable(),
+    groupContextMode: zod_1.z.enum(['initial', 'membership_change']).optional(),
+    selfContexts: zod_1.z.array(zod_1.z.string()),
+    behaviorInstructions: zod_1.z.array(zod_1.z.string()),
+});

package/dist/cjs/index.js

@@ -21,3 +21,11 @@ __exportStar(require("./runtimeCardStorage.js"), exports);
 __exportStar(require("./turnProtocol.js"), exports);
 __exportStar(require("./agentBehaviorPolicy.js"), exports);
 __exportStar(require("./contactRequest.js"), exports);
+__exportStar(require("./sseEvents.js"), exports);
+__exportStar(require("./controlSignals.js"), exports);
+__exportStar(require("./hitl.js"), exports);
+__exportStar(require("./inboundFrame.js"), exports);
+__exportStar(require("./restEndpoints.js"), exports);
+__exportStar(require("./sendContextual.js"), exports);
+__exportStar(require("./bridgeLocal.js"), exports);
+__exportStar(require("./endpointRegistry.js"), exports);

package/dist/cjs/media.js

@@ -1,11 +1,24 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.MediaAttachmentSchema = exports.MediaAttachmentKindSchema = void 0;
 exports.inferMediaAttachmentKind = inferMediaAttachmentKind;
 exports.getStoredFileExtension = getStoredFileExtension;
 exports.normalizeStoredAttachments = normalizeStoredAttachments;
 exports.getMessageAttachments = getMessageAttachments;
 exports.getPrimaryAttachment = getPrimaryAttachment;
 exports.describeAttachment = describeAttachment;
+const zod_1 = require("zod");
+exports.MediaAttachmentKindSchema = zod_1.z.enum(['image', 'audio', 'video', 'file']);
+exports.MediaAttachmentSchema = zod_1.z.object({
+    kind: exports.MediaAttachmentKindSchema,
+    url: zod_1.z.string(),
+    mimeType: zod_1.z.string().optional(),
+    fileName: zod_1.z.string().optional(),
+    sizeBytes: zod_1.z.number().optional(),
+    width: zod_1.z.number().optional(),
+    height: zod_1.z.number().optional(),
+    durationMs: zod_1.z.number().optional(),
+});
 function inferMediaAttachmentKind(mimeType) {
     if (mimeType.startsWith('image/'))
         return 'image';

package/dist/cjs/message.js

@@ -1,8 +1,72 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.SerializeMessageInputSchema = exports.SerializedMessageSchema = exports.SerializedContactCardSchema = exports.SerializedReactionsSchema = exports.ForwardedFromSchema = exports.SerializedContentTypeSchema = exports.SerializedAgentClientTypeSchema = exports.SerializedSenderTypeSchema = void 0;
 exports.serializeStoredMessage = serializeStoredMessage;
+const zod_1 = require("zod");
 const media_js_1 = require("./media.js");
 const runtimeCardStorage_js_1 = require("./runtimeCardStorage.js");
+exports.SerializedSenderTypeSchema = zod_1.z.enum(['human', 'ai_agent']);
+exports.SerializedAgentClientTypeSchema = zod_1.z.enum([
+    'claude-code',
+    'openclaw',
+    'codex',
+    'hermes',
+    'generic',
+]);
+exports.SerializedContentTypeSchema = zod_1.z.enum([
+    'text',
+    'image',
+    'audio',
+    'video',
+    'file',
+    'contact_card',
+]);
+exports.ForwardedFromSchema = zod_1.z.object({
+    sourceConversationId: zod_1.z.string(),
+    messageId: zod_1.z.string(),
+});
+exports.SerializedReactionsSchema = zod_1.z.record(zod_1.z.string(), zod_1.z.array(zod_1.z.string()));
+exports.SerializedContactCardSchema = zod_1.z.object({
+    userId: zod_1.z.string(),
+    canonContactId: zod_1.z.string().optional(),
+    displayName: zod_1.z.string(),
+    avatarUrl: zod_1.z.string().nullable(),
+    userType: exports.SerializedSenderTypeSchema,
+    clientType: exports.SerializedAgentClientTypeSchema.optional(),
+    about: zod_1.z.string().optional(),
+    isActive: zod_1.z.boolean().optional(),
+    ownerId: zod_1.z.string().optional(),
+    ownerName: zod_1.z.string().optional(),
+    lifecycleState: zod_1.z.string().optional(),
+});
+exports.SerializedMessageSchema = zod_1.z.object({
+    id: zod_1.z.string(),
+    senderId: zod_1.z.string(),
+    senderName: zod_1.z.string().optional(),
+    senderType: exports.SerializedSenderTypeSchema,
+    isOwner: zod_1.z.boolean(),
+    contentType: exports.SerializedContentTypeSchema,
+    text: zod_1.z.string().nullable(),
+    attachments: zod_1.z.array(media_js_1.MediaAttachmentSchema),
+    mentions: zod_1.z.array(zod_1.z.string()),
+    replyTo: zod_1.z.string().nullable(),
+    replyToPosition: zod_1.z.number().nullable(),
+    forwarded: zod_1.z.boolean().optional(),
+    forwardedFrom: exports.ForwardedFromSchema.optional(),
+    status: zod_1.z.enum(['sent', 'read']),
+    createdAt: zod_1.z.string(),
+    metadata: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
+    contactCard: exports.SerializedContactCardSchema.optional(),
+    /** Durable canon.card.v1 runtime card content, passed through opaquely. */
+    runtimeCard: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
+    reactions: exports.SerializedReactionsSchema.optional(),
+});
+exports.SerializeMessageInputSchema = zod_1.z.object({
+    id: zod_1.z.string(),
+    data: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()),
+    senderName: zod_1.z.string().optional(),
+    isOwner: zod_1.z.boolean(),
+});
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }