@canonmsg/agent-sdk 11.2.1 → 12.1.0

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

@@ -0,0 +1,286 @@
+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 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';
+}
+/** 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 buildRuntimeInputOutcome(inputId: string, status: RuntimeInputResolutionStatus, details?: {
+    kind?: RuntimeInputKind;
+    reason?: RuntimeInputOutcomeMetadata['reason'];
+}): {
+    text: string;
+    metadata: RuntimeInputOutcomeMetadata;
+};
+export declare function buildRuntimeCardOutcome(cardId: string, status: RuntimeCardResolutionStatus, details?: {
+    reason?: RuntimeCardOutcomeMetadata['reason'];
+}): {
+    text: string;
+    metadata: RuntimeCardOutcomeMetadata;
+};

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

@@ -0,0 +1,16 @@
+export { normalizeRuntimeCommandAlias, normalizeRuntimeCommandAliases } from '../backend-contracts/index.js';
+import type { ExecutionEnvironmentMode } from './execution-environment-mode.js';
+import type { CanonRuntimeCommandDescriptor } from './types.js';
+export interface NormalizeRuntimeCommandDescriptorsOptions {
+    reservedAliases?: Iterable<string>;
+    maxCommands?: number;
+}
+export declare function normalizeRuntimeCommandDescriptors(commands: ReadonlyArray<CanonRuntimeCommandDescriptor>, options?: NormalizeRuntimeCommandDescriptorsOptions): CanonRuntimeCommandDescriptor[];
+export declare const EXECUTION_MODE_CONTROL_OPTIONS: ReadonlyArray<{
+    value: ExecutionEnvironmentMode;
+    label: string;
+    description: string;
+}>;
+export declare const RUNTIME_STOP_ACTION: CanonRuntimeCommandDescriptor;
+export declare const RUNTIME_STOP_AND_DROP_ACTION: CanonRuntimeCommandDescriptor;
+export declare const RUNTIME_NEW_SESSION_ACTION: CanonRuntimeCommandDescriptor;

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

@@ -0,0 +1,26 @@
+import { type CanonEnvironmentId } from '../backend-contracts/index.js';
+export interface CanonRuntimeEndpointDefaults {
+    apiBaseUrl: string;
+    streamUrl: string;
+    rtdbUrl: string;
+    firebaseWebApiKey: string;
+}
+export interface CanonRuntimeConnectionOptions {
+    environmentId: string;
+    apiBaseUrl?: string | null;
+    streamUrl?: string | null;
+    rtdbUrl?: string | null;
+    firebaseWebApiKey?: string | null;
+}
+export interface CanonRuntimeConnection extends CanonRuntimeEndpointDefaults {
+    environmentId: CanonEnvironmentId;
+    projectId: string;
+    region: string;
+}
+export declare const CANON_RUNTIME_ENDPOINT_DEFAULTS: Readonly<Partial<Record<CanonEnvironmentId, CanonRuntimeEndpointDefaults>>>;
+export declare const DEFAULT_CANON_ENVIRONMENT_ID: "canon-dev-v1" | "canon-prod-v1";
+export declare function getCanonRuntimeEndpointDefaults(environmentId: string): CanonRuntimeEndpointDefaults | null;
+export declare function requireCanonRuntimeEndpointDefaults(environmentId: string): CanonRuntimeEndpointDefaults;
+export declare function resolveCanonRuntimeConnection(options: CanonRuntimeConnectionOptions): CanonRuntimeConnection;
+export declare function verifyCanonRuntimeConnection(connection: CanonRuntimeConnection, fetchImpl?: typeof fetch): Promise<void>;
+export declare const DEFAULT_CANON_RUNTIME_ENDPOINTS: CanonRuntimeEndpointDefaults;

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

@@ -0,0 +1,29 @@
+import type { RuntimeStatePublisher } from './runtime-state-publisher.js';
+import type { AgentRuntime } from './types.js';
+export type RuntimeHeartbeatOperation = 'publish' | 'refresh-details' | 'clear' | 'clear-details';
+export interface RuntimeHeartbeatOptions {
+    /** Retain one publisher so clearing preserves its last public descriptor. */
+    publisher: Pick<RuntimeStatePublisher, 'publishAgentRuntime' | 'clearAgentRuntime'>;
+    getRuntime: () => AgentRuntime;
+    intervalMs?: number;
+    /** Slow work has its own serialized lane; observe cancellation before writing. */
+    refreshDetails?: (signal: AbortSignal) => Promise<void>;
+    /** Runs after any in-flight detail refresh, including during disposal. */
+    clearDetails?: () => Promise<void>;
+    onError: (error: unknown, operation: RuntimeHeartbeatOperation) => void;
+}
+export interface RuntimeHeartbeat {
+    connect(): void;
+    disconnect(): Promise<void>;
+    /** Publish a changed descriptor and request fresh details while connected. */
+    refresh(): void;
+    /** Terminal, idempotent cleanup. Create a new controller to restart. */
+    dispose(): Promise<void>;
+}
+/**
+ * Connection-scoped publication over a retained runtime publisher. Liveness
+ * and slow details have independent lanes, each with at most one queued refresh.
+ * Connection generations discard obsolete queued work; in-flight writes finish
+ * before the next clear/publish so a late write cannot restore stale liveness.
+ */
+export declare function createRuntimeHeartbeat(options: RuntimeHeartbeatOptions): RuntimeHeartbeat;

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

