@canonmsg/agent-sdk 12.0.0 → 12.1.0

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

@@ -1,174 +0,0 @@
-import type { EndpointInboundStartResult } from '../endpoint/index.js';
-import type { SendMessageOptions } from './types.js';
-export interface AttachedSessionBinding {
-    environmentId: string;
-    agentId: string;
-    conversationId: string;
-    provider: string;
-    /** Exact provider thread/session ID, not a session-tree root. */
-    nativeSessionId: string;
-}
-export interface NativeSessionItem {
-    itemId: string;
-    turnId: string;
-    role: 'user' | 'assistant';
-    text: string;
-}
-export type NativeSessionEvent = {
-    type: 'item';
-    nativeSessionId: string;
-    item: NativeSessionItem;
-} | {
-    type: 'turn';
-    nativeSessionId: string;
-    turnId: string;
-    state: 'running' | 'completed' | 'failed' | 'interrupted';
-} | {
-    type: 'disconnected';
-    nativeSessionId: string;
-    reason: string;
-};
-export interface NativeSessionSnapshot {
-    nativeSessionId: string;
-    /** Completed user/assistant items, in native transcript order. */
-    items: NativeSessionItem[];
-    /** Existing user/assistant IDs, including partial items; used only to establish a private history boundary. */
-    baselineItemIds?: Array<{
-        itemId: string;
-        turnId: string;
-    }>;
-    activeTurnId: string | null;
-}
-export type NativeSubmissionResult = {
-    status: 'accepted';
-    turnId: string;
-    mode: 'started_or_appended' | 'appended';
-} | {
-    status: 'not_submitted';
-    reason: string;
-};
-export interface AttachedNativeSessionAdapter {
-    subscribe(listener: (event: NativeSessionEvent) => void): Promise<void>;
-    /** Must include all completed items since the attachment baseline. */
-    inspect(): Promise<NativeSessionSnapshot>;
-    /** Throw when acceptance is uncertain. Never silently retry native input. */
-    submit(text: string): Promise<NativeSubmissionResult>;
-    /** Detach this observer/connection; leave the native runner alive. */
-    close(): Promise<void>;
-}
-/** Provenance only. Shared native turns always require proactive authority. */
-export type AttachedSessionOrigin = {
-    kind: 'local';
-} | {
-    kind: 'shared';
-    sourceMessageIds: string[];
-};
-export interface AttachedSessionMessagePart {
-    messageId: string;
-    text: string;
-    options: Omit<SendMessageOptions, 'messageId'>;
-}
-export interface AttachedSessionPublisher {
-    prepare(input: {
-        binding: AttachedSessionBinding;
-        item: NativeSessionItem;
-        origin: AttachedSessionOrigin;
-    }): AttachedSessionMessagePart[];
-    /** Reject on any unacknowledged result. Replays receive identical parts. */
-    send(part: AttachedSessionMessagePart): Promise<void>;
-}
-export interface AttachedSessionInput {
-    messageId: string;
-    text: string;
-    /** Retained with the request, never borrowed for native output. */
-    replyAuthority?: SendMessageOptions['replyAuthority'];
-}
-export type AttachedSessionSubmitResult = {
-    status: 'accepted';
-    turnId: string;
-    mode: 'started_or_appended' | 'appended';
-    replayed: boolean;
-} | {
-    status: 'busy';
-} | {
-    status: 'deferred';
-} | {
-    status: 'not_submitted';
-    reason: string;
-} | {
-    status: 'uncertain';
-    messageId: string;
-};
-interface StoredSubmission extends AttachedSessionInput {
-    nativeText: string;
-    status: 'submitting' | 'accepted' | 'uncertain' | 'not_submitted' | 'busy';
-    turnId?: string;
-    mode?: 'started_or_appended' | 'appended';
-    reason?: string;
-    echoedItemKey?: string;
-}
-export interface AttachedSessionJournal {
-    version: 1;
-    binding: AttachedSessionBinding;
-    baselineEstablished: boolean;
-    /** Intentional detach skips subsequent native work on the next attachment. */
-    detached?: boolean;
-    seenItemKeys: string[];
-    bufferedItems: NativeSessionItem[];
-    submissions: Record<string, StoredSubmission>;
-    canonBaselineMessageIds?: string[];
-    canonBaselineCreatedAt?: string | null;
-    skippedCanonMessageIds: string[];
-    outbox: Array<{
-        key: string;
-        parts: AttachedSessionMessagePart[];
-        nextPart: number;
-    }>;
-}
-/**
- * The store must hold an exclusive journal writer lock until close(). The host
- * separately enforces one active Canon audience per native session, even when
- * different accounts/bindings use different journal files.
- */
-export interface AttachedSessionStore {
-    load(): Promise<AttachedSessionJournal | null>;
-    save(journal: AttachedSessionJournal): Promise<void>;
-    close(): Promise<void>;
-}
-export interface AttachedSessionState {
-    status: 'stopped' | 'starting' | 'ready' | 'disconnected' | 'uncertain';
-    activeTurnId: string | null;
-    pendingPublicationCount: number;
-    pendingSourceMessageId: string | null;
-}
-export interface AttachedNativeSessionOptions {
-    /** Caller validates admission and exclusively owns this native audience route. */
-    binding: AttachedSessionBinding;
-    store: AttachedSessionStore;
-    adapter: AttachedNativeSessionAdapter;
-    publisher: AttachedSessionPublisher;
-    /** Hold durable publications until the audience route is ready. Call flush after activation. */
-    isPublicationReady?: () => boolean;
-    /** Last durable execution fence, immediately before invoking the provider. */
-    beforeNativeSubmit?: (input: AttachedSessionInput) => Promise<boolean>;
-    /** Own the atomic execution handoff; invoke submit only after durable admission. */
-    submitNative?: (input: AttachedSessionInput, submit: () => Promise<NativeSubmissionResult>) => Promise<EndpointInboundStartResult<NativeSubmissionResult>>;
-    onState?: (state: AttachedSessionState) => void;
-    onError?: (error: unknown, operation: string) => void;
-}
-export interface AttachedNativeSession {
-    start(): Promise<void>;
-    submit(input: AttachedSessionInput): Promise<AttachedSessionSubmitResult>;
-    reconcile(): Promise<void>;
-    flush(): Promise<void>;
-    stop(): Promise<void>;
-    getState(): AttachedSessionState;
-    initializeCanonBaseline(messageIds: readonly string[], createdAt?: string | null): Promise<boolean>;
-    isBeforeCanonBaseline(messageId: string, createdAt: string): boolean;
-    hasCanonMessage(messageId: string): boolean;
-    recordSkippedCanonMessage(messageId: string, reason?: string): Promise<void>;
-}
-export declare function validateAttachedSessionJournal(value: unknown, binding: AttachedSessionBinding): asserts value is AttachedSessionJournal;
-/** A single observer, durable outbox and one pending input RPC. No execution queue. */
-export declare function createAttachedNativeSession(options: AttachedNativeSessionOptions): AttachedNativeSession;
-export {};

