@canonmsg/agent-sdk 11.2.0 → 12.0.0

package/dist/internal/backend-contracts/preparedContent.d.ts

@@ -0,0 +1,54 @@
+import { type EndpointPreconditions } from './endpoint.js';
+export declare const PREPARED_CONTENT_VERSION: 1;
+export declare const PREPARED_JSON_CODEC: "canon.json.v1";
+/** Reviewed public routing context. Authentication and installation/operation
+ * identity stay in the containing endpoint request, never in this payload. */
+export interface PreparedContentContext {
+    readonly action: string;
+    readonly conversationId?: string;
+    readonly messageId?: string;
+}
+export interface PreparedBlobDependency {
+    /** Logical identity survives replacement of a transport upload session. */
+    readonly id: string;
+    readonly index: number;
+}
+export interface PreparedContentExpected {
+    readonly installationGeneration: number;
+    readonly protocolRevision: number;
+    readonly admission?: Readonly<EndpointPreconditions>;
+}
+export interface PreparedContent {
+    readonly version: typeof PREPARED_CONTENT_VERSION;
+    readonly context: PreparedContentContext;
+    readonly codec: typeof PREPARED_JSON_CODEC;
+    /** Exact immutable bytes represented as UTF-8 JSON; transport retries reuse it. */
+    readonly payload: string;
+    readonly blobs: readonly PreparedBlobDependency[];
+    readonly expected: PreparedContentExpected;
+}
+export interface PreparedJsonInput {
+    context: PreparedContentContext;
+    body: Record<string, unknown>;
+    envelope?: Record<string, unknown>;
+    blobs?: readonly PreparedBlobDependency[];
+    expected: PreparedContentExpected;
+}
+export interface DecodedPreparedJsonContent {
+    body: Record<string, unknown>;
+    envelope?: Record<string, unknown>;
+}
+export declare class PreparedContentError extends Error {
+    readonly code: 'INVALID_PREPARED_CONTENT' | 'UNSUPPORTED_PREPARED_CONTENT_VERSION' | 'UNSUPPORTED_PREPARED_CONTENT_CODEC' | 'PREPARED_CONTENT_MEMORY_ONLY';
+    constructor(code: 'INVALID_PREPARED_CONTENT' | 'UNSUPPORTED_PREPARED_CONTENT_VERSION' | 'UNSUPPORTED_PREPARED_CONTENT_CODEC' | 'PREPARED_CONTENT_MEMORY_ONLY');
+}
+/** Shared deterministic JSON after normal transport serialization. This keeps
+ * existing endpoint fingerprint semantics, including omitted undefined fields. */
+export declare function canonicalEndpointJson(value: unknown): string;
+/** Only the JSON processor may inspect this payload. It returns a fresh copy;
+ * neither decoding nor transport can mutate the sealed publication. */
+export declare function decodePreparedJsonContent(value: unknown): DecodedPreparedJsonContent;
+export declare function isPreparedContent(value: unknown): value is PreparedContent;
+export declare function prepareJsonContent(input: PreparedJsonInput): PreparedContent;
+/** Stable media dependency identity contains no renewable upload id or URL. */
+export declare function logicalMediaBlobId(conversationId: string, messageId: string, index: number): string;

package/dist/internal/backend-contracts/replyAuthority.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Opaque, server-issued authority for one agent reply to one inbound message.
+ *
+ * The stream delivers this beside the triggering message. Runtimes keep it out
+ * of model-visible schemas and return it only on the ordinary reply path.
+ */
+export interface AgentReplyAuthorityV1 {
+    schema: 'canon.agent-reply-authority.v1';
+    sourceMessageId: string;
+    token: string;
+    expiresAt: string;
+    /** Agent membership admission at issuance; absent/null only for legacy membership. */
+    admissionId?: string | null;
+}

package/dist/internal/backend-contracts/runtimeCardFields.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Canonical `canon.card.v1` action-field type vocabulary. The runtime array is
+ * the single source of truth and the type is derived from it, so a value and a
+ * type cannot drift.
+ *
+ * ORDER IS LOAD-BEARING: scripts/generate-skill-bundles.mjs renders this list
+ * verbatim (via @canonmsg/rich-cards) into two committed SKILL.md files, and
+ * `npm run check:skill-bundles` fails on a byte change.
+ */
+export declare const RUNTIME_CARD_FIELD_TYPES: readonly ["text", "textarea", "select", "multiSelect", "boolean", "date", "number", "currency", "searchSelect", "lineItems"];
+export type RuntimeCardFieldType = (typeof RUNTIME_CARD_FIELD_TYPES)[number];
+/**
+ * Caps shared across runtime-card normalizers, response validation, and
+ * authoring tools. Keep these backend-safe so Functions can import them.
+ */
+export declare const RUNTIME_CARD_LIMITS: {
+    readonly detailsRows: 32;
+    readonly lineItemRows: 50;
+    readonly lineItemColumns: 8;
+    readonly searchSelectChoices: 100;
+};
+export interface RuntimeCardFieldChoice {
+    label: string;
+    value?: string;
+    description?: string;
+    preview?: string;
+}
+/** Column cell types allowed inside a `lineItems` field. */
+export declare const RUNTIME_CARD_LINE_ITEM_COLUMN_TYPES: readonly ["text", "number", "currency", "date", "select"];
+export type RuntimeCardLineItemColumnType = (typeof RUNTIME_CARD_LINE_ITEM_COLUMN_TYPES)[number];
+export interface RuntimeCardLineItemColumn {
+    id: string;
+    label: string;
+    type: RuntimeCardLineItemColumnType;
+    required?: boolean;
+    choices?: RuntimeCardFieldChoice[];
+    min?: number;
+    max?: number;
+    step?: number;
+    precision?: number;
+    currencyCode?: string;
+    allowOther?: boolean;
+}
+export interface RuntimeCardField {
+    id: string;
+    label: string;
+    type: RuntimeCardFieldType;
+    required?: boolean;
+    placeholder?: string;
+    choices?: RuntimeCardFieldChoice[];
+    allowOther?: boolean;
+    sensitive?: boolean;
+    min?: number | string;
+    max?: number | string;
+    step?: number;
+    precision?: number;
+    currencyCode?: string;
+    columns?: RuntimeCardLineItemColumn[];
+    minRows?: number;
+    maxRows?: number;
+}
+export declare function validateRuntimeCardFieldValues(input: {
+    actionId: string | undefined;
+    actionFields: ReadonlyArray<RuntimeCardField> | undefined;
+    values: Record<string, unknown> | undefined;
+}): string | null;

package/dist/internal/backend-contracts/runtimeCardStorage.d.ts

@@ -0,0 +1,3 @@
+export declare function decodeStoredRuntimeCard(input: {
+    runtimeCardJson?: unknown;
+}): Record<string, unknown> | undefined;

package/dist/internal/backend-contracts/runtimeDescriptor.d.ts

@@ -0,0 +1,88 @@
+export type CanonControlValue = string;
+export type CanonRuntimeStreamingMode = 'none' | 'status' | 'snapshot' | 'block' | 'delta';
+export type CanonRuntimeDetailTier = 'primary' | 'detail' | 'diagnostic';
+export type CanonRuntimeVisibility = 'conversation' | 'hidden';
+export type CanonRuntimeActionAvailability = 'idle' | 'busy' | 'busy_with_queue' | 'waiting_input' | 'always';
+export type CanonRuntimeActionPlacement = 'composer_slash' | 'command_palette' | 'session_strip';
+export type CanonRuntimeActionCategory = 'plan' | 'turn' | 'session' | 'runtime' | 'details' | 'skill' | 'custom';
+export type CanonRuntimePrimitiveId = 'runtime.status' | 'runtime.reasoning.set' | 'runtime.verbosity.set' | 'runtime.usage' | 'context.compact' | 'session.new' | 'session.reset';
+export type CanonRuntimeCommandArgumentKind = 'string' | 'enum' | 'boolean';
+export interface CanonRuntimeCommandArgumentChoice {
+    value: string;
+    label: string;
+    description?: string;
+}
+export interface CanonRuntimeCommandArgumentDescriptor {
+    id: string;
+    label: string;
+    kind: CanonRuntimeCommandArgumentKind;
+    required?: boolean;
+    captureRemaining?: boolean;
+    choices?: ReadonlyArray<CanonRuntimeCommandArgumentChoice>;
+}
+export type CanonRuntimeActionDispatch = {
+    kind: 'control';
+    controlId: string;
+    value?: CanonControlValue;
+} | {
+    kind: 'signal';
+    signal: 'interrupt' | 'stop_and_drop' | 'new_session';
+} | {
+    kind: 'primitive';
+    primitive: CanonRuntimePrimitiveId;
+} | {
+    kind: 'text_passthrough';
+    template: string;
+} | {
+    kind: 'compose';
+    text: string;
+} | {
+    kind: 'open_details';
+    target?: string;
+};
+export interface CanonRuntimeActionDescriptor {
+    id: string;
+    label: string;
+    description?: string;
+    visibility?: CanonRuntimeVisibility;
+    tier?: CanonRuntimeDetailTier;
+    sensitive?: boolean;
+    primitive?: CanonRuntimePrimitiveId;
+    aliases?: ReadonlyArray<string>;
+    category?: CanonRuntimeActionCategory;
+    placements?: ReadonlyArray<CanonRuntimeActionPlacement>;
+    availability?: ReadonlyArray<CanonRuntimeActionAvailability>;
+    ownerOnly?: boolean;
+    disabledReason?: string | null;
+    trailingTextBehavior?: 'ignore' | 'send_as_prompt';
+    args?: ReadonlyArray<CanonRuntimeCommandArgumentDescriptor>;
+    dispatch: CanonRuntimeActionDispatch;
+}
+export interface CanonRuntimeCommandDescriptor extends CanonRuntimeActionDescriptor {
+    primitive?: CanonRuntimePrimitiveId;
+    args?: ReadonlyArray<CanonRuntimeCommandArgumentDescriptor>;
+}
+export declare function normalizeRuntimeCommandAlias(value: string): string | null;
+export declare function normalizeRuntimeCommandAliases(command: Pick<CanonRuntimeCommandDescriptor, 'id' | 'aliases'>): string[];
+export declare const MAX_PUBLIC_RUNTIME_COMMANDS = 256;
+export declare function isRuntimePrimitiveId(value: unknown): value is CanonRuntimePrimitiveId;
+/** Public command metadata shared by endpoint-backed runtime publishers. Never copies local configuration. */
+export declare function normalizePublicRuntimeCommands(value: unknown): CanonRuntimeCommandDescriptor[];
+export interface PublicRuntimeDescriptor {
+    supportsInterrupt?: boolean;
+    supportsInputInterrupt?: boolean;
+    streamingTextMode?: CanonRuntimeStreamingMode;
+    commands?: CanonRuntimeCommandDescriptor[];
+}
+export declare function normalizePublicRuntimeDescriptor(value: unknown): PublicRuntimeDescriptor;
+/** Read-only session facts, excluding local paths, inventories, and hidden/sensitive values. */
+export declare function normalizePublicRuntimeFacts(value: unknown): {
+    id: string;
+    group: "runtime" | "model" | "connection" | "route";
+    label: string;
+    value: string;
+    tier: "primary" | "detail" | "diagnostic" | undefined;
+    tone: "neutral" | "good" | "warning" | "danger" | undefined;
+    copyable: boolean | undefined;
+    updatedAt: number | undefined;
+}[];

package/dist/internal/backend-contracts/selfContext.d.ts

@@ -0,0 +1,9 @@
+/** Stored self-context id, or null when absent, empty, or path-like. */
+export declare function normalizeStoredSelfContextId(value: unknown): string | null;
+/**
+ * Agent-facing projection of an `agentSelfContexts` document; null for anything
+ * that is not a usable cross-session context. Ownership and conversation
+ * scoping stay with the CALLER — both consumers check them against their own
+ * Firestore handle before calling this.
+ */
+export declare function serializeSelfContext(id: string, data: Record<string, unknown>): Record<string, unknown> | null;

package/dist/internal/backend-contracts/turnProtocol.d.ts

@@ -0,0 +1,43 @@
+export type SenderType = 'human' | 'ai_agent';
+export type TurnLifecycleState = 'idle' | 'thinking' | 'streaming' | 'tool' | 'waiting_input' | 'completed' | 'interrupted';
+export type TurnMessageSemantics = 'progress' | 'turn_complete' | 'control';
+export type DeliveryIntent = 'queue' | 'interrupt' | 'interleave' | 'stop';
+export type InboundDisposition = 'queued' | 'accepted_now' | 'interleaved' | 'trigger_suppressed' | 'rejected' | 'cancelled';
+export interface TurnMetadata {
+    turnId?: string | null;
+    turnSemantics?: TurnMessageSemantics;
+    deliveryIntent?: DeliveryIntent;
+    replyBehavior?: 'allow_auto_reply' | 'suppress_auto_reply';
+    inboundDisposition?: InboundDisposition;
+    requestedTurnMode?: string;
+}
+export interface TriggerDecision {
+    allow: boolean;
+    semantics: TurnMessageSemantics;
+    reason: string;
+}
+export interface TurnStateLike {
+    state: TurnLifecycleState;
+    openedAt?: number;
+    updatedAt?: number;
+    turnUpdatedAt?: number | null;
+}
+export declare const ACTIVE_TURN_STALE_THRESHOLD_MS: number;
+export declare const WAITING_INPUT_STALE_THRESHOLD_MS: number;
+export declare function normalizeTurnMetadata(metadata: unknown): TurnMetadata | null;
+export declare function isTurnOpen(turnState: TurnStateLike | null | undefined): boolean;
+export declare function getTurnStateStaleThresholdMs(state: TurnLifecycleState): number;
+export declare function isTurnStateStale(turnState: TurnStateLike | null | undefined): boolean;
+export declare function resolveTurnMessageSemantics(input: {
+    senderType: SenderType;
+    metadata?: unknown;
+}): TurnMessageSemantics;
+export declare function shouldPromoteConversationMessage(input: {
+    senderType: SenderType;
+    metadata?: unknown;
+}): boolean;
+export declare function shouldTriggerAgentTurn(input: {
+    senderType: SenderType;
+    metadata?: unknown;
+}): TriggerDecision;
+export declare function normalizeRuntimeTurnState(value: unknown): TurnStateLike | null;