@canonmsg/agent-sdk 11.2.1 → 12.0.0

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,35 @@
+import type { AgentRuntime, AgentSessionSnapshot, CanonRuntimeActivityItem, CanonRuntimeDescriptor, CanonRuntimePresentationField, CanonRuntimePresentationPolicy, RuntimeInfoPayload } from './types.js';
+export declare const RUNTIME_PRESENTATION_FIELDS: readonly ["model", "permissionMode", "effort", "workspace", "executionMode", "contextUsage", "cwd", "branch", "worktreePath", "workspaceRoot", "workspaceRelativePath", "fallbackReason"];
+export declare const DEFAULT_FIRST_PARTY_RUNTIME_PRESENTATION: CanonRuntimePresentationPolicy;
+export declare function isRuntimePresentationField(value: string): value is CanonRuntimePresentationField;
+export declare function buildRuntimePresentationPolicy(input?: {
+    preset?: CanonRuntimePresentationPolicy['preset'];
+    show?: ReadonlyArray<string>;
+    hide?: ReadonlyArray<string>;
+    base?: CanonRuntimePresentationPolicy;
+}): CanonRuntimePresentationPolicy;
+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 redactAgentRuntimeForConversation(runtime: AgentRuntime): AgentRuntime;
+type SessionStatePresentationLike = {
+    model?: unknown;
+    permissionMode?: unknown;
+    effort?: unknown;
+    cwd?: unknown;
+    executionMode?: unknown;
+    executionBranch?: unknown;
+    worktreePath?: unknown;
+    executionFallbackReason?: unknown;
+    contextUsage?: unknown;
+    availableModels?: unknown;
+    runtimeControlValues?: Record<string, unknown>;
+    controlState?: Record<string, unknown>;
+};
+export declare function redactSessionStateForConversation<T extends SessionStatePresentationLike>(descriptor: CanonRuntimeDescriptor | null | undefined, state: T): T;
+export declare function redactAgentSessionSnapshotForConversation(descriptor: CanonRuntimeDescriptor | null | undefined, snapshot: Partial<AgentSessionSnapshot> & Record<string, unknown>, options?: {
+    patch?: boolean;
+}): Partial<AgentSessionSnapshot> & Record<string, unknown>;
+export {};

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

@@ -0,0 +1,284 @@
+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;
+}
+export type RuntimeResolveReason = 'replied' | 'timeout' | 'aborted';
+/** 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>;

package/dist/internal/core/runtime-state-publisher.d.ts

@@ -0,0 +1,42 @@
+import type { AgentClientType, AgentRuntime, CanonRuntimeActivityItem, RuntimeInfoPayload, TurnOutputBlock } from './types.js';
+import { type AgentSessionSnapshotPatch, type RTDBClientHandle, type SessionStatePayload, type TurnStatePayload } from './rtdb-rest.js';
+export interface RuntimeStatePublisherOptions {
+    agentId: string;
+    clientType: AgentClientType;
+    hostMode: boolean;
+    /** Scoped endpoint-backed runtime-state handle from `initRTDBAuth`. */
+    rtdb: RTDBClientHandle;
+}
+export interface RuntimeStreamingPayload {
+    text: string;
+    status: 'thinking' | 'streaming' | 'tool' | 'waiting_input';
+    messageId?: string;
+    turnId?: string | null;
+    blocks?: TurnOutputBlock[];
+    updatedAt?: number | {
+        '.sv': 'timestamp';
+    };
+}
+export interface ClearRuntimeActivityOptions {
+    itemIds?: ReadonlyArray<string>;
+    terminalOnly?: boolean;
+    olderThanMs?: number;
+    all?: boolean;
+}
+export interface RuntimeStatePublisher {
+    publishAgentRuntime(runtime: AgentRuntime): Promise<void>;
+    clearAgentRuntime(): Promise<void>;
+    writeSessionState(conversationId: string, state: Omit<SessionStatePayload, 'updatedAt'>): Promise<void>;
+    clearSessionState(conversationId: string): Promise<void>;
+    writeTurnState(conversationId: string, state: Omit<TurnStatePayload, 'updatedAt'>): Promise<void>;
+    clearTurnState(conversationId: string): Promise<void>;
+    patchAgentSessionSnapshot(conversationId: string, snapshot: Omit<AgentSessionSnapshotPatch, 'updatedAt'>): Promise<void>;
+    writeRuntimeInfo(conversationId: string, payload: Omit<RuntimeInfoPayload, 'updatedAt'>): Promise<void>;
+    patchRuntimeInfo(conversationId: string, payload: Partial<Omit<RuntimeInfoPayload, 'updatedAt'>>): Promise<void>;
+    clearRuntimeInfo(conversationId: string): Promise<void>;
+    writeRuntimeActivity(conversationId: string, item: CanonRuntimeActivityItem): Promise<void>;
+    clearRuntimeActivity(conversationId: string, options?: ClearRuntimeActivityOptions): Promise<void>;
+    writeStreaming(conversationId: string, payload: RuntimeStreamingPayload): Promise<void>;
+    clearStreaming(conversationId: string): Promise<void>;
+}
+export declare function createRuntimeStatePublisher(options: RuntimeStatePublisherOptions): RuntimeStatePublisher;