package/dist/internal/core/attached-session-file-store.d.ts

@@ -1,3 +0,0 @@
-import type { AttachedSessionStore } from './attached-native-session.js';
-/** Lazy exclusive lock plus private atomic snapshots. No process/ratchet state is shared. */
-export declare function createFileAttachedSessionStore(path: string): AttachedSessionStore;

package/dist/internal/core/control-poller.d.ts

@@ -1,221 +0,0 @@
-/**
- * Shared RTDB `/control/{conversationId}/{agentId}` channel poller.
- *
- * Four hosts historically implemented this loop independently (agent-sdk,
- * claude-code-plugin, codex-plugin, openclaw-plugin) with duplicated
- * constants and drifting semantics. This class covers the union of their
- * behaviors via configuration so each host can migrate onto one engine:
- *
- * - Keys: `signal` (all) and `primitive` (sdk/openclaw), always read in that
- *   order.
- * - Cadence: live endpoint hints with a one-minute reconciliation fallback;
- *   disconnected/legacy handles use fixed interval (agent-sdk) or active/idle delays + jitter
- *   (claude/codex/openclaw), with the activity probe sampled either at cycle
- *   start (claude/codex) or after the poll completes (openclaw).
- * - Dedupe: endpoint revision identity (legacy handles use timestamp), primed
- *   either eagerly via {@link ControlChannelPoller.baseline} (sdk/claude/codex)
- *   or lazily against the poller start time (openclaw).
- * - Consume: shared endpoint handles acknowledge the observed revision; whether a node is consumed
- *   after a handler error is configurable per key, and primitive dedupe
- *   entries may be released only on successful consume (agent-sdk).
- *
- * Normalizations shared by every profile (pinned by the characterization
- * tests as the new contract):
- * - Single-flight polling via setTimeout chaining — no overlapping cycles,
- *   even where the legacy host used a flat setInterval.
- * - stop()/start() during an in-flight poll can never double-schedule.
- * - A null agent id skips the cycle but keeps the cadence alive.
- * - No added backoff on errors: the next cycle runs at the normal cadence.
- *
- * The poller uses the scoped runtime handle backed by its CanonClient endpoint.
- * Passing the observed value into consume prevents a newer control request
- * from being deleted after an older native handler completes.
- */
-export type ControlSignalType = 'interrupt' | 'stop_and_drop' | 'new_session';
-export type ControlChannelKey = 'signal' | 'primitive';
-/** Minimal scoped RTDB surface; `RTDBClientHandle` satisfies it. */
-export interface ControlChannelRTDB {
-    read(path: string): Promise<unknown>;
-    write(path: string, data: unknown): Promise<void>;
-    /** Shared endpoint handles bind consumption to the exact observed revision. */
-    consume?(path: string, observed: unknown): Promise<void>;
-    observedRevision?(path: string, observed: unknown): string | undefined;
-    /** Shared endpoint hints; legacy handles retain their configured polling cadence. */
-    observeControls?(changed: (conversationId?: string) => void, connected: (value: boolean) => void): () => void;
-}
-export interface ControlSignalEvent {
-    conversationId: string;
-    type: ControlSignalType;
-    updatedAt: number;
-    raw: Record<string, unknown>;
-}
-export interface ControlPrimitiveEvent {
-    conversationId: string;
-    requestId: string;
-    updatedAt: number;
-    value: Record<string, unknown>;
-}
-/**
- * Handlers may return `{ consume: false }` to leave the RTDB node in place
- * while still marking it seen — it will not be re-dispatched for this
- * revision. Returning `{ defer: true }` means "not mine yet": the node
- * is left in place AND stays unseen, so it is re-dispatched on the next cycle
- * — this is how a runtime that registers a handler after polling has started
- * still receives signals observed during the gap. Returning nothing consumes
- * the node after a successful handle. A throw never defers: the node is
- * marked seen (and consumed per `consumeOnError`) so a crashing handler
- * cannot spin on the same request.
- */
-export type ControlHandlerResult = {
-    consume?: boolean;
-    defer?: boolean;
-} | void;
-export interface ControlSignalHandlerConfig {
-    handle(event: ControlSignalEvent): Promise<ControlHandlerResult> | ControlHandlerResult;
-    /**
-     * Consume the signal node even when the handler throws.
-     * agent-sdk/openclaw: true. claude/codex hosts: false (default).
-     */
-    consumeOnError?: boolean;
-}
-export interface ControlPrimitiveHandlerConfig {
-    handle(event: ControlPrimitiveEvent): Promise<ControlHandlerResult> | ControlHandlerResult;
-    /** Both primitive hosts consume requests even when the handler throws (default true). */
-    consumeOnError?: boolean;
-    /**
-     * `sequential` handles object entries oldest-first by `updatedAt` (agent-sdk);
-     * `parallel` handles all entries concurrently and unsorted (openclaw).
-     * Default: `sequential`.
-     */
-    ordering?: 'sequential' | 'parallel';
-    /** Dedupe entry TTL; omitted means entries are remembered forever (openclaw). */
-    dedupeTtlMs?: number;
-    /** Oldest dedupe entries are evicted beyond this cap (agent-sdk: 1000). */
-    dedupeMaxEntries?: number;
-    /**
-     * Release the dedupe entry once the request node is successfully consumed,
-     * so a lingering node (failed consume) stays suppressed until TTL expiry
-     * while cleared requests free their slot immediately (agent-sdk). Default false.
-     */
-    releaseDedupeOnConsume?: boolean;
-    /**
-     * Consume entries whose value is not a plain object instead of leaving them
-     * untouched. openclaw: true (normalize-fail → consume); agent-sdk: false.
-     */
-    consumeInvalidEntries?: boolean;
-    /**
-     * Skip (but still consume) requests stamped before the poller started
-     * (openclaw replay guard). Default false.
-     */
-    skipStaleBeforeStart?: boolean;
-}
-export type ControlPollerCadence = {
-    /** Flat interval between cycle completions (agent-sdk: 2000ms). */
-    kind: 'fixed';
-    intervalMs: number;
-} | {
-    /** Active/idle delays + jitter (claude/codex/openclaw: 2000/10000 + [0,1000)). */
-    kind: 'adaptive';
-    activeMs: number;
-    idleMs: number;
-    jitterMs: number;
-    hasActiveWork: () => boolean;
-    /**
-     * When the activity probe is sampled for the post-cycle delay:
-     * claude/codex sample before the poll runs (`cycle-start`, default);
-     * openclaw samples after the poll completes (`cycle-end`).
-     */
-    activitySample?: 'cycle-start' | 'cycle-end';
-};
-export interface ControlPollerError {
-    scope: 'read' | 'consume' | 'handler' | 'poll';
-    key?: ControlChannelKey;
-    conversationId?: string;
-    requestId?: string;
-    error: unknown;
-}
-export interface ControlChannelPollerOptions {
-    /** Scoped RTDB handle — the poller never touches the module-global default client. */
-    rtdb: ControlChannelRTDB;
-    /** Static agent id, or a getter for hosts whose id can become unavailable. */
-    agentId: string | (() => string | null);
-    /** Live conversation scope, snapshotted at the start of every cycle. */
-    conversationIds: () => Iterable<string>;
-    cadence: ControlPollerCadence;
-    /**
-     * Run the first cycle immediately on start (claude/codex/openclaw).
-     * `false` waits one cadence delay first (agent-sdk setInterval semantics).
-     * Default true.
-     */
-    pollOnStart?: boolean;
-    /**
-     * `sequential` polls conversations one at a time (claude/codex);
-     * `parallel` polls them concurrently (agent-sdk/openclaw). Default `sequential`.
-     */
-    conversationConcurrency?: 'sequential' | 'parallel';
-    /**
-     * Lazily prime signal dedupe against the poller start time on first
-     * sighting instead of requiring an eager {@link ControlChannelPoller.baseline}
-     * pass (openclaw). Default false.
-     */
-    lazyBaselineFromStart?: boolean;
-    handlers: {
-        signal?: ControlSignalHandlerConfig;
-        primitive?: ControlPrimitiveHandlerConfig;
-    };
-    onError?: (error: ControlPollerError) => void;
-    /** Injectable jitter source (default Math.random). */
-    random?: () => number;
-    /** Injectable clock (default Date.now). */
-    now?: () => number;
-}
-export declare class ControlChannelPoller {
-    private readonly options;
-    private timer;
-    private running;
-    private startedAt;
-    private connected;
-    private unsubscribe?;
-    private cycleActive;
-    private readonly cycleRetryRooms;
-    private readonly retryAt;
-    private fullRefresh;
-    private nextFullRefreshAt;
-    private readonly changedRooms;
-    private readonly lastSeenSignal;
-    private readonly lastSeenSignalRevision;
-    private readonly primitiveDedupe;
-    constructor(options: ControlChannelPollerOptions);
-    start(): void;
-    stop(): void;
-    isRunning(): boolean;
-    /**
-     * Eagerly prime signal dedupe from the current RTDB node without
-     * handling them (agent-sdk at connect; claude/codex at session creation).
-     */
-    baseline(conversationIds: Iterable<string>): Promise<void>;
-    /** Run one full poll cycle across the current conversation scope. */
-    pollOnce(): Promise<void>;
-    private pollRooms;
-    private wake;
-    private schedule;
-    private runCycle;
-    private sampleActivity;
-    private nextDelayMs;
-    private pollConversation;
-    private pollSignalKey;
-    private pollPrimitiveKey;
-    private processPrimitiveEntry;
-    private dispatch;
-    private readKey;
-    private consumeKey;
-    private baselineKey;
-    private maybeLazyBaseline;
-    private prunePrimitiveDedupe;
-    private releasePrimitiveDedupe;
-    private controlBasePath;
-    private resolveAgentId;
-    private reportError;
-    private random;
-    private now;
-}

