@canonmsg/agent-sdk 11.2.1 → 12.0.0

package/dist/session-manager.d.ts

@@ -1,77 +0,0 @@
-import type { CanonMessage } from '@canonmsg/core';
-import { type InboundHandoffs } from './inbound-handoff.js';
-export interface SessionConfig {
-    /** Max messages to retain per session (default: 50) */
-    contextLimit?: number;
-    /** Max sessions processing concurrently (default: 10) */
-    concurrency?: number;
-    /** Evict idle sessions after this many ms (default: 1h) */
-    idleTimeoutMs?: number;
-}
-export interface Session {
-    /** Session ID (= conversationId) */
-    id: string;
-    /** Accumulated messages for this conversation, oldest first */
-    messages: CanonMessage[];
-    /** Arbitrary per-session state managed by the agent */
-    metadata: Record<string, unknown>;
-    /** When this session last processed a message */
-    lastActiveAt: number;
-}
-type SessionHandler = (session: Session, newMessages: CanonMessage[], handoffs: InboundHandoffs) => Promise<void>;
-export interface EnqueueOptions {
-    /** Place this batch ahead of other not-yet-running batches. */
-    toFront?: boolean;
-    /** Execution receipts carried with this batch, independent of retained history. */
-    handoffs?: InboundHandoffs;
-}
-/**
- * Manages per-conversation sessions with:
- * - In-memory message buffer per session
- * - Serialized processing within a session (queue)
- * - Parallel processing across sessions (bounded concurrency)
- * - Idle session eviction
- */
-export declare class SessionManager {
-    private sessions;
-    private queues;
-    private activeCount;
-    private destroyed;
-    private pending;
-    private processing;
-    private seenMessages;
-    private seededSessions;
-    private sweepTimer;
-    private contextLimit;
-    private concurrency;
-    private idleTimeoutMs;
-    constructor(config?: SessionConfig);
-    /** Get or create a session for a conversation */
-    getSession(conversationId: string): Session;
-    private appendMessagesToSession;
-    private removeMessagesFromSession;
-    /**
-     * Enqueue messages for processing in a specific session.
-     * Returns a promise that resolves when the handler completes for these messages.
-     *
-     * - Messages within the same session are serialized (queued).
-     * - Messages across different sessions run concurrently up to the concurrency limit.
-     */
-    enqueue(conversationId: string, messages: CanonMessage[], handler: SessionHandler, options?: EnqueueOptions): Promise<void>;
-    private drainSession;
-    /** Seed a session with historical messages (e.g. fetched from API) */
-    seedHistory(conversationId: string, history: CanonMessage[]): void;
-    /** Remove idle sessions */
-    private sweep;
-    /** Number of queued batches waiting behind the active turn for this conversation. */
-    getQueueDepth(conversationId: string): number;
-    /** Drop one not-yet-running queued message for a conversation. */
-    dropQueuedMessage(conversationId: string, messageId: string): CanonMessage[];
-    /** Drop queued, not-yet-running batches for a conversation. */
-    dropQueued(conversationId: string): CanonMessage[];
-    /** Drop queued work and clear retained context for a conversation. */
-    resetSession(conversationId: string): CanonMessage[];
-    /** Clean up all state */
-    destroy(): void;
-}
-export {};

package/dist/session-manager.js

@@ -1,285 +0,0 @@
-import { disposeInboundHandoffs, selectInboundHandoffs } from './inbound-handoff.js';
-const DEFAULT_CONTEXT_LIMIT = 50;
-const DEFAULT_CONCURRENCY = 10;
-const DEFAULT_IDLE_TIMEOUT_MS = 60 * 60 * 1000; // 1 hour
-const SWEEP_INTERVAL_MS = 60 * 1000; // 1 minute
-/**
- * Manages per-conversation sessions with:
- * - In-memory message buffer per session
- * - Serialized processing within a session (queue)
- * - Parallel processing across sessions (bounded concurrency)
- * - Idle session eviction
- */
-export class SessionManager {
-    sessions = new Map();
-    queues = new Map();
-    activeCount = 0;
-    destroyed = false;
-    // Use Set<string> instead of Array for O(1) dedup and correct pop semantics (#1, #2)
-    pending = new Set();
-    processing = new Set();
-    // Per-session seen message ID sets for O(1) dedup (#9)
-    seenMessages = new Map();
-    // Track seeded sessions so seedHistory is idempotent (#7)
-    seededSessions = new Set();
-    sweepTimer = null;
-    contextLimit;
-    concurrency;
-    idleTimeoutMs;
-    constructor(config = {}) {
-        this.contextLimit = config.contextLimit ?? DEFAULT_CONTEXT_LIMIT;
-        this.concurrency = config.concurrency ?? DEFAULT_CONCURRENCY;
-        this.idleTimeoutMs = config.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
-        this.sweepTimer = setInterval(() => this.sweep(), SWEEP_INTERVAL_MS);
-        // Don't hold the process open for the sweeper
-        if (this.sweepTimer.unref)
-            this.sweepTimer.unref();
-    }
-    /** Get or create a session for a conversation */
-    getSession(conversationId) {
-        let session = this.sessions.get(conversationId);
-        if (!session) {
-            session = {
-                id: conversationId,
-                messages: [],
-                metadata: {},
-                lastActiveAt: Date.now(),
-            };
-            this.sessions.set(conversationId, session);
-            this.seenMessages.set(conversationId, new Set());
-        }
-        // Refresh lastActiveAt on every access to prevent premature eviction (#8)
-        session.lastActiveAt = Date.now();
-        return session;
-    }
-    appendMessagesToSession(conversationId, messages) {
-        const session = this.getSession(conversationId);
-        const seen = this.seenMessages.get(conversationId);
-        for (const msg of messages) {
-            if (!seen.has(msg.id)) {
-                seen.add(msg.id);
-                session.messages.push(msg);
-            }
-        }
-        if (session.messages.length > this.contextLimit) {
-            session.messages = session.messages.slice(-this.contextLimit);
-            const retainedIds = new Set(session.messages.map((message) => message.id));
-            for (const id of Array.from(seen)) {
-                if (!retainedIds.has(id)) {
-                    seen.delete(id);
-                }
-            }
-        }
-        session.lastActiveAt = Date.now();
-        return session;
-    }
-    removeMessagesFromSession(conversationId, messages) {
-        if (messages.length === 0)
-            return;
-        const session = this.sessions.get(conversationId);
-        const seen = this.seenMessages.get(conversationId);
-        if (!session && !seen)
-            return;
-        const droppedIds = new Set(messages.map((message) => message.id));
-        if (session) {
-            session.messages = session.messages.filter((message) => !droppedIds.has(message.id));
-        }
-        if (seen) {
-            for (const id of droppedIds) {
-                seen.delete(id);
-            }
-        }
-    }
-    /**
-     * Enqueue messages for processing in a specific session.
-     * Returns a promise that resolves when the handler completes for these messages.
-     *
-     * - Messages within the same session are serialized (queued).
-     * - Messages across different sessions run concurrently up to the concurrency limit.
-     */
-    async enqueue(conversationId, messages, handler, options = {}) {
-        if (this.destroyed) {
-            await disposeInboundHandoffs(options.handoffs ?? new Map(), 'release', 'session-manager-closed');
-            return;
-        }
-        const session = this.getSession(conversationId);
-        session.lastActiveAt = Date.now();
-        return new Promise((resolve, reject) => {
-            // Add to this session's queue
-            let queue = this.queues.get(conversationId);
-            if (!queue) {
-                queue = [];
-                this.queues.set(conversationId, queue);
-            }
-            const batch = { messages, handler, resolve, reject, handoffs: options.handoffs ?? new Map() };
-            if (options.toFront) {
-                queue.unshift(batch);
-            }
-            else {
-                queue.push(batch);
-            }
-            // Try to drain
-            this.drainSession(conversationId);
-        });
-    }
-    drainSession(conversationId) {
-        // Already processing this session — the current run will pick up queued items
-        if (this.destroyed || this.processing.has(conversationId))
-            return;
-        const queue = this.queues.get(conversationId);
-        if (!queue || queue.length === 0)
-            return;
-        // Check concurrency limit
-        if (this.activeCount >= this.concurrency) {
-            // Park this session — Set.add() is atomic and idempotent, eliminating
-            // the race between check and insert (#1)
-            this.pending.add(conversationId);
-            return;
-        }
-        // Take the next item
-        const item = queue.shift();
-        if (queue.length === 0)
-            this.queues.delete(conversationId);
-        this.activeCount++;
-        this.processing.add(conversationId);
-        const session = this.appendMessagesToSession(conversationId, item.messages);
-        item.handler(session, item.messages, item.handoffs)
-            .then(() => item.resolve())
-            .catch((err) => item.reject(err))
-            .finally(() => {
-            this.processing.delete(conversationId);
-            this.activeCount--;
-            // Continue draining this session if more items queued
-            const remaining = this.queues.get(conversationId);
-            if (remaining && remaining.length > 0) {
-                this.drainSession(conversationId);
-            }
-            // Unpark the next pending session.
-            // Use Set iteration + explicit delete to get the correct conversation ID
-            // rather than shift() which could dequeue the wrong entry (#2)
-            if (this.pending.size > 0) {
-                const nextId = this.pending.values().next().value;
-                this.pending.delete(nextId);
-                this.drainSession(nextId);
-            }
-        });
-    }
-    /** Seed a session with historical messages (e.g. fetched from API) */
-    seedHistory(conversationId, history) {
-        // Idempotent: only seed once per session, preventing races between
-        // concurrent batches that both observe an empty session (#7)
-        if (this.seededSessions.has(conversationId))
-            return;
-        const session = this.getSession(conversationId);
-        // Only seed if session is empty (first time)
-        if (session.messages.length > 0)
-            return;
-        this.seededSessions.add(conversationId);
-        const seen = this.seenMessages.get(conversationId);
-        const sliced = history.slice(-this.contextLimit);
-        session.messages = sliced;
-        for (const msg of sliced) {
-            seen.add(msg.id);
-        }
-    }
-    /** Remove idle sessions */
-    sweep() {
-        const now = Date.now();
-        for (const [id, session] of this.sessions) {
-            if (now - session.lastActiveAt > this.idleTimeoutMs &&
-                !this.processing.has(id) &&
-                !this.queues.has(id) &&
-                !this.pending.has(id) // also skip sessions waiting for a concurrency slot (#8)
-            ) {
-                this.sessions.delete(id);
-                this.seenMessages.delete(id);
-                this.seededSessions.delete(id);
-            }
-        }
-    }
-    /** Number of queued batches waiting behind the active turn for this conversation. */
-    getQueueDepth(conversationId) {
-        return this.queues.get(conversationId)?.length ?? 0;
-    }
-    /** Drop one not-yet-running queued message for a conversation. */
-    dropQueuedMessage(conversationId, messageId) {
-        const queue = this.queues.get(conversationId);
-        if (!queue || queue.length === 0)
-            return [];
-        const droppedMessages = [];
-        const nextQueue = [];
-        for (const item of queue) {
-            const keptMessages = item.messages.filter((message) => {
-                const drop = message.id === messageId;
-                if (drop) {
-                    droppedMessages.push(message);
-                    void disposeInboundHandoffs(selectInboundHandoffs(item.handoffs, [message.id]), 'cancel', 'message-deleted');
-                }
-                return !drop;
-            });
-            if (keptMessages.length === 0) {
-                item.resolve();
-            }
-            else if (keptMessages.length !== item.messages.length) {
-                nextQueue.push({ ...item, messages: keptMessages, handoffs: selectInboundHandoffs(item.handoffs, keptMessages.map((message) => message.id)) });
-            }
-            else {
-                nextQueue.push(item);
-            }
-        }
-        if (droppedMessages.length === 0)
-            return [];
-        if (nextQueue.length === 0) {
-            this.queues.delete(conversationId);
-            this.pending.delete(conversationId);
-        }
-        else {
-            this.queues.set(conversationId, nextQueue);
-        }
-        this.removeMessagesFromSession(conversationId, droppedMessages);
-        return droppedMessages;
-    }
-    /** Drop queued, not-yet-running batches for a conversation. */
-    dropQueued(conversationId) {
-        const queue = this.queues.get(conversationId);
-        if (!queue || queue.length === 0)
-            return [];
-        this.queues.delete(conversationId);
-        this.pending.delete(conversationId);
-        const droppedMessages = queue.flatMap((item) => item.messages);
-        this.removeMessagesFromSession(conversationId, droppedMessages);
-        for (const item of queue) {
-            void disposeInboundHandoffs(item.handoffs, 'cancel', 'queue-dropped');
-            item.resolve();
-        }
-        return droppedMessages;
-    }
-    /** Drop queued work and clear retained context for a conversation. */
-    resetSession(conversationId) {
-        const droppedMessages = this.dropQueued(conversationId);
-        this.sessions.delete(conversationId);
-        this.seenMessages.delete(conversationId);
-        this.seededSessions.delete(conversationId);
-        return droppedMessages;
-    }
-    /** Clean up all state */
-    destroy() {
-        this.destroyed = true;
-        for (const queue of this.queues.values()) {
-            for (const item of queue) {
-                void disposeInboundHandoffs(item.handoffs, 'release', 'session-manager-closed');
-                item.resolve();
-            }
-        }
-        if (this.sweepTimer) {
-            clearInterval(this.sweepTimer);
-            this.sweepTimer = null;
-        }
-        this.sessions.clear();
-        this.queues.clear();
-        this.pending.clear();
-        this.processing.clear();
-        this.seenMessages.clear();
-        this.seededSessions.clear();
-    }
-}

package/dist/turn-streaming-request.d.ts

@@ -1,17 +0,0 @@
-import type { CanonClient, TurnOutputSnapshot } from '@canonmsg/core';
-export type TurnStreamingRequest = Parameters<CanonClient['setStreaming']>[0];
-/**
- * Builds the `POST /streaming` body for one turn-output snapshot.
- *
- * Extracted from the turn loop for one reason: `blocks` must be forwarded
- * VERBATIM, empty array included. `POST /streaming` merges into the RTDB node,
- * so an absent `blocks` key leaves the previous trail in place — and the
- * `onStreamingCleared` trigger rebuilds salvage text out of block titles. A
- * silent turn blanks the node with `text: ''` and `blocks: []`; drop the empty
- * array on the way out and the turn the model declined to send comes back as a
- * durable bubble made of its own tool-trail headings.
- */
-export declare function buildTurnStreamingRequest(input: {
-    conversationId: string;
-    snapshot: TurnOutputSnapshot;
-}): TurnStreamingRequest;

package/dist/turn-streaming-request.js

@@ -1,22 +0,0 @@
-/**
- * Builds the `POST /streaming` body for one turn-output snapshot.
- *
- * Extracted from the turn loop for one reason: `blocks` must be forwarded
- * VERBATIM, empty array included. `POST /streaming` merges into the RTDB node,
- * so an absent `blocks` key leaves the previous trail in place — and the
- * `onStreamingCleared` trigger rebuilds salvage text out of block titles. A
- * silent turn blanks the node with `text: ''` and `blocks: []`; drop the empty
- * array on the way out and the turn the model declined to send comes back as a
- * durable bubble made of its own tool-trail headings.
- */
-export function buildTurnStreamingRequest(input) {
-    const { conversationId, snapshot } = input;
-    return {
-        conversationId,
-        text: snapshot.text,
-        status: snapshot.status,
-        messageId: snapshot.messageId,
-        turnId: snapshot.turnId,
-        blocks: snapshot.blocks,
-    };
-}

package/dist/turn-verbosity-option.d.ts

@@ -1,33 +0,0 @@
-import { type TurnVerbosityConfig, type TurnVerbosityConversationType } from '@canonmsg/core';
-/**
- * What a developer may write for `CanonAgentOptions.turnVerbosity`.
- *
- * The SDK is the one runtime where a per-conversation-type OBJECT is idiomatic:
- * it has no argv and no config file, so `{ group: 'verbose' }` costs a
- * developer nothing while the hosts would have to invent a flag grammar for the
- * same thing. Everything else — the vocabulary, the defaults, `'auto'` ≡ unset
- * — stays in core's `resolveTurnVerbosity`, which this folds into rather than
- * reimplements.
- *
- * Deliberately NOT promoted to `@canonmsg/core`: the Claude host, the Codex
- * host, OpenClaw and Hermes all take a scalar (a CLI flag, an env var or a
- * config-file string), so core would grow a shape with exactly one consumer.
- */
-export type CanonAgentTurnVerbosityOption = TurnVerbosityConfig | {
-    /** Applies to direct chats — Hermes's `'dm'` spelling included. */
-    direct?: TurnVerbosityConfig;
-    group?: TurnVerbosityConfig;
-};
-/**
- * Picks the configured value this turn's conversation type is subject to, in
- * the shape `resolveTurnVerbosity` takes.
- *
- * `null` means "nothing configured for this type" and lets core's per-type
- * default decide — which is also what an `'auto'` entry and an unrecognized
- * string produce, so an object that names only `group` leaves DMs on the
- * default rather than forcing them anywhere. A conversation type that resolves
- * to `'unknown'` (the fetch failed, or provenance was absent) matches no key
- * and therefore falls through to the fail-open default too: an object form
- * cannot silence a turn whose shape Canon could not name.
- */
-export declare function selectConfiguredTurnVerbosity(option: CanonAgentTurnVerbosityOption | null | undefined, conversationType: TurnVerbosityConversationType | null | undefined): TurnVerbosityConfig | null;

package/dist/turn-verbosity-option.js

@@ -1,23 +0,0 @@
-import { normalizeTurnVerbosityConversationType, parseTurnVerbosityConfig, } from '@canonmsg/core';
-/**
- * Picks the configured value this turn's conversation type is subject to, in
- * the shape `resolveTurnVerbosity` takes.
- *
- * `null` means "nothing configured for this type" and lets core's per-type
- * default decide — which is also what an `'auto'` entry and an unrecognized
- * string produce, so an object that names only `group` leaves DMs on the
- * default rather than forcing them anywhere. A conversation type that resolves
- * to `'unknown'` (the fetch failed, or provenance was absent) matches no key
- * and therefore falls through to the fail-open default too: an object form
- * cannot silence a turn whose shape Canon could not name.
- */
-export function selectConfiguredTurnVerbosity(option, conversationType) {
-    if (option === null || option === undefined)
-        return null;
-    if (typeof option === 'string')
-        return parseTurnVerbosityConfig(option);
-    const key = normalizeTurnVerbosityConversationType(conversationType);
-    if (key === 'unknown')
-        return null;
-    return parseTurnVerbosityConfig(option[key]);
-}