@canonmsg/agent-sdk 12.0.0 → 12.2.0

package/dist/internal/core/local-runtime-catalog.d.ts

@@ -1,131 +0,0 @@
-import type { AgentClientType, ExecutionEnvironmentMode } from './types.js';
-import type { WorkSessionSettings } from '../backend-contracts/index.js';
-export type LocalRuntimeKind = AgentClientType | 'sdk';
-export type LocalRuntimeStatus = 'running' | 'offline' | 'stale' | 'manual' | 'embedded';
-export type LocalRuntimeReviveCapability = 'revivable' | 'manual' | 'embedded' | 'missing-profile';
-export interface LocalRuntimeSessionState {
-    conversationId: string;
-    workspaceId?: string;
-    baseCwd: string;
-    executionMode?: ExecutionEnvironmentMode;
-    codexPolicyFingerprint?: string;
-    /** Identifies fingerprints created from deployer-owned local runtime policy. */
-    codexPolicyFingerprintFormat?: 'local-v1';
-    /**
-     * Confirmed owner setup, saved before the first native turn. Runtime-neutral
-     * despite its name: every managed coding host (Codex, Claude Code) stores its
-     * setup here. The key keeps its original name so existing records and older
-     * hosts stay compatible.
-     */
-    codexManagedSetup?: {
-        requestId: string;
-        settings: WorkSessionSettings;
-    };
-    /**
-     * Explicit local reset fences older native session mappings (any resume
-     * field) from adoption. Runtime-neutral; see `codexManagedSetup` on the name.
-     */
-    codexThreadResetAt?: string;
-    /** Local ownership fence; older records without these fields remain importable. */
-    ownerId?: string;
-    ownershipVersion?: number;
-    threadId?: string;
-    claudeSessionId?: string;
-    hermesSessionId?: string;
-    lastInboundMessageId?: string;
-    updatedAt: string;
-}
-export interface LocalRuntimeCatalogEntry {
-    id: string;
-    runtime: LocalRuntimeKind;
-    profile: string | null;
-    agentId?: string;
-    agentName?: string;
-    cwd: string;
-    baseCwd?: string;
-    workspaceRoots?: string[];
-    workspaces?: string[];
-    launchCommand: string[];
-    pid?: number;
-    status: LocalRuntimeStatus;
-    reviveCapability: LocalRuntimeReviveCapability;
-    surfaceMode?: 'host' | 'channel' | 'embedded';
-    lastStartedAt?: string;
-    lastHeartbeatAt?: string;
-    lastStoppedAt?: string;
-    lastAuthError?: string;
-    lastError?: string;
-    sessions?: Record<string, LocalRuntimeSessionState>;
-}
-export type LocalRuntimeResumeField = 'threadId' | 'claudeSessionId' | 'hermesSessionId';
-export type LocalRuntimeSessionResolution = {
-    status: 'new';
-} | {
-    status: 'exact' | 'adopted';
-    state: LocalRuntimeSessionState;
-} | {
-    status: 'configuration_required';
-    reason: 'ambiguous_mapping' | 'invalid_mapping_timestamp' | 'workspace_unavailable' | 'execution_mode_unavailable';
-    message: string;
-};
-export declare const RUNTIMES_DIR: string;
-export declare function buildLocalRuntimeId(input: {
-    runtime: LocalRuntimeKind;
-    profile?: string | null;
-    cwd: string;
-    launchCommand?: string[];
-}): string;
-export declare function readLocalRuntimeEntry(id: string): LocalRuntimeCatalogEntry | null;
-export declare function upsertLocalRuntimeEntry(entry: LocalRuntimeCatalogEntry): LocalRuntimeCatalogEntry;
-export declare function heartbeatLocalRuntimeEntry(id: string, patch?: Partial<LocalRuntimeCatalogEntry>): LocalRuntimeCatalogEntry | null;
-export declare function markLocalRuntimeStopped(id: string, patch?: Partial<LocalRuntimeCatalogEntry>): LocalRuntimeCatalogEntry | null;
-export declare function listLocalRuntimeEntries(options?: {
-    runtime?: LocalRuntimeKind;
-}): LocalRuntimeCatalogEntry[];
-export declare function loadRuntimeSessionState(runtimeId: string, input: {
-    conversationId: string;
-    baseCwd: string;
-    executionMode?: ExecutionEnvironmentMode;
-    workspaceId?: string;
-}): LocalRuntimeSessionState | null;
-/**
- * Resolve the durable local thread/session for a Canon conversation.
- *
- * The current tuple always wins. A changed local default may otherwise point
- * the host at a fresh tuple and accidentally fork a conversation's runtime
- * history, so the unique newest resumable tuple may be adopted when the host
- * can still recreate its workspace and execution mode. Legacy runtime IDs are
- * considered only for the same local agent/profile/surface, and conflicting
- * historical mappings fail closed instead of donating an arbitrary thread.
- */
-export declare function resolveLocalRuntimeSessionState(runtimeId: string, input: {
-    conversationId: string;
-    baseCwd: string;
-    executionMode?: ExecutionEnvironmentMode;
-    workspaceId?: string;
-    resumeField: LocalRuntimeResumeField;
-    configuredBaseCwds: readonly string[];
-    availableExecutionModes: readonly ExecutionEnvironmentMode[];
-}): LocalRuntimeSessionResolution;
-export declare function saveRuntimeSessionState(runtimeId: string, input: Omit<LocalRuntimeSessionState, 'updatedAt'>): LocalRuntimeSessionState;
-/**
- * Atomically discard a conversation's native session IDs (any runtime) while
- * retaining its confirmed setup, ownership and inbound cursor, and fence older
- * mappings from being adopted again.
- */
-export declare function resetRuntimeSessionState(runtimeId: string, input: {
-    conversationId: string;
-    baseCwd: string;
-    executionMode: ExecutionEnvironmentMode;
-}): LocalRuntimeSessionState;
-/** @deprecated Runtime-neutral now; use {@link resetRuntimeSessionState}. */
-export declare const resetCodexRuntimeSessionState: typeof resetRuntimeSessionState;
-export declare function clearRuntimeSessionState(runtimeId: string, input: {
-    conversationId: string;
-    baseCwd?: string;
-    executionMode?: ExecutionEnvironmentMode;
-    workspaceId?: string;
-    preserveInboundCursor?: boolean;
-    preserveCodexManagedSetup?: boolean;
-}): void;
-export declare function describeProfileLock(profile: string): string;

