@canonmsg/core 0.2.2

package/dist/stream.js

@@ -0,0 +1,244 @@
+import { DEFAULT_STREAM_URL } from './constants.js';
+const MAX_BACKOFF_MS = 30_000;
+/**
+ * Manages a persistent SSE connection to Canon's stream service.
+ *
+ * Uses native fetch + ReadableStream (Node 18+) — no EventSource polyfill.
+ * Supports Last-Event-ID for gapless replay on reconnect.
+ */
+export class CanonStream {
+    apiKey;
+    agentId;
+    streamUrl;
+    handler;
+    running = false;
+    abortController = null;
+    lastEventId = null;
+    reconnectAttempt = 0;
+    reconnectTimer = null;
+    constructor(opts) {
+        this.apiKey = opts.apiKey;
+        this.agentId = opts.agentId;
+        this.streamUrl = opts.streamUrl || DEFAULT_STREAM_URL;
+        this.handler = opts.handler;
+    }
+    async start() {
+        this.running = true;
+        this.reconnectAttempt = 0;
+        await this.connect();
+    }
+    stop() {
+        this.running = false;
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        if (this.abortController) {
+            this.abortController.abort();
+            this.abortController = null;
+        }
+        this.handler.onDisconnected?.();
+    }
+    isRunning() {
+        return this.running;
+    }
+    // ── SSE connection ────────────────────────────────────────────────────
+    async connect() {
+        if (!this.running)
+            return;
+        this.abortController = new AbortController();
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            Accept: 'text/event-stream',
+        };
+        if (this.lastEventId) {
+            headers['Last-Event-ID'] = this.lastEventId;
+        }
+        try {
+            const res = await fetch(`${this.streamUrl}/agents/stream`, {
+                headers,
+                signal: this.abortController.signal,
+            });
+            if (!res.ok) {
+                throw new Error(`SSE connect failed: ${res.status} ${res.statusText}`);
+            }
+            this.handler.onConnected?.();
+            await this.readStream(res);
+        }
+        catch (err) {
+            if (!this.running)
+                return;
+            const msg = err instanceof Error ? err.message : String(err);
+            if (msg.includes('abort'))
+                return;
+            this.handler.onError?.(err instanceof Error ? err : new Error(msg));
+            this.scheduleReconnect();
+        }
+    }
+    async readStream(res) {
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        try {
+            while (this.running) {
+                const { value, done } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                let boundary;
+                while ((boundary = buffer.indexOf('\n\n')) !== -1) {
+                    const frame = buffer.slice(0, boundary);
+                    buffer = buffer.slice(boundary + 2);
+                    this.processFrame(frame);
+                }
+            }
+        }
+        catch (err) {
+            if (!this.running)
+                return;
+            const msg = err instanceof Error ? err.message : String(err);
+            if (msg.includes('abort'))
+                return;
+            this.handler.onError?.(err instanceof Error ? err : new Error(msg));
+        }
+        finally {
+            reader.releaseLock();
+        }
+        if (this.running) {
+            this.handler.onDisconnected?.();
+            this.scheduleReconnect();
+        }
+    }
+    // ── SSE frame parsing ─────────────────────────────────────────────────
+    processFrame(frame) {
+        let id = null;
+        let event = null;
+        let data = '';
+        for (const line of frame.split('\n')) {
+            if (line.startsWith('id:')) {
+                id = line.slice(3).trim();
+            }
+            else if (line.startsWith('event:')) {
+                event = line.slice(6).trim();
+            }
+            else if (line.startsWith('data:')) {
+                data += (data ? '\n' : '') + line.slice(5).trim();
+            }
+            // Lines starting with ':' are comments — ignore
+        }
+        if (id) {
+            this.lastEventId = id;
+        }
+        if (!event || !data)
+            return;
+        switch (event) {
+            case 'agent.context':
+                this.reconnectAttempt = 0;
+                this.handleAgentContext(data);
+                break;
+            case 'message.created':
+                this.reconnectAttempt = 0;
+                this.handleMessageCreated(data);
+                break;
+            case 'typing':
+                this.reconnectAttempt = 0;
+                this.handleTyping(data);
+                break;
+            case 'presence':
+                this.reconnectAttempt = 0;
+                this.handlePresence(data);
+                break;
+            case 'message.deleted':
+                this.reconnectAttempt = 0;
+                this.handleMessageDeleted(data);
+                break;
+            case 'conversation.updated':
+                this.reconnectAttempt = 0;
+                this.handleConversationUpdated(data);
+                break;
+            case 'heartbeat':
+                this.reconnectAttempt = 0;
+                break;
+            case 'replay.expired':
+                this.reconnectAttempt = 0;
+                this.handler.onError?.(new Error('Replay expired — some messages may have been missed'));
+                break;
+            case 'error':
+                // Don't reset backoff — error events mean something is wrong
+                this.handler.onError?.(new Error(`Stream error: ${data}`));
+                break;
+            default:
+                break;
+        }
+    }
+    handleAgentContext(raw) {
+        try {
+            const ctx = JSON.parse(raw);
+            this.handler.onAgentContext?.(ctx);
+        }
+        catch (err) {
+            this.handler.onError?.(new Error(`Failed to parse agent.context: ${err}`));
+        }
+    }
+    handleMessageCreated(raw) {
+        try {
+            const payload = JSON.parse(raw);
+            // Skip own messages
+            if (payload.message.senderId === this.agentId)
+                return;
+            this.handler.onMessage(payload);
+        }
+        catch (err) {
+            this.handler.onError?.(new Error(`Failed to parse message.created: ${err}`));
+        }
+    }
+    handleTyping(raw) {
+        try {
+            const data = JSON.parse(raw);
+            this.handler.onTyping?.(data);
+        }
+        catch {
+            // Ignore parse errors for non-critical events
+        }
+    }
+    handlePresence(raw) {
+        try {
+            const data = JSON.parse(raw);
+            this.handler.onPresence?.(data);
+        }
+        catch {
+            // Ignore parse errors for non-critical events
+        }
+    }
+    handleMessageDeleted(raw) {
+        try {
+            const data = JSON.parse(raw);
+            this.handler.onMessageDeleted?.(data);
+        }
+        catch {
+            // Ignore parse errors for non-critical events
+        }
+    }
+    handleConversationUpdated(raw) {
+        try {
+            const data = JSON.parse(raw);
+            this.handler.onConversationUpdated?.(data);
+        }
+        catch {
+            // Ignore parse errors for non-critical events
+        }
+    }
+    // ── Reconnect with exponential backoff + jitter ───────────────────────
+    scheduleReconnect() {
+        if (!this.running)
+            return;
+        const base = Math.min(1000 * Math.pow(2, this.reconnectAttempt), MAX_BACKOFF_MS);
+        const jitter = Math.random() * 0.25 * base;
+        const delay = base + jitter;
+        this.reconnectAttempt++;
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            this.connect();
+        }, delay);
+    }
+}

