@canonmsg/agent-sdk 11.2.1 → 12.0.0

package/dist/internal/core/retry.d.ts

@@ -0,0 +1,122 @@
+import type { SendMessageOptions } from './types.js';
+import { type CanonClient } from './client.js';
+export interface SendMessageRetryOptions {
+    /** Stable replacement recorded by the product after a conclusive rejection. */
+    operationId?: string;
+    replacesOperationId?: string;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    maxAttempts?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+}
+export declare const CANON_MESSAGE_TEXT_MAX_BYTES: number;
+export declare const DEFAULT_CHUNKED_MESSAGE_TEXT_MAX_BYTES = 3800;
+export interface SendMessageChunkingOptions {
+    maxTextBytes?: number;
+    /**
+     * Opt in to resumable chunked delivery.
+     *
+     * With it on, a mid-sequence failure throws a `ChunkedSendMessageError`
+     * carrying the ids of the parts that ARE durable, so a later attempt can pick
+     * up the tail. Off by default so callers that do not resume keep today's
+     * behaviour: the raw send error, unwrapped.
+     *
+     * Implied by a non-empty `deliveredMessageIds` — passing progress back IS
+     * opting in.
+     */
+    resumable?: boolean;
+    /**
+     * Ids of the parts an earlier attempt already made durable, in part order.
+     * Those parts are skipped and their ids are carried into the result, so a
+     * resumed send still reports the whole answer.
+     */
+    deliveredMessageIds?: readonly string[];
+}
+export interface ChunkedSendMessageResult {
+    messageIds: string[];
+}
+/**
+ * The server's message-id idempotency guard rejecting a send.
+ *
+ * A byte-identical replay of a message succeeds (`created: false`), so a 409
+ * `MESSAGE_ID_EXISTS` means a message already exists under this id whose stored
+ * content diverges from what is being sent now. Either way the id is TAKEN:
+ * that message is durable in Canon and re-sending it is impossible.
+ */
+export declare function isCanonMessageIdConflict(error: unknown): boolean;
+/** Pending delivery is visible, but cannot truthfully produce a failure notice. */
+export declare function isPendingCanonOperation(error: unknown): boolean;
+/**
+ * A chunked send that stopped part-way, with the progress needed to resume it.
+ *
+ * Parts 1..`deliveredMessageIds.length` are durable in Canon; only the tail is
+ * missing. Handing `deliveredMessageIds` back to `sendMessageWithRetryChunked`
+ * restarts at the next part instead of re-sending the answer's head — which the
+ * server would reject or duplicate, and which the reader has already seen.
+ */
+export declare class ChunkedSendMessageError extends Error {
+    /** Ids of the parts that are durable in Canon, in part order. */
+    readonly deliveredMessageIds: string[];
+    /** The part the send stopped on (1-based). */
+    readonly failedPart: number;
+    /** How many parts the text splits into in total. */
+    readonly totalParts: number;
+    /** The underlying send failure — what callers should classify. */
+    readonly cause: unknown;
+    constructor(input: {
+        cause: unknown;
+        deliveredMessageIds: readonly string[];
+        failedPart: number;
+        totalParts: number;
+    });
+    /** How many parts are durable — a resume starts at the next one. */
+    get deliveredParts(): number;
+}
+/**
+ * Structural check as well as `instanceof`, so progress survives a caller that
+ * ended up with a second copy of this module (a workspace package resolved to
+ * both `dist` and source, say) instead of silently degrading to "no progress".
+ */
+export declare function isChunkedSendMessageError(error: unknown): error is ChunkedSendMessageError;
+export declare function isRetryableCanonDeliveryError(error: unknown): boolean;
+export declare function sendMessageWithRetry(client: CanonClient, conversationId: string, text: string, options?: SendMessageOptions, retryOptions?: SendMessageRetryOptions): Promise<{
+    messageId: string;
+}>;
+export declare function utf8ByteLength(value: string): number;
+export declare function splitTextByUtf8Bytes(text: string, maxBytes?: number): string[];
+export declare function chunkMessageId(baseMessageId: string | undefined, index: number): string | undefined;
+export interface ChunkedMessagePartMetadataInput {
+    /** Stable group id shared by every part, normally the unsuffixed message id. */
+    groupId?: string;
+    metadata?: Record<string, unknown>;
+    index: number;
+    count: number;
+}
+/**
+ * Build metadata for one visible part of a logically single message.
+ *
+ * Earlier parts are progress-only and cannot trigger replies or notifications.
+ * The last part preserves the caller's terminal semantics while removing
+ * streamed text from the trail, because that text is already visible in the
+ * preceding message parts.
+ */
+export declare function buildChunkedMessagePartMetadata(input: ChunkedMessagePartMetadataInput): Record<string, unknown>;
+/**
+ * Send `text` as one message, or as an ordered sequence of `-part-N` messages
+ * when it exceeds the byte budget.
+ *
+ * Sequential by construction, so a failure leaves parts 1..k durable and the
+ * tail unsent. Callers that opt into `resumable` get that progress back (see
+ * `ChunkedSendMessageError`) and can hand it to a later attempt, which then
+ * picks up at part k+1. The split is a pure function of the text and the byte
+ * budget, so part N of a resumed attempt is byte-identical to part N of the
+ * attempt that delivered it — which is what makes the `-part-N` ids a safe
+ * resume cursor.
+ *
+ * A byte-identical replay succeeds at the server. Any idempotency conflict
+ * therefore means the stored part differs and is always reported; treating it
+ * as delivered would stitch two different answers together.
+ */
+export declare function sendMessageWithRetryChunked(client: CanonClient, conversationId: string, text: string, options?: SendMessageOptions, retryOptions?: SendMessageRetryOptions, chunkingOptions?: SendMessageChunkingOptions): Promise<ChunkedSendMessageResult>;