package/dist/internal/core/message-format.d.ts

@@ -1,13 +0,0 @@
-import type { CanonMessage } from './types.js';
-/**
- * Project a CanonMessage to a single text representation suitable as a
- * baseline for plugins that feed messages to an LLM as plain text.
- *
- * Plugins that compose richer prompts (placeholders, capability hints,
- * native vision input) layer on top of this — the goal here is only to
- * guarantee that no contentType is ever silently dropped to an empty
- * string. Adding a new contentType to CanonMessage and forgetting to
- * handle it here surfaces in this file's tests, not as a silent
- * regression in every consumer plugin.
- */
-export declare function formatCanonMessageAsText(message: Pick<CanonMessage, 'contentType' | 'text' | 'attachments' | 'contactCard' | 'interaction'>): string;

package/dist/internal/core/native-session-interaction.d.ts

@@ -1,44 +0,0 @@
-import type { ApprovalNativeRequestMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRisk } from './approval-types.js';
-import type { CanonUnifiedDiff } from './types.js';
-import type { RuntimeInputRequestPayload } from './runtime-request-manager.js';
-import type { RuntimeInputAnswers } from './runtime-cards.js';
-interface NativeInteractionIdentity {
-    /** Provider-scoped request identity, used to correlate cancellation and replies. */
-    nativeRequestId: string;
-    nativeSessionId: string;
-    turnId?: string;
-}
-export type NativeSessionInteractionRequest = NativeInteractionIdentity & ({
-    kind: 'approval';
-    approval: {
-        toolName: string;
-        toolInput: Record<string, unknown>;
-        toolSummary: string;
-        category?: ApprovalRequestCategory;
-        risk?: ApprovalRisk;
-        riskLevel?: 'normal' | 'destructive';
-        native?: ApprovalNativeRequestMetadata;
-        details?: ApprovalRequestDetail[];
-        diff?: CanonUnifiedDiff;
-    };
-} | {
-    kind: 'input';
-    input: Omit<RuntimeInputRequestPayload, 'responseUserId' | 'turnId'>;
-});
-export type NativeSessionInteractionResult = {
-    kind: 'approval';
-    decision: 'allow' | 'deny';
-} | {
-    kind: 'input';
-    answers: RuntimeInputAnswers;
-} | {
-    kind: 'cancelled';
-};
-/** The host owns the Canon audience, owner responder, request IDs and deadlines. */
-export interface NativeSessionInteractionBridge {
-    /** Abort when a native client answers first, the observer closes, or the request is cleared. */
-    request(request: NativeSessionInteractionRequest, options: {
-        signal: AbortSignal;
-    }): Promise<NativeSessionInteractionResult>;
-}
-export {};

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

