@canonmsg/agent-sdk 11.2.0 → 12.0.0

package/dist/debouncer.d.ts

@@ -1,18 +0,0 @@
-import type { CanonMessage, CanonRuntimeProvenance, EndpointInboundHandoff } from '@canonmsg/core';
-import { type InboundHandoffs } from './inbound-handoff.js';
-export declare class Debouncer {
-    private debounceMs;
-    private pending;
-    private provenanceByConversation;
-    private handoffsByConversation;
-    private timers;
-    private orderedFlags;
-    private callback;
-    constructor(debounceMs: number);
-    setCallback(cb: (conversationId: string, messages: CanonMessage[], provenanceByMessageId: ReadonlyMap<string, CanonRuntimeProvenance>, handoffs: InboundHandoffs) => void | Promise<void>): void;
-    add(conversationId: string, message: CanonMessage, provenance?: CanonRuntimeProvenance | null, handoff?: EndpointInboundHandoff): void;
-    removeMessage(conversationId: string, messageId: string): boolean;
-    private flush;
-    dropConversation(conversationId: string): CanonMessage[];
-    destroy(): void;
-}

package/dist/debouncer.js

@@ -1,133 +0,0 @@
-import { disposeInboundHandoffs } from './inbound-handoff.js';
-export class Debouncer {
-    debounceMs;
-    pending = new Map();
-    provenanceByConversation = new Map();
-    handoffsByConversation = new Map();
-    timers = new Map();
-    // Track whether each conversation's pending messages are already in sorted
-    // order so we can skip the sort on flush when possible (#10)
-    orderedFlags = new Map();
-    callback = null;
-    constructor(debounceMs) {
-        this.debounceMs = debounceMs;
-    }
-    setCallback(cb) {
-        this.callback = cb;
-    }
-    add(conversationId, message, provenance, handoff) {
-        const existing = this.pending.get(conversationId) || [];
-        if (provenance) {
-            const provenanceByMessageId = this.provenanceByConversation.get(conversationId) ?? new Map();
-            provenanceByMessageId.set(message.id, provenance);
-            this.provenanceByConversation.set(conversationId, provenanceByMessageId);
-        }
-        if (handoff) {
-            const handoffs = this.handoffsByConversation.get(conversationId) ?? new Map();
-            handoffs.set(message.id, handoff);
-            this.handoffsByConversation.set(conversationId, handoffs);
-        }
-        // Deduplicate by message ID
-        if (!existing.some((m) => m.id === message.id)) {
-            if (existing.length === 0) {
-                // First message for this conversation — trivially ordered
-                this.orderedFlags.set(conversationId, true);
-            }
-            else if (this.orderedFlags.get(conversationId) !== false) {
-                // Still potentially ordered — check if new message maintains sort order
-                const lastTime = new Date(existing[existing.length - 1].createdAt).getTime();
-                const newTime = new Date(message.createdAt).getTime();
-                if (newTime < lastTime) {
-                    this.orderedFlags.set(conversationId, false);
-                }
-            }
-            existing.push(message);
-            this.pending.set(conversationId, existing);
-        }
-        // Reset timer for this conversation
-        const existingTimer = this.timers.get(conversationId);
-        if (existingTimer)
-            clearTimeout(existingTimer);
-        this.timers.set(conversationId, setTimeout(() => {
-            this.flush(conversationId);
-        }, this.debounceMs));
-    }
-    removeMessage(conversationId, messageId) {
-        const existing = this.pending.get(conversationId);
-        if (!existing || existing.length === 0)
-            return false;
-        const next = existing.filter((message) => message.id !== messageId);
-        if (next.length === existing.length)
-            return false;
-        this.provenanceByConversation.get(conversationId)?.delete(messageId);
-        const handoff = this.handoffsByConversation.get(conversationId)?.get(messageId);
-        if (handoff)
-            void disposeInboundHandoffs(new Map([[messageId, handoff]]), 'cancel', 'message-deleted');
-        this.handoffsByConversation.get(conversationId)?.delete(messageId);
-        if (next.length === 0) {
-            this.pending.delete(conversationId);
-            this.provenanceByConversation.delete(conversationId);
-            this.handoffsByConversation.delete(conversationId);
-            this.orderedFlags.delete(conversationId);
-            const timer = this.timers.get(conversationId);
-            if (timer)
-                clearTimeout(timer);
-            this.timers.delete(conversationId);
-        }
-        else {
-            this.pending.set(conversationId, next);
-        }
-        return true;
-    }
-    flush(conversationId) {
-        const messages = this.pending.get(conversationId);
-        const isOrdered = this.orderedFlags.get(conversationId) ?? false;
-        this.pending.delete(conversationId);
-        this.timers.delete(conversationId);
-        this.orderedFlags.delete(conversationId);
-        if (messages && messages.length > 0 && this.callback) {
-            // Only sort if insertions arrived out of order (#10)
-            if (!isOrdered) {
-                messages.sort((a, b) => new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime());
-            }
-            const provenanceByMessageId = this.provenanceByConversation.get(conversationId) ?? new Map();
-            const handoffs = this.handoffsByConversation.get(conversationId) ?? new Map();
-            this.provenanceByConversation.delete(conversationId);
-            this.handoffsByConversation.delete(conversationId);
-            const failed = async (error) => {
-                await disposeInboundHandoffs(handoffs, 'release', 'dispatch-failed');
-                console.error('[canon-sdk] Inbound dispatch failed:', error);
-            };
-            try {
-                void Promise.resolve(this.callback(conversationId, messages, provenanceByMessageId, handoffs)).catch(failed);
-            }
-            catch (error) {
-                void failed(error);
-            }
-        }
-        else {
-            void disposeInboundHandoffs(this.handoffsByConversation.get(conversationId) ?? new Map(), 'release', 'no-dispatcher');
-            this.provenanceByConversation.delete(conversationId);
-            this.handoffsByConversation.delete(conversationId);
-        }
-    }
-    dropConversation(conversationId) {
-        const messages = this.pending.get(conversationId) ?? [];
-        for (const message of messages)
-            this.removeMessage(conversationId, message.id);
-        return messages;
-    }
-    destroy() {
-        for (const handoffs of this.handoffsByConversation.values()) {
-            void disposeInboundHandoffs(handoffs, 'release', 'debouncer-closed');
-        }
-        this.handoffsByConversation.clear();
-        for (const timer of this.timers.values()) {
-            clearTimeout(timer);
-        }
-        this.timers.clear();
-        this.pending.clear();
-        this.provenanceByConversation.clear();
-        this.orderedFlags.clear();
-    }
-}