package/dist/internal/core/rtdb-rest.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Compatibility-shaped runtime state handle backed exclusively by the shared
+ * endpoint. Paths are parsed locally into fixed typed projections; no database
+ * path or Firebase credential is sent to the server.
+ */
+import type { CanonClient } from './client.js';
+import type { DeliveryIntent, RuntimeCapabilities, TurnLifecycleState } from './turn-protocol.js';
+import type { CanonControlValue, CanonRuntimeActivityItem, ModelOption, RuntimeControlError, RuntimeControlState, RuntimeInfoPayload } from './types.js';
+export interface SessionStatePayload {
+    lastError?: string;
+    hostMode?: boolean;
+    clientType?: string;
+    isActive: boolean;
+    /** Runtimes that cannot report a context window (e.g. Codex) publish totalTokens only. */
+    contextUsage?: {
+        percentage?: number;
+        totalTokens: number;
+        maxTokens?: number;
+    };
+    updatedAt: {
+        '.sv': 'timestamp';
+    };
+}
+export interface TurnStatePayload {
+    turnId?: string | null;
+    state: TurnLifecycleState;
+    queueDepth: number;
+    currentSpeakerId?: string | null;
+    lastAcceptedIntent?: DeliveryIntent | null;
+    activeMessageIds?: string[];
+    capabilities?: RuntimeCapabilities;
+    openedAt?: number | {
+        '.sv': 'timestamp';
+    };
+    turnUpdatedAt?: number | {
+        '.sv': 'timestamp';
+    } | null;
+    completedAt?: number | {
+        '.sv': 'timestamp';
+    } | null;
+    updatedAt: {
+        '.sv': 'timestamp';
+    };
+}
+export interface AgentSessionSnapshotPatch {
+    clientType?: string;
+    hostMode?: boolean;
+    model?: string | null;
+    modelOptions?: ModelOption[] | null;
+    permissionMode?: string | null;
+    permissionModeOptions?: Array<{
+        value: string;
+        label: string;
+    }> | null;
+    effort?: string | null;
+    runtimeControlValues?: Record<string, CanonControlValue> | null;
+    controlState?: Record<string, RuntimeControlState> | null;
+    runtimeControlErrors?: Record<string, RuntimeControlError> | null;
+    workspaceId?: string | null;
+    workspaceOptions?: Array<{
+        id: string;
+        label: string;
+    }> | null;
+    executionMode?: 'worktree' | 'locked' | null;
+    availableExecutionModes?: Array<'worktree' | 'locked'> | null;
+    executionBranch?: string | null;
+    resolvedCwd?: string | null;
+    worktreePath?: string | null;
+    executionFallbackReason?: string | null;
+    state?: null;
+    turnState?: TurnLifecycleState | null;
+    turnId?: string | null;
+    turnOpenedAt?: number | {
+        '.sv': 'timestamp';
+    } | null;
+    turnUpdatedAt?: number | {
+        '.sv': 'timestamp';
+    } | null;
+    supportsQueue?: boolean | null;
+    supportsInputInterrupt?: boolean | null;
+    queueDepth?: number;
+    waitingForInput?: boolean;
+    contextUsage?: {
+        percentage?: number;
+        totalTokens: number;
+        maxTokens?: number;
+    } | null;
+    lastError?: string | null;
+    configurationStatus?: 'ready' | 'configuration_required' | null;
+    lastHeartbeatAt?: number | {
+        '.sv': 'timestamp';
+    };
+    updatedAt?: {
+        '.sv': 'timestamp';
+    };
+}
+/**
+ * Canon stores only operational conversation state. Runtime configuration is
+ * owned by the adapter and its local session factory, even when an older host
+ * still supplies those fields to this compatibility-shaped API.
+ */
+export declare function sanitizeAgentSessionSnapshotPatch(snapshot: Omit<AgentSessionSnapshotPatch, 'updatedAt'>): Omit<AgentSessionSnapshotPatch, 'updatedAt'>;
+export interface RuntimeInfoPayloadData extends Omit<RuntimeInfoPayload, 'updatedAt'> {
+    updatedAt: {
+        '.sv': 'timestamp';
+    };
+}
+export interface RuntimeActivityPayloadData extends Omit<CanonRuntimeActivityItem, 'updatedAt'> {
+    updatedAt: number | {
+        '.sv': 'timestamp';
+    };
+}
+/** Retained only for callers upgrading from the old RTDB helper. */
+interface RTDBAuthOptions {
+    rtdbUrl?: string;
+    firebaseApiKey?: string;
+}
+export interface RTDBClientHandle {
+    observeControls?(changed: (conversationId?: string) => void, connected: (value: boolean) => void): () => void;
+    /** Consume only the exact value returned by this handle before dispatch. */
+    consume(path: string, observed: unknown): Promise<void>;
+    observedRevision(path: string, observed: unknown): string | undefined;
+    read(path: string): Promise<unknown>;
+    write(path: string, data: unknown): Promise<void>;
+    patch(path: string, data: unknown): Promise<void>;
+    remove(path: string): Promise<void>;
+    writeSessionState(conversationId: string, agentId: string, state: Omit<SessionStatePayload, 'updatedAt'>): Promise<void>;
+    clearSessionState(conversationId: string, agentId: string): Promise<void>;
+    writeTurnState(conversationId: string, agentId: string, state: Omit<TurnStatePayload, 'updatedAt'>): Promise<void>;
+    clearTurnState(conversationId: string, agentId: string): Promise<void>;
+    patchAgentSessionSnapshot(conversationId: string, agentId: string, snapshot: Omit<AgentSessionSnapshotPatch, 'updatedAt'>): Promise<void>;
+    writeRuntimeInfo(conversationId: string, agentId: string, payload: Omit<RuntimeInfoPayload, 'updatedAt'>): Promise<void>;
+    patchRuntimeInfo(conversationId: string, agentId: string, payload: Partial<Omit<RuntimeInfoPayload, 'updatedAt'>>): Promise<void>;
+    clearRuntimeInfo(conversationId: string, agentId: string): Promise<void>;
+    readRuntimeActivity(conversationId: string, agentId: string): Promise<Record<string, CanonRuntimeActivityItem>>;
+    writeRuntimeActivity(conversationId: string, agentId: string, item: CanonRuntimeActivityItem): Promise<void>;
+    removeRuntimeActivityItem(conversationId: string, agentId: string, itemId: string): Promise<void>;
+    clearRuntimeActivity(conversationId: string, agentId: string): Promise<void>;
+}
+/**
+ * Existing adapters keep this scoped handle while all runtime traffic uses
+ * their CanonClient endpoint. Legacy Firebase options have no effect.
+ */
+export declare function initRTDBAuth(client: CanonClient, _options?: RTDBAuthOptions): RTDBClientHandle;
+export {};