@@ -1,31 +0,0 @@
-import type { CanonConversation, CanonMessage, CanonRuntimeProvenance } from './types.js';
-import type { CanonSelfContext } from './self-context.js';
-export declare function buildRuntimeProvenance(input: {
-    conversationId: string;
-    conversationType?: CanonConversation['type'] | 'unknown' | string | null;
-    memberCount?: number | null;
-    senderId: string;
-    senderName?: string | null;
-    senderType?: CanonMessage['senderType'] | string | null;
-    isOwner?: boolean | null;
-    agentId?: string | null;
-    mentions?: readonly string[] | null;
-    mentionedAgent?: boolean | null;
-    activeSelfContextId?: string | null;
-    selfContexts?: readonly CanonSelfContext[] | null;
-}): CanonRuntimeProvenance;
-export declare function resolveRuntimeProvenance(input: {
-    provenance?: CanonRuntimeProvenance | null;
-    conversationId: string;
-    conversationType?: CanonConversation['type'] | 'unknown' | string | null;
-    memberCount?: number | null;
-    senderId: string;
-    senderName?: string | null;
-    senderType?: CanonMessage['senderType'] | string | null;
-    isOwner?: boolean | null;
-    agentId?: string | null;
-    mentions?: readonly string[] | null;
-    mentionedAgent?: boolean | null;
-    activeSelfContextId?: string | null;
-    selfContexts?: readonly CanonSelfContext[] | null;
-}): CanonRuntimeProvenance;

package/dist/internal/core/registration-cli.d.ts

@@ -1,40 +0,0 @@
-import { type AgentOriginDeclaration } from '../backend-contracts/index.js';
-import type { AgentClientType } from './types.js';
-export interface RegistrationCliOptions {
-    /**
-     * `import.meta.url` of the plugin's own CLI entry module. Required so
-     * direct-execution detection and `--version` resolve against the plugin
-     * package, not @canonmsg/core.
-     */
-    moduleUrl: string;
-    clientType: AgentClientType;
-    /** Optional self-reported public source; callers may override it with CLI flags. */
-    origin?: AgentOriginDeclaration;
-    /** Published bin name, e.g. `canon-register`. */
-    cliName: string;
-    /** Host bin the operator starts after approval, e.g. `canon-claude`. */
-    hostBinName: string;
-    developerInfo: string;
-    help: string;
-    /** Full usage line printed when a required flag is missing. */
-    usage: string;
-    /** Noun used in the "Registering <label> ..." progress line. */
-    registeringLabel: string;
-    /**
-     * Optional host-specific instructions printed after approval. When omitted,
-     * Canon emits the conventional local host-binary startup guidance.
-     */
-    approvedInstructions?: (profileName: string) => readonly string[];
-}
-/**
- * Shared orchestration for the per-plugin registration CLIs
- * (`canon-register`, `canon-codex-register`). Every string that differs
- * between plugins is a parameter so each CLI's stdout/stderr stays exactly
- * what it was before consolidation.
- */
-export declare function runRegistrationCli(options: RegistrationCliOptions): Promise<void>;
-/**
- * Entry-point wrapper: runs {@link runRegistrationCli} under the shared
- * `runCli` harness (direct-execution guard, `--help` / `--version`).
- */
-export declare function registerRegistrationCli(options: RegistrationCliOptions): void;

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