@@ -0,0 +1,9 @@
+import type { AgentSessionSnapshot, CanonRuntimeActivityItem, CanonRuntimeDescriptor, CanonRuntimePresentationField, RuntimeInfoPayload } from './types.js';
+export declare function isRuntimePresentationFieldHidden(descriptor: CanonRuntimeDescriptor | null | undefined, field: CanonRuntimePresentationField): boolean;
+export declare function redactRuntimeActivityItemForConversation(item: CanonRuntimeActivityItem): CanonRuntimeActivityItem | null;
+export declare function redactRuntimeInfoForConversation<T extends Partial<Omit<RuntimeInfoPayload, 'updatedAt'>> | RuntimeInfoPayload>(payload: T, options?: {
+    descriptor?: CanonRuntimeDescriptor | null;
+}): T;
+export declare function redactAgentSessionSnapshotForConversation(descriptor: CanonRuntimeDescriptor | null | undefined, snapshot: Partial<AgentSessionSnapshot> & Record<string, unknown>, options?: {
+    patch?: boolean;
+}): Partial<AgentSessionSnapshot> & Record<string, unknown>;

package/dist/internal/core/runtime-request-manager.d.ts

@@ -0,0 +1,283 @@
+import type { CanonClient } from './client.js';
+import type { SessionRule } from './approval-types.js';
+import type { RuntimeCardV1, RuntimeCardNativeMetadata, RuntimeInputAnswers, RuntimeInputChoice, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputQuestion } from './runtime-cards.js';
+/**
+ * The five runtime request families. `contact` is non-interactive (no pending
+ * node / no manager loop); the other four flow through {@link RuntimeRequestManager}.
+ */
+export type RuntimeRequestKind = 'contact' | 'approval' | 'input' | 'plan' | 'card';
+export interface RuntimeRequestContext {
+    agentId: string;
+    ownerId: string;
+}
+/** Normalized outcome of a single consume poll. */
+export type RuntimeConsumeOutcome<Result> = {
+    state: 'pending';
+} | {
+    state: 'resolved';
+    result: Result;
+} | {
+    state: 'timeout';
+};
+/** Outcome message the host emits after a request settles (via `onOutcome`). */
+export interface RuntimeOutcomeMessage {
+    text: string;
+    metadata: Record<string, unknown>;
+}
+/**
+ * Everything the descriptor's create step surfaced to the host, handed to
+ * `onCreated`. Hosts that must sequence side effects on the server response
+ * (turn blocks, streaming state, display-vs-poll control flow) read these
+ * instead of re-deriving them.
+ */
+export interface RuntimeCreateResult {
+    requestId: string;
+    messageId?: string;
+    /** Card family: whether the created card is interactive (a response is pending). */
+    interactive?: boolean;
+    expiresAt?: number;
+}
+/**
+ * How the built-in input/card descriptors pick `responseUserId` when the payload
+ * does not set it explicitly. An explicit `payload.responseUserId` always wins.
+ * - `'owner'` — fall back to `ctx.ownerId` (omit when that is empty).
+ * - `'infer'` — omit, so the backend targets the owner if present else the sole
+ *   other member (correct for agent→user DMs where the owner is not a member).
+ */
+export type ResponderPolicy = 'owner' | 'infer';
+export interface RuntimeRequestOptions {
+    /** Caller-chosen request id. When omitted the descriptor generates one. */
+    requestId?: string;
+    /** Absolute deadline (epoch ms). Overrides `timeoutMs`. */
+    expiresAt?: number;
+    timeoutMs?: number;
+    pollMs?: number;
+    signal?: AbortSignal;
+    /** Responder fallback for the built-in input/card create (see {@link ResponderPolicy}). */
+    responderPolicy?: ResponderPolicy;
+    /** Host side effects immediately after the server request is created (turn block, typing). */
+    onCreated?: (created: RuntimeCreateResult) => void | Promise<void>;
+    /** Host emits the durable outcome message after the request settles. */
+    onOutcome?: (outcome: RuntimeOutcomeMessage) => void | Promise<void>;
+}
+/** Error used to reject an in-flight request that is explicitly cancelled. */
+export declare class RuntimeRequestCancelledError extends Error {
+    constructor(message?: string);
+}
+export interface RuntimeRequestCallInput<Payload, State> {
+    client: CanonClient;
+    ctx: RuntimeRequestContext;
+    conversationId: string;
+    requestId: string;
+    payload: Payload;
+    /** Resolved absolute deadline (epoch ms). */
+    expiresAt: number;
+    state: State | undefined;
+}
+export interface RuntimeRequestPreflightInput<Payload> {
+    client: CanonClient;
+    ctx: RuntimeRequestContext;
+    conversationId: string;
+    payload: Payload;
+    options: RuntimeRequestOptions;
+}
+export interface RuntimeRequestPushInput {
+    conversationId: string;
+    message: {
+        senderId: string;
+        metadata?: Record<string, unknown>;
+    };
+    ctx: RuntimeRequestContext;
+}
+export interface RuntimeRequestPushMatch {
+    requestId: string;
+}
+/**
+ * Everything that varies per request family. The engine ({@link RuntimeRequestManager})
+ * owns the pending map, timers, poll/notify/abort loop and cancellation; the
+ * descriptor supplies only the family-specific pieces.
+ */
+export interface KindDescriptor<Payload = unknown, Result = unknown, State = unknown> {
+    readonly kind: RuntimeRequestKind;
+    /** Fresh request id when the caller supplies none. */
+    generateId(payload: Payload): string;
+    /** Deadline for this request (epoch ms). Falls back to options / default when omitted. */
+    resolveExpiry?(input: {
+        payload: Payload;
+        options: RuntimeRequestOptions;
+    }): number | undefined;
+    /** Poll cadence (ms). Defaults to the manager default. */
+    pollMs?(payload: Payload): number;
+    /**
+     * Optional immediate resolution BEFORE any server request is created (e.g. the
+     * approval session-rule fast path). Returning a result skips create + poll.
+     */
+    preflight?(input: RuntimeRequestPreflightInput<Payload>): Result | null;
+    /**
+     * Create the server-side request; returns the effective id + optional per-request
+     * state, plus any create-response fields the host needs back (surfaced via
+     * {@link RuntimeCreateResult} to `onCreated`).
+     */
+    create(input: RuntimeRequestCallInput<Payload, State> & {
+        options: RuntimeRequestOptions;
+    }): Promise<{
+        requestId: string;
+        expiresAt?: number;
+        state?: State;
+        messageId?: string;
+        interactive?: boolean;
+    }>;
+    /** Poll the server once and interpret the response. */
+    consume(input: RuntimeRequestCallInput<Payload, State>): Promise<RuntimeConsumeOutcome<Result>>;
+    /** Best-effort cancellation (abort / explicit cancel / dispose). */
+    cancel?(input: RuntimeRequestCallInput<Payload, State>): Promise<void>;
+    /** Result produced when the local deadline fires. */
+    timeoutResult(input: RuntimeRequestCallInput<Payload, State>): Result;
+    /**
+     * Finalization side effects + optional result override. Runs on `replied` /
+     * `timeout` (never `aborted`). Approval uses this to store the accepted session
+     * rule and emit its own outcome messages; returning a result lets it narrow the
+     * accepted rule into the returned value.
+     */
+    finalize?(input: RuntimeRequestCallInput<Payload, State> & {
+        result: Result;
+        reason: 'replied' | 'timeout';
+    }): Result | void;
+    /** Outcome message for the host to emit via `onOutcome` (input/card families). */
+    buildOutcome?(input: RuntimeRequestCallInput<Payload, State> & {
+        result: Result;
+        reason: 'replied' | 'timeout';
+    }): RuntimeOutcomeMessage | null;
+    /** Map an inbound push message to a pending request that should poll now. */
+    matchPush?(input: RuntimeRequestPushInput): RuntimeRequestPushMatch | null;
+}
+/**
+ * Platform-agnostic engine for Canon's interactive runtime requests.
+ *
+ * Generalizes the former `ApprovalManager`: it owns the pending map, deadline
+ * timers, the poll-with-abort loop that races an inbound push wakeup, and
+ * cancellation — all keyed by {@link KindDescriptor}. Approval, runtime input,
+ * runtime card, and plan families register over the same primitive; the former
+ * hand-written await-loops collapse into `request()`.
+ *
+ * Session-rule storage lives here because the approval descriptor's preflight /
+ * finalize read and write it; other families ignore it.
+ */
+export declare class RuntimeRequestManager {
+    protected client: CanonClient;
+    protected ctx: RuntimeRequestContext;
+    private descriptors;
+    private pending;
+    private rules;
+    constructor(client: CanonClient, ctx: RuntimeRequestContext);
+    /** Register (or override) the descriptor for a kind. */
+    register<Payload, Result, State>(kind: RuntimeRequestKind, descriptor: KindDescriptor<Payload, Result, State>): void;
+    /** Built-in input, card, and plan descriptors. Subclasses add approval policy. */
+    protected registerBuiltins(): void;
+    get pendingCount(): number;
+    /**
+     * Run one interactive runtime request end to end:
+     * preflight → create → onCreated → register pending → poll (racing push wakeup
+     * and abort) → post-deadline consume → finalize → onOutcome → resolve.
+     */
+    request<Payload, Result, State = unknown>(kind: RuntimeRequestKind, conversationId: string, payload: Payload, options?: RuntimeRequestOptions): Promise<Result>;
+    /** Push short-circuit: wake the pending request's poll to consume immediately. */
+    notify(kind: RuntimeRequestKind, conversationId: string, requestId: string): void;
+    /**
+     * Feed an inbound message to the manager. Returns true when a matching pending
+     * request was woken to consume canonical state. Receipt metadata never settles
+     * the request directly. Fails closed on unknown / mismatched ids.
+     */
+    handleMessage(conversationId: string, message: {
+        senderId: string;
+        metadata?: Record<string, unknown>;
+    }): boolean;
+    /** Cancel a specific pending request (rejects its promise, best-effort server cancel). */
+    cancel(kind: RuntimeRequestKind, conversationId: string, requestId: string): Promise<void>;
+    checkSessionRules(toolName: string, conversationId?: string): SessionRule | null;
+    addSessionRule(conversationId: string, rule: SessionRule): void;
+    getSessionRules(): SessionRule[];
+    clearSessionRules(): void;
+    dispose(): void;
+    protected pruneExpiredRules(): void;
+    /** Sleep that resolves on timeout, on `notify()` wakeup, or when the request settles. */
+    private sleep;
+}
+/** Interactive runtime input (`AskUserQuestion`, secret prompts, choices). */
+export interface RuntimeInputRequestPayload {
+    kind: RuntimeInputKind;
+    title?: string;
+    prompt?: string;
+    choices?: RuntimeInputChoice[];
+    questions?: RuntimeInputQuestion[];
+    secretName?: string;
+    native?: RuntimeInputNativeMetadata;
+    sensitive?: boolean;
+    responseUserId?: string;
+    turnId?: string;
+}
+export type RuntimeInputRequestResult = {
+    status: 'submitted';
+    inputId: string;
+    value: string;
+    answers?: RuntimeInputAnswers;
+} | {
+    status: 'cancelled';
+    inputId: string;
+} | {
+    status: 'timeout';
+    inputId: string;
+};
+export declare const runtimeInputDescriptor: KindDescriptor<RuntimeInputRequestPayload, RuntimeInputRequestResult>;
+/** Interactive runtime card (canon.card.v1 with an actions block). */
+export interface RuntimeCardRequestPayload {
+    card: RuntimeCardV1;
+    responseUserId?: string;
+    runtimeId?: string;
+    turnId?: string;
+    native?: RuntimeCardNativeMetadata;
+}
+export type RuntimeCardRequestResult = {
+    status: 'submitted';
+    cardId: string;
+    actionId?: string;
+    values?: Record<string, unknown>;
+    respondedBy?: string;
+} | {
+    status: 'cancelled';
+    cardId: string;
+    respondedBy?: string;
+} | {
+    status: 'timeout';
+    cardId: string;
+};
+export declare const runtimeCardDescriptor: KindDescriptor<RuntimeCardRequestPayload, RuntimeCardRequestResult>;
+/** Blocking plan review produced by coding runtimes. */
+export interface RuntimePlanRequestPayload {
+    title?: string;
+    summary?: string;
+    body?: string;
+    allowedPrompts?: ReadonlyArray<{
+        tool: string;
+        prompt: string;
+    }>;
+    responseUserId?: string;
+    turnId?: string;
+}
+export type RuntimePlanRequestResult = {
+    status: 'approve' | 'revise' | 'reject';
+    planId: string;
+    feedback?: string;
+    grantedPrompts?: Array<{
+        tool: string;
+        prompt: string;
+    }>;
+    receiptId?: string;
+} | {
+    status: 'cancelled';
+    planId: string;
+} | {
+    status: 'timeout';
+    planId: string;
+};
+export declare const runtimePlanDescriptor: KindDescriptor<RuntimePlanRequestPayload, RuntimePlanRequestResult>;