@canonmsg/agent-sdk 11.2.1 → 12.1.0

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

@@ -0,0 +1,386 @@
+import type { MediaAttachment } from './media.js';
+/**
+ * Shared work beside a conversation (protocol v2). The relay sequences opaque
+ * command envelopes; every endpoint reduces the same log with the same rules.
+ * Nothing a member writes may make the work unreadable for other members: only
+ * integrity failures and a newer envelope version halt replay. Everything else
+ * becomes a precise rejected outcome.
+ */
+export declare const ARTIFACT_PROTOCOL_VERSION = 2;
+/** Older envelopes were written by the retired v1 preview; they are rejected, not halted. */
+export declare const ARTIFACT_PROTOCOL_MIN_VERSION = 2;
+export declare const artifactSchemaName: (version: number) => string;
+/** Message metadata reference protocol. The wire name is unchanged in v2. */
+export declare const ARTIFACT_CONTEXT_PROTOCOL: "canon.artifact-context.v1";
+export declare const ARTIFACT_COMMAND_MAX_BYTES: number;
+/** Checked after every accepted command. */
+export declare const ARTIFACT_STATE_MAX_BYTES: number;
+/** Artifact, command, variant and asset identifiers. */
+export declare const ARTIFACT_ID_PATTERN: RegExp;
+/** Form field, column and row identifiers. */
+export declare const ARTIFACT_KEY_PATTERN: RegExp;
+export declare const ARTIFACT_KINDS: readonly ["chess", "form", "image"];
+export declare const ARTIFACT_COMMAND_TYPES: readonly ["create", "chess.move", "chess.resign", "form.set", "form.fields", "image.add", "image.select", "archive"];
+export declare const ARTIFACT_FORM_FIELD_TYPES: readonly ["text", "textarea", "number", "date", "select", "checkbox", "email", "tel", "url"];
+export declare const ARTIFACT_LIMITS: Readonly<{
+    titleChars: 120;
+    chessMaxPlies: 600;
+    formFields: 60;
+    formOptions: 40;
+    formOptionChars: 120;
+    formColumns: 10;
+    formRows: 200;
+    formLabelChars: 120;
+    formHintChars: 300;
+    formValueChars: 1000;
+    formChanges: 200;
+    formMaxDecimals: 6;
+    /**
+     * Largest magnitude of a form number. 200 rows of it still sum to a finite,
+     * exactly representable whole number (below Number.MAX_SAFE_INTEGER).
+     */
+    formNumberMax: 10000000000000;
+    imageVariants: 50;
+    imageLabelChars: 120;
+    imagePromptChars: 1000;
+    outcomes: 200;
+    outcomeMessageChars: 500;
+}>;
+export declare function isArtifactId(value: unknown): value is string;
+export declare function isArtifactKey(value: unknown): value is string;
+/** Shared work is a Dev-only preview. */
+export declare function isCanonArtifactEnvironmentEnabled(environmentId: string | null | undefined): boolean;
+export type ArtifactJson = null | boolean | number | string | ArtifactJson[] | {
+    [key: string]: ArtifactJson;
+};
+export type ArtifactKind = typeof ARTIFACT_KINDS[number];
+export type ArtifactCommandType = typeof ARTIFACT_COMMAND_TYPES[number];
+/** `title` is 1..120 characters after trimming. `initialState` is the kind's create input. */
+export interface ArtifactDefinition {
+    kind: ArtifactKind;
+    title: string;
+    initialState: ArtifactJson;
+}
+/** Principal IDs. A set seat restricts who may move that colour. */
+export interface ArtifactChessPlayers {
+    white?: string;
+    black?: string;
+}
+export interface ArtifactChessMove {
+    san: string;
+    from: string;
+    to: string;
+    by: string;
+}
+export interface ArtifactChessState {
+    fen: string;
+    initialFen: string;
+    moves: ArtifactChessMove[];
+    players?: ArtifactChessPlayers;
+    turn: 'w' | 'b';
+    check: boolean;
+    status: 'active' | 'checkmate' | 'stalemate' | 'draw' | 'resigned';
+    result?: '1-0' | '0-1' | '1/2-1/2';
+    resignedBy?: string;
+    /** Position key (FEN without clocks) -> count; reset on captures and pawn moves. */
+    repetition: Record<string, number>;
+}
+export interface ArtifactChessCreateInput {
+    fen?: string;
+    players?: ArtifactChessPlayers;
+}
+export type ArtifactFormFieldType = typeof ARTIFACT_FORM_FIELD_TYPES[number];
+export type ArtifactFormValue = string | number | boolean | null;
+export interface ArtifactFormField {
+    id: string;
+    label: string;
+    type: ArtifactFormFieldType;
+    options?: string[];
+    required?: boolean;
+    placeholder?: string;
+    help?: string;
+    decimals?: number;
+}
+export interface ArtifactFormColumn {
+    id: string;
+    label: string;
+    type: Exclude<ArtifactFormFieldType, 'textarea'>;
+    options?: string[];
+    decimals?: number;
+    sum?: boolean;
+}
+export interface ArtifactFormTable {
+    label?: string;
+    columns: ArtifactFormColumn[];
+}
+export interface ArtifactFormRow {
+    id: string;
+    cells: Record<string, ArtifactFormValue>;
+}
+/** `values` holds every field (null when empty); every row holds every column. */
+export interface ArtifactFormState {
+    fields: ArtifactFormField[];
+    values: Record<string, ArtifactFormValue>;
+    table?: ArtifactFormTable;
+    rows: ArtifactFormRow[];
+}
+/** Row IDs are optional on input and generated deterministically (`r-<index + 1>`). */
+export interface ArtifactFormCreateInput {
+    fields: ArtifactFormField[];
+    values?: Record<string, ArtifactFormValue>;
+    table?: ArtifactFormTable;
+    rows?: Array<{
+        id?: string;
+        cells: Record<string, ArtifactFormValue>;
+    }>;
+}
+/** `assetId` refers to a retained Canon upload, never a remote or bearer URL. */
+export interface ArtifactImageVariant {
+    id: string;
+    assetId: string;
+    label: string;
+    prompt?: string;
+    sourceVariantId?: string;
+    by: string;
+    at: string;
+}
+export interface ArtifactImageState {
+    variants: ArtifactImageVariant[];
+    currentVariantId?: string;
+}
+export type ArtifactImageCreateInput = Record<string, never>;
+export type ArtifactFormChange = {
+    field: string;
+    before: ArtifactFormValue;
+    after: ArtifactFormValue;
+} | {
+    row: string;
+    column: string;
+    before: ArtifactFormValue;
+    after: ArtifactFormValue;
+} | {
+    row: string;
+    add: Record<string, ArtifactFormValue>;
+} | {
+    row: string;
+    remove: {
+        before: Record<string, ArtifactFormValue>;
+    };
+};
+/** A field to remove with the value its author last saw: a newer value is a CONFLICT, never silently discarded. */
+export interface ArtifactFormFieldRemoval {
+    id: string;
+    before: ArtifactFormValue;
+}
+export type ArtifactCommandBody = {
+    type: 'create';
+    definition: ArtifactDefinition;
+}
+/** SAN or UCI. */
+ | {
+    type: 'chess.move';
+    baseRevisionId: string;
+    move: string;
+} | {
+    type: 'chess.resign';
+}
+/** 1..200 changes, all-or-nothing. */
+ | {
+    type: 'form.set';
+    changes: ArtifactFormChange[];
+} | {
+    type: 'form.fields';
+    add?: ArtifactFormField[];
+    remove?: ArtifactFormFieldRemoval[];
+} | {
+    type: 'image.add';
+    variant: {
+        id: string;
+        assetId: string;
+        label: string;
+        prompt?: string;
+        sourceVariantId?: string;
+    };
+    select?: boolean;
+} | {
+    type: 'image.select';
+    variantId: string;
+} | {
+    type: 'archive';
+    archived: boolean;
+};
+export type ArtifactCommand = {
+    schema: string;
+} & ArtifactCommandBody;
+export interface ArtifactContent {
+    encoding: 'json';
+    version: number;
+    data: string;
+}
+export interface AppendArtifactCommandBody {
+    conversationId: string;
+    artifactId: string;
+    commandId: string;
+    content: ArtifactContent;
+}
+export interface ArtifactStoredReceipt {
+    artifactId: string;
+    commandId: string;
+    sequence: number;
+    status: 'stored';
+}
+export interface ArtifactCommandRecord extends ArtifactStoredReceipt {
+    actorId: string;
+    actorAdmissionId: string;
+    createdAt: string;
+    content: ArtifactContent;
+}
+export interface ArtifactCatalogEntry {
+    artifactId: string;
+    sequence: number;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface ArtifactCatalogPage {
+    artifacts: ArtifactCatalogEntry[];
+    nextCursor?: string;
+}
+export interface ArtifactLogPage {
+    headSequence?: number;
+    commands: ArtifactCommandRecord[];
+    nextCursor?: string;
+}
+export interface ArtifactAsset {
+    assetId: string;
+    attachment: MediaAttachment;
+}
+export interface ArtifactSnapshot {
+    conversationId: string;
+    artifactId: string;
+    revisionId: string;
+    sequence: number;
+    definition: ArtifactDefinition;
+    state: ArtifactJson;
+    archived: boolean;
+    createdBy: string;
+    createdAt: string;
+    updatedBy: string;
+    updatedAt: string;
+}
+export type ArtifactOutcomeCode = 'INVALID_COMMAND' | 'CONFLICT' | 'UNAUTHORIZED' | 'RETIRED_PROTOCOL';
+export interface ArtifactDomainOutcome {
+    commandId: string;
+    sequence: number;
+    status: 'accepted' | 'rejected';
+    actorId: string;
+    /** A known command type, or 'unknown'. */
+    type: string;
+    at: string;
+    revisionId?: string;
+    code?: ArtifactOutcomeCode;
+    message?: string;
+}
+/** `outcomes` keeps the newest 200. */
+export interface ArtifactReadResult {
+    snapshot: ArtifactSnapshot | null;
+    outcomes: ArtifactDomainOutcome[];
+    sequence: number;
+}
+export type ArtifactSelection = {
+    kind: 'artifact';
+    variantId?: string;
+}
+/** ['fields', id] | ['rows', rowId, columnId] */
+ | {
+    kind: 'field';
+    path: string[];
+} | {
+    kind: 'position';
+    ply: number;
+    square?: string;
+}
+/** Fractions of the image, origin top-left. */
+ | {
+    kind: 'region';
+    assetId: string;
+    variantId?: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+export type ArtifactReferenceOrigin = 'open' | 'selected' | 'activity';
+export interface ArtifactReference {
+    artifactId: string;
+    revisionId: string;
+    /** Always 1 in v2; kept for wire compatibility. */
+    definitionVersion: number;
+    label?: string;
+    origin?: ArtifactReferenceOrigin;
+    selection: ArtifactSelection;
+}
+export interface ArtifactContext {
+    schema: typeof ARTIFACT_CONTEXT_PROTOCOL;
+    references: ArtifactReference[];
+}
+/** A precise, author-facing validation failure. Messages never echo unbounded input. */
+export declare class ArtifactValidationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Quote an attacker-controlled identifier or label for a message, truncated to
+ * 80 characters. Only strings, numbers and booleans are quoted; other values
+ * are described by their type and never converted with String().
+ */
+export declare function quoteArtifactText(value: unknown): string;
+/**
+ * Titles, labels, options and hints are one line: they are embedded in
+ * one-line summaries, prompts and messages. Each run of control characters
+ * (including newlines) becomes one space; the result is trimmed.
+ */
+export declare function artifactSingleLine(value: string): string;
+/**
+ * Round half away from zero to `decimals` places, without binary-fraction
+ * surprises such as 1.005 -> 1.00. Non-finite input (or invalid `decimals`)
+ * is returned unchanged.
+ */
+export declare function roundFormNumber(value: number, decimals: number): number;
+export type ArtifactFormValueSpec = Pick<ArtifactFormField, 'type'> & {
+    options?: string[];
+    decimals?: number;
+    label?: string;
+};
+/**
+ * Normalize one typed value. '' (and undefined) become null for every type and
+ * null is always allowed: `required` is a hint, not enforced.
+ */
+export declare function validateFormValue(spec: ArtifactFormValueSpec, value: unknown): ArtifactFormValue;
+/** Missing, '' and null are the same empty value. */
+export declare function formValuesEqual(a: unknown, b: unknown): boolean;
+/** Readable value for messages and summaries. */
+export declare function formatFormValue(value: unknown): string;
+/** Validate one field definition (used for create and form.fields). */
+export declare function normalizeFormField(value: unknown): ArtifactFormField;
+/** Validate a table definition: an optional label and 1..10 uniquely identified columns. */
+export declare function normalizeFormTable(value: unknown): ArtifactFormTable;
+/** Validate a row's cells against the table; every column is present (null when empty). */
+export declare function normalizeFormCells(table: ArtifactFormTable, value: unknown, where: string): Record<string, ArtifactFormValue>;
+/** Create input -> state. Generated row IDs are `r-<index + 1>`; duplicate IDs are rejected. */
+export declare function normalizeFormInput(input: unknown): ArtifactFormState;
+/** Human label for a change against the form it applies to. */
+export declare function formChangeLabel(state: Pick<ArtifactFormState, 'fields' | 'rows'> & {
+    table?: ArtifactFormTable;
+}, change: ArtifactFormChange): string;
+/** Strict (server and composer): reject malformed known metadata instead of dropping it. Returns a clean copy. */
+export declare function parseArtifactContext(value: unknown): ArtifactContext;
+/** Lenient (prompt projection, rendering): keeps valid references and never throws. */
+export declare function readArtifactContext(value: unknown): ArtifactContext | undefined;
+/** Activity text stays well inside the 4 KiB message text limit, leaving metadata room. */
+export declare const ARTIFACT_ACTIVITY_TEXT_MAX_BYTES = 2048;
+/** Text for an ordinary chat message a person posts after acting on shared work. */
+export declare function artifactActivityText(input: {
+    action: 'created' | 'chess.move' | 'chess.resign' | 'form.updated';
+    kind: ArtifactKind;
+    title: string;
+    detail?: string;
+}): string;

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

@@ -0,0 +1,41 @@
+/**
+ * Which client is calling, and the oldest version Canon still serves (mls-cutover-operator.md §2 15b). Every client names
+ * itself on its endpoint requests with `X-Canon-Client: <kind>/<version>`. While a floor exists, Canon refuses a kind
+ * below its minimum, and any request without a valid header, with `426 CLIENT_UPDATE_REQUIRED`.
+ */
+export declare const CANON_CLIENT_HEADER = "X-Canon-Client";
+export declare const CLIENT_UPDATE_REQUIRED = "CLIENT_UPDATE_REQUIRED";
+/**
+ * - `app-ios`, `app-android`: the native build's version (an OTA update cannot add native code, so the bundle's does not count);
+ * - `web`, `runner` (`@canonmsg/agent-sdk`), `hermes` (the plugin), and `core` for other first-party tools (the CLIs);
+ * - `connector`: Canon's hosted MCP connector, which deploys with Functions. Like `web`, it ships one build at a time and
+ *   names itself `0.0.0`; neither gets a minimum.
+ */
+export declare const CANON_CLIENT_KINDS: readonly ["app-ios", "app-android", "web", "runner", "hermes", "core", "connector"];
+export type CanonClientKind = typeof CANON_CLIENT_KINDS[number];
+export interface CanonClientIdentity {
+    readonly kind: CanonClientKind;
+    readonly version: string;
+}
+/** `major.minor.patch`, each at most six digits: no prerelease or build suffix, so versions compare exactly. */
+export declare function isCanonClientVersion(value: unknown): value is string;
+export declare function formatCanonClientHeader(client: CanonClientIdentity): string;
+/** A malformed header is treated as absent. */
+export declare function parseCanonClientHeader(value: unknown): CanonClientIdentity | null;
+export declare function compareCanonClientVersions(left: string, right: string): number;
+/** `mlsRollout/clientFloor`: per-kind minimums. A kind it does not name has none. */
+export interface CanonClientFloor {
+    readonly minimum: Readonly<Partial<Record<CanonClientKind, string>>>;
+}
+/** The server-only record, in its exact shape; anything else is a broken floor, which the caller refuses rather than ignore. */
+export declare function parseCanonClientFloor(data: unknown): CanonClientFloor;
+/** The refusal's message, naming the minimum, so a runner or plugin log says what to install. */
+export declare function canonClientUpdateMessage(refusal: {
+    kind: CanonClientKind | null;
+    minimum: string | null;
+}): string;
+/** The refusal a request gets under a floor, or null when it passes: no valid header, or a version below its kind's minimum. */
+export declare function canonClientBelowFloor(floor: CanonClientFloor, header: unknown): {
+    kind: CanonClientKind | null;
+    minimum: string | null;
+} | null;

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

@@ -0,0 +1,146 @@
+import type { ListConversationsResult } from './verbContract.js';
+import type { DiscoverAgentsInput, DiscoverAgentsResult } from './agentDirectory.js';
+/** The deliberately small policy vocabulary for principal communication. */
+export type CommunicationRule = 'open' | 'approval-required' | 'closed';
+/** Missing or invalid policy never widens access. */
+export declare function readCommunicationRule(value: unknown): CommunicationRule;
+/** Canon conversation selection is principal-neutral; a conversation is a runtime session boundary. */
+export type DirectConversationSelection = {
+    mode: 'latest_or_new';
+} | {
+    mode: 'new';
+} | {
+    mode: 'specific';
+    conversationId: string;
+};
+export type CommunicateInput = ({
+    action: 'discover_agents';
+} & DiscoverAgentsInput) | {
+    action: 'message_existing';
+    conversationId: string;
+    text: string;
+    messageId?: string;
+    /** Private note for the resident Codex's next ordinary room turn. */
+    privateContext?: string;
+    /** Optional short private description of this local Codex task. */
+    sourceLabel?: string;
+} | {
+    action: 'start_direct' | 'start_conversation';
+    principalId: string;
+    text: string;
+    selection?: DirectConversationSelection;
+    messageId?: string;
+} | {
+    action: 'create_group' | 'create_conversation';
+    name?: string;
+    memberIds: string[];
+} | {
+    action: 'forward_message';
+    sourceConversationId: string;
+    targetConversationId: string;
+    messageId: string;
+    selfContextId?: string;
+    text?: string;
+} | {
+    action: 'share_contact';
+    conversationId: string;
+    contactUserId: string;
+    text?: string;
+    messageId?: string;
+} | {
+    action: 'manage_group_members' | 'manage_participants';
+    conversationId: string;
+    userId: string;
+    operation: 'add' | 'remove';
+} | {
+    action: 'list_conversations';
+    limit?: number;
+} | {
+    action: 'leave_conversation';
+    conversationId: string;
+};
+export type CommunicateResult = ({
+    status: 'listed';
+} & ListConversationsResult) | {
+    status: 'left';
+    conversationId: string;
+} | ({
+    status: 'discovered';
+} & DiscoverAgentsResult) | {
+    status: 'messaged';
+    conversationId: string;
+    messageId: string;
+    created?: boolean;
+    reused?: boolean;
+} | {
+    status: 'requested' | 'pending';
+    requestId: string;
+} | {
+    status: 'created';
+    conversationId: string;
+    added: string[];
+    pending: Array<{
+        userId: string;
+        requestId: string;
+    }>;
+    skipped: Array<{
+        userId: string;
+        reason: string;
+    }>;
+} | {
+    status: 'forwarded';
+    messageId: string;
+    targetConversationId: string;
+} | {
+    status: 'shared';
+    conversationId: string;
+    messageId: string;
+} | {
+    status: 'added' | 'removed';
+    conversationId: string;
+    userId: string;
+} | {
+    status: 'approval_required';
+    reason: string;
+} | {
+    status: 'blocked' | 'unavailable';
+    reason: string;
+};
+/** Principal-neutral app/SDK command. Humans may open a composer before sending. */
+export interface StartDirectInput {
+    targetUserId: string;
+    /** `withheld`: the client holds a line it sends only encrypted. Canon reserves `messageId` and answers
+     * `openingText: 'deferred'` for an encrypted room, and `opening-text-required` (writing nothing) for a plaintext one,
+     * which the client then starts again with its text (mls-rooms-by-default.md §2a.9). */
+    opener?: {
+        text: string;
+        messageId?: string;
+    } | {
+        withheld: true;
+        messageId: string;
+    } | null;
+    selection?: DirectConversationSelection;
+}
+export type StartDirectResult = {
+    status: 'opened' | 'messaged';
+    conversationId: string;
+    messageId?: string;
+    created?: boolean;
+    reused?: boolean;
+    /** The room is encrypted, so Canon stored no opening text: the requester's client sends it encrypted, under
+     * `messageId` (mls-rooms-by-default.md §2a.9). */
+    openingText?: 'deferred';
+} | {
+    status: 'requested' | 'pending';
+    requestId: string;
+    /** The room the request made, which the requester may open and write in (§2a.2). An encrypted room stores no
+     * opener: the requester's client sends it into `conversationId` under `messageId` once the request's other
+     * approvers have approved and the target's device is in (§2a.4, §2a.9). */
+    conversationId?: string;
+    messageId?: string;
+    openingText?: 'deferred';
+} | {
+    status: 'blocked' | 'unavailable';
+    reason: string;
+};
+export declare function parseDirectConversationSelection(value: unknown): DirectConversationSelection;