package/dist/internal/core/runtime-cards.d.ts

@@ -0,0 +1,331 @@
+import { RUNTIME_CARD_FIELD_TYPES, RUNTIME_CARD_LIMITS, RUNTIME_CARD_LINE_ITEM_COLUMN_TYPES, validateRuntimeCardFieldValues, type RuntimeCardField, type RuntimeCardFieldChoice, type RuntimeCardFieldType, type RuntimeCardLineItemColumn, type RuntimeCardLineItemColumnType, type VerbNativeMetadata } from '../backend-contracts/index.js';
+export { RUNTIME_CARD_FIELD_TYPES, RUNTIME_CARD_LIMITS, RUNTIME_CARD_LINE_ITEM_COLUMN_TYPES, validateRuntimeCardFieldValues, };
+export type { RuntimeCardField, RuntimeCardFieldChoice, RuntimeCardFieldType, RuntimeCardLineItemColumn, RuntimeCardLineItemColumnType, };
+export interface PlanApprovalMetadata {
+    type: 'plan_approval';
+    planId: string;
+    /** Canon user who should answer this card. UI hint only; reply APIs still enforce authorization. */
+    responseUserId?: string;
+    title?: string;
+    summary?: string;
+    body?: string;
+    allowedPrompts?: ReadonlyArray<{
+        tool: string;
+        prompt: string;
+    }>;
+}
+/**
+ * Plan approval decision.
+ * - `approve`: proceed with the plan.
+ * - `revise`: request changes (carries free-text `feedback`).
+ * - `reject`: decline / keep planning — the Mac-app "No, keep planning" path,
+ *   distinct from a feedback-bearing revision.
+ */
+export type PlanApprovalDecision = 'approve' | 'revise' | 'reject';
+export interface PlanApprovalReplyMetadata {
+    type: 'plan_approval_reply';
+    planId: string;
+    decision: PlanApprovalDecision;
+    feedback?: string;
+    /**
+     * When the plan card showed `allowedPrompts`, the subset the user granted on
+     * approval. The host pre-approves these as session rules. Absent = grant all
+     * (legacy/full-approve behavior).
+     */
+    grantedPrompts?: ReadonlyArray<{
+        tool: string;
+        prompt: string;
+    }>;
+}
+export type RuntimeInputKind = 'clarify' | 'sudo' | 'secret';
+export type RuntimeInputReplyStatus = 'submitted' | 'cancelled';
+export type RuntimeInputResolutionStatus = RuntimeInputReplyStatus | 'timeout';
+export interface RuntimeInputChoice {
+    label: string;
+    value?: string;
+    description?: string;
+    /**
+     * Optional preview content rendered when this option is focused/expanded —
+     * mockups, code snippets, or comparisons. Matches the Mac-app
+     * AskUserQuestion option preview.
+     */
+    preview?: string;
+}
+export interface RuntimeInputQuestion {
+    id: string;
+    question: string;
+    header?: string;
+    choices?: RuntimeInputChoice[];
+    allowOther?: boolean;
+    isSecret?: boolean;
+    multiSelect?: boolean;
+}
+export type RuntimeInputAnswers = Record<string, {
+    answers: string[];
+}>;
+export type RuntimeInputNativeMetadata = Pick<VerbNativeMetadata, 'runtime' | 'method' | 'requestId' | 'sessionKey' | 'turnId' | 'handles'>;
+export interface RuntimeInputRequestMetadata {
+    type: 'runtime_input_request';
+    inputId: string;
+    /** Canon user who should answer this card. UI hint only; reply APIs still enforce authorization. */
+    responseUserId?: string;
+    kind: RuntimeInputKind;
+    prompt: string;
+    title?: string;
+    choices?: RuntimeInputChoice[];
+    questions?: RuntimeInputQuestion[];
+    secretName?: string;
+    native?: RuntimeInputNativeMetadata;
+    expiresAt: string;
+    sensitive?: boolean;
+}
+export interface RuntimeInputReplyMetadata {
+    type: 'runtime_input_reply';
+    inputId: string;
+    kind?: RuntimeInputKind;
+    status: RuntimeInputReplyStatus;
+    answerSummary?: string;
+    answersSummary?: string;
+    sensitive?: boolean;
+}
+export interface RuntimeInputOutcomeMetadata {
+    type: 'runtime_input_outcome';
+    inputId: string;
+    kind?: RuntimeInputKind;
+    status: RuntimeInputResolutionStatus;
+    reason?: 'submitted' | 'cancelled' | 'timeout' | 'expired' | 'interrupted';
+}
+export declare const RUNTIME_CARD_SCHEMA_V1: "canon.card.v1";
+export declare const RUNTIME_CARD_PUBLIC_REQUEST_TEXT: "Action requested";
+export type RuntimeCardSchemaV1 = typeof RUNTIME_CARD_SCHEMA_V1;
+export type RuntimeCardBlockKind = 'summary' | 'metricGrid' | 'chart' | 'table' | 'list' | 'callout' | 'actions' | 'mediaPreview' | 'details';
+export type RuntimeCardTone = 'neutral' | 'primary' | 'positive' | 'warning' | 'negative' | 'danger' | 'critical' | 'welcome';
+export type RuntimeCardReplyStatus = 'submitted' | 'cancelled';
+export type RuntimeCardResolutionStatus = RuntimeCardReplyStatus | 'timeout';
+export interface RuntimeCardSummaryBlock {
+    kind: 'summary';
+    title?: string;
+    text: string;
+}
+export interface RuntimeCardMetric {
+    label: string;
+    value: string;
+    delta?: string;
+    tone?: RuntimeCardTone;
+}
+export interface RuntimeCardMetricGridBlock {
+    kind: 'metricGrid';
+    title?: string;
+    metrics: RuntimeCardMetric[];
+}
+export interface RuntimeCardChartPoint {
+    x: string;
+    y: number;
+}
+export interface RuntimeCardChartSeries {
+    name?: string;
+    points: RuntimeCardChartPoint[];
+}
+export interface RuntimeCardChartBlock {
+    kind: 'chart';
+    chart: 'line' | 'bar';
+    title?: string;
+    yLabel?: string;
+    series: RuntimeCardChartSeries[];
+}
+export interface RuntimeCardTableBlock {
+    kind: 'table';
+    title?: string;
+    columns: string[];
+    rows: string[][];
+}
+export interface RuntimeCardListItem {
+    label: string;
+    detail?: string;
+    status?: 'pending' | 'done' | 'blocked' | 'warning';
+}
+export interface RuntimeCardListBlock {
+    kind: 'list';
+    title?: string;
+    items: RuntimeCardListItem[];
+}
+export interface RuntimeCardCalloutBlock {
+    kind: 'callout';
+    title?: string;
+    text: string;
+    tone?: RuntimeCardTone;
+}
+export type RuntimeCardMediaKind = 'image' | 'file';
+export interface RuntimeCardMediaPreviewMedia {
+    /** 'file' covers application/pdf and other documents. */
+    kind: RuntimeCardMediaKind;
+    /** REQUIRED. Canon Storage URL only (server enforces). */
+    url: string;
+    /** Resumable-upload identity for the primary media, when applicable. */
+    uploadId?: string;
+    /** REQUIRED. Allowlist enforced server-side: image/*, application/pdf. */
+    mimeType: string;
+    fileName?: string;
+    sizeBytes?: number;
+    /** Canon Storage URL; inline preview for non-image media (e.g. pdf page render). */
+    thumbnailUrl?: string;
+    /** Resumable-upload identity for thumbnailUrl, when it is a separate upload. */
+    thumbnailUploadId?: string;
+    /** 1-based page the thumbnail shows. */
+    page?: number;
+    pageCount?: number;
+}
+export interface RuntimeCardMediaPreviewBlock {
+    kind: 'mediaPreview';
+    title?: string;
+    media: RuntimeCardMediaPreviewMedia;
+    /** Recommended — old clients render this; should contain the open-link text. */
+    fallbackText?: string;
+}
+export interface RuntimeCardDetailsRow {
+    label: string;
+    value: string;
+    tone?: RuntimeCardTone;
+    /** 0..1 inclusive. */
+    confidence?: number;
+    hint?: string;
+}
+export interface RuntimeCardDetailsBlock {
+    kind: 'details';
+    title?: string;
+    rows: RuntimeCardDetailsRow[];
+}
+/**
+ * Block preserved when a renderer/normalizer does not recognize `kind`. Forward
+ * compatibility: unknown blocks are kept (not dropped) so renderers can degrade
+ * to `fallbackText` instead of silently losing content.
+ */
+export interface RuntimeCardUnknownBlock {
+    kind: string;
+    fallbackText?: string;
+}
+export interface RuntimeCardAction {
+    id: string;
+    label: string;
+    tone?: RuntimeCardTone;
+    fields?: RuntimeCardField[];
+}
+export interface RuntimeCardActionsBlock {
+    kind: 'actions';
+    title?: string;
+    actions: RuntimeCardAction[];
+}
+export type RuntimeCardBlock = RuntimeCardSummaryBlock | RuntimeCardMetricGridBlock | RuntimeCardChartBlock | RuntimeCardTableBlock | RuntimeCardListBlock | RuntimeCardCalloutBlock | RuntimeCardActionsBlock | RuntimeCardMediaPreviewBlock | RuntimeCardDetailsBlock | RuntimeCardUnknownBlock;
+export interface RuntimeCardV1 {
+    schema: RuntimeCardSchemaV1;
+    cardId?: string;
+    template?: string;
+    tone?: RuntimeCardTone;
+    title: string;
+    fallbackText: string;
+    blocks: RuntimeCardBlock[];
+}
+export interface RuntimeCardPreview {
+    title?: string;
+    tone?: RuntimeCardTone;
+    template?: string;
+    blockKinds: RuntimeCardBlockKind[];
+}
+export type RuntimeCardNativeMetadata = RuntimeInputNativeMetadata;
+export interface RuntimeCardRequestMetadata {
+    type: 'runtime_card_request';
+    cardId: string;
+    cardKind: string;
+    schemaVersion: RuntimeCardSchemaV1;
+    fallbackText: string;
+    responseUserId?: string;
+    expiresAt: string;
+    runtimeId?: string;
+    turnId?: string;
+    native?: RuntimeCardNativeMetadata;
+    /** True when the card carries an actions block (the agent waits for a
+     *  response); false/absent for display/report cards shown to all members. */
+    interactive?: boolean;
+    cardPreview: RuntimeCardPreview;
+    turnSemantics: 'control';
+    replyBehavior: 'suppress_auto_reply';
+}
+export interface RuntimeCardReplyMetadata {
+    type: 'runtime_card_reply';
+    cardId: string;
+    status: RuntimeCardReplyStatus;
+    actionId?: string;
+    answerSummary?: string;
+    sensitive?: boolean;
+    turnSemantics: 'control';
+    replyBehavior: 'suppress_auto_reply';
+}
+export interface RuntimeCardOutcomeMetadata {
+    type: 'runtime_card_outcome';
+    cardId: string;
+    status: RuntimeCardResolutionStatus;
+    reason?: 'submitted' | 'cancelled' | 'timeout' | 'expired' | 'interrupted';
+    turnSemantics: 'control';
+    replyBehavior: 'suppress_auto_reply';
+}
+/**
+ * Mac-app parity: a choice-bearing question always offers a free-text "Other"
+ * escape hatch unless the producing agent explicitly opts out. Shared by every
+ * runtime's question mapper so the fallback is consistent across agents.
+ */
+export declare function resolveQuestionAllowOther(hasChoices: boolean, explicit?: unknown): boolean;
+/** Block kinds this version of core knows how to fully normalize/render. */
+export type RuntimeCardKnownBlockKind = 'summary' | 'metricGrid' | 'chart' | 'table' | 'list' | 'callout' | 'actions' | 'mediaPreview' | 'details';
+export declare function parseRuntimeCardV1(value: unknown): RuntimeCardV1 | null;
+export declare function buildRuntimeCardPreview(card: RuntimeCardV1): RuntimeCardPreview;
+export declare function buildRuntimeInputRequest(inputId: string, input: Omit<RuntimeInputRequestMetadata, 'type' | 'inputId'>): {
+    text: string;
+    metadata: RuntimeInputRequestMetadata;
+};
+export declare function buildRuntimeInputReply(inputId: string, status: RuntimeInputReplyStatus, details?: {
+    kind?: RuntimeInputKind;
+    answerSummary?: string;
+    answersSummary?: string;
+    sensitive?: boolean;
+}): {
+    text: string;
+    metadata: RuntimeInputReplyMetadata;
+};
+export declare function buildRuntimeInputOutcome(inputId: string, status: RuntimeInputResolutionStatus, details?: {
+    kind?: RuntimeInputKind;
+    reason?: RuntimeInputOutcomeMetadata['reason'];
+}): {
+    text: string;
+    metadata: RuntimeInputOutcomeMetadata;
+};
+export declare function buildRuntimeCardRequest(card: RuntimeCardV1, input: {
+    cardId?: string;
+    responseUserId?: string;
+    expiresAt: string | number | Date;
+    runtimeId?: string;
+    turnId?: string;
+    native?: RuntimeCardNativeMetadata;
+}): {
+    text: string;
+    metadata: RuntimeCardRequestMetadata;
+};
+export declare function buildRuntimeCardReply(cardId: string, status: RuntimeCardReplyStatus, details?: {
+    actionId?: string;
+    answerSummary?: string;
+    sensitive?: boolean;
+}): {
+    text: string;
+    metadata: RuntimeCardReplyMetadata;
+};
+export declare function buildRuntimeCardOutcome(cardId: string, status: RuntimeCardResolutionStatus, details?: {
+    reason?: RuntimeCardOutcomeMetadata['reason'];
+}): {
+    text: string;
+    metadata: RuntimeCardOutcomeMetadata;
+};
+export declare function parseRuntimeInputRequestMetadata(value: unknown): RuntimeInputRequestMetadata | null;
+export declare function parseRuntimeCardRequestMetadata(value: unknown): RuntimeCardRequestMetadata | null;
+export declare function parseRuntimeCardReplyMetadata(value: unknown): RuntimeCardReplyMetadata | null;
+export declare function parseRuntimeCardOutcomeMetadata(value: unknown): RuntimeCardOutcomeMetadata | null;
+export declare function parseRuntimeInputReplyMetadata(value: unknown): RuntimeInputReplyMetadata | null;
+export declare function parseRuntimeInputOutcomeMetadata(value: unknown): RuntimeInputOutcomeMetadata | null;

