@canonmsg/backend-contracts 1.7.0 → 1.8.0

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/hitl.js

@@ -0,0 +1,171 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HitlPendingSchema = exports.HitlResolutionSchema = exports.HitlRequestAcceptedSchema = exports.HitlCardOutcomeRecordSchema = exports.HitlCardReplyRecordSchema = exports.HitlCardRequestRecordSchema = exports.HitlInputOutcomeRecordSchema = exports.HitlInputReplyRecordSchema = exports.HitlInputRequestRecordSchema = exports.HitlInputAnswersSchema = exports.HitlInputQuestionSchema = exports.HitlInputKindSchema = exports.HitlApprovalOutcomeRecordSchema = exports.HitlApprovalReplyRecordSchema = exports.HitlApprovalRequestRecordSchema = exports.HitlSessionRuleSchema = exports.HitlApprovalDetailSchema = exports.HitlApprovalCategorySchema = exports.HitlApprovalRiskSchema = exports.HitlResolutionStatusSchema = exports.HitlRequestKindSchema = void 0;
+// Wire contract v1 — HITL (human-in-the-loop) request / resolution records.
+//
+// HITL is durable state, not a held request (bridge-local-api.md): the pending
+// request is a persisted record (message metadata + RTDB node with expiresAt),
+// and the resolution arrives later. These schemas ground the three record
+// families as core's hosts publish/consume them today:
+//   approval — approval_request / approval_reply / approval_outcome
+//   input    — runtime_input_request / runtime_input_reply / runtime_input_outcome
+//   card     — runtime_card_request / runtime_card_reply / runtime_card_outcome
+// plus the unified bridge-level resolution record (§C6 onHitlResolved).
+const zod_1 = require("zod");
+const runtimeCardFields_js_1 = require("./runtimeCardFields.js");
+exports.HitlRequestKindSchema = zod_1.z.enum(['approval', 'input', 'card']);
+exports.HitlResolutionStatusSchema = zod_1.z.enum(['submitted', 'cancelled', 'timeout']);
+// ── Approval records ───────────────────────────────────────────────────
+exports.HitlApprovalRiskSchema = zod_1.z.enum(['low', 'normal', 'high', 'destructive']);
+exports.HitlApprovalCategorySchema = zod_1.z.enum([
+    'command',
+    'file',
+    'network',
+    'browser',
+    'mcp',
+    'plugin',
+    'canon',
+    'tool',
+]);
+exports.HitlApprovalDetailSchema = zod_1.z.object({
+    label: zod_1.z.string(),
+    value: zod_1.z.string(),
+    monospace: zod_1.z.boolean().optional(),
+});
+exports.HitlSessionRuleSchema = zod_1.z.object({
+    type: zod_1.z.enum(['approve-all', 'approve-tool', 'deny-tool']),
+    toolPattern: zod_1.z.string().optional(),
+    expiresAt: zod_1.z.string().nullable().optional(),
+});
+exports.HitlApprovalRequestRecordSchema = zod_1.z.looseObject({
+    type: zod_1.z.literal('approval_request'),
+    approvalId: zod_1.z.string(),
+    responseUserId: zod_1.z.string().optional(),
+    toolName: zod_1.z.string(),
+    /** Pre-computed, redacted summary — raw tool input is never stored. */
+    toolSummary: zod_1.z.string(),
+    category: exports.HitlApprovalCategorySchema.optional(),
+    risk: exports.HitlApprovalRiskSchema.optional(),
+    riskLevel: zod_1.z.enum(['normal', 'destructive']).optional(),
+    runtimeId: zod_1.z.string().optional(),
+    turnId: zod_1.z.string().optional(),
+    /** Native runtime correlation handles — opaque pass-through. */
+    native: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
+    details: zod_1.z.array(exports.HitlApprovalDetailSchema).optional(),
+    /** File-change preview (CanonUnifiedDiff) — opaque pass-through. */
+    diff: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
+    expiresAt: zod_1.z.string(),
+});
+exports.HitlApprovalReplyRecordSchema = zod_1.z.looseObject({
+    type: zod_1.z.literal('approval_reply'),
+    approvalId: zod_1.z.string(),
+    decision: zod_1.z.enum(['allow', 'deny']),
+    sessionRule: exports.HitlSessionRuleSchema.optional(),
+});
+exports.HitlApprovalOutcomeRecordSchema = zod_1.z.looseObject({
+    type: zod_1.z.literal('approval_outcome'),
+    approvalId: zod_1.z.string().optional(),
+    decision: zod_1.z.enum(['allow', 'deny']).optional(),
+    reason: zod_1.z.enum(['replied', 'timeout', 'session-rule']).optional(),
+});
+// ── Input records ──────────────────────────────────────────────────────
+exports.HitlInputKindSchema = zod_1.z.enum(['clarify', 'sudo', 'secret']);
+exports.HitlInputQuestionSchema = zod_1.z.object({
+    id: zod_1.z.string(),
+    question: zod_1.z.string(),
+    header: zod_1.z.string().optional(),
+    choices: zod_1.z.array(runtimeCardFields_js_1.RuntimeCardFieldChoiceSchema).optional(),
+    allowOther: zod_1.z.boolean().optional(),
+    isSecret: zod_1.z.boolean().optional(),
+    multiSelect: zod_1.z.boolean().optional(),
+});
+/** questionId → selected/typed answers. */
+exports.HitlInputAnswersSchema = zod_1.z.record(zod_1.z.string(), zod_1.z.object({ answers: zod_1.z.array(zod_1.z.string()) }));
+exports.HitlInputRequestRecordSchema = zod_1.z.looseObject({
+    type: zod_1.z.literal('runtime_input_request'),
+    inputId: zod_1.z.string(),
+    responseUserId: zod_1.z.string().optional(),
+    kind: exports.HitlInputKindSchema,
+    prompt: zod_1.z.string(),
+    title: zod_1.z.string().optional(),
+    choices: zod_1.z.array(runtimeCardFields_js_1.RuntimeCardFieldChoiceSchema).optional(),
+    questions: zod_1.z.array(exports.HitlInputQuestionSchema).optional(),
+    secretName: zod_1.z.string().optional(),
+    native: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
+    expiresAt: zod_1.z.string(),
+    sensitive: zod_1.z.boolean().optional(),
+});
+exports.HitlInputReplyRecordSchema = zod_1.z.looseObject({
+    type: zod_1.z.literal('runtime_input_reply'),
+    inputId: zod_1.z.string(),
+    kind: exports.HitlInputKindSchema.optional(),
+    status: zod_1.z.enum(['submitted', 'cancelled']),
+    answerSummary: zod_1.z.string().optional(),
+    answersSummary: zod_1.z.string().optional(),
+    sensitive: zod_1.z.boolean().optional(),
+});
+exports.HitlInputOutcomeRecordSchema = zod_1.z.looseObject({
+    type: zod_1.z.literal('runtime_input_outcome'),
+    inputId: zod_1.z.string(),
+    kind: exports.HitlInputKindSchema.optional(),
+    status: exports.HitlResolutionStatusSchema,
+    reason: zod_1.z.enum(['submitted', 'cancelled', 'timeout', 'expired', 'interrupted']).optional(),
+});
+// ── Card records ───────────────────────────────────────────────────────
+exports.HitlCardRequestRecordSchema = zod_1.z.looseObject({
+    type: zod_1.z.literal('runtime_card_request'),
+    cardId: zod_1.z.string(),
+    cardKind: zod_1.z.string(),
+    schemaVersion: zod_1.z.literal('canon.card.v1'),
+    fallbackText: zod_1.z.string(),
+    responseUserId: zod_1.z.string().optional(),
+    expiresAt: zod_1.z.string(),
+    runtimeId: zod_1.z.string().optional(),
+    turnId: zod_1.z.string().optional(),
+    native: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
+    /** True when the card carries an actions block (agent waits for a response). */
+    interactive: zod_1.z.boolean().optional(),
+    /** RuntimeCardPreview — opaque pass-through. */
+    cardPreview: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()),
+    turnSemantics: zod_1.z.literal('control'),
+    replyBehavior: zod_1.z.literal('suppress_auto_reply'),
+});
+exports.HitlCardReplyRecordSchema = zod_1.z.looseObject({
+    type: zod_1.z.literal('runtime_card_reply'),
+    cardId: zod_1.z.string(),
+    status: zod_1.z.enum(['submitted', 'cancelled']),
+    actionId: zod_1.z.string().optional(),
+    answerSummary: zod_1.z.string().optional(),
+    sensitive: zod_1.z.boolean().optional(),
+    turnSemantics: zod_1.z.literal('control'),
+    replyBehavior: zod_1.z.literal('suppress_auto_reply'),
+});
+exports.HitlCardOutcomeRecordSchema = zod_1.z.looseObject({
+    type: zod_1.z.literal('runtime_card_outcome'),
+    cardId: zod_1.z.string(),
+    status: exports.HitlResolutionStatusSchema,
+    reason: zod_1.z.enum(['submitted', 'cancelled', 'timeout', 'expired', 'interrupted']).optional(),
+    turnSemantics: zod_1.z.literal('control'),
+    replyBehavior: zod_1.z.literal('suppress_auto_reply'),
+});
+// ── Unified bridge-level records (bridge-local-api §B7/§C6) ────────────
+/** Immediate result of requestApproval/requestInput/requestCard. */
+exports.HitlRequestAcceptedSchema = zod_1.z.object({
+    requestId: zod_1.z.string(),
+    expiresAt: zod_1.z.string(),
+});
+/** `onHitlResolved` — matches an earlier requestId. */
+exports.HitlResolutionSchema = zod_1.z.object({
+    requestId: zod_1.z.string(),
+    kind: exports.HitlRequestKindSchema.optional(),
+    status: exports.HitlResolutionStatusSchema,
+    /** Kind-specific answer payload (decision / answers / card action values). */
+    answer: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
+});
+/** `onHitlPending` — replayed on reconnect for still-open requests. */
+exports.HitlPendingSchema = zod_1.z.object({
+    requestId: zod_1.z.string(),
+    kind: exports.HitlRequestKindSchema,
+    conversationId: zod_1.z.string(),
+    expiresAt: zod_1.z.string(),
+});

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';