@canonmsg/agent-sdk 11.2.0 → 12.0.0

package/dist/internal/core/turn-output-controller.d.ts

@@ -0,0 +1,69 @@
+import type { StreamingStatus, TurnOutputBlock, TurnOutputBlockKind, TurnOutputBlockStatus } from './types.js';
+export type TurnOutputMode = 'delta' | 'block' | 'snapshot' | 'status';
+export interface TurnOutputSnapshot {
+    turnId: string;
+    messageId: string;
+    text: string;
+    status: StreamingStatus;
+    blocks?: TurnOutputBlock[];
+}
+export interface TurnOutputBlockInput {
+    id: string;
+    kind: TurnOutputBlockKind;
+    status?: TurnOutputBlockStatus;
+    sequence?: number;
+    title?: string;
+    text?: string;
+    summary?: string;
+    detail?: string;
+}
+export interface BuildBoundedTurnTrailOptions {
+    maxBlocks?: number;
+    maxMetadataBytes?: number;
+}
+export interface TurnOutputControllerOptions {
+    turnId: string;
+    mode?: TurnOutputMode;
+    throttleMs?: number;
+    blockSeparator?: string;
+    writeSnapshot: (snapshot: TurnOutputSnapshot) => void | Promise<void>;
+    clearSnapshot: () => void | Promise<void>;
+    schedule?: typeof setTimeout;
+    cancel?: typeof clearTimeout;
+}
+export interface TurnOutputController {
+    readonly turnId: string;
+    readonly mode: TurnOutputMode;
+    getText(): string;
+    getStatus(): StreamingStatus;
+    getBlocks(): TurnOutputBlock[];
+    getFinalTrail(): TurnOutputBlock[];
+    startThinking(text?: string): Promise<void>;
+    startStreaming(text?: string): Promise<void>;
+    appendDelta(delta: string): void;
+    appendBlock(block: string): void;
+    appendTextSegmentDelta(id: string, delta: string, patch?: Partial<Omit<TurnOutputBlockInput, 'id' | 'kind' | 'sequence' | 'text'>>): void;
+    replaceTextSegmentSnapshot(id: string, text: string, patch?: Partial<Omit<TurnOutputBlockInput, 'id' | 'kind' | 'sequence' | 'text'>>): void;
+    replaceSnapshot(text: string, status?: StreamingStatus): Promise<void>;
+    setStatus(status: StreamingStatus, text?: string): Promise<void>;
+    addBlock(block: TurnOutputBlockInput): Promise<TurnOutputBlock>;
+    updateBlock(id: string, patch: Partial<Omit<TurnOutputBlockInput, 'id' | 'sequence'>>): Promise<TurnOutputBlock | null>;
+    completeBlock(id: string, patch?: Partial<Omit<TurnOutputBlockInput, 'id' | 'sequence' | 'status'>>): Promise<TurnOutputBlock | null>;
+    failBlock(id: string, patch?: Partial<Omit<TurnOutputBlockInput, 'id' | 'sequence' | 'status'>>): Promise<TurnOutputBlock | null>;
+    flush(status?: StreamingStatus): Promise<void>;
+    waitingInput(): Promise<void>;
+    interrupt(): Promise<void>;
+    clear(): Promise<void>;
+    /**
+     * Deliberate silence: blank the node (text '' and an EXPLICIT empty blocks
+     * array) and then delete it, so onStreamingCleared sees empty content and
+     * skips the salvage fallback. The empty array is load-bearing: merge writers
+     * (POST /streaming, OpenClaw PATCH) leave stale blocks behind when the key
+     * is absent, and the trigger then synthesizes salvage text from block titles.
+     */
+    blankAndClear(): Promise<void>;
+}
+export declare const DEFAULT_TURN_TRAIL_MAX_BLOCKS = 20;
+export declare const DEFAULT_TURN_TRAIL_METADATA_BUDGET_BYTES = 2500;
+export declare function buildBoundedTurnTrail(blocks: readonly TurnOutputBlock[], options?: BuildBoundedTurnTrailOptions): TurnOutputBlock[];
+export declare function createTurnOutputController(options: TurnOutputControllerOptions): TurnOutputController;

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

@@ -0,0 +1,33 @@
+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 declare const FINAL_MESSAGE_HANDOFF_MS = 750;
+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;
+}
+export declare const DEFAULT_RUNTIME_CAPABILITIES: RuntimeCapabilities;
+/** The one optional proactive communication capability a runtime may expose. */
+export interface HostAdmissionActionCapabilities {
+    communicate: boolean;
+}
+export declare const HOST_ADMISSION_ACTION_CAPABILITIES: HostAdmissionActionCapabilities;
+export declare const HOST_ADMISSION_ACTIONS_DISABLED: HostAdmissionActionCapabilities;
+export declare function normalizeTurnState(value: unknown): TurnState | null;

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

@@ -0,0 +1,97 @@
+/**
+ * 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.
+ * - `TurnOutputController`'s `mode: 'status'` silences the `/streaming` writes
+ *   but does NOT suppress the trail — blocks still accumulate in memory and
+ *   `getFinalTrail()` still returns them. Gate the trail separately, with
+ *   `shouldPublishTurnTrail`, at every site that attaches it to a final.
+ * - 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";
+};
+/**
+ * Does quiet also drop the margin turnTrail rows on the final?
+ * Owner ruling 5's open sub-question, answered YES. Named so a veto is a
+ * one-line flip here rather than a five-host revert.
+ */
+export declare const QUIET_SUPPRESSES_TURN_TRAIL: boolean;
+/**
+ * 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;
+/** Convenience for the trail attach sites; folds the ruling above in. */
+export declare function shouldPublishTurnTrail(verbosity: TurnVerbosity): boolean;