package/dist/inbound-handoff.d.ts

@@ -1,6 +0,0 @@
-import type { EndpointInboundHandoff } from '@canonmsg/core';
-/** Message-keyed handles within one conversation, carried with its queue entry. */
-export type InboundHandoffs = ReadonlyMap<string, EndpointInboundHandoff>;
-export declare function selectInboundHandoffs(handoffs: InboundHandoffs, messageIds: readonly string[]): InboundHandoffs;
-/** Calls record intent synchronously, even when a durable claim is awaiting IO. */
-export declare function disposeInboundHandoffs(handoffs: InboundHandoffs, disposition: 'cancel' | 'release' | 'settle', reason: string): Promise<void>;

package/dist/inbound-handoff.js

@@ -1,17 +0,0 @@
-export function selectInboundHandoffs(handoffs, messageIds) {
-    const selected = new Map();
-    for (const id of messageIds) {
-        const handoff = handoffs.get(id);
-        if (handoff)
-            selected.set(id, handoff);
-    }
-    return selected;
-}
-/** Calls record intent synchronously, even when a durable claim is awaiting IO. */
-export async function disposeInboundHandoffs(handoffs, disposition, reason) {
-    const results = await Promise.allSettled([...handoffs.values()].map((handoff) => handoff[disposition](reason)));
-    for (const result of results) {
-        if (result.status === 'rejected')
-            console.error(`[canon-sdk] Inbound ${disposition} failed:`, result.reason);
-    }
-}

package/dist/managed-session-host.d.ts

@@ -1,27 +0,0 @@
-import { CanonClient, type WorkSessionBinding, type WorkSessionCatalog, type WorkSessionDetailFields, type WorkSessionRequest, type WorkSessionSettings } from '@canonmsg/core';
-import { type WorkSessionHostStore } from './work-session-state.js';
-export interface CanonManagedSessionHostOptions {
-    client: CanonClient;
-    agentId: string;
-    environmentId: string;
-    hostId: string;
-    displayName: string;
-    store: WorkSessionHostStore;
-    catalog(): Promise<WorkSessionCatalog>;
-    /** Must durably save the resolved selection before returning. May be called again after a crash. */
-    configure(request: WorkSessionRequest): Promise<{
-        settings: WorkSessionSettings;
-        fields: WorkSessionDetailFields;
-    }>;
-    onError?: (error: unknown, operation: string) => void;
-    pollIntervalMs?: number;
-    heartbeatIntervalMs?: number;
-}
-/** Broker coordination for a managed host whose ordinary message loop owns turns. */
-export declare function createCanonManagedSessionHost(options: CanonManagedSessionHostOptions): {
-    start: () => Promise<void>;
-    stop: () => Promise<void>;
-    reconcile: () => Promise<void>;
-    report: (conversationId: string, fields: WorkSessionDetailFields, setupState?: "configured" | "attached") => Promise<void>;
-    binding: (conversationId: string) => WorkSessionBinding | undefined;
-};