package/dist/internal/core/exclusive-json-file-store.d.ts

@@ -1,7 +0,0 @@
-export interface ExclusiveJsonFileStore<T> {
-    load(): Promise<T | null>;
-    save(value: T): Promise<void>;
-    close(): Promise<void>;
-}
-/** Private atomic snapshots guarded by one recoverable process lock. */
-export declare function createExclusiveJsonFileStore<T>(path: string, name?: string): ExclusiveJsonFileStore<T>;

package/dist/internal/core/execution-environment.d.ts

@@ -1,55 +0,0 @@
-import type { WorkspaceOption, WorkspaceOptionSource } from './types.js';
-import { EXECUTION_ENVIRONMENT_MODES, isExecutionEnvironmentMode, type ExecutionEnvironmentMode } from './execution-environment-mode.js';
-export { EXECUTION_ENVIRONMENT_MODES, isExecutionEnvironmentMode };
-export type { ExecutionEnvironmentMode };
-export interface PreparedExecutionEnvironment {
-    cwd: string;
-    baseCwd: string;
-    mode: ExecutionEnvironmentMode;
-    repoRoot?: string;
-    branch?: string;
-    worktreePath?: string;
-    lockPath?: string;
-    reason?: string;
-}
-export declare class ExecutionEnvironmentError extends Error {
-    readonly userMessage: string;
-    constructor(message: string, userMessage?: string);
-}
-interface WorkspaceResolverOption {
-    id: string;
-    cwd: string;
-}
-export interface ConfiguredWorkspaceOption extends WorkspaceResolverOption {
-    label: string;
-    description?: string;
-    workspaceRootId?: string;
-    workspaceRelativePath?: string;
-    source?: WorkspaceOptionSource;
-}
-export declare function normalizeOptionalString(value: unknown): string | undefined;
-export declare function isEnabledFlag(value: unknown): boolean;
-export declare function buildConversationEnvironmentKey(conversationId: string, workspaceCwd: string): string;
-export declare function buildWorkspaceOptionId(workspaceCwd: string): string;
-export declare function buildConfiguredWorkspaceOptions(primaryCwd: string, configured: string[]): ConfiguredWorkspaceOption[];
-export declare function buildPublicWorkspaceOptions(workspaceOptions: Array<Pick<ConfiguredWorkspaceOption, 'id' | 'label'> & Partial<Pick<ConfiguredWorkspaceOption, 'description' | 'workspaceRootId' | 'workspaceRelativePath' | 'source'>>>): WorkspaceOption[];
-export declare function resolveConfiguredWorkspaceCwd(input: {
-    workspaceOptions: WorkspaceResolverOption[];
-    workspaceId?: string;
-    defaultCwd: string;
-}): string;
-export declare function buildConversationWorktreeSpec(input: {
-    agentId: string;
-    conversationId: string;
-    workspaceCwd: string;
-}): {
-    branch: string;
-    worktreePath: string;
-};
-export declare function prepareConversationEnvironment(input: {
-    agentId: string;
-    conversationId: string;
-    workspaceCwd: string;
-    allowWorktrees?: boolean;
-}): PreparedExecutionEnvironment;
-export declare function releaseConversationEnvironment(environment: Pick<PreparedExecutionEnvironment, 'lockPath'>): void;

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