package/dist/internal/core/self-context.d.ts

@@ -0,0 +1,61 @@
+export type CanonSelfContextType = 'cross_session';
+export interface CanonSelfContext {
+    id: string;
+    type: CanonSelfContextType;
+    context: string;
+    /** Public message sent with this private explanation. */
+    targetMessageId?: string | null;
+    /** The Canon room that originated an older cross-session action. */
+    sourceConversationId?: string | null;
+    /** A local task may originate an action without having its own Canon room. */
+    externalSource?: {
+        kind: 'external';
+        integration: 'codex';
+        label?: string;
+    } | null;
+    /** Public target text hydrated from this room; never stored in the private note. */
+    targetMessageText?: string | null;
+    /** Public message time hydrated at delivery, used to order recent actions. */
+    targetMessageCreatedAt?: string | null;
+    createdAt?: string | null;
+    updatedAt?: string | null;
+}
+export interface SelfContextPromptRenderOptions {
+    maxSelfContexts?: number;
+}
+export declare function normalizeSelfContexts(selfContexts?: CanonSelfContext[] | null, options?: SelfContextPromptRenderOptions): CanonSelfContext[];
+export declare function resolveMessageActiveSelfContextId(input: {
+    messageId?: string | null;
+    activeSelfContextId?: string | null;
+    activeSelfContextIdByMessageId?: Record<string, string> | null;
+}): string | null;
+export declare function selectActiveSelfContexts(selfContexts?: CanonSelfContext[] | null, activeSelfContextId?: string | null): CanonSelfContext[];
+/**
+ * Select private explanations for one inbound turn. A reply can activate only
+ * the explanation attached to its exact target. Other recent explanations are
+ * background, not a claim that the incoming message answers any one of them.
+ */
+export declare function selectInboundSelfContexts(input: {
+    selfContexts?: CanonSelfContext[] | null;
+    replyTo?: string | null;
+    /** Backend-validated association for this inbound message, when available. */
+    linkedSelfContextId?: string | null;
+    messages?: ReadonlyArray<{
+        id?: string | null;
+        text?: string | null;
+        createdAt?: string | null;
+        deleted?: boolean | null;
+    }> | null;
+    replyContext?: {
+        messageId: string;
+        text?: string | null;
+        found: boolean;
+    } | null;
+    maxSelfContexts?: number;
+}): {
+    activeSelfContextId: string | null;
+    selfContexts: CanonSelfContext[];
+};
+export declare function buildSelfContextPromptLines(selfContexts?: CanonSelfContext[] | null, options?: SelfContextPromptRenderOptions & {
+    activeSelfContextId?: string | null;
+}): string[];