package/dist/managed-session-host.js

@@ -1,195 +0,0 @@
-import { randomUUID } from 'node:crypto';
-import { CanonApiError, } from '@canonmsg/core';
-import { createWorkSessionJournal } from './work-session-state.js';
-import { createWorkSessionAuthority, fingerprintWorkSessionRequest } from './work-session-coordination.js';
-/** Broker coordination for a managed host whose ordinary message loop owns turns. */
-export function createCanonManagedSessionHost(options) {
-    const journal = createWorkSessionJournal(options.store, {
-        environmentId: options.environmentId, agentId: options.agentId, hostId: options.hostId,
-    });
-    const runtimeEpoch = randomUUID();
-    const pollMs = options.pollIntervalMs ?? 2_000;
-    const heartbeatMs = options.heartbeatIntervalMs ?? 25_000;
-    if (!options.hostId || !Number.isFinite(pollMs) || pollMs <= 0 || !Number.isFinite(heartbeatMs)
-        || heartbeatMs <= 0 || heartbeatMs > 30_000)
-        throw new Error('Invalid managed-session host configuration.');
-    let broker;
-    let stopped = false;
-    const authority = createWorkSessionAuthority({ client: options.client, hostId: options.hostId,
-        runtimeEpoch, displayName: options.displayName, isStopped: () => stopped });
-    let started = false;
-    let pollTimer;
-    let heartbeatTimer;
-    let processing;
-    let renewing;
-    let starting;
-    const reportError = (error, operation) => { try {
-        options.onError?.(error, operation);
-    }
-    catch { /* observer */ } };
-    const auth = authority.auth;
-    const fence = authority.fence;
-    function retain(state) {
-        broker = authority.retain(state);
-    }
-    async function processRequest(request, replayed) {
-        if (request.status !== 'claimed' && request.status !== 'uncertain')
-            return;
-        fence();
-        const hash = fingerprintWorkSessionRequest(request);
-        let configuredFields;
-        let entry = journal.read().operations.find((operation) => operation.request.requestId === request.requestId);
-        if (entry && entry.fingerprint !== hash)
-            throw new Error('Managed-session request changed during recovery.');
-        if (!entry) {
-            entry = { request, fingerprint: hash, phase: 'configuring',
-                ...(replayed ? { completion: { status: 'uncertain', error: { code: 'local_state_missing',
-                            message: 'The host lost the saved setup result. Inspect this local runtime before trying again.' } }, phase: 'complete' } : {}),
-            };
-            await journal.mutate((state) => { state.operations.push(entry); });
-        }
-        if (!entry.completion) {
-            if (request.selection.mode !== 'configure') {
-                entry.completion = { status: 'failed', error: { code: 'unsupported_setup', message: 'This host only supports managed setup.' } };
-            }
-            else {
-                try {
-                    const result = await options.configure(request);
-                    fence();
-                    entry.completion = { status: 'configured', settings: result.settings };
-                    configuredFields = result.fields;
-                    await journal.mutate((state) => {
-                        const saved = state.operations.find((operation) => operation.request.requestId === request.requestId);
-                        saved.phase = 'complete';
-                        saved.completion = entry.completion;
-                    });
-                }
-                catch (error) {
-                    reportError(error, 'configure');
-                    entry.completion = { status: 'failed', error: { code: 'managed_configuration_failed',
-                            message: (error instanceof Error ? error.message : String(error)).slice(0, 512) } };
-                }
-            }
-            if (entry.completion.status !== 'configured') {
-                await journal.mutate((state) => {
-                    const saved = state.operations.find((operation) => operation.request.requestId === request.requestId);
-                    saved.phase = 'complete';
-                    saved.completion = entry.completion;
-                });
-            }
-        }
-        fence();
-        const completed = await authority.acknowledge(journal, request.requestId, entry.completion);
-        if (completed.binding) {
-            broker.bindings = [...broker.bindings.filter((binding) => binding.conversationId !== completed.conversationId), completed.binding];
-        }
-        if (configuredFields && completed.status === 'configured') {
-            await report(request.conversationId, configuredFields).catch((error) => reportError(error, 'report-configured'));
-        }
-    }
-    async function doReconcile() {
-        fence();
-        const outstanding = journal.read().operations.find((entry) => !entry.acknowledged && !entry.quarantined);
-        let claimed;
-        try {
-            claimed = await authority.claim(outstanding?.request.requestId);
-        }
-        catch (error) {
-            if (outstanding && error instanceof CanonApiError && error.code === 'WORK_SESSION_MEMBERSHIP_REQUIRED') {
-                await journal.mutate((state) => {
-                    state.operations.find((entry) => entry.request.requestId === outstanding.request.requestId).quarantined = 'Conversation membership was removed.';
-                });
-                return;
-            }
-            throw error;
-        }
-        fence();
-        if (!claimed.request) {
-            if (outstanding)
-                await journal.mutate((state) => {
-                    state.operations.find((entry) => entry.request.requestId === outstanding.request.requestId).quarantined = 'Request no longer belongs to this runtime.';
-                });
-            return;
-        }
-        if (['configured', 'failed', 'expired'].includes(claimed.request.status)) {
-            if (outstanding)
-                await journal.mutate((state) => {
-                    state.operations.find((entry) => entry.request.requestId === outstanding.request.requestId).acknowledged = true;
-                });
-            if (claimed.request.binding) {
-                broker.bindings = [...broker.bindings.filter((binding) => binding.conversationId !== claimed.request.conversationId), claimed.request.binding];
-            }
-            return;
-        }
-        await processRequest(claimed.request, claimed.replayed);
-    }
-    function reconcile() {
-        if (stopped || !started)
-            return Promise.resolve();
-        processing ??= doReconcile().finally(() => { processing = undefined; });
-        return processing;
-    }
-    async function renew() {
-        fence();
-        const state = await authority.heartbeat(await options.catalog());
-        if (!stopped)
-            retain(state);
-    }
-    function start() {
-        if (stopped)
-            throw new Error('Managed-session host already stopped.');
-        if (started && broker && broker.lease.expiresAt - Date.now() >= 5_000)
-            return Promise.resolve();
-        starting ??= (async () => {
-            if (!started)
-                await journal.load();
-            retain(await authority.register(await options.catalog()));
-            if (stopped)
-                return;
-            if (!started) {
-                started = true;
-                heartbeatTimer = setInterval(() => {
-                    if (!renewing)
-                        renewing = renew().catch((error) => reportError(error, 'lease-renewal')).finally(() => { renewing = undefined; });
-                }, heartbeatMs);
-                heartbeatTimer.unref?.();
-                pollTimer = setInterval(() => { void reconcile().catch((error) => reportError(error, 'request')); }, pollMs);
-                pollTimer.unref?.();
-            }
-            await reconcile();
-        })().finally(() => { starting = undefined; });
-        return starting;
-    }
-    async function report(conversationId, fields, setupState) {
-        fence();
-        const binding = broker.bindings.find((entry) => entry.conversationId === conversationId);
-        await options.client.reportWorkSessionDetails({ ...auth(), conversationId,
-            ...(binding ? { workSessionId: binding.workSessionId } : {}),
-            ...(setupState ? { setupState } : binding ? { setupState: binding.kind === 'managed' ? 'configured' : 'attached' } : {}),
-            fields });
-    }
-    async function stop() {
-        if (stopped)
-            return;
-        stopped = true;
-        if (pollTimer)
-            clearInterval(pollTimer);
-        if (heartbeatTimer)
-            clearInterval(heartbeatTimer);
-        await Promise.allSettled([starting, processing, renewing].filter(Boolean));
-        try {
-            if (broker)
-                await options.client.releaseWorkSessionRuntime(auth());
-        }
-        catch (error) {
-            reportError(error, 'release-runtime');
-        }
-        await journal.close();
-    }
-    function binding(conversationId) {
-        if (stopped || !broker || broker.lease.expiresAt - Date.now() < 5_000)
-            return undefined;
-        return broker.bindings.find((entry) => entry.conversationId === conversationId && entry.kind === 'managed');
-    }
-    return { start, stop, reconcile, report, binding };
-}

package/dist/managed-session-setup.d.ts

@@ -1,99 +0,0 @@
-import { type ExecutionEnvironmentMode, type LocalRuntimeResumeField, type LocalRuntimeSessionState, type WorkSessionCatalog, type WorkSessionChoice, type WorkSessionDetailFields, type WorkSessionModelChoice, type WorkSessionRequest, type WorkSessionSettings } from '@canonmsg/core';
-/**
- * Owner-confirmed ("managed") setup for a coding host whose own message loop
- * runs the turns. The broker side lives in `createCanonManagedSessionHost`;
- * these helpers are the runtime-neutral host side: the catalog it offers, the
- * idempotent `configure`, the saved-state fences and the private details it
- * reports. A runtime supplies its labels, models and permission mapping.
- */
-export interface ManagedSessionProject {
-    id: string;
-    label: string;
-    cwd: string;
-}
-/** How a runtime names itself and its native session in owner-facing errors. */
-export interface ManagedSessionRuntime {
-    /** e.g. `Codex`, `Claude Code`. */
-    label: string;
-    /** e.g. `thread`, `session`. */
-    nativeSession: string;
-    /** The local runtime catalog field holding the native session id. */
-    resumeField: LocalRuntimeResumeField;
-}
-/** Runtime-specific configured facts shown beside the generic settings. */
-export interface ManagedSessionConfiguredFacts {
-    sandbox?: string | null;
-    approvalPolicy?: string | null;
-    nativeThreadBehavior?: string;
-}
-export declare const MANAGED_EXECUTION_MODE_LABELS: Readonly<Record<ExecutionEnvironmentMode, string>>;
-export declare function buildManagedSessionCatalog(input: {
-    provider: string;
-    projects: readonly ManagedSessionProject[];
-    models: readonly WorkSessionModelChoice[];
-    defaultModelId?: string;
-    defaultReasoningEffort?: string | null;
-    /** Catalog-wide thinking levels, for models that list none of their own. */
-    reasoningEfforts?: readonly WorkSessionChoice[];
-    permissionModes: readonly WorkSessionChoice[];
-    defaultPermissionMode: string;
-    executionModes: readonly ExecutionEnvironmentMode[];
-    defaultExecutionMode: ExecutionEnvironmentMode;
-}): WorkSessionCatalog;
-/** The one saved setup for a conversation, or null; conflicting copies fail closed. */
-export declare function findManagedSessionState(runtimeId: string, conversationId: string, runtime: Pick<ManagedSessionRuntime, 'label'>): LocalRuntimeSessionState | null;
-export declare function hasSavedNativeSession(runtimeId: string, conversationId: string, resumeField: LocalRuntimeResumeField): boolean;
-/** Older records without ownership fields stay usable; a different owner generation does not. */
-export declare function savedSessionMatchesOwner(state: LocalRuntimeSessionState, ownerId: string | null, ownershipVersion: number | undefined): boolean;
-export declare function inspectGitEnvironment(cwd: string): Pick<WorkSessionDetailFields, 'branch' | 'worktreePath'>;
-/** Private owner details for a running session: confirmed settings, then what the runtime and Git observe. */
-export declare function managedSessionFields(input: {
-    settings: WorkSessionSettings;
-    cwd: string;
-    projectLabel?: string;
-    configured?: ManagedSessionConfiguredFacts;
-    observedModel?: string;
-    observedEffort?: string;
-}): WorkSessionDetailFields;
-/** Private details for a running session nobody set up: what the host and Git observe. */
-export declare function observedSessionFields(input: {
-    cwd: string;
-    executionMode?: string;
-    project?: {
-        id: string;
-        label: string;
-    };
-    observedModel?: string;
-    observedEffort?: string;
-}): WorkSessionDetailFields;
-/** Read only: details for a saved session with no live native process, if its directory still exists. */
-export declare function savedSessionFields(input: {
-    state: LocalRuntimeSessionState;
-    agentId: string;
-    projects: readonly ManagedSessionProject[];
-    describeConfigured?: (settings: WorkSessionSettings) => ManagedSessionConfiguredFacts;
-}): WorkSessionDetailFields;
-/**
- * Idempotent configuration for `createCanonManagedSessionHost`. Validates the
- * owner's selection against the catalog, prepares the requested environment
- * (a requested worktree that cannot be created fails instead of falling back)
- * and saves the setup before the broker is acknowledged. A replayed request
- * returns the saved setup; a conversation that already has a native session or
- * a different confirmed setup keeps it.
- */
-export declare function configureManagedSession(input: {
-    request: WorkSessionRequest;
-    runtimeId: string;
-    agentId: string;
-    catalog: WorkSessionCatalog;
-    projects: readonly ManagedSessionProject[];
-    runtime: ManagedSessionRuntime;
-    ownerId?: string;
-    ownershipVersion?: number;
-    /** False when the runtime cannot apply a catalog permission mode with the selected model. */
-    isPermissionModeApplicable?: (permissionMode: string, modelId: string | undefined) => boolean;
-    describeConfigured?: (settings: WorkSessionSettings) => ManagedSessionConfiguredFacts;
-}): {
-    settings: WorkSessionSettings;
-    fields: WorkSessionDetailFields;
-};