@@ -1,25 +0,0 @@
-import type { CanonConversation, CanonGroupContext, CanonGroupContextMode, CanonKnownRecentParticipant, CanonMembershipChange, CanonMessage } from './types.js';
-type MessageLike = {
-    senderId?: string | null;
-    senderName?: string | null;
-    senderType?: CanonMessage['senderType'];
-    isOwner?: boolean;
-    createdAt?: string | null;
-};
-export declare function diffCanonMemberIds(previousMemberIds: unknown[], nextMemberIds: unknown[]): CanonMembershipChange | null;
-export declare function buildCanonKnownRecentParticipants(input: {
-    messages: MessageLike[];
-    agentId: string;
-    ownerId?: string | null;
-    maxParticipants?: number;
-}): CanonKnownRecentParticipant[];
-export declare function buildCanonGroupContext(input: {
-    conversation: CanonConversation | null | undefined;
-    messages: MessageLike[];
-    agentId: string;
-    ownerId?: string | null;
-    ownerName?: string | null;
-    membershipChange?: CanonMembershipChange | null;
-}): CanonGroupContext | undefined;
-export declare function buildCompactGroupContextLines(groupContext: CanonGroupContext, mode: CanonGroupContextMode): string[];
-export {};

package/dist/internal/core/inbound-frame.d.ts