package/dist/internal/core/runtime-descriptor.d.ts

@@ -0,0 +1,75 @@
+export { normalizeRuntimeCommandAlias, normalizeRuntimeCommandAliases } from '../backend-contracts/index.js';
+import type { ExecutionEnvironmentMode } from './execution-environment-mode.js';
+import { type AgentCapabilities, type AgentClientType, type CanonControlDescriptor, type CanonControlLiveBehavior, type CanonRuntimeCommandDescriptor, type CanonRuntimeDescriptor, type CanonRuntimeStreamingMode, type CanonRuntimeTurnModeDescriptor, type CanonWorkspaceRootMetadata, type ModelOption, type PermissionModeOption, type WorkspaceOption } from './types.js';
+import type { CanonRuntimePresentationPolicy } from './types.js';
+import type { HostAdmissionActionCapabilities } from './turn-protocol.js';
+export interface NormalizeRuntimeCommandDescriptorsOptions {
+    reservedAliases?: Iterable<string>;
+    maxCommands?: number;
+}
+export declare function normalizeRuntimeCommandDescriptors(commands: ReadonlyArray<CanonRuntimeCommandDescriptor>, options?: NormalizeRuntimeCommandDescriptorsOptions): CanonRuntimeCommandDescriptor[];
+/**
+ * Default reasoning/thinking-level options. This is plain data, not Claude
+ * logic — any coding agent can reuse it or supply its own option set. Each
+ * agent passes its native effort levels into the shared descriptor builder.
+ */
+export declare const EFFORT_OPTIONS: readonly [{
+    readonly value: "low";
+    readonly label: "Low";
+}, {
+    readonly value: "medium";
+    readonly label: "Medium";
+}, {
+    readonly value: "high";
+    readonly label: "High";
+}, {
+    readonly value: "xhigh";
+    readonly label: "Extra high";
+}, {
+    readonly value: "max";
+    readonly label: "Max";
+}];
+export declare const EXECUTION_MODE_CONTROL_OPTIONS: ReadonlyArray<{
+    value: ExecutionEnvironmentMode;
+    label: string;
+    description: string;
+}>;
+export declare function buildRuntimeWorkspaceControlOptions(workspaces: ReadonlyArray<WorkspaceOption>): ModelOption[];
+export declare const RUNTIME_STOP_ACTION: CanonRuntimeCommandDescriptor;
+export declare const RUNTIME_STOP_AND_DROP_ACTION: CanonRuntimeCommandDescriptor;
+export declare const RUNTIME_NEW_SESSION_ACTION: CanonRuntimeCommandDescriptor;
+export declare function buildFirstPartyCodingRuntimeDescriptor(input: {
+    /**
+     * Any agent client type may use this builder. Per-agent differences are
+     * driven by the {@link AGENT_CAPABILITIES} table and the option/behavior
+     * fields below — not by hard-coded clientType branches — so adding a coding
+     * agent is a capability-table entry plus its own option lists.
+     */
+    clientType: AgentClientType;
+    models: ReadonlyArray<ModelOption>;
+    workspaces: ReadonlyArray<WorkspaceOption>;
+    workspaceRoots?: ReadonlyArray<CanonWorkspaceRootMetadata>;
+    executionModes: ReadonlyArray<ExecutionEnvironmentMode>;
+    /** Deployer-owned local default used when a conversation has no override. */
+    defaultExecutionMode?: ExecutionEnvironmentMode;
+    permissionModes?: ReadonlyArray<PermissionModeOption>;
+    defaultPermissionMode?: string | null;
+    /** Permission-mode control label override (e.g. Codex uses "Execution policy"). */
+    permissionModeLabel?: string;
+    /** Effort/thinking-level options. When provided, an effort control is emitted. */
+    effortOptions?: ReadonlyArray<ModelOption>;
+    defaultEffort?: string | null;
+    effortLiveBehavior?: CanonControlLiveBehavior;
+    /** Model control live behavior. Defaults to immediate; Codex applies next turn. */
+    modelLiveBehavior?: 'immediate' | 'next_turn';
+    /** Capability overrides; defaults to the AGENT_CAPABILITIES entry for clientType. */
+    capabilities?: AgentCapabilities;
+    commands?: ReadonlyArray<CanonRuntimeCommandDescriptor>;
+    turnModes?: ReadonlyArray<CanonRuntimeTurnModeDescriptor>;
+    /** Extra runtime controls appended after the built-in effort control. */
+    extraRuntimeControls?: ReadonlyArray<CanonControlDescriptor>;
+    streamingTextMode: CanonRuntimeStreamingMode;
+    admissionActions?: HostAdmissionActionCapabilities;
+    presentation?: CanonRuntimePresentationPolicy;
+    runtimeCards?: CanonRuntimeDescriptor['runtimeCards'];
+}): CanonRuntimeDescriptor;