package/dist/internal/core/silent-turn.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Deliberate silence — the shared half of the `no_reply` verb.
+ *
+ * A turn that calls `no_reply` must end without posting anything: the trigger
+ * gate is message-driven, so no message means no other agent is woken. Every
+ * host wires its own teardown, but they all ask the same question here.
+ */
+/**
+ * The model-facing closure sentence, re-exported so a runtime that answers
+ * `no_reply` locally reads it from the same definition the server sends. It is
+ * DEFINED in @canonmsg/backend-contracts because that is the only package both
+ * the server and the hosts depend on.
+ */
+export { NO_REPLY_ACK_NOTE } from '../backend-contracts/index.js';
+import { type CanonVerbWireRequest } from '../backend-contracts/index.js';
+/** The one client capability the outcome report needs. */
+export interface NoReplyReportClient {
+    executeVerbWire(wire: CanonVerbWireRequest): Promise<unknown>;
+}
+/**
+ * What `reportNoReplyOutcome` puts on the wire in place of any caller-supplied
+ * reason text. The server stores only `hasReason` and discards the text, so
+ * transmitting the model- or handler-authored sentence would be pure exposure:
+ * the sentinel preserves the server's `hasReason` signal without moving the
+ * text. The reason a binding was handed never leaves its process.
+ */
+export declare const NO_REPLY_REASON_SENTINEL = "given";
+/**
+ * Report a locally-answered `no_reply` to the server, fire-and-forget.
+ *
+ * Four of the five runtimes answer the silence tool inside their own process
+ * and never reach `POST /agent/verbs/no_reply`, so Canon's durable record of
+ * deliberate silence (`/runtime-silence/{convoId}/{agentId}`) would otherwise
+ * cover Claude turns only. This is telemetry, not behavior: the silence flag
+ * is already set locally before this is called, so a failed or unreachable
+ * report degrades to exactly the pre-report behavior — never to a posted
+ * message and never to a failed turn.
+ *
+ * `params.reason` is read only for its presence: the wire carries
+ * `NO_REPLY_REASON_SENTINEL` in its place, never the caller's text.
+ *
+ * The Claude host must NOT call this helper: its binding already POSTs the
+ * verb via agent-tools, so calling both would double-record the silence.
+ */
+export declare function reportNoReplyOutcome(client: NoReplyReportClient, params: {
+    conversationId: string;
+    messageId?: string;
+    reason?: string;
+    now?: number;
+}): void;
+/**
+ * Owner ruling 2026-07-31 (docs/history/group-behavior-2026-08-01.md), as
+ * implemented. `strict` (default): a no_reply call suppresses the final
+ * unconditionally. `advisory`: non-empty final text overrides the sentinel.
+ * ONE switch, so the ruling can be flipped without touching five hosts.
+ */
+export type SilentTurnPrecedence = 'strict' | 'advisory';
+export declare const DEFAULT_SILENT_TURN_PRECEDENCE: SilentTurnPrecedence;
+export declare function resolveSilentTurnDelivery(input: {
+    silenced: boolean;
+    finalText: string | null | undefined;
+    precedence?: SilentTurnPrecedence;
+}): 'deliver' | 'suppress';
+/**
+ * Whether SILENCE is what withholds this turn's own output — the single
+ * question every consumer of the ruling asks, so they cannot disagree.
+ *
+ * `resolveSilentTurnDelivery` answers "is there anything to deliver", which
+ * also returns `suppress` for an ordinary turn that simply produced no text.
+ * A caller deciding what ELSE a silenced turn withholds — its workspace
+ * artifacts, its plan card — needs the narrower question, and deriving it by
+ * hand (`silenced && ...`) is how a second, independent reading of
+ * `DEFAULT_SILENT_TURN_PRECEDENCE` creeps in. Flipping that constant to
+ * `advisory` must move a turn's text and its artifacts together: a turn that
+ * talks about the chart it made and then ships no chart is worse than either
+ * consistent behaviour.
+ *
+ * `finalText` is the MODEL's own text for the turn — never Canon's failure
+ * notice, which is a host diagnostic rather than something the model said, and
+ * which is delivered whether the turn went silent or not.
+ */
+export declare function isSilentTurnSuppressed(input: {
+    silenced: boolean;
+    finalText: string | null | undefined;
+    precedence?: SilentTurnPrecedence;
+}): boolean;

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