@@ -1,64 +0,0 @@
-import type { CanonGroupContext, CanonGroupContextMode } from './types.js';
-import type { CanonTurnContextReplyContextV2, CanonTurnContextV2 } from './host-runtime.js';
-import { type CanonSelfContext } from './self-context.js';
-export declare const CANON_INBOUND_FRAME_SCHEMA_V1: "canon.inbound_frame.v1";
-export type CanonInboundFrameShapeV1 = 'direct_owner' | 'direct_human' | 'direct_agent' | 'group' | 'unknown';
-export interface CanonInboundFrameV1 {
-    schema: typeof CANON_INBOUND_FRAME_SCHEMA_V1;
-    shape: CanonInboundFrameShapeV1;
-    sender: {
-        name: string;
-        type: 'human' | 'ai_agent';
-        isOwner: boolean;
-    };
-    conversation: {
-        type: CanonTurnContextV2['conversation']['type'];
-        memberCount: number | null;
-    };
-    addressed: boolean;
-    message: {
-        text: string;
-        contentType: CanonTurnContextV2['message']['contentType'];
-        artifactContext?: CanonTurnContextV2['message']['artifactContext'];
-        artifactSummaries?: CanonTurnContextV2['message']['artifactSummaries'];
-    };
-    replyContext: CanonTurnContextReplyContextV2 | null;
-    groupContext: CanonGroupContext | null;
-    groupContextMode: CanonGroupContextMode | undefined;
-    /** V1 projection retained for callers that construct or inspect frames. */
-    selfContexts: string[];
-    /** Structured private notes enable exact reply attribution when present. */
-    selfContextDetails?: CanonSelfContext[];
-    activeSelfContextId?: string | null;
-    behaviorInstructions: string[];
-    /**
-     * Resolved consecutive-agent-turn cap for this conversation, or `null` when
-     * the room is uncapped. Groups resolve to a default backstop; direct
-     * conversations stay uncapped.
-     */
-    maxConsecutiveAgentTurns: number | null;
-}
-export interface CanonInboundPromptOptions {
-    /**
-     * What the model sees for the `no_reply` verb on this runtime — e.g.
-     * `mcp__canon__no_reply` on the Claude host. It stands for the affordance,
-     * not just its name: omit it on a runtime that cannot end a turn without
-     * posting, and the group guidance drops the whole "otherwise stay silent"
-     * clause rather than asking for something the model cannot do.
-     */
-    noReplyToolName?: string;
-    /**
-     * The shared-work tools as the model sees them on this runtime (e.g.
-     * `mcp__canon__artifact_read`). Omit on a runtime without them: the
-     * references are still described, without tool hints. `generate` names the
-     * image tool in the hint to edit the version a person saw.
-     */
-    artifactToolNames?: {
-        read: string;
-        update: string;
-        generate?: string;
-    };
-}
-export declare function buildCanonInboundFrameV1(context: CanonTurnContextV2): CanonInboundFrameV1;
-export declare function renderCodingHostInboundPrompt(frame: CanonInboundFrameV1, options?: CanonInboundPromptOptions): string;
-export declare function renderOpenClawSystemPrompt(frame: CanonInboundFrameV1, options?: CanonInboundPromptOptions): string | undefined;