@canonmsg/agent-sdk 4.0.0 → 5.1.0

package/dist/types.d.ts

@@ -0,0 +1,321 @@
+export type { AddMemberResult, AgentClientType, CanonGroupContext, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeDescriptor, CanonRuntimeFact, CanonRuntimeFactGroup, CanonRuntimePrimitiveId, CanonRuntimeProvenance, CanonTurnContextV2, CanonMessage, CanonConversation, CanonReplyContext, CanonContact, CanonContactRequest, CanonResolveAdmissionResult, ContactAddedPayload, ContactRemovedPayload, ContactSource, AgentContext, ResolveAdmissionTargetInput, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, CanonSelfContext, CreateConversationResult, DirectSessionSelection, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, SessionConfig, CreateConversationOptions, TurnLifecycleState, TurnOutputBlock, TurnOutputBlockInput, ApprovalNativeRequestMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRequestMetadata, ApprovalRisk, ApprovalReplyMetadata, ApprovalOutcomeMetadata, RuntimeInputChoice, RuntimeInputAnswers, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputQuestion, RuntimeCardNativeMetadata, RuntimeCardV1, SessionRule, ApprovalResult, } from '@canonmsg/core';
+import type { AddMemberResult, CanonGroupContext, CanonMessage, CanonConversation, CanonReplyContext, ContactCardPayload, CanonRuntimeActionDispatch, CanonRuntimePrimitiveId, CanonRuntimeProvenance, CanonTurnContextV2, ApprovalNativeRequestMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalResult, ApprovalRisk, RuntimeInputChoice, RuntimeInputAnswers, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputQuestion, RuntimeCardNativeMetadata, RuntimeCardV1, SendMessageOptions, SendContextualSelfContextInput, SessionConfig, DirectSessionSelection, TurnOutputBlock, TurnOutputBlockInput } from '@canonmsg/core';
+import type { MaterializeMediaOptions, MaterializedCanonAttachment, ReplyWithFileOptions, UploadMediaFileOptions } from './media.js';
+export interface ProgressMessageOptions extends SendMessageOptions {
+    /**
+     * Persist the progress update to Firestore.
+     * By default, progress stays ephemeral and only updates the live RTDB turn state.
+     */
+    durable?: boolean;
+}
+export type ProgressMessageResult = {
+    turnId: string;
+    durable: false;
+    messageId: null;
+} | {
+    turnId: string;
+    durable: true;
+    messageId: string;
+};
+export interface SessionInfo {
+    /** Session ID (= conversationId) */
+    id: string;
+    /** All accumulated messages for this conversation (within the context limit), oldest first */
+    messages: CanonMessage[];
+    /** Arbitrary per-session state the agent can read/write across handler calls */
+    metadata: Record<string, unknown>;
+    queueDepth?: number;
+}
+export interface TurnController {
+    id: string;
+    state: import('@canonmsg/core').TurnLifecycleState;
+    setThinking: (text?: string) => Promise<void>;
+    setStreaming: (text: string) => Promise<void>;
+    appendDelta: (delta: string) => void;
+    appendBlock: (block: string) => void;
+    appendTextSegmentDelta: (id: string, delta: string) => void;
+    replaceTextSegmentSnapshot: (id: string, text: string) => 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>;
+    replaceSnapshot: (text: string) => Promise<void>;
+    flush: () => Promise<void>;
+    clear: () => Promise<void>;
+    setTool: (text: string) => Promise<void>;
+    setWaitingInput: (text?: string) => Promise<void>;
+}
+export interface RuntimeApprovalRequest {
+    /** Native runtime/tool/action name that is asking for permission. */
+    toolName: string;
+    /** Structured native input. Raw values are summarized/redacted before storage. */
+    toolInput?: Record<string, unknown>;
+    /** Optional pre-redacted summary when a runtime already has user-facing copy. */
+    toolSummary?: string;
+    category?: ApprovalRequestCategory;
+    risk?: ApprovalRisk;
+    riskLevel?: 'normal' | 'destructive';
+    runtimeId?: string;
+    turnId?: string;
+    native?: ApprovalNativeRequestMetadata;
+    details?: ApprovalRequestDetail[];
+    /**
+     * Ignore in-memory session rules for this approval request. Useful when the
+     * action was triggered by someone other than the agent owner.
+     */
+    ignoreSessionRules?: boolean;
+    /** Whether an approval reply may set an in-memory session rule. */
+    allowSessionRule?: boolean;
+}
+export interface RuntimeInputRequest {
+    kind: RuntimeInputKind;
+    title: string;
+    prompt: string;
+    choices?: RuntimeInputChoice[];
+    questions?: RuntimeInputQuestion[];
+    secretName?: string;
+    sensitive?: boolean;
+    runtimeId?: string;
+    turnId?: string;
+    native?: RuntimeInputNativeMetadata;
+    inputId?: string;
+    timeoutMs?: number;
+}
+export interface RuntimeInputResult {
+    status: 'submitted' | 'cancelled' | 'timeout';
+    value?: string;
+    answers?: RuntimeInputAnswers;
+    inputId: string;
+}
+export interface RuntimeCardRequest {
+    card: RuntimeCardV1;
+    cardId?: string;
+    expiresAt?: string | number | Date;
+    responseUserId?: string;
+    timeoutMs?: number;
+    runtimeId?: string;
+    turnId?: string;
+    native?: RuntimeCardNativeMetadata;
+}
+export interface RuntimeCardResult {
+    status: 'submitted' | 'cancelled' | 'timeout' | 'displayed';
+    cardId: string;
+    actionId?: string;
+    values?: Record<string, unknown>;
+}
+export interface MessageHandlerContext {
+    messages: CanonMessage[];
+    history: CanonMessage[];
+    /** Resolved message/media content for the latest swipe-reply target, if any. */
+    replyContext: CanonReplyContext | null;
+    conversationId: string;
+    conversation: CanonConversation;
+    /** Lightweight group awareness, present for group conversations. */
+    groupContext?: CanonGroupContext;
+    replyFinal: (text: string, options?: SendMessageOptions) => Promise<{
+        messageId: string;
+    }>;
+    replyProgress: (text: string, options?: ProgressMessageOptions) => Promise<ProgressMessageResult>;
+    /** Soft-delete a message (agent must be the sender) */
+    deleteMessage: (messageId: string) => Promise<void>;
+    /** Mark conversation as read */
+    markAsRead: () => Promise<void>;
+    /** Leave this conversation */
+    leave: () => Promise<void>;
+    /** Toggle emoji reaction on a message */
+    react: (messageId: string, emoji: string) => Promise<void>;
+    /**
+     * Add a member to this conversation (requires owner/admin role).
+     * Returns `{ status: 'added' }` on immediate add, or
+     * `{ status: 'pending', requestId }` if the target requires approval —
+     * a contact-request (kind: 'group_invite') is created and the join
+     * lands when the approver accepts.
+     */
+    addMember: (userId: string) => Promise<AddMemberResult>;
+    /** Remove a member from this conversation (requires owner/admin role) */
+    removeMember: (userId: string) => Promise<void>;
+    /** Send into another Canon conversation with private cross-session self-context. */
+    sendContextualMessage: (target: {
+        targetConversationId: string;
+    } | {
+        targetUserId: string;
+    }, text: string, options: Omit<import('@canonmsg/core').SendContextualMessageOptions, 'sourceConversationId' | 'targetConversationId' | 'targetUserId' | 'text'>) => Promise<import('@canonmsg/core').SendContextualMessageResult>;
+    /** Reach a contact card from this conversation; contextual reach-outs use this conversation as source. */
+    reachOut: (card: ContactCardPayload, options?: Omit<ReachOutOptions, 'sourceConversationId'>) => Promise<ReachOutResult>;
+    /** Trusted agent identity & access context */
+    agent: import('@canonmsg/core').AgentContext;
+    /** Active private self-context to continue for this turn, if Canon supplied one. */
+    activeSelfContextId: string | null;
+    /** Canon-provided private context explaining this agent's cross-session actions. */
+    selfContexts?: import('@canonmsg/core').CanonSelfContext[];
+    /** Trusted Canon provenance for the latest inbound message in this handler batch. */
+    provenance: CanonRuntimeProvenance;
+    /** Compact structured Canon turn context for the latest inbound message in this handler batch. */
+    turnContext: CanonTurnContextV2;
+    /** Runtime turn mode requested by the sender for this inbound turn, if any. */
+    requestedTurnMode: string | null;
+    /**
+     * Ask the conversation owner to approve a native runtime action. This only
+     * renders Canon's inline approval card; runtimes must explicitly wait for
+     * and enforce the returned decision in their own approval hook.
+     */
+    requestApproval: (request: RuntimeApprovalRequest) => Promise<ApprovalResult>;
+    /**
+     * Ask the agent owner for runtime input such as clarification, sudo, or a
+     * secret. Sensitive values are returned only to the calling runtime and are
+     * never persisted in Canon message metadata.
+     */
+    requestRuntimeInput: (request: RuntimeInputRequest) => Promise<RuntimeInputResult>;
+    /**
+     * Ask the agent owner to review/respond to a generic rich card. The visible
+     * card document is redacted for presentation; raw response values return
+     * only to the calling runtime through Canon's control path.
+     */
+    requestCard: (request: RuntimeCardRequest) => Promise<RuntimeCardResult>;
+    /**
+     * Post a fire-and-forget display/report card and return immediately with
+     * `{ status: 'displayed' }` — no waiting-input lifecycle. Use requestCard for
+     * cards that expect a response. (requestCard also auto-detects action-less
+     * cards and delegates here.)
+     */
+    sendCard: (request: RuntimeCardRequest) => Promise<RuntimeCardResult>;
+    /** Canon-managed local media access for the current conversation. */
+    media: {
+        materialize: (message?: CanonMessage, options?: Omit<MaterializeMediaOptions, 'agentId' | 'conversationId' | 'messageId'>) => Promise<MaterializedCanonAttachment[]>;
+        uploadFile: (filePath: string, options?: UploadMediaFileOptions) => Promise<{
+            url: string;
+            attachment: import('@canonmsg/core').MediaAttachment;
+        }>;
+        replyWithFile: (filePath: string, text?: string, options?: ReplyWithFileOptions) => Promise<{
+            messageId: string;
+        }>;
+    };
+    /** Per-conversation session state. Present when sessions are enabled. */
+    session?: SessionInfo;
+    /** Turn lifecycle helpers for live-work rendering and progress reporting. */
+    turn?: TurnController;
+    /** Aborted when Canon sends an interrupt/stop signal for this active turn. */
+    abortSignal: AbortSignal;
+}
+export type MessageHandler = (ctx: MessageHandlerContext) => Promise<void>;
+export type MessageUpdatedHandler = (payload: import('@canonmsg/core').MessageUpdatedPayload) => void | Promise<void>;
+export interface SessionOptions {
+    /** Enable per-conversation session management (default: false) */
+    enabled: boolean;
+    /** Max messages retained per session (default: 50) */
+    contextLimit?: number;
+    /** Max sessions processing concurrently (default: 10) */
+    concurrency?: number;
+    /** Evict idle sessions after this many ms (default: 3600000 = 1h) */
+    idleTimeoutMs?: number;
+}
+export type DeliveryMode = 'auto' | 'sse';
+export type RuntimeSignalType = Extract<CanonRuntimeActionDispatch, {
+    kind: 'signal';
+}>['signal'];
+export interface RuntimeSignalContext {
+    conversationId: string;
+    signal: RuntimeSignalType;
+    updatedAt?: number;
+    abortSignal?: AbortSignal;
+    droppedMessageIds: string[];
+}
+export type RuntimeSignalHandler = (context: RuntimeSignalContext) => void | Promise<void>;
+export interface RuntimeControlHandlers {
+    onInterrupt?: RuntimeSignalHandler;
+    onStopAndDrop?: RuntimeSignalHandler;
+    onNewSession?: RuntimeSignalHandler;
+}
+export type RuntimeControlSurface = 'agent' | 'host';
+export interface RuntimePrimitiveContext {
+    conversationId: string;
+    primitive: CanonRuntimePrimitiveId;
+    args: Record<string, string | boolean>;
+    rawText?: string;
+    alias?: string;
+    requestId?: string;
+    updatedAt?: number;
+}
+export type RuntimePrimitiveHandler = (context: RuntimePrimitiveContext) => void | Promise<void>;
+export type RuntimePrimitiveHandlers = Partial<Record<CanonRuntimePrimitiveId, RuntimePrimitiveHandler>> & {
+    '*'?: RuntimePrimitiveHandler;
+};
+export interface CanonAgentOptions {
+    apiKey: string;
+    baseUrl?: string;
+    streamUrl?: string;
+    /** `auto` resolves to SSE. */
+    deliveryMode?: DeliveryMode;
+    debounceMs?: number;
+    historyLimit?: number;
+    /** Automatically mark conversations as read when handling messages (default: true) */
+    autoMarkRead?: boolean;
+    /** Per-conversation session management */
+    sessions?: SessionOptions;
+    /** Agent client type for capability detection. Defaults to 'generic'. */
+    clientType?: import('@canonmsg/core').AgentClientType;
+    /** Optional runtime descriptor published to Canon for setup/live UI rendering. */
+    runtimeDescriptor?: import('@canonmsg/core').CanonRuntimeDescriptor;
+    /** Optional Canon runtime signal handlers. Enables interrupt controls when provided. */
+    runtimeControls?: RuntimeControlHandlers;
+    /** Runtime publishing surface. Use `host` when this agent owns live runtime controls. */
+    runtimeControlSurface?: RuntimeControlSurface;
+    /** Optional typed runtime primitive handlers. Enables descriptor-backed command controls when provided. */
+    runtimePrimitives?: RuntimePrimitiveHandlers;
+    /**
+     * Enable RTDB session-state reporting. Off by default.
+     * Turn-state reporting is automatic while handlers run.
+     */
+    sessionState?: boolean;
+}
+export type ContactRequestHandler = (request: import('@canonmsg/core').CanonContactRequest) => void | Promise<void>;
+export type ContactAddedHandler = (contact: import('@canonmsg/core').ContactAddedPayload) => void | Promise<void>;
+export type ContactRemovedHandler = (payload: import('@canonmsg/core').ContactRemovedPayload) => void | Promise<void>;
+/**
+ * Result of `agent.reachOut(card)` — describes which side-effect ran so the
+ * caller can decide what to tell the LLM. `messaged` means the agent opened
+ * (or sent into) a direct conversation; `requested` means the target's
+ * inbound policy required a contact request, which has been created;
+ * `pending` means a prior outbound request is still awaiting approval; and
+ * `blocked` / `unavailable` describe terminal states with `reason` set.
+ */
+export type ReachOutResult = {
+    status: 'messaged';
+    conversationId: string;
+    messageId?: string;
+    selfContextId?: string;
+    created?: boolean;
+    reused?: boolean;
+    sessionSelection?: DirectSessionSelection['mode'];
+} | {
+    status: 'requested';
+    requestId: string | null;
+    deferredIntentId?: string | null;
+} | {
+    status: 'pending';
+    requestId: string | null;
+    deferredIntentId?: string | null;
+} | {
+    status: 'setup_required';
+    reason: string;
+} | {
+    status: 'no_session';
+    reason: string;
+} | {
+    status: 'blocked' | 'unavailable';
+    reason: string;
+};
+export interface ReachOutOptions {
+    /** Optional first message to send when admission is `allowed`. */
+    text?: string;
+    /** Optional contact-request note. Defaults to `text` when admission is `request-required`. */
+    requestMessage?: string;
+    /** Explicit session setup to use when the contact-card target is an agent. */
+    sessionConfig?: SessionConfig | null;
+    /** Whether to continue an existing direct agent session or start a fresh one. */
+    sessionSelection?: DirectSessionSelection;
+    /** Source conversation for contextual cross-session reach-outs. */
+    sourceConversationId?: string;
+    /** Private context for the agent when this reach-out sends a cross-session message. */
+    selfContext?: SendContextualSelfContextInput;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,18 +1,18 @@
 {
   "name": "@canonmsg/agent-sdk",
-  "version": "4.0.0",
-  "description": "Canon media helpers + in-process session queue for integration adapters (the pre-bridge CanonAgent runtime lives on only in the published 3.x line)",
+  "version": "5.1.0",
+  "description": "Canon Agent SDK — build AI agents that participate in Canon conversations",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
     },
     "./media": {
-      "types": "./dist/media.d.ts",
-      "import": "./dist/media.js"
+      "import": "./dist/media.js",
+      "types": "./dist/media.d.ts"
     }
   },
   "files": [
@@ -28,7 +28,7 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@canonmsg/core": "^3.3.0"
+    "@canonmsg/core": "^4.2.0"
   },
   "publishConfig": {
     "access": "public"