@@ -0,0 +1,77 @@
+import type { CanonEndpoint } from './endpoint-client.js';
+import type { AgentContext, ContactAddedPayload, ContactRemovedPayload, ConversationUpdatedPayload, MessageCreatedPayload, MessageUpdatedPayload, TypingPayload, PresencePayload, RuntimeUpdatedPayload, RuntimeControlEventPayload, TurnUpdatedPayload, ParticipationSuppressedPayload, VoiceSessionEventPayload } from './types.js';
+export interface CanonStreamErrorPayload {
+    code?: string;
+    message?: string;
+    retryAfterMs?: number;
+    activeConnections?: number;
+    maxConnections?: number;
+    [key: string]: unknown;
+}
+export interface ReplayExpiredPayload {
+    /** Oldest event id still available in the server's replay buffer, if any. */
+    lastAvailableId?: string | null;
+    message?: string;
+    [key: string]: unknown;
+}
+export declare class CanonStreamError extends Error {
+    readonly code?: string;
+    readonly retryAfterMs?: number;
+    readonly payload: CanonStreamErrorPayload;
+    constructor(payload: CanonStreamErrorPayload, fallbackMessage: string);
+}
+export type StreamHandler = {
+    onMessage: (payload: MessageCreatedPayload) => void;
+    onMessageUpdated?: (payload: MessageUpdatedPayload) => void;
+    onAgentContext?: (ctx: AgentContext) => void;
+    onContactAdded?: (payload: ContactAddedPayload) => void;
+    onContactRemoved?: (payload: ContactRemovedPayload) => void;
+    onTyping?: (data: TypingPayload) => void;
+    onPresence?: (data: PresencePayload) => void;
+    onRuntimeUpdated?: (payload: RuntimeUpdatedPayload) => void;
+    onTurnUpdated?: (payload: TurnUpdatedPayload) => void;
+    /** Observe-only: the participation gate suppressed a turn for this agent. */
+    onParticipationSuppressed?: (payload: ParticipationSuppressedPayload) => void;
+    onRuntimeControl?: (payload: RuntimeControlEventPayload) => void;
+    onVoiceSessionStarted?: (payload: VoiceSessionEventPayload) => void;
+    onVoiceSessionEnded?: (payload: VoiceSessionEventPayload) => void;
+    onMessageDeleted?: (payload: {
+        conversationId: string;
+        messageId: string;
+    }) => void;
+    onConversationUpdated?: (payload: ConversationUpdatedPayload) => void;
+    onConnected?: () => void;
+    onDisconnected?: () => void;
+    /**
+     * Fired when the server reports the replay window expired (`replay.expired`):
+     * the reconnect cursor was evicted, so events in the gap were NOT replayed
+     * and must be recovered out-of-band (e.g. via the REST API). The transport
+     * stays policy-free — it only clears its cursor and surfaces the expiry.
+     *
+     * When this handler is provided it REPLACES the synthetic
+     * `Replay expired — some messages may have been missed` error on `onError`;
+     * raw consumers that only register `onError` keep the existing behavior.
+     */
+    onReplayExpired?: (payload: ReplayExpiredPayload) => void;
+    onError?: (error: Error) => void;
+};
+/** Typed agent event projection; the endpoint owns authentication, SSE and reconnect. */
+export declare class CanonStream {
+    private readonly endpoint;
+    private readonly agentId;
+    private readonly handler;
+    private unsubscribe?;
+    private releaseRecovery?;
+    private running;
+    private generation;
+    private resolveStopped?;
+    constructor(options: {
+        endpoint: CanonEndpoint;
+        agentId: string;
+        handler: StreamHandler;
+    });
+    start(): Promise<void>;
+    private forwardPlaintextMessage;
+    stop(): void;
+    isRunning(): boolean;
+}