@@ -1,77 +0,0 @@
-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;
-}

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

@@ -1,69 +0,0 @@
-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/typing-status-publisher.d.ts

@@ -1,14 +0,0 @@
-import type { TypingPayload } from './types.js';
-export type TypingPresenceStatus = TypingPayload['status'];
-export interface TypingStatusPublisherOptions {
-    setTyping: (conversationId: string, typing: boolean, status?: TypingPresenceStatus) => Promise<void> | void;
-    keepaliveMs?: number;
-    schedule?: typeof setInterval;
-    cancel?: typeof clearInterval;
-}
-export interface TypingStatusPublisher {
-    start(conversationId: string, status?: TypingPresenceStatus): Promise<void>;
-    clear(conversationId: string): Promise<void>;
-    dispose(conversationId?: string): void;
-}
-export declare function createTypingStatusPublisher(options: TypingStatusPublisherOptions): TypingStatusPublisher;

package/dist/internal/core/work-session-provider.d.ts

@@ -1,29 +0,0 @@
-import type { WorkSessionCatalog, WorkSessionDetailFields, WorkSessionSelection, WorkSessionSettings } from '../backend-contracts/index.js';
-import type { AttachedNativeSessionAdapter } from './attached-native-session.js';
-import type { NativeSessionInteractionBridge } from './native-session-interaction.js';
-export interface NativeWorkSessionCreateContext {
-    requestId: string;
-    conversationId: string;
-    agentId: string;
-}
-export interface NativeWorkSessionCreated {
-    nativeSessionId: string;
-    settings: WorkSessionSettings;
-}
-/** A lost acknowledgement is not permission to create another native session. */
-export declare class NativeWorkSessionCreateError extends Error {
-    readonly outcome: 'not_created' | 'uncertain';
-    constructor(message: string, outcome: 'not_created' | 'uncertain', options?: ErrorOptions);
-}
-/** Provider-only operations; Canon admission, bindings and transport belong to the SDK host. */
-export interface NativeWorkSessionProvider {
-    catalog(): Promise<WorkSessionCatalog>;
-    create(selection: Extract<WorkSessionSelection, {
-        mode: 'create';
-    }>, context: NativeWorkSessionCreateContext): Promise<NativeWorkSessionCreated>;
-    open(nativeSessionId: string, interactionBridge?: NativeSessionInteractionBridge): Promise<AttachedNativeSessionAdapter>;
-    /** Private, read-only runtime observations. Opening details must not resume the native thread. */
-    describe?(nativeSessionId: string, settings: WorkSessionSettings): Promise<WorkSessionDetailFields>;
-    /** Close owned connections. Never delete native sessions or their working directories. */
-    close(): Promise<void>;
-}

package/dist/internal/core/workspace-discovery.d.ts

@@ -1,17 +0,0 @@
-import { type ConfiguredWorkspaceOption } from './execution-environment.js';
-import type { CanonWorkspaceRootMetadata } from './types.js';
-export interface ConfiguredWorkspaceRoot extends CanonWorkspaceRootMetadata {
-    cwd: string;
-}
-export interface WorkspaceDiscoveryResult {
-    workspaceOptions: ConfiguredWorkspaceOption[];
-    workspaceRoots: ConfiguredWorkspaceRoot[];
-    warnings: string[];
-}
-export declare function buildWorkspaceRootId(workspaceRoot: string): string;
-export declare function buildPublicWorkspaceRoots(roots: ReadonlyArray<ConfiguredWorkspaceRoot>): CanonWorkspaceRootMetadata[];
-export declare function buildConfiguredWorkspaceOptionsWithRoots(input: {
-    primaryCwd: string;
-    configuredWorkspaces?: string[];
-    workspaceRoots?: string[];
-}): WorkspaceDiscoveryResult;