@canonmsg/agent-sdk 11.2.1 → 12.1.0

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,22 @@
+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;
+}

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

@@ -0,0 +1,49 @@
+/**
+ * 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.
+ */
+/**
+ * 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;

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

@@ -0,0 +1,78 @@
+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;
+    /** `conversationId` names the room when endpoint recovery failed for one. */
+    onError?: (error: Error, conversationId?: string) => 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;
+}

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

@@ -0,0 +1,28 @@
+import type { DeliveryIntent, TurnLifecycleState } from '../backend-contracts/index.js';
+export { ACTIVE_TURN_STALE_THRESHOLD_MS, WAITING_INPUT_STALE_THRESHOLD_MS, getTurnStateStaleThresholdMs, isTurnOpen, isTurnStateStale, normalizeTurnMetadata, resolveTurnMessageSemantics, shouldPromoteConversationMessage, shouldTriggerAgentTurn, } from '../backend-contracts/index.js';
+export type { DeliveryIntent, InboundDisposition, TriggerDecision, TurnLifecycleState, TurnMessageSemantics, TurnMetadata, } from '../backend-contracts/index.js';
+export interface RuntimeCapabilities {
+    supportsInterrupt: boolean;
+    supportsInputInterrupt: boolean;
+    supportsQueue: boolean;
+    supportsInterleave: boolean;
+    supportsRequiresAction: boolean;
+    supportsNonFinalPermanentMessages: boolean;
+}
+export interface TurnState {
+    turnId?: string | null;
+    state: TurnLifecycleState;
+    queueDepth: number;
+    currentSpeakerId?: string | null;
+    lastAcceptedIntent?: DeliveryIntent | null;
+    activeMessageIds?: string[];
+    capabilities?: RuntimeCapabilities;
+    openedAt?: number;
+    turnUpdatedAt?: number | null;
+    updatedAt?: number;
+    completedAt?: number | null;
+}
+/** The one optional proactive communication capability a runtime may expose. */
+export interface HostAdmissionActionCapabilities {
+    communicate: boolean;
+}

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

@@ -0,0 +1,85 @@
+/**
+ * Turn verbosity — how much of a turn's middle the reader sees.
+ *
+ * `quiet` = the thinking indicator and the final message only: no `/streaming`
+ * narration and no runtime-generated per-tool-call step output. Emission the
+ * DEVELOPER asks for explicitly is not narration and survives — owner ruling
+ * D1: `replyProgress(text, { durable: true })` keeps its durable send, and only
+ * the implicit `/streaming` half is gated. Interaction requests and their
+ * `control` outcome receipts are real interactions, not steps, and are
+ * untouched in both modes; the duplicate trail rows that summarize them go with
+ * the trail (D4).
+ *
+ * Owner ruling 5, 2026-07-31 (docs/history/group-behavior-2026-08-01.md): configured
+ * by the AGENT DEVELOPER per host/SDK, never by Canon and never per
+ * conversation by users. ONE resolver so five integrations cannot disagree.
+ *
+ * This lives in @canonmsg/core rather than @canonmsg/backend-contracts because
+ * quiet mode has no server participant: it is emission control at the agent
+ * side. Nothing on the server reads it, no verb carries it, and clients need
+ * no change — they simply have nothing to render.
+ *
+ * Notes for the runtimes that consume this (the guards are per-integration):
+ * - Suppress by CALL SITE, never by `turnSemantics === 'progress'` (D5): the
+ *   leading parts of a chunked final carry that semantic and are answer body.
+ * - A quiet turn still clears `/streaming` at turn open (a surviving node from
+ *   an earlier turn would otherwise strand a stale bubble), still writes
+ *   `/turn-state`, and still writes `/typing`. Quiet removes the narration,
+ *   not the fact that the agent is working.
+ */
+/** The resolved mode a turn runs in. Named `turnVerbosity`, never `verbosity` —
+ * `runtime.verbosity.set` is a different, user-facing primitive. */
+export type TurnVerbosity = 'verbose' | 'quiet';
+/** What a developer may write in config. `'auto'` === unset. */
+export type TurnVerbosityConfig = TurnVerbosity | 'auto';
+/**
+ * Hermes spells a direct chat `'dm'` (adapter.py `_chat_type_from_conversation`);
+ * the TS stack spells it `'direct'` and can also be `'unknown'` when the
+ * conversation fetch failed (host-runtime.ts HostInboundParticipantContext).
+ */
+export type TurnVerbosityConversationType = 'direct' | 'dm' | 'group' | 'unknown';
+/**
+ * The per-conversation-type defaults. `canon-hermes-plugin` will hand-port this
+ * map into Python — that package has no dependency on this one — and pin the
+ * two sides with a cross-language parity test, the way it already does for the
+ * turn-trail budgets and the group guidance wording.
+ */
+export declare const DEFAULT_TURN_VERBOSITY_BY_CONVERSATION_TYPE: {
+    readonly direct: "verbose";
+    readonly group: "quiet";
+    readonly unknown: "verbose";
+};
+/**
+ * Folds every spelling a runtime might hand us onto the three keys the
+ * defaults map has. Accepts a raw string because the value arrives from
+ * provenance, a conversation fetch, or a Python-side payload.
+ */
+export declare function normalizeTurnVerbosityConversationType(value: string | null | undefined): 'direct' | 'group' | 'unknown';
+/**
+ * An explicit `'verbose'`/`'quiet'` wins outright; `'auto'`, unset and any
+ * unrecognized value fall through to the per-conversation-type default.
+ *
+ * `configured` goes through `parseTurnVerbosityConfig` on the way in, so a
+ * caller handing over a raw config value gets the same answer as one that
+ * pre-parsed. That matters because the escape hatch is the whole point of the
+ * field: an operator who writes `Verbose` in a group is opting OUT of quiet,
+ * and a byte-exact comparison would drop that back onto the group default —
+ * i.e. into silence — with nothing anywhere to warn about it.
+ */
+export declare function resolveTurnVerbosity(input: {
+    configured?: TurnVerbosityConfig | null;
+    conversationType?: TurnVerbosityConversationType | null;
+}): TurnVerbosity;
+/**
+ * Shared parser for CLI flags, env vars and config files, so four TS runtimes
+ * agree on what a developer typed. Case-insensitive and trimmed.
+ *
+ * `null` means absent OR unrecognized — `''`, whitespace, `null` and `undefined`
+ * land there alongside a genuine typo. A host that warns on `null` must first
+ * check the raw input was a non-empty string, or a declared-but-empty
+ * `CANON_TURN_VERBOSITY=` (routine in launchd plists, Docker `ENV` and `.env`
+ * files) gets reported as a mistake the operator never made. Absent stays `null`
+ * rather than collapsing to `'auto'` so that the usual flag-then-env fallback,
+ * `parse(flag) ?? parse(env)`, keeps working.
+ */
+export declare function parseTurnVerbosityConfig(raw: string | null | undefined): TurnVerbosityConfig | null;