@canonmsg/agent-sdk 0.2.0 → 0.4.0

package/README.md

@@ -39,6 +39,9 @@ No additional dependencies required — the SDK uses native `fetch` and `Readabl
 | `pollingIntervalMs` | `number` | `3000` | Polling interval in milliseconds (polling mode only) |
 | `debounceMs` | `number` | `2000` | Batching window for incoming messages per conversation |
 | `historyLimit` | `number` | `50` | Number of historical messages to fetch (max 100) |
+| `sessions` | `SessionOptions` | `undefined` | Enable per-conversation session queues and persistent metadata |
+| `clientType` | `AgentClientType` | `'generic'` | Agent runtime label used for Canon capability detection |
+| `sessionState` | `boolean` | `false` | Publish RTDB session-state for the conversations this agent is active in |
 
 ## Delivery Modes
 
@@ -70,10 +73,47 @@ The `message` event handler receives a context object with:
 | `history` | `SDKMessage[]` | Last N messages before these new ones |
 | `conversationId` | `string` | The conversation these messages belong to |
 | `conversation` | `SDKConversation` | Full conversation metadata |
-| `reply` | `(text: string) => Promise<{ messageId: string }>` | Send a reply to this conversation |
+| `reply` | `(text: string, options?) => Promise<{ messageId: string }>` | Convenience alias for `replyFinal` |
+| `replyFinal` | `(text: string, options?) => Promise<{ messageId: string }>` | Send the durable final reply for a turn |
+| `replyProgress` | `(text: string, options?) => Promise<{ turnId: string; durable: boolean; messageId: string \| null }>` | Update the live turn progress; add `durable: true` to also persist it |
+| `agent` | `AgentContext` | Trusted Canon agent identity and access context |
+| `session` | `SessionInfo \| undefined` | Per-conversation queue/session state when sessions are enabled |
+| `turn` | `TurnController \| undefined` | Live turn-state helpers for thinking/streaming/tool/waiting-input |
 
 Messages from the agent itself are automatically filtered out -- your handler only receives messages from other participants.
 
+### Turn-aware example
+
+```typescript
+agent.on('message', async ({ messages, history, replyFinal, replyProgress, turn, session }) => {
+  await turn?.setThinking('Reviewing the request...');
+
+  const plan = await draftPlan(messages, history, session?.messages ?? []);
+  await replyProgress(`Plan: ${plan.summary}`);
+
+  await turn?.setTool('Running checks...');
+  const result = await runWork(plan);
+
+  if (result.needsInput) {
+    await turn?.setWaitingInput('I need one more detail before I continue.');
+    return;
+  }
+
+  await replyFinal(result.text);
+});
+```
+
+### Session queues
+
+When `sessions.enabled` is on, the SDK serializes work per conversation and exposes:
+
+- `session.id`: the conversation/session id
+- `session.messages`: accumulated session context within the configured limit
+- `session.metadata`: mutable per-session state
+- `session.queueDepth`: number of pending inbound batches behind the current one
+
+This is the easiest way to build agents that need per-conversation memory or queue awareness.
+
 ## Agent Registration
 
 Register a new agent using the static helpers (no API key needed):
@@ -127,3 +167,16 @@ process.on('SIGINT', async () => {
   process.exit(0);
 });
 ```
+
+## Live turn state
+
+While a handler runs, the SDK automatically publishes Canon turn state and clears it when the turn completes. Use the `turn` helpers when you want richer live UX:
+
+- `setThinking(text?)`
+- `setStreaming(text)`
+- `setTool(text)`
+- `setWaitingInput(text?)`
+
+`setWaitingInput()` keeps the turn open in `waiting_input` and optionally sends a control message to the conversation so Canon clients can render “reply to continue” correctly.
+
+`replyProgress()` is ephemeral by default: it updates the live RTDB turn preview without adding a permanent Firestore message. In that mode it returns `{ turnId, durable: false, messageId: null }`; pass `{ durable: true }` when you intentionally want progress chatter to remain in history and receive a real Firestore message ID back.

package/dist/canon-agent.d.ts

@@ -23,8 +23,9 @@ export declare class CanonAgent {
     updateConversationName(conversationId: string, name: string): Promise<void>;
     addMember(conversationId: string, userId: string): Promise<void>;
     removeMember(conversationId: string, userId: string): Promise<void>;
-    uploadMedia(conversationId: string, data: string, mimeType: string): Promise<{
+    uploadMedia(conversationId: string, data: string, mimeType: string, fileName?: string): Promise<{
         url: string;
+        attachment: import('@canonmsg/core').MediaAttachment;
     }>;
     stop(): Promise<void>;
     private handleMessages;

package/dist/canon-agent.js

@@ -1,9 +1,20 @@
-import { CanonClient, initRTDBAuth, writeSessionState, clearSessionState, } from '@canonmsg/core';
+import { CanonClient, FINAL_MESSAGE_HANDOFF_MS, initRTDBAuth, writeSessionState, clearSessionState, writeTurnState, clearTurnState, } from '@canonmsg/core';
+import { randomUUID } from 'node:crypto';
 import { AuthManager } from './auth.js';
 import { Debouncer } from './debouncer.js';
 import { PollingManager } from './polling.js';
 import { SessionManager } from './session-manager.js';
 const AUTO_MODE_THRESHOLD = 500;
+const SDK_RUNTIME_CAPABILITIES = {
+    supportsInterrupt: false,
+    supportsQueue: true,
+    supportsInterleave: false,
+    supportsRequiresAction: false,
+    supportsNonFinalPermanentMessages: false,
+};
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 export class CanonAgent {
     options;
     apiClient;
@@ -47,6 +58,7 @@ export class CanonAgent {
         if (this.running)
             return;
         this.running = true;
+        initRTDBAuth(this.apiClient);
         // 1. Authenticate
         const { agentId } = await this.authManager.authenticate();
         this.agentId = agentId;
@@ -79,7 +91,6 @@ export class CanonAgent {
         }
         // 3c. Initialize RTDB session state reporting (opt-in)
         if (this.options.sessionState) {
-            initRTDBAuth(this.apiClient);
             for (const id of this.cachedConversationIds) {
                 writeSessionState(id, agentId, {
                     cwd: process.cwd(),
@@ -126,8 +137,8 @@ export class CanonAgent {
     async removeMember(conversationId, userId) {
         return this.apiClient.removeMember(conversationId, userId);
     }
-    async uploadMedia(conversationId, data, mimeType) {
-        return this.apiClient.uploadMedia(conversationId, data, mimeType);
+    async uploadMedia(conversationId, data, mimeType, fileName) {
+        return this.apiClient.uploadMedia(conversationId, data, mimeType, fileName);
     }
     async stop() {
         if (!this.running)
@@ -139,6 +150,11 @@ export class CanonAgent {
                 clearSessionState(id, this.agentId).catch(() => { });
             }
         }
+        if (this.agentId) {
+            for (const id of this.cachedConversationIds) {
+                clearTurnState(id, this.agentId).catch(() => { });
+            }
+        }
         this.pollingManager?.stop();
         this.realtimeManager?.stop();
         this.sessionManager?.destroy();
@@ -163,6 +179,44 @@ export class CanonAgent {
     async executeHandler(conversationId, messages, session) {
         if (!this.handler)
             return;
+        const turnId = randomUUID();
+        const turnOpenedAt = Date.now();
+        let turnState = 'thinking';
+        let shouldPersistTurnState = false;
+        const agentId = this.agentId;
+        const queueDepth = () => this.sessionManager?.getQueueDepth(conversationId) ?? 0;
+        const writeTurn = async (state) => {
+            if (!agentId)
+                return;
+            turnState = state;
+            await writeTurnState(conversationId, agentId, {
+                turnId,
+                state,
+                queueDepth: queueDepth(),
+                currentSpeakerId: agentId,
+                capabilities: SDK_RUNTIME_CAPABILITIES,
+                openedAt: turnOpenedAt,
+                ...(state === 'completed' || state === 'interrupted' || state === 'idle'
+                    ? { completedAt: { '.sv': 'timestamp' } }
+                    : {}),
+            }).catch(() => { });
+        };
+        const setLiveState = async (state, text, streamingStatus) => {
+            await writeTurn(state);
+            if (streamingStatus) {
+                try {
+                    await this.apiClient.setStreaming({
+                        conversationId,
+                        text: text ?? '',
+                        status: streamingStatus,
+                        messageId: turnId,
+                    });
+                }
+                catch {
+                    // Non-critical
+                }
+            }
+        };
         // Show thinking indicator and keep it alive (5s client-side expiry)
         try {
             await this.apiClient.setTyping(conversationId, true, 'thinking');
@@ -170,8 +224,17 @@ export class CanonAgent {
         catch {
             // Non-critical
         }
+        await setLiveState('thinking', 'Thinking...', 'thinking');
         const thinkingKeepalive = setInterval(() => {
             this.apiClient.setTyping(conversationId, true, 'thinking').catch(() => { });
+            if (turnState === 'thinking') {
+                this.apiClient.setStreaming({
+                    conversationId,
+                    text: 'Thinking...',
+                    status: 'thinking',
+                    messageId: turnId,
+                }).catch(() => { });
+            }
         }, 3500);
         try {
             // Fetch history from API
@@ -185,19 +248,45 @@ export class CanonAgent {
             const conversation = conversations.find((c) => c.id === conversationId);
             if (!conversation)
                 return;
-            // Build reply function — switch to typing, send, then clear
-            const reply = async (text) => {
+            // Build reply functions
+            const replyFinal = async (text, options) => {
                 try {
                     await this.apiClient.setTyping(conversationId, true, 'typing');
                 }
                 catch { }
-                const result = await this.apiClient.sendMessage(conversationId, text);
+                const result = await this.apiClient.sendMessage(conversationId, text, {
+                    ...(options ?? {}),
+                    metadata: {
+                        ...(options?.metadata ?? {}),
+                        turnId,
+                        turnSemantics: 'turn_complete',
+                        turnComplete: true,
+                    },
+                });
+                await sleep(FINAL_MESSAGE_HANDOFF_MS);
                 try {
                     await this.apiClient.setTyping(conversationId, false);
                 }
                 catch { }
                 return result;
             };
+            const replyProgress = async (text, options) => {
+                await setLiveState('streaming', text, 'streaming');
+                if (!options?.durable) {
+                    return { turnId, durable: false, messageId: null };
+                }
+                const { durable: _durable, ...sendOptions } = options;
+                const result = await this.apiClient.sendMessage(conversationId, text, {
+                    ...sendOptions,
+                    metadata: {
+                        ...(sendOptions.metadata ?? {}),
+                        turnId,
+                        turnSemantics: 'progress',
+                        turnComplete: false,
+                    },
+                });
+                return { turnId, durable: true, messageId: result.messageId };
+            };
             // Enrich history messages with isOwner
             if (this.agentContext?.ownerId) {
                 const ownerId = this.agentContext.ownerId;
@@ -225,7 +314,9 @@ export class CanonAgent {
                 history,
                 conversationId,
                 conversation,
-                reply,
+                reply: replyFinal,
+                replyFinal,
+                replyProgress,
                 deleteMessage,
                 markAsRead,
                 leave,
@@ -238,8 +329,45 @@ export class CanonAgent {
                         id: session.id,
                         messages: session.messages,
                         metadata: session.metadata,
+                        queueDepth: queueDepth(),
                     }
                     : undefined,
+                turn: {
+                    id: turnId,
+                    get state() {
+                        return turnState;
+                    },
+                    setThinking: async (text) => {
+                        await setLiveState('thinking', text ?? 'Thinking...', 'thinking');
+                    },
+                    setStreaming: async (text) => {
+                        await setLiveState('streaming', text, 'streaming');
+                    },
+                    setTool: async (text) => {
+                        await setLiveState('tool', text, 'tool');
+                    },
+                    setWaitingInput: async (text) => {
+                        shouldPersistTurnState = true;
+                        try {
+                            await this.apiClient.clearStreaming(conversationId);
+                        }
+                        catch { }
+                        await writeTurn('waiting_input');
+                        try {
+                            await this.apiClient.setTyping(conversationId, false);
+                        }
+                        catch { }
+                        if (text) {
+                            await this.apiClient.sendMessage(conversationId, text, {
+                                metadata: {
+                                    turnId,
+                                    turnSemantics: 'control',
+                                    replyBehavior: 'suppress_auto_reply',
+                                },
+                            });
+                        }
+                    },
+                },
             });
             // Auto-mark conversation as read after successful processing
             if (this.options.autoMarkRead) {
@@ -253,6 +381,7 @@ export class CanonAgent {
         }
         catch (err) {
             console.error(`[canon-sdk] Handler error for ${conversationId}:`, err);
+            await writeTurn('interrupted');
         }
         finally {
             clearInterval(thinkingKeepalive);
@@ -261,6 +390,13 @@ export class CanonAgent {
                 await this.apiClient.setTyping(conversationId, false);
             }
             catch { }
+            try {
+                await this.apiClient.clearStreaming(conversationId);
+            }
+            catch { }
+            if (agentId && !shouldPersistTurnState) {
+                await clearTurnState(conversationId, agentId).catch(() => { });
+            }
         }
     }
     // Static registration helpers (unauthenticated)

package/dist/index.d.ts

@@ -3,4 +3,4 @@ export { CanonApiError } from '@canonmsg/core';
 export { SessionManager } from './session-manager.js';
 export type { SessionConfig, Session } from './session-manager.js';
 export type { AgentContext, CanonMessage, CanonConversation, SendMessageOptions, CreateConversationOptions, } from '@canonmsg/core';
-export type { SDKMessage, SDKConversation, CanonAgentOptions, MessageHandler, MessageHandlerContext, SessionInfo, SessionOptions, DeliveryMode, } from './types.js';
+export type { SDKMessage, SDKConversation, CanonAgentOptions, MessageHandler, MessageHandlerContext, ProgressMessageOptions, ProgressMessageResult, SessionInfo, SessionOptions, DeliveryMode, } from './types.js';

package/dist/policy-history.d.ts

@@ -0,0 +1,10 @@
+import { type CanonMessage, type ParticipationHistorySnapshot } from '@canonmsg/core';
+export type { ParticipationHistorySnapshot } from '@canonmsg/core';
+/**
+ * Builds message-specific participation history snapshots for backlog delivery.
+ *
+ * `messages` must be ordered newest-first, matching Canon's `getMessages()`
+ * API. Each snapshot is computed from older history only, never from the
+ * target message itself or newer messages that had not occurred yet.
+ */
+export declare function buildParticipationHistorySnapshots(messages: CanonMessage[], agentId: string): Map<string, ParticipationHistorySnapshot>;

package/dist/policy-history.js

@@ -0,0 +1,11 @@
+import { buildParticipationHistorySnapshots as buildSharedParticipationHistorySnapshots, } from '@canonmsg/core';
+/**
+ * Builds message-specific participation history snapshots for backlog delivery.
+ *
+ * `messages` must be ordered newest-first, matching Canon's `getMessages()`
+ * API. Each snapshot is computed from older history only, never from the
+ * target message itself or newer messages that had not occurred yet.
+ */
+export function buildParticipationHistorySnapshots(messages, agentId) {
+    return buildSharedParticipationHistorySnapshots(messages, agentId);
+}

package/dist/polling.js

@@ -1,3 +1,5 @@
+import { buildParticipationHistorySnapshots } from './policy-history.js';
+import { shouldDispatchInboundMessage } from './turn-filter.js';
 export class PollingManager {
     apiClient;
     debouncer;
@@ -31,14 +33,26 @@ export class PollingManager {
             const activeConvos = this.findActiveConversations(conversations);
             await Promise.all(activeConvos.map(async (convo) => {
                 try {
-                    const messages = await this.apiClient.getMessages(convo.id, 50);
+                    const page = await this.apiClient.getMessagesPage(convo.id, 50);
+                    const messages = page.messages;
+                    const participationHistory = buildParticipationHistorySnapshots(messages, this.agentId);
                     // Filter to only new messages (after lastSeen, not from self)
                     const lastSeen = this.lastSeenTimestamps.get(convo.id) || 0;
                     const newMessages = messages.filter((m) => {
                         const msgTime = new Date(m.createdAt).getTime();
                         return msgTime > lastSeen && m.senderId !== this.agentId;
                     });
-                    for (const msg of newMessages) {
+                    const dispatchable = await Promise.all(newMessages.map(async (message) => ({
+                        message,
+                        allow: await shouldDispatchInboundMessage(convo.id, this.agentId, message, {
+                            conversationType: convo.type,
+                            behavior: page.behavior,
+                            recentHumanCount: participationHistory.get(message.id)?.recentHumanCount,
+                            consecutiveAgentTurns: participationHistory.get(message.id)?.consecutiveAgentTurns,
+                            currentAgentStreakStartedByHuman: participationHistory.get(message.id)?.currentAgentStreakStartedByHuman,
+                        }),
+                    })));
+                    for (const msg of dispatchable.filter((entry) => entry.allow).map((entry) => entry.message)) {
                         this.debouncer.add(convo.id, msg);
                     }
                     // Update lastSeen to latest message timestamp

package/dist/realtime.js

@@ -1,4 +1,6 @@
 import { CanonClient, CanonStream } from '@canonmsg/core';
+import { buildParticipationHistorySnapshots } from './policy-history.js';
+import { shouldDispatchInboundMessage } from './turn-filter.js';
 const DISCOVERY_INTERVAL_MS = 5_000;
 /**
  * Wraps @canonmsg/core's CanonStream with SDK-specific features:
@@ -36,6 +38,7 @@ export class RealtimeManager {
                         imageUrl: m.imageUrl ?? null,
                         audioUrl: m.audioUrl ?? null,
                         audioDurationMs: m.audioDurationMs ?? null,
+                        attachments: m.attachments ?? [],
                         mentions: m.mentions ?? [],
                         replyTo: m.replyTo ?? null,
                         replyToPosition: m.replyToPosition ?? null,
@@ -106,8 +109,23 @@ export class RealtimeManager {
             // Fetch and deliver pending messages from new conversations
             for (const convoId of newConvoIds) {
                 try {
-                    const messages = await this.apiClient.getMessages(convoId, 50);
-                    const newMessages = messages.filter((m) => m.senderId !== this.agentId);
+                    const conversation = convos.find((item) => item.id === convoId);
+                    const page = await this.apiClient.getMessagesPage(convoId, 50);
+                    const messages = page.messages;
+                    const participationHistory = buildParticipationHistorySnapshots(messages, this.agentId);
+                    const dispatchable = await Promise.all(messages.map(async (message) => ({
+                        message,
+                        allow: await shouldDispatchInboundMessage(convoId, this.agentId, message, {
+                            conversationType: conversation?.type ?? 'unknown',
+                            behavior: page.behavior,
+                            recentHumanCount: participationHistory.get(message.id)?.recentHumanCount,
+                            consecutiveAgentTurns: participationHistory.get(message.id)?.consecutiveAgentTurns,
+                            currentAgentStreakStartedByHuman: participationHistory.get(message.id)?.currentAgentStreakStartedByHuman,
+                        }),
+                    })));
+                    const newMessages = dispatchable
+                        .filter((entry) => entry.allow)
+                        .map((entry) => entry.message);
                     for (const msg of newMessages) {
                         this.debouncer.add(convoId, msg);
                     }

package/dist/session-manager.d.ts

@@ -55,6 +55,8 @@ export declare class SessionManager {
     private sweep;
     /** Number of active sessions */
     get sessionCount(): number;
+    /** Number of queued batches waiting behind the active turn for this conversation. */
+    getQueueDepth(conversationId: string): number;
     /** Clean up all state */
     destroy(): void;
 }

package/dist/session-manager.js

@@ -163,6 +163,10 @@ export class SessionManager {
     get sessionCount() {
         return this.sessions.size;
     }
+    /** Number of queued batches waiting behind the active turn for this conversation. */
+    getQueueDepth(conversationId) {
+        return this.queues.get(conversationId)?.length ?? 0;
+    }
     /** Clean up all state */
     destroy() {
         if (this.sweepTimer) {

package/dist/turn-filter.d.ts

@@ -0,0 +1,8 @@
+import { type ResolvedAgentBehaviorPolicy, type CanonMessage } from '@canonmsg/core';
+export declare function shouldDispatchInboundMessage(conversationId: string, agentId: string, message: CanonMessage, options?: {
+    conversationType?: 'direct' | 'group' | 'unknown';
+    behavior?: ResolvedAgentBehaviorPolicy | null;
+    recentHumanCount?: number;
+    consecutiveAgentTurns?: number;
+    currentAgentStreakStartedByHuman?: boolean;
+}): Promise<boolean>;

package/dist/turn-filter.js

@@ -0,0 +1,51 @@
+import { evaluateParticipationPolicy, normalizeTurnState, rtdbRead, shouldTriggerAgentTurn, } from '@canonmsg/core';
+function normalizeRuntimeTurnState(value) {
+    const turnState = normalizeTurnState(value);
+    if (turnState) {
+        return { state: turnState.state };
+    }
+    if (!value || typeof value !== 'object')
+        return null;
+    const state = value.state;
+    if (state === 'running') {
+        return { state: 'streaming' };
+    }
+    if (state === 'requires_action') {
+        return { state: 'waiting_input' };
+    }
+    return null;
+}
+export async function shouldDispatchInboundMessage(conversationId, agentId, message, options) {
+    if (message.senderId === agentId)
+        return false;
+    let senderTurnState = null;
+    try {
+        const [turnState, sessionState] = await Promise.all([
+            rtdbRead(`/turn-state/${conversationId}/${message.senderId}`),
+            rtdbRead(`/session-state/${conversationId}/${message.senderId}`),
+        ]);
+        senderTurnState = normalizeRuntimeTurnState(turnState)
+            ?? normalizeRuntimeTurnState(sessionState);
+    }
+    catch {
+        senderTurnState = null;
+    }
+    const triggerDecision = shouldTriggerAgentTurn({
+        senderType: message.senderType,
+        metadata: message.metadata,
+        senderTurnState,
+    });
+    if (!triggerDecision.allow)
+        return false;
+    if (!options?.behavior)
+        return true;
+    return evaluateParticipationPolicy(options.behavior, {
+        conversationType: options.conversationType ?? 'unknown',
+        senderType: message.senderType,
+        isOwner: message.isOwner,
+        mentionedAgent: Array.isArray(message.mentions) && message.mentions.includes(agentId),
+        recentHumanCount: options.recentHumanCount,
+        consecutiveAgentTurns: options.consecutiveAgentTurns,
+        currentAgentStreakStartedByHuman: options.currentAgentStreakStartedByHuman,
+    }).allow;
+}

package/dist/types.d.ts

@@ -1,7 +1,23 @@
-export type { AgentClientType, CanonMessage, CanonConversation, AgentContext, SendMessageOptions, CreateConversationOptions, } from '@canonmsg/core';
-import type { CanonMessage, CanonConversation } from '@canonmsg/core';
+export type { AgentClientType, CanonMessage, CanonConversation, AgentContext, SendMessageOptions, CreateConversationOptions, TurnLifecycleState, } from '@canonmsg/core';
+import type { CanonMessage, CanonConversation, SendMessageOptions } from '@canonmsg/core';
 export type SDKMessage = CanonMessage;
 export type SDKConversation = CanonConversation;
+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;
@@ -9,15 +25,28 @@ export interface SessionInfo {
     messages: SDKMessage[];
     /** 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>;
+    setTool: (text: string) => Promise<void>;
+    setWaitingInput: (text?: string) => Promise<void>;
 }
 export interface MessageHandlerContext {
     messages: SDKMessage[];
     history: SDKMessage[];
     conversationId: string;
     conversation: SDKConversation;
-    reply: (text: string) => Promise<{
+    reply: (text: string, options?: SendMessageOptions) => Promise<{
+        messageId: string;
+    }>;
+    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 */
@@ -34,6 +63,8 @@ export interface MessageHandlerContext {
     agent: import('@canonmsg/core').AgentContext;
     /** Per-conversation session state. Present when sessions are enabled. */
     session?: SessionInfo;
+    /** Turn lifecycle helpers for live-work rendering and progress reporting. */
+    turn?: TurnController;
 }
 export type MessageHandler = (ctx: MessageHandlerContext) => Promise<void>;
 export interface SessionOptions {
@@ -62,10 +93,8 @@ export interface CanonAgentOptions {
     /** Agent client type for capability detection. Defaults to 'generic'. */
     clientType?: import('@canonmsg/core').AgentClientType;
     /**
-     * Enable RTDB session state reporting. Off by default.
-     * When enabled, the SDK writes { cwd, isActive, ... } to
-     * /session-state/{convoId}/{agentId} so the Canon app can display
-     * the agent's active status and configuration.
+     * Enable RTDB session-state reporting. Off by default.
+     * Turn-state reporting is automatic while handlers run.
      */
     sessionState?: boolean;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/agent-sdk",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Canon Agent SDK — build AI agents that participate in Canon conversations",
   "type": "module",
   "main": "dist/index.js",
@@ -15,15 +15,15 @@
     "dist"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc",
     "dev": "tsc --watch",
-    "prepublishOnly": "npm run build"
+    "prepack": "npm run build"
   },
   "engines": {
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@canonmsg/core": "^0.2.2"
+    "@canonmsg/core": "^0.4.0"
   },
   "publishConfig": {
     "access": "public"

package/dist/api-client.d.ts

@@ -1,64 +0,0 @@
-import { SDKMessage, SDKConversation, SendMessageOptions, CreateConversationOptions, AgentContext, VisibilityConfig, ContactRequestInfo } from './types';
-export declare class ApiClient {
-    private baseUrl;
-    private apiKey;
-    constructor(apiKey: string, baseUrl?: string);
-    private authHeaders;
-    getAuthToken(): Promise<{
-        token: string;
-        expiresAt: string;
-        agentId: string;
-    }>;
-    getAgentMe(): Promise<AgentContext>;
-    getConversations(): Promise<SDKConversation[]>;
-    getMessages(conversationId: string, limit?: number, before?: string): Promise<SDKMessage[]>;
-    sendMessage(conversationId: string, text: string, options?: SendMessageOptions): Promise<{
-        messageId: string;
-    }>;
-    createConversation(options: CreateConversationOptions): Promise<{
-        conversationId: string;
-    }>;
-    requestContact(targetUserId: string, message?: string): Promise<{
-        requestId: string;
-    }>;
-    getContactRequests(): Promise<ContactRequestInfo[]>;
-    approveContactRequest(requestId: string): Promise<void>;
-    rejectContactRequest(requestId: string): Promise<void>;
-    updateVisibility(config: VisibilityConfig): Promise<void>;
-    uploadMedia(conversationId: string, data: string, mimeType: string): Promise<{
-        url: string;
-    }>;
-    updateTopic(conversationId: string, topic: string): Promise<void>;
-    deleteMessage(conversationId: string, messageId: string): Promise<void>;
-    markAsRead(conversationId: string): Promise<void>;
-    leaveConversation(conversationId: string): Promise<void>;
-    react(conversationId: string, messageId: string, emoji: string): Promise<void>;
-    updateConversationName(conversationId: string, name: string): Promise<void>;
-    addMember(conversationId: string, userId: string): Promise<void>;
-    removeMember(conversationId: string, userId: string): Promise<void>;
-    setTyping(conversationId: string, typing: boolean): Promise<void>;
-    static register(baseUrl: string | undefined, body: {
-        name: string;
-        description: string;
-        ownerPhone: string;
-        developerInfo: string;
-        avatarUrl?: string;
-    }): Promise<{
-        requestId: string;
-    }>;
-    static checkStatus(baseUrl: string | undefined, requestId: string): Promise<{
-        status: string;
-        agentName: string;
-        agentId?: string;
-        apiKey?: string;
-    }>;
-}
-export declare class ApiError extends Error {
-    status: number;
-    constructor(status: number, body: string);
-}
-export declare class ApprovalRequiredError extends Error {
-    targetUserId: string;
-    hint: string;
-    constructor(targetUserId: string, hint: string);
-}

package/dist/api-client.js

@@ -1,257 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ApprovalRequiredError = exports.ApiError = exports.ApiClient = void 0;
-const DEFAULT_BASE_URL = 'https://api-6m6mlelskq-uc.a.run.app';
-class ApiClient {
-    baseUrl;
-    apiKey;
-    constructor(apiKey, baseUrl) {
-        this.apiKey = apiKey;
-        this.baseUrl = baseUrl || DEFAULT_BASE_URL;
-    }
-    authHeaders() {
-        return {
-            'Authorization': `Bearer ${this.apiKey}`,
-            'Content-Type': 'application/json',
-        };
-    }
-    async getAuthToken() {
-        const res = await fetch(`${this.baseUrl}/agents/auth-token`, {
-            method: 'POST',
-            headers: this.authHeaders(),
-        });
-        if (!res.ok)
-            throw new ApiError(res.status, await res.text());
-        return res.json();
-    }
-    async getAgentMe() {
-        const res = await fetch(`${this.baseUrl}/agents/me`, {
-            headers: this.authHeaders(),
-        });
-        if (!res.ok)
-            throw new ApiError(res.status, await res.text());
-        return res.json();
-    }
-    async getConversations() {
-        const res = await fetch(`${this.baseUrl}/conversations`, {
-            headers: this.authHeaders(),
-        });
-        if (!res.ok)
-            throw new ApiError(res.status, await res.text());
-        const data = await res.json();
-        return data.conversations;
-    }
-    async getMessages(conversationId, limit = 50, before) {
-        const params = new URLSearchParams({ limit: String(limit) });
-        if (before)
-            params.set('before', before);
-        const res = await fetch(`${this.baseUrl}/conversations/${conversationId}/messages?${params}`, { headers: this.authHeaders() });
-        if (!res.ok)
-            throw new ApiError(res.status, await res.text());
-        const data = await res.json();
-        return data.messages;
-    }
-    async sendMessage(conversationId, text, options) {
-        const res = await fetch(`${this.baseUrl}/messages/send`, {
-            method: 'POST',
-            headers: this.authHeaders(),
-            body: JSON.stringify({ conversationId, text, ...options }),
-        });
-        if (!res.ok)
-            throw new ApiError(res.status, await res.text());
-        return res.json();
-    }
-    async createConversation(options) {
-        const res = await fetch(`${this.baseUrl}/conversations/create`, {
-            method: 'POST',
-            headers: this.authHeaders(),
-            body: JSON.stringify(options),
-        });
-        if (!res.ok) {
-            const body = await res.text();
-            try {
-                const parsed = JSON.parse(body);
-                if (parsed.code === 'APPROVAL_REQUIRED') {
-                    throw new ApprovalRequiredError(options.targetUserId ?? '', parsed.hint ?? 'Contact request required');
-                }
-            }
-            catch (e) {
-                if (e instanceof ApprovalRequiredError)
-                    throw e;
-            }
-            throw new ApiError(res.status, body);
-        }
-        return res.json();
-    }
-    async requestContact(targetUserId, message) {
-        const res = await fetch(`${this.baseUrl}/contacts/request`, {
-            method: 'POST',
-            headers: this.authHeaders(),
-            body: JSON.stringify({ targetUserId, message }),
-        });
-        if (!res.ok)
-            throw new ApiError(res.status, await res.text());
-        return res.json();
-    }
-    async getContactRequests() {
-        const res = await fetch(`${this.baseUrl}/contacts/requests`, {
-            headers: this.authHeaders(),
-        });
-        if (!res.ok)
-            throw new ApiError(res.status, await res.text());
-        const data = await res.json();
-        return data.requests;
-    }
-    async approveContactRequest(requestId) {
-        const res = await fetch(`${this.baseUrl}/contacts/requests/${requestId}/approve`, {
-            method: 'POST',
-            headers: this.authHeaders(),
-        });
-        if (!res.ok)
-            throw new ApiError(res.status, await res.text());
-    }
-    async rejectContactRequest(requestId) {
-        const res = await fetch(`${this.baseUrl}/contacts/requests/${requestId}/reject`, {
-            method: 'POST',
-            headers: this.authHeaders(),
-        });
-        if (!res.ok)
-            throw new ApiError(res.status, await res.text());
-    }
-    async updateVisibility(config) {
-        const res = await fetch(`${this.baseUrl}/agents/visibility`, {
-            method: 'PATCH',
-            headers: this.authHeaders(),
-            body: JSON.stringify(config),
-        });
-        if (!res.ok)
-            throw new ApiError(res.status, await res.text());
-    }
-    async uploadMedia(conversationId, data, mimeType) {
-        const res = await fetch(`${this.baseUrl}/media/upload`, {
-            method: 'POST',
-            headers: this.authHeaders(),
-            body: JSON.stringify({ conversationId, mimeType, data }),
-        });
-        if (!res.ok)
-            throw new ApiError(res.status, await res.text());
-        return res.json();
-    }
-    async updateTopic(conversationId, topic) {
-        const res = await fetch(`${this.baseUrl}/conversations/${conversationId}/topic`, {
-            method: 'PATCH',
-            headers: this.authHeaders(),
-            body: JSON.stringify({ topic }),
-        });
-        if (!res.ok)
-            throw new ApiError(res.status, await res.text());
-    }
-    async deleteMessage(conversationId, messageId) {
-        const res = await fetch(`${this.baseUrl}/conversations/${conversationId}/messages/${messageId}`, {
-            method: 'DELETE',
-            headers: this.authHeaders(),
-        });
-        if (!res.ok)
-            throw new ApiError(res.status, await res.text());
-    }
-    async markAsRead(conversationId) {
-        const res = await fetch(`${this.baseUrl}/conversations/${conversationId}/read`, {
-            method: 'POST',
-            headers: this.authHeaders(),
-        });
-        if (!res.ok)
-            throw new ApiError(res.status, await res.text());
-    }
-    async leaveConversation(conversationId) {
-        const res = await fetch(`${this.baseUrl}/conversations/${conversationId}/leave`, {
-            method: 'POST',
-            headers: this.authHeaders(),
-        });
-        if (!res.ok)
-            throw new ApiError(res.status, await res.text());
-    }
-    async react(conversationId, messageId, emoji) {
-        const res = await fetch(`${this.baseUrl}/messages/react`, {
-            method: 'POST',
-            headers: this.authHeaders(),
-            body: JSON.stringify({ conversationId, messageId, emoji }),
-        });
-        if (!res.ok)
-            throw new ApiError(res.status, await res.text());
-    }
-    async updateConversationName(conversationId, name) {
-        const res = await fetch(`${this.baseUrl}/conversations/${conversationId}/name`, {
-            method: 'PATCH',
-            headers: this.authHeaders(),
-            body: JSON.stringify({ name }),
-        });
-        if (!res.ok)
-            throw new ApiError(res.status, await res.text());
-    }
-    async addMember(conversationId, userId) {
-        const res = await fetch(`${this.baseUrl}/conversations/${conversationId}/members`, {
-            method: 'POST',
-            headers: this.authHeaders(),
-            body: JSON.stringify({ userId }),
-        });
-        if (!res.ok)
-            throw new ApiError(res.status, await res.text());
-    }
-    async removeMember(conversationId, userId) {
-        const res = await fetch(`${this.baseUrl}/conversations/${conversationId}/members/${userId}`, {
-            method: 'DELETE',
-            headers: this.authHeaders(),
-        });
-        if (!res.ok)
-            throw new ApiError(res.status, await res.text());
-    }
-    async setTyping(conversationId, typing) {
-        const res = await fetch(`${this.baseUrl}/typing`, {
-            method: 'POST',
-            headers: this.authHeaders(),
-            body: JSON.stringify({ conversationId, typing }),
-        });
-        if (!res.ok)
-            throw new ApiError(res.status, await res.text());
-    }
-    // Static helpers for unauthenticated registration endpoints
-    static async register(baseUrl, body) {
-        const url = baseUrl || DEFAULT_BASE_URL;
-        const res = await fetch(`${url}/agents/register`, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify(body),
-        });
-        if (!res.ok)
-            throw new ApiError(res.status, await res.text());
-        return res.json();
-    }
-    static async checkStatus(baseUrl, requestId) {
-        const url = baseUrl || DEFAULT_BASE_URL;
-        const res = await fetch(`${url}/agents/status/${requestId}`);
-        if (!res.ok)
-            throw new ApiError(res.status, await res.text());
-        return res.json();
-    }
-}
-exports.ApiClient = ApiClient;
-class ApiError extends Error {
-    status;
-    constructor(status, body) {
-        super(`API error ${status}: ${body}`);
-        this.name = 'ApiError';
-        this.status = status;
-    }
-}
-exports.ApiError = ApiError;
-class ApprovalRequiredError extends Error {
-    targetUserId;
-    hint;
-    constructor(targetUserId, hint) {
-        super(`Contact request required for user ${targetUserId}`);
-        this.name = 'ApprovalRequiredError';
-        this.targetUserId = targetUserId;
-        this.hint = hint;
-    }
-}
-exports.ApprovalRequiredError = ApprovalRequiredError;