@canonmsg/backend-contracts 1.7.0 → 1.8.0

package/dist/hitl.js

@@ -0,0 +1,168 @@
+// 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).
+import { z } from 'zod';
+import { RuntimeCardFieldChoiceSchema } from './runtimeCardFields.js';
+export const HitlRequestKindSchema = z.enum(['approval', 'input', 'card']);
+export const HitlResolutionStatusSchema = z.enum(['submitted', 'cancelled', 'timeout']);
+// ── Approval records ───────────────────────────────────────────────────
+export const HitlApprovalRiskSchema = z.enum(['low', 'normal', 'high', 'destructive']);
+export const HitlApprovalCategorySchema = z.enum([
+    'command',
+    'file',
+    'network',
+    'browser',
+    'mcp',
+    'plugin',
+    'canon',
+    'tool',
+]);
+export const HitlApprovalDetailSchema = z.object({
+    label: z.string(),
+    value: z.string(),
+    monospace: z.boolean().optional(),
+});
+export const HitlSessionRuleSchema = z.object({
+    type: z.enum(['approve-all', 'approve-tool', 'deny-tool']),
+    toolPattern: z.string().optional(),
+    expiresAt: z.string().nullable().optional(),
+});
+export const HitlApprovalRequestRecordSchema = z.looseObject({
+    type: z.literal('approval_request'),
+    approvalId: z.string(),
+    responseUserId: z.string().optional(),
+    toolName: z.string(),
+    /** Pre-computed, redacted summary — raw tool input is never stored. */
+    toolSummary: z.string(),
+    category: HitlApprovalCategorySchema.optional(),
+    risk: HitlApprovalRiskSchema.optional(),
+    riskLevel: z.enum(['normal', 'destructive']).optional(),
+    runtimeId: z.string().optional(),
+    turnId: z.string().optional(),
+    /** Native runtime correlation handles — opaque pass-through. */
+    native: z.record(z.string(), z.unknown()).optional(),
+    details: z.array(HitlApprovalDetailSchema).optional(),
+    /** File-change preview (CanonUnifiedDiff) — opaque pass-through. */
+    diff: z.record(z.string(), z.unknown()).optional(),
+    expiresAt: z.string(),
+});
+export const HitlApprovalReplyRecordSchema = z.looseObject({
+    type: z.literal('approval_reply'),
+    approvalId: z.string(),
+    decision: z.enum(['allow', 'deny']),
+    sessionRule: HitlSessionRuleSchema.optional(),
+});
+export const HitlApprovalOutcomeRecordSchema = z.looseObject({
+    type: z.literal('approval_outcome'),
+    approvalId: z.string().optional(),
+    decision: z.enum(['allow', 'deny']).optional(),
+    reason: z.enum(['replied', 'timeout', 'session-rule']).optional(),
+});
+// ── Input records ──────────────────────────────────────────────────────
+export const HitlInputKindSchema = z.enum(['clarify', 'sudo', 'secret']);
+export const HitlInputQuestionSchema = z.object({
+    id: z.string(),
+    question: z.string(),
+    header: z.string().optional(),
+    choices: z.array(RuntimeCardFieldChoiceSchema).optional(),
+    allowOther: z.boolean().optional(),
+    isSecret: z.boolean().optional(),
+    multiSelect: z.boolean().optional(),
+});
+/** questionId → selected/typed answers. */
+export const HitlInputAnswersSchema = z.record(z.string(), z.object({ answers: z.array(z.string()) }));
+export const HitlInputRequestRecordSchema = z.looseObject({
+    type: z.literal('runtime_input_request'),
+    inputId: z.string(),
+    responseUserId: z.string().optional(),
+    kind: HitlInputKindSchema,
+    prompt: z.string(),
+    title: z.string().optional(),
+    choices: z.array(RuntimeCardFieldChoiceSchema).optional(),
+    questions: z.array(HitlInputQuestionSchema).optional(),
+    secretName: z.string().optional(),
+    native: z.record(z.string(), z.unknown()).optional(),
+    expiresAt: z.string(),
+    sensitive: z.boolean().optional(),
+});
+export const HitlInputReplyRecordSchema = z.looseObject({
+    type: z.literal('runtime_input_reply'),
+    inputId: z.string(),
+    kind: HitlInputKindSchema.optional(),
+    status: z.enum(['submitted', 'cancelled']),
+    answerSummary: z.string().optional(),
+    answersSummary: z.string().optional(),
+    sensitive: z.boolean().optional(),
+});
+export const HitlInputOutcomeRecordSchema = z.looseObject({
+    type: z.literal('runtime_input_outcome'),
+    inputId: z.string(),
+    kind: HitlInputKindSchema.optional(),
+    status: HitlResolutionStatusSchema,
+    reason: z.enum(['submitted', 'cancelled', 'timeout', 'expired', 'interrupted']).optional(),
+});
+// ── Card records ───────────────────────────────────────────────────────
+export const HitlCardRequestRecordSchema = z.looseObject({
+    type: z.literal('runtime_card_request'),
+    cardId: z.string(),
+    cardKind: z.string(),
+    schemaVersion: z.literal('canon.card.v1'),
+    fallbackText: z.string(),
+    responseUserId: z.string().optional(),
+    expiresAt: z.string(),
+    runtimeId: z.string().optional(),
+    turnId: z.string().optional(),
+    native: z.record(z.string(), z.unknown()).optional(),
+    /** True when the card carries an actions block (agent waits for a response). */
+    interactive: z.boolean().optional(),
+    /** RuntimeCardPreview — opaque pass-through. */
+    cardPreview: z.record(z.string(), z.unknown()),
+    turnSemantics: z.literal('control'),
+    replyBehavior: z.literal('suppress_auto_reply'),
+});
+export const HitlCardReplyRecordSchema = z.looseObject({
+    type: z.literal('runtime_card_reply'),
+    cardId: z.string(),
+    status: z.enum(['submitted', 'cancelled']),
+    actionId: z.string().optional(),
+    answerSummary: z.string().optional(),
+    sensitive: z.boolean().optional(),
+    turnSemantics: z.literal('control'),
+    replyBehavior: z.literal('suppress_auto_reply'),
+});
+export const HitlCardOutcomeRecordSchema = z.looseObject({
+    type: z.literal('runtime_card_outcome'),
+    cardId: z.string(),
+    status: HitlResolutionStatusSchema,
+    reason: z.enum(['submitted', 'cancelled', 'timeout', 'expired', 'interrupted']).optional(),
+    turnSemantics: z.literal('control'),
+    replyBehavior: z.literal('suppress_auto_reply'),
+});
+// ── Unified bridge-level records (bridge-local-api §B7/§C6) ────────────
+/** Immediate result of requestApproval/requestInput/requestCard. */
+export const HitlRequestAcceptedSchema = z.object({
+    requestId: z.string(),
+    expiresAt: z.string(),
+});
+/** `onHitlResolved` — matches an earlier requestId. */
+export const HitlResolutionSchema = z.object({
+    requestId: z.string(),
+    kind: HitlRequestKindSchema.optional(),
+    status: HitlResolutionStatusSchema,
+    /** Kind-specific answer payload (decision / answers / card action values). */
+    answer: z.record(z.string(), z.unknown()).optional(),
+});
+/** `onHitlPending` — replayed on reconnect for still-open requests. */
+export const HitlPendingSchema = z.object({
+    requestId: z.string(),
+    kind: HitlRequestKindSchema,
+    conversationId: z.string(),
+    expiresAt: z.string(),
+});

package/dist/inboundFrame.d.ts

@@ -0,0 +1,229 @@
+import { z } from 'zod';
+export declare const INBOUND_FRAME_SCHEMA_V1: "canon.inbound_frame.v1";
+export declare const InboundFrameShapeV1Schema: z.ZodEnum<{
+    unknown: "unknown";
+    group: "group";
+    direct_owner: "direct_owner";
+    direct_human: "direct_human";
+    direct_agent: "direct_agent";
+}>;
+export type InboundFrameShapeV1 = z.infer<typeof InboundFrameShapeV1Schema>;
+export declare const InboundFrameAttachmentV1Schema: z.ZodObject<{
+    index: z.ZodNumber;
+    kind: z.ZodEnum<{
+        file: "file";
+        image: "image";
+        audio: "audio";
+        video: "video";
+    }>;
+    placeholder: z.ZodString;
+    fileName: z.ZodNullable<z.ZodString>;
+    mimeType: z.ZodNullable<z.ZodString>;
+    sizeBytes: z.ZodNullable<z.ZodNumber>;
+    width: z.ZodNullable<z.ZodNumber>;
+    height: z.ZodNullable<z.ZodNumber>;
+    durationMs: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+export type InboundFrameAttachmentV1 = z.infer<typeof InboundFrameAttachmentV1Schema>;
+export declare const InboundFrameContactCardV1Schema: z.ZodObject<{
+    userId: z.ZodString;
+    canonContactId: z.ZodNullable<z.ZodString>;
+    displayName: z.ZodString;
+    userType: z.ZodEnum<{
+        human: "human";
+        ai_agent: "ai_agent";
+    }>;
+    ownerName: z.ZodNullable<z.ZodString>;
+    about: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type InboundFrameContactCardV1 = z.infer<typeof InboundFrameContactCardV1Schema>;
+/** CanonTurnContextReplyContextV2 — the reply-to summary carried by the frame. */
+export declare const InboundFrameReplyContextV1Schema: z.ZodObject<{
+    messageId: z.ZodString;
+    found: z.ZodBoolean;
+    senderId: z.ZodNullable<z.ZodString>;
+    senderName: z.ZodNullable<z.ZodString>;
+    senderType: z.ZodNullable<z.ZodEnum<{
+        human: "human";
+        ai_agent: "ai_agent";
+    }>>;
+    contentType: z.ZodNullable<z.ZodEnum<{
+        file: "file";
+        image: "image";
+        audio: "audio";
+        video: "video";
+        text: "text";
+        contact_card: "contact_card";
+    }>>;
+    text: z.ZodNullable<z.ZodString>;
+    body: z.ZodString;
+    replyToPosition: z.ZodNullable<z.ZodNumber>;
+    attachments: z.ZodArray<z.ZodObject<{
+        index: z.ZodNumber;
+        kind: z.ZodEnum<{
+            file: "file";
+            image: "image";
+            audio: "audio";
+            video: "video";
+        }>;
+        placeholder: z.ZodString;
+        fileName: z.ZodNullable<z.ZodString>;
+        mimeType: z.ZodNullable<z.ZodString>;
+        sizeBytes: z.ZodNullable<z.ZodNumber>;
+        width: z.ZodNullable<z.ZodNumber>;
+        height: z.ZodNullable<z.ZodNumber>;
+        durationMs: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>>;
+    contactCard: z.ZodNullable<z.ZodObject<{
+        userId: z.ZodString;
+        canonContactId: z.ZodNullable<z.ZodString>;
+        displayName: z.ZodString;
+        userType: z.ZodEnum<{
+            human: "human";
+            ai_agent: "ai_agent";
+        }>;
+        ownerName: z.ZodNullable<z.ZodString>;
+        about: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type InboundFrameReplyContextV1 = z.infer<typeof InboundFrameReplyContextV1Schema>;
+export declare const InboundFrameGroupContextV1Schema: z.ZodObject<{
+    memberCount: z.ZodNumber;
+    memberIds: z.ZodArray<z.ZodString>;
+    ownerId: z.ZodString;
+    ownerName: z.ZodString;
+    ownerPresent: z.ZodBoolean;
+    knownRecentParticipants: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        userType: z.ZodEnum<{
+            human: "human";
+            ai_agent: "ai_agent";
+            unknown: "unknown";
+        }>;
+        isOwner: z.ZodBoolean;
+        isSelf: z.ZodBoolean;
+    }, z.core.$strip>>;
+    membershipChange: z.ZodOptional<z.ZodObject<{
+        addedMemberIds: z.ZodArray<z.ZodString>;
+        removedMemberIds: z.ZodArray<z.ZodString>;
+        memberCount: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type InboundFrameGroupContextV1 = z.infer<typeof InboundFrameGroupContextV1Schema>;
+export declare const InboundFrameV1Schema: z.ZodObject<{
+    schema: z.ZodLiteral<"canon.inbound_frame.v1">;
+    shape: z.ZodEnum<{
+        unknown: "unknown";
+        group: "group";
+        direct_owner: "direct_owner";
+        direct_human: "direct_human";
+        direct_agent: "direct_agent";
+    }>;
+    sender: z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodEnum<{
+            human: "human";
+            ai_agent: "ai_agent";
+        }>;
+        isOwner: z.ZodBoolean;
+    }, z.core.$strip>;
+    conversation: z.ZodObject<{
+        type: z.ZodEnum<{
+            unknown: "unknown";
+            direct: "direct";
+            group: "group";
+        }>;
+        memberCount: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>;
+    addressed: z.ZodBoolean;
+    message: z.ZodObject<{
+        text: z.ZodString;
+        contentType: z.ZodNullable<z.ZodEnum<{
+            file: "file";
+            image: "image";
+            audio: "audio";
+            video: "video";
+            text: "text";
+            contact_card: "contact_card";
+        }>>;
+    }, z.core.$strip>;
+    replyContext: z.ZodNullable<z.ZodObject<{
+        messageId: z.ZodString;
+        found: z.ZodBoolean;
+        senderId: z.ZodNullable<z.ZodString>;
+        senderName: z.ZodNullable<z.ZodString>;
+        senderType: z.ZodNullable<z.ZodEnum<{
+            human: "human";
+            ai_agent: "ai_agent";
+        }>>;
+        contentType: z.ZodNullable<z.ZodEnum<{
+            file: "file";
+            image: "image";
+            audio: "audio";
+            video: "video";
+            text: "text";
+            contact_card: "contact_card";
+        }>>;
+        text: z.ZodNullable<z.ZodString>;
+        body: z.ZodString;
+        replyToPosition: z.ZodNullable<z.ZodNumber>;
+        attachments: z.ZodArray<z.ZodObject<{
+            index: z.ZodNumber;
+            kind: z.ZodEnum<{
+                file: "file";
+                image: "image";
+                audio: "audio";
+                video: "video";
+            }>;
+            placeholder: z.ZodString;
+            fileName: z.ZodNullable<z.ZodString>;
+            mimeType: z.ZodNullable<z.ZodString>;
+            sizeBytes: z.ZodNullable<z.ZodNumber>;
+            width: z.ZodNullable<z.ZodNumber>;
+            height: z.ZodNullable<z.ZodNumber>;
+            durationMs: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strip>>;
+        contactCard: z.ZodNullable<z.ZodObject<{
+            userId: z.ZodString;
+            canonContactId: z.ZodNullable<z.ZodString>;
+            displayName: z.ZodString;
+            userType: z.ZodEnum<{
+                human: "human";
+                ai_agent: "ai_agent";
+            }>;
+            ownerName: z.ZodNullable<z.ZodString>;
+            about: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    groupContext: z.ZodNullable<z.ZodObject<{
+        memberCount: z.ZodNumber;
+        memberIds: z.ZodArray<z.ZodString>;
+        ownerId: z.ZodString;
+        ownerName: z.ZodString;
+        ownerPresent: z.ZodBoolean;
+        knownRecentParticipants: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            userType: z.ZodEnum<{
+                human: "human";
+                ai_agent: "ai_agent";
+                unknown: "unknown";
+            }>;
+            isOwner: z.ZodBoolean;
+            isSelf: z.ZodBoolean;
+        }, z.core.$strip>>;
+        membershipChange: z.ZodOptional<z.ZodObject<{
+            addedMemberIds: z.ZodArray<z.ZodString>;
+            removedMemberIds: z.ZodArray<z.ZodString>;
+            memberCount: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    groupContextMode: z.ZodOptional<z.ZodEnum<{
+        initial: "initial";
+        membership_change: "membership_change";
+    }>>;
+    selfContexts: z.ZodArray<z.ZodString>;
+    behaviorInstructions: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type InboundFrameV1 = z.infer<typeof InboundFrameV1Schema>;

package/dist/inboundFrame.js

@@ -0,0 +1,89 @@
+// 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.
+import { z } from 'zod';
+import { SerializedContentTypeSchema } from './message.js';
+import { SseMembershipChangeSchema } from './sseEvents.js';
+export const INBOUND_FRAME_SCHEMA_V1 = 'canon.inbound_frame.v1';
+export const InboundFrameShapeV1Schema = z.enum([
+    'direct_owner',
+    'direct_human',
+    'direct_agent',
+    'group',
+    'unknown',
+]);
+export const InboundFrameAttachmentV1Schema = z.object({
+    index: z.number(),
+    kind: z.enum(['image', 'audio', 'video', 'file']),
+    placeholder: z.string(),
+    fileName: z.string().nullable(),
+    mimeType: z.string().nullable(),
+    sizeBytes: z.number().nullable(),
+    width: z.number().nullable(),
+    height: z.number().nullable(),
+    durationMs: z.number().nullable(),
+});
+export const InboundFrameContactCardV1Schema = z.object({
+    userId: z.string(),
+    canonContactId: z.string().nullable(),
+    displayName: z.string(),
+    userType: z.enum(['human', 'ai_agent']),
+    ownerName: z.string().nullable(),
+    about: z.string().nullable(),
+});
+/** CanonTurnContextReplyContextV2 — the reply-to summary carried by the frame. */
+export const InboundFrameReplyContextV1Schema = z.object({
+    messageId: z.string(),
+    found: z.boolean(),
+    senderId: z.string().nullable(),
+    senderName: z.string().nullable(),
+    senderType: z.enum(['human', 'ai_agent']).nullable(),
+    contentType: SerializedContentTypeSchema.nullable(),
+    text: z.string().nullable(),
+    body: z.string(),
+    replyToPosition: z.number().nullable(),
+    attachments: z.array(InboundFrameAttachmentV1Schema),
+    contactCard: InboundFrameContactCardV1Schema.nullable(),
+});
+export const InboundFrameGroupContextV1Schema = z.object({
+    memberCount: z.number(),
+    memberIds: z.array(z.string()),
+    ownerId: z.string(),
+    ownerName: z.string(),
+    ownerPresent: z.boolean(),
+    knownRecentParticipants: z.array(z.object({
+        id: z.string(),
+        name: z.string(),
+        userType: z.enum(['human', 'ai_agent', 'unknown']),
+        isOwner: z.boolean(),
+        isSelf: z.boolean(),
+    })),
+    membershipChange: SseMembershipChangeSchema.optional(),
+});
+export const InboundFrameV1Schema = z.object({
+    schema: z.literal(INBOUND_FRAME_SCHEMA_V1),
+    shape: InboundFrameShapeV1Schema,
+    sender: z.object({
+        name: z.string(),
+        type: z.enum(['human', 'ai_agent']),
+        isOwner: z.boolean(),
+    }),
+    conversation: z.object({
+        type: z.enum(['direct', 'group', 'unknown']),
+        memberCount: z.number().nullable(),
+    }),
+    addressed: z.boolean(),
+    message: z.object({
+        text: z.string(),
+        contentType: SerializedContentTypeSchema.nullable(),
+    }),
+    replyContext: InboundFrameReplyContextV1Schema.nullable(),
+    groupContext: InboundFrameGroupContextV1Schema.nullable(),
+    groupContextMode: z.enum(['initial', 'membership_change']).optional(),
+    selfContexts: z.array(z.string()),
+    behaviorInstructions: z.array(z.string()),
+});

package/dist/index.d.ts

@@ -5,3 +5,11 @@ export * from './runtimeCardStorage.js';
 export * from './turnProtocol.js';
 export * from './agentBehaviorPolicy.js';
 export * from './contactRequest.js';
+export * from './sseEvents.js';
+export * from './controlSignals.js';
+export * from './hitl.js';
+export * from './inboundFrame.js';
+export * from './restEndpoints.js';
+export * from './sendContextual.js';
+export * from './bridgeLocal.js';
+export * from './endpointRegistry.js';

package/dist/index.js

@@ -5,3 +5,11 @@ export * from './runtimeCardStorage.js';
 export * from './turnProtocol.js';
 export * from './agentBehaviorPolicy.js';
 export * from './contactRequest.js';
+export * from './sseEvents.js';
+export * from './controlSignals.js';
+export * from './hitl.js';
+export * from './inboundFrame.js';
+export * from './restEndpoints.js';
+export * from './sendContextual.js';
+export * from './bridgeLocal.js';
+export * from './endpointRegistry.js';

package/dist/media.d.ts

@@ -1,14 +1,27 @@
-export type MediaAttachmentKind = 'image' | 'audio' | 'video' | 'file';
-export interface MediaAttachment {
-    kind: MediaAttachmentKind;
-    url: string;
-    mimeType?: string;
-    fileName?: string;
-    sizeBytes?: number;
-    width?: number;
-    height?: number;
-    durationMs?: number;
-}
+import { z } from 'zod';
+export declare const MediaAttachmentKindSchema: z.ZodEnum<{
+    file: "file";
+    image: "image";
+    audio: "audio";
+    video: "video";
+}>;
+export type MediaAttachmentKind = z.infer<typeof MediaAttachmentKindSchema>;
+export declare const MediaAttachmentSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        file: "file";
+        image: "image";
+        audio: "audio";
+        video: "video";
+    }>;
+    url: z.ZodString;
+    mimeType: z.ZodOptional<z.ZodString>;
+    fileName: z.ZodOptional<z.ZodString>;
+    sizeBytes: z.ZodOptional<z.ZodNumber>;
+    width: z.ZodOptional<z.ZodNumber>;
+    height: z.ZodOptional<z.ZodNumber>;
+    durationMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type MediaAttachment = z.infer<typeof MediaAttachmentSchema>;
 export declare function inferMediaAttachmentKind(mimeType: string): MediaAttachmentKind;
 export declare function getStoredFileExtension(input: {
     mimeType?: string | null;

package/dist/media.js

@@ -1,3 +1,15 @@
+import { z } from 'zod';
+export const MediaAttachmentKindSchema = z.enum(['image', 'audio', 'video', 'file']);
+export const MediaAttachmentSchema = z.object({
+    kind: MediaAttachmentKindSchema,
+    url: z.string(),
+    mimeType: z.string().optional(),
+    fileName: z.string().optional(),
+    sizeBytes: z.number().optional(),
+    width: z.number().optional(),
+    height: z.number().optional(),
+    durationMs: z.number().optional(),
+});
 export function inferMediaAttachmentKind(mimeType) {
     if (mimeType.startsWith('image/'))
         return 'image';