package/dist/streaming.d.ts

@@ -0,0 +1,52 @@
+import type { StreamingStatus } from './types.js';
+/** Minimal subset of firebase-admin Database to avoid a hard dependency. */
+export interface RTDBHandle {
+    ref(path: string): RTDBRef;
+}
+export interface RTDBRef {
+    set(value: unknown): Promise<void>;
+    update(value: Record<string, unknown>): Promise<void>;
+    remove(): Promise<void>;
+}
+/** Server-timestamp sentinel — the consumer passes the appropriate value
+ *  (e.g. `admin.database.ServerValue.TIMESTAMP` for firebase-admin). */
+export type ServerTimestamp = object;
+export interface StreamingHelperOptions {
+    /** RTDB instance (e.g. `admin.database()`) */
+    db: RTDBHandle;
+    /** Server-timestamp sentinel (e.g. `admin.database.ServerValue.TIMESTAMP`) */
+    serverTimestamp: ServerTimestamp;
+}
+export interface StreamingNode {
+    text: string;
+    status: StreamingStatus;
+    startedAt: unknown;
+    updatedAt: unknown;
+    messageId: string;
+}
+/**
+ * Creates helpers that read/write the RTDB streaming node for a single
+ * agent in a single conversation.
+ *
+ * Usage (in the Canon plugin):
+ * ```ts
+ * const s = createStreamingHelper({ db, serverTimestamp: ServerValue.TIMESTAMP });
+ * const h = s.forConversation(convoId, agentId);
+ * await h.start(messageId);            // status → thinking
+ * await h.update('Hello ', 'streaming');
+ * await h.update('Hello world', 'streaming');
+ * await h.clear();                     // remove the node
+ * ```
+ */
+export declare function createStreamingHelper(opts: StreamingHelperOptions): {
+    forConversation: (conversationId: string, agentId: string) => {
+        /** Write the initial streaming node (status: "thinking", empty text). */
+        start(messageId: string): Promise<void>;
+        /** Update the accumulated text and optionally change status. */
+        update(text: string, status?: StreamingStatus): Promise<void>;
+        /** Set status without changing text (e.g. switching to "tool"). */
+        setStatus(status: StreamingStatus): Promise<void>;
+        /** Remove the streaming node (call after final Firestore message is written). */
+        clear(): Promise<void>;
+    };
+};

package/dist/streaming.js

@@ -0,0 +1,55 @@
+// ── Helper ─────────────────────────────────────────────────────────────
+/**
+ * Creates helpers that read/write the RTDB streaming node for a single
+ * agent in a single conversation.
+ *
+ * Usage (in the Canon plugin):
+ * ```ts
+ * const s = createStreamingHelper({ db, serverTimestamp: ServerValue.TIMESTAMP });
+ * const h = s.forConversation(convoId, agentId);
+ * await h.start(messageId);            // status → thinking
+ * await h.update('Hello ', 'streaming');
+ * await h.update('Hello world', 'streaming');
+ * await h.clear();                     // remove the node
+ * ```
+ */
+export function createStreamingHelper(opts) {
+    const { db, serverTimestamp } = opts;
+    function forConversation(conversationId, agentId) {
+        const nodePath = `/streaming/${conversationId}/${agentId}`;
+        const nodeRef = db.ref(nodePath);
+        return {
+            /** Write the initial streaming node (status: "thinking", empty text). */
+            async start(messageId) {
+                const node = {
+                    text: '',
+                    status: 'thinking',
+                    startedAt: serverTimestamp,
+                    updatedAt: serverTimestamp,
+                    messageId,
+                };
+                await nodeRef.set(node);
+            },
+            /** Update the accumulated text and optionally change status. */
+            async update(text, status = 'streaming') {
+                await nodeRef.update({
+                    text,
+                    status,
+                    updatedAt: serverTimestamp,
+                });
+            },
+            /** Set status without changing text (e.g. switching to "tool"). */
+            async setStatus(status) {
+                await nodeRef.update({
+                    status,
+                    updatedAt: serverTimestamp,
+                });
+            },
+            /** Remove the streaming node (call after final Firestore message is written). */
+            async clear() {
+                await nodeRef.remove();
+            },
+        };
+    }
+    return { forConversation };
+}

package/dist/types.d.ts

@@ -0,0 +1,194 @@
+export interface CanonMessage {
+    id: string;
+    senderId: string;
+    senderType: 'human' | 'ai_agent';
+    /** Whether the sender is this agent's owner (server-computed, trusted) */
+    isOwner: boolean;
+    contentType: 'text' | 'image' | 'audio' | 'contact_card';
+    text: string | null;
+    imageUrl: string | null;
+    audioUrl: string | null;
+    audioDurationMs: number | null;
+    mentions: string[];
+    replyTo: string | null;
+    replyToPosition: number | null;
+    metadata?: Record<string, unknown>;
+    status: 'sent' | 'read';
+    deleted: boolean;
+    createdAt: string;
+}
+export interface CanonConversation {
+    id: string;
+    type: 'direct' | 'group';
+    name: string | null;
+    topic: string | null;
+    memberIds: string[];
+    isAgentChat: boolean;
+    hasUnread?: boolean;
+    lastMessage: {
+        text: string;
+        senderId: string;
+        senderType?: 'human' | 'ai_agent';
+        timestamp: string;
+    } | null;
+    createdAt: string;
+}
+export type AgentClientType = 'claude-code' | 'openclaw' | 'codex' | 'generic';
+/** Declares what session controls an agent type supports. */
+export interface AgentCapabilities {
+    supportsModelSwitch: boolean;
+    supportsPermissionMode: boolean;
+    supportsEffort: boolean;
+    supportsSessionState: boolean;
+    supportsInterrupt: boolean;
+}
+export interface ModelOption {
+    value: string;
+    label: string;
+}
+export interface WorkspaceOption {
+    id: string;
+    label: string;
+}
+/**
+ * Capability map keyed by clientType. Add new agent types here.
+ * ALSO update the duplicate in app/src/types/index.ts (RN app can't
+ * import from core directly due to different bundler/runtime).
+ */
+export declare const AGENT_CAPABILITIES: Record<AgentClientType, AgentCapabilities>;
+/** Trusted agent identity & access context, provided by the server */
+export interface AgentContext {
+    agentId: string;
+    displayName?: string;
+    avatarUrl?: string | null;
+    description?: string | null;
+    ownerId: string;
+    ownerName: string;
+    accessLevel: 'open' | 'owner-only';
+    /** Identifies the agent's client platform for UI feature detection */
+    clientType?: AgentClientType;
+}
+export interface MessageCreatedPayload {
+    conversationId: string;
+    message: {
+        id: string;
+        senderId: string;
+        senderName?: string;
+        senderType?: 'human' | 'ai_agent';
+        /** Whether the sender is this agent's owner (server-computed, trusted) */
+        isOwner?: boolean;
+        text?: string;
+        contentType?: 'text' | 'image' | 'audio' | 'contact_card';
+        imageUrl?: string;
+        audioUrl?: string;
+        audioDurationMs?: number;
+        replyTo?: string;
+        replyToPosition?: number;
+        mentions?: string[];
+        createdAt?: string;
+        /** Structured metadata for rich UI (approval cards, etc.) */
+        metadata?: Record<string, unknown>;
+    };
+}
+export interface TypingPayload {
+    conversationId: string;
+    userId: string;
+    isTyping: boolean;
+    status?: 'thinking' | 'typing';
+}
+export interface PresencePayload {
+    userId: string;
+    online: boolean;
+}
+export interface SendMessageOptions {
+    contentType?: 'text' | 'audio' | 'image' | 'contact_card';
+    replyTo?: string;
+    replyToPosition?: number;
+    audioUrl?: string;
+    audioDurationMs?: number;
+    imageUrl?: string;
+    contactCardUserId?: string;
+    mentions?: string[];
+    /** Structured metadata for rich UI (approval cards, etc.) */
+    metadata?: Record<string, unknown>;
+}
+export interface CreateConversationOptions {
+    type: 'direct' | 'group';
+    targetUserId?: string;
+    memberIds?: string[];
+    name?: string;
+}
+export type StreamingStatus = 'thinking' | 'streaming' | 'tool';
+export interface SetStreamingOptions {
+    conversationId: string;
+    text: string;
+    status: StreamingStatus;
+    messageId: string;
+}
+/** Written by Canon app to /control/{convoId}/{agentId}/session in RTDB */
+export interface SessionControl {
+    model?: string;
+    permissionMode?: 'default' | 'acceptEdits' | 'plan' | 'bypassPermissions' | 'auto';
+    effort?: 'low' | 'medium' | 'high' | 'max';
+    updatedAt: number;
+    updatedBy: string;
+}
+/** Written by agent to /session-state/{convoId}/{agentId} in RTDB */
+export interface SessionState {
+    model?: string;
+    permissionMode?: string;
+    effort?: string;
+    cwd?: string;
+    /** True when the agent is running under the host wrapper (host.ts) which can apply control signals */
+    hostMode?: boolean;
+    isActive: boolean;
+    state?: 'idle' | 'running' | 'requires_action';
+    contextUsage?: {
+        percentage: number;
+        totalTokens: number;
+        maxTokens: number;
+    };
+    availableModels?: ModelOption[];
+    updatedAt: number;
+}
+export interface SessionConfig {
+    clientType?: AgentClientType;
+    hostMode?: boolean;
+    model?: string;
+    permissionMode?: string;
+    workspaceId?: string;
+    availableModels?: ModelOption[];
+    workspaceOptions?: WorkspaceOption[];
+    updatedAt?: number;
+}
+export interface AgentRuntime {
+    clientType?: AgentClientType;
+    hostMode?: boolean;
+    defaultModel?: string;
+    defaultPermissionMode?: string;
+    defaultWorkspaceId?: string;
+    availableModels?: ModelOption[];
+    availableWorkspaces?: WorkspaceOption[];
+    updatedAt?: number;
+}
+export interface RegistrationInput {
+    name: string;
+    description: string;
+    ownerPhone: string;
+    developerInfo?: string;
+    avatarUrl?: string;
+    baseUrl?: string;
+    clientType?: AgentClientType;
+}
+export interface RegistrationResult {
+    status: 'approved' | 'rejected' | 'timeout';
+    apiKey?: string;
+    agentId?: string;
+    agentName?: string;
+}
+export interface RegistrationStatus {
+    status: 'pending' | 'approved' | 'rejected';
+    agentName: string;
+    agentId?: string;
+    apiKey?: string;
+}

package/dist/types.js

@@ -0,0 +1,31 @@
+// ── Message ────────────────────────────────────────────────────────────
+const DEFAULT_CAPABILITIES = {
+    supportsModelSwitch: false,
+    supportsPermissionMode: false,
+    supportsEffort: false,
+    supportsSessionState: false,
+    supportsInterrupt: false,
+};
+/**
+ * Capability map keyed by clientType. Add new agent types here.
+ * ALSO update the duplicate in app/src/types/index.ts (RN app can't
+ * import from core directly due to different bundler/runtime).
+ */
+export const AGENT_CAPABILITIES = {
+    'claude-code': {
+        supportsModelSwitch: true,
+        supportsPermissionMode: true,
+        supportsEffort: true,
+        supportsSessionState: true,
+        supportsInterrupt: true,
+    },
+    'codex': {
+        supportsModelSwitch: false,
+        supportsPermissionMode: false,
+        supportsEffort: false,
+        supportsSessionState: true,
+        supportsInterrupt: true,
+    },
+    'openclaw': { ...DEFAULT_CAPABILITIES },
+    'generic': { ...DEFAULT_CAPABILITIES },
+};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@canonmsg/core",
+  "version": "0.2.2",
+  "description": "Canon core — shared types, REST client, SSE stream, and registration for Canon messaging",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "canon",
+    "messaging",
+    "ai-agents",
+    "sse",
+    "rest-client"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/HeyBobChan/canon",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/HeyBobChan/canon/tree/main/packages/core",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "~5.7.0"
+  },
+  "license": "MIT"
+}