@canonmsg/backend-contracts 1.9.0 → 2.0.0

package/dist/hitl.js

@@ -1,168 +0,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).
-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

@@ -1,229 +0,0 @@
-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

@@ -1,89 +0,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.
-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()),
-});