@canonmsg/claude-code-plugin 0.3.0

package/dist/register.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/register.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+import { setDefaultResultOrder } from 'node:dns';
+setDefaultResultOrder('ipv4first');
+/**
+ * CLI script for Canon agent registration.
+ * Invoked by the /canon-register skill.
+ *
+ * Usage:
+ *   node register.js --name "My Agent" --description "What it does" --phone "+15551234567" [--profile "my-agent"]
+ *
+ * On approval, saves the agent to ~/.canon/agents.json under the profile name.
+ */
+import { registerAndWaitForApproval } from '@canonmsg/core';
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { parseArgs } from 'node:util';
+const CANON_DIR = join(homedir(), '.canon');
+const AGENTS_PATH = join(CANON_DIR, 'agents.json');
+const { values } = parseArgs({
+    options: {
+        name: { type: 'string' },
+        description: { type: 'string' },
+        phone: { type: 'string' },
+        profile: { type: 'string' },
+        'base-url': { type: 'string' },
+    },
+    strict: true,
+});
+if (!values.name || !values.description || !values.phone) {
+    console.error('Usage: node register.js --name "Agent Name" --description "Description" --phone "+15551234567" [--profile "my-agent"]');
+    process.exit(1);
+}
+// Default profile name: sanitized agent name
+const profileName = values.profile || values.name.toLowerCase().replace(/[^a-z0-9-]/g, '-').replace(/-+/g, '-');
+console.log(`Registering agent "${values.name}" (profile: ${profileName})...`);
+const result = await registerAndWaitForApproval({
+    name: values.name,
+    description: values.description,
+    ownerPhone: values.phone,
+    developerInfo: 'Claude Code plugin',
+    clientType: 'claude-code',
+    baseUrl: values['base-url'],
+}, {
+    onSubmitted: (requestId) => {
+        console.log(`Registration submitted (request ID: ${requestId}).`);
+        console.log('Waiting for approval in Canon app...');
+    },
+    onPollUpdate: () => {
+        process.stdout.write('.');
+    },
+});
+console.log(''); // newline after dots
+switch (result.status) {
+    case 'approved': {
+        // Save to ~/.canon/agents.json
+        mkdirSync(CANON_DIR, { recursive: true });
+        let profiles = {};
+        try {
+            profiles = JSON.parse(readFileSync(AGENTS_PATH, 'utf-8'));
+        }
+        catch {
+            // File doesn't exist yet
+        }
+        profiles[profileName] = {
+            apiKey: result.apiKey,
+            agentId: result.agentId,
+            agentName: result.agentName,
+            registeredAt: new Date().toISOString(),
+        };
+        writeFileSync(AGENTS_PATH, JSON.stringify(profiles, null, 2));
+        console.log(`Approved! Agent: ${result.agentName} (${result.agentId})`);
+        console.log(`Saved as profile "${profileName}" in ~/.canon/agents.json`);
+        console.log('Restart Claude Code to connect.');
+        break;
+    }
+    case 'rejected':
+        console.log('Registration was rejected.');
+        process.exit(1);
+        break;
+    case 'timeout':
+        console.log('Registration timed out (5 minutes). Try again later.');
+        process.exit(1);
+        break;
+}

package/dist/rtdb-rest.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Lightweight RTDB REST helper for session state.
+ *
+ * Uses Firebase Realtime Database REST API to avoid adding firebase-admin
+ * as a dependency to the MCP plugin. The custom token from /agents/auth-token
+ * is exchanged for a Firebase ID token before use with RTDB REST.
+ */
+import { type CanonClient } from '@canonapp/core';
+export interface SessionStatePayload {
+    model?: string;
+    permissionMode?: string;
+    effort?: string;
+    cwd?: string;
+    hostMode?: boolean;
+    isActive: boolean;
+    updatedAt: {
+        '.sv': 'timestamp';
+    };
+}
+/** Must be called once before any RTDB operations. */
+export declare function initRTDBAuth(client: CanonClient): void;
+/** Generic RTDB REST write (PUT). */
+export declare function rtdbWrite(path: string, data: unknown): Promise<void>;
+/** Generic RTDB REST read (GET). */
+export declare function rtdbRead(path: string): Promise<unknown>;
+/**
+ * Write session state to RTDB via REST API.
+ * Path: /session-state/{conversationId}/{agentId}
+ */
+export declare function writeSessionState(conversationId: string, agentId: string, state: Omit<SessionStatePayload, 'updatedAt'>): Promise<void>;
+/**
+ * Clear session state from RTDB (full overwrite with isActive: false).
+ */
+export declare function clearSessionState(conversationId: string, agentId: string): Promise<void>;

package/dist/rtdb-rest.js

@@ -0,0 +1,128 @@
+/**
+ * Lightweight RTDB REST helper for session state.
+ *
+ * Uses Firebase Realtime Database REST API to avoid adding firebase-admin
+ * as a dependency to the MCP plugin. The custom token from /agents/auth-token
+ * is exchanged for a Firebase ID token before use with RTDB REST.
+ */
+import { DEFAULT_RTDB_URL, FIREBASE_WEB_API_KEY } from '@canonapp/core';
+const RTDB_BASE = process.env.CANON_RTDB_URL || DEFAULT_RTDB_URL;
+const FIREBASE_API_KEY = process.env.CANON_FIREBASE_API_KEY || FIREBASE_WEB_API_KEY;
+// ── Token management ──────────────────────────────────────────────────
+let cachedIdToken = null;
+let idTokenExpiresAt = 0;
+let tokenClient = null;
+/** Must be called once before any RTDB operations. */
+export function initRTDBAuth(client) {
+    tokenClient = client;
+}
+/**
+ * Exchange a Firebase custom token for an ID token via the Identity Toolkit API.
+ */
+async function exchangeCustomTokenForIdToken(customToken) {
+    const url = `https://identitytoolkit.googleapis.com/v1/accounts:signInWithCustomToken?key=${FIREBASE_API_KEY}`;
+    const res = await fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ token: customToken, returnSecureToken: true }),
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`Token exchange failed (${res.status}): ${text}`);
+    }
+    const data = await res.json();
+    return { idToken: data.idToken, expiresIn: parseInt(data.expiresIn, 10) };
+}
+/** Get a valid ID token for RTDB REST, refreshing if expired or expiring soon. */
+async function getToken() {
+    // Refresh if missing, expired, or expiring within 5 minutes
+    if (!cachedIdToken || Date.now() > idTokenExpiresAt - 5 * 60 * 1000) {
+        if (!tokenClient)
+            return null;
+        try {
+            const auth = await tokenClient.getAuthToken();
+            const { idToken, expiresIn } = await exchangeCustomTokenForIdToken(auth.token);
+            cachedIdToken = idToken;
+            idTokenExpiresAt = Date.now() + expiresIn * 1000;
+        }
+        catch (err) {
+            console.error('[canon] RTDB token refresh failed:', err);
+            return cachedIdToken; // Return stale token as fallback
+        }
+    }
+    return cachedIdToken;
+}
+// ── RTDB operations ───────────────────────────────────────────────────
+/** Generic RTDB REST write (PUT). */
+export async function rtdbWrite(path, data) {
+    const token = await getToken();
+    if (!token)
+        return;
+    const url = `${RTDB_BASE}${path}.json?auth=${token}`;
+    const res = await fetch(url, {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(data),
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`RTDB write failed (${res.status}): ${text}`);
+    }
+}
+/** Generic RTDB REST read (GET). */
+export async function rtdbRead(path) {
+    const token = await getToken();
+    if (!token)
+        return null;
+    const url = `${RTDB_BASE}${path}.json?auth=${token}`;
+    const res = await fetch(url);
+    if (!res.ok)
+        return null;
+    return res.json();
+}
+/**
+ * Write session state to RTDB via REST API.
+ * Path: /session-state/{conversationId}/{agentId}
+ */
+export async function writeSessionState(conversationId, agentId, state) {
+    const token = await getToken();
+    if (!token)
+        return;
+    const url = `${RTDB_BASE}/session-state/${conversationId}/${agentId}.json?auth=${token}`;
+    const body = {
+        ...state,
+        updatedAt: { '.sv': 'timestamp' },
+    };
+    const res = await fetch(url, {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`RTDB write failed (${res.status}): ${text}`);
+    }
+}
+/**
+ * Clear session state from RTDB (full overwrite with isActive: false).
+ */
+export async function clearSessionState(conversationId, agentId) {
+    const token = await getToken();
+    if (!token)
+        return;
+    const url = `${RTDB_BASE}/session-state/${conversationId}/${agentId}.json?auth=${token}`;
+    const body = {
+        isActive: false,
+        updatedAt: { '.sv': 'timestamp' },
+    };
+    // Use PUT (not PATCH) to clear stale fields like model/cwd
+    const res = await fetch(url, {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        console.error(`[canon] RTDB clear failed (${res.status}): ${text}`);
+    }
+}

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/server.js

@@ -0,0 +1,400 @@
+#!/usr/bin/env node
+import { setDefaultResultOrder } from 'node:dns';
+setDefaultResultOrder('ipv4first');
+/**
+ * Canon channel MCP server for Claude Code.
+ *
+ * Connects to Canon's SSE stream for real-time inbound messages and exposes
+ * tools for Claude to reply, send messages, list conversations, and set
+ * typing indicators.
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { CanonClient, CanonStream, ApprovalManager, loadProfiles, isProfileLocked, resolveCanonAgent, getActiveProfile, releaseLock, initRTDBAuth, writeSessionState, clearSessionState, } from '@canonmsg/core';
+import { ApprovalHttpServer } from './approval-server.js';
+// ── MCP server ─────────────────────────────────────────────────────────
+const server = new Server({ name: 'canon-channel', version: '0.1.0' }, {
+    capabilities: {
+        tools: {},
+        experimental: { 'claude/channel': {} },
+    },
+});
+let client = null;
+let stream = null;
+let agentContext = null;
+let approvalManager = null;
+let approvalServer = null;
+const conversationCache = new Map();
+/** The conversation that most recently triggered work (for approval routing) */
+let triggerConversationId = null;
+// ── Tool definitions ───────────────────────────────────────────────────
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: 'reply',
+            description: 'Reply to a Canon conversation',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    conversation_id: {
+                        type: 'string',
+                        description: 'The conversation ID to reply to',
+                    },
+                    text: {
+                        type: 'string',
+                        description: 'Message text to send',
+                    },
+                },
+                required: ['conversation_id', 'text'],
+            },
+        },
+        {
+            name: 'send_message',
+            description: 'Send a message to a Canon conversation (supports text, images, audio)',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    conversation_id: {
+                        type: 'string',
+                        description: 'The conversation ID',
+                    },
+                    text: {
+                        type: 'string',
+                        description: 'Message text',
+                    },
+                    content_type: {
+                        type: 'string',
+                        enum: ['text', 'image', 'audio'],
+                        description: 'Content type (default: text)',
+                    },
+                    image_url: {
+                        type: 'string',
+                        description: 'Image URL (when content_type is image)',
+                    },
+                    audio_url: {
+                        type: 'string',
+                        description: 'Audio URL (when content_type is audio)',
+                    },
+                },
+                required: ['conversation_id', 'text'],
+            },
+        },
+        {
+            name: 'list_conversations',
+            description: "List Canon conversations this agent participates in",
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    limit: {
+                        type: 'number',
+                        description: 'Max conversations to return (default: 20)',
+                    },
+                },
+            },
+        },
+        {
+            name: 'list_agents',
+            description: 'List registered Canon agent profiles and their lock status',
+            inputSchema: {
+                type: 'object',
+                properties: {},
+            },
+        },
+        {
+            name: 'set_typing',
+            description: 'Show or hide typing indicator in a Canon conversation',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    conversation_id: {
+                        type: 'string',
+                        description: 'The conversation ID',
+                    },
+                    typing: {
+                        type: 'boolean',
+                        description: 'Whether to show typing indicator',
+                    },
+                    status: {
+                        type: 'string',
+                        enum: ['typing', 'thinking'],
+                        description: 'Typing status (default: typing). Use "thinking" when processing/reasoning.',
+                    },
+                },
+                required: ['conversation_id', 'typing'],
+            },
+        },
+    ],
+}));
+// ── Tool handlers ──────────────────────────────────────────────────────
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    if (!client) {
+        return {
+            content: [{ type: 'text', text: 'Canon not connected' }],
+            isError: true,
+        };
+    }
+    const args = request.params.arguments;
+    switch (request.params.name) {
+        case 'reply': {
+            const conversationId = args.conversation_id;
+            const text = args.text;
+            const result = await client.sendMessage(conversationId, text);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Message sent (${result.messageId})`,
+                    },
+                ],
+            };
+        }
+        case 'send_message': {
+            const conversationId = args.conversation_id;
+            const text = args.text;
+            const contentType = args.content_type || 'text';
+            const opts = {
+                contentType: contentType,
+            };
+            if (args.image_url)
+                opts.imageUrl = args.image_url;
+            if (args.audio_url)
+                opts.audioUrl = args.audio_url;
+            const result = await client.sendMessage(conversationId, text, opts);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Message sent (${result.messageId})`,
+                    },
+                ],
+            };
+        }
+        case 'list_conversations': {
+            const limit = args.limit || 20;
+            const convos = await client.getConversations();
+            const slice = convos.slice(0, limit);
+            const summary = slice.map((c) => ({
+                id: c.id,
+                type: c.type,
+                name: c.name,
+                members: c.memberIds.length,
+                lastMessage: c.lastMessage?.text?.slice(0, 100) || null,
+            }));
+            return {
+                content: [
+                    { type: 'text', text: JSON.stringify(summary, null, 2) },
+                ],
+            };
+        }
+        case 'list_agents': {
+            const profiles = loadProfiles();
+            const entries = Object.entries(profiles).map(([name, p]) => {
+                const lock = isProfileLocked(name);
+                return {
+                    profile: name,
+                    agentName: p.agentName,
+                    agentId: p.agentId,
+                    status: getActiveProfile() === name ? 'active (this session)' : lock.locked ? `in use (PID ${lock.pid})` : 'available',
+                };
+            });
+            if (entries.length === 0) {
+                return {
+                    content: [{ type: 'text', text: 'No agents registered. Run /canon-register to register one.' }],
+                };
+            }
+            return {
+                content: [{ type: 'text', text: JSON.stringify(entries, null, 2) }],
+            };
+        }
+        case 'set_typing': {
+            const conversationId = args.conversation_id;
+            const typing = args.typing;
+            const status = args.status;
+            await client.setTyping(conversationId, typing, status);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: typing ? 'Typing indicator shown' : 'Typing indicator hidden',
+                    },
+                ],
+            };
+        }
+        default:
+            return {
+                content: [
+                    { type: 'text', text: `Unknown tool: ${request.params.name}` },
+                ],
+                isError: true,
+            };
+    }
+});
+// ── Inbound message handler ────────────────────────────────────────────
+async function handleInboundMessage(payload) {
+    const m = payload.message;
+    const convo = conversationCache.get(payload.conversationId);
+    // Track trigger conversation — updated when the owner sends a message
+    if (m.isOwner) {
+        triggerConversationId = payload.conversationId;
+    }
+    // Route to approval manager first — if consumed, don't forward to Claude
+    if (approvalManager) {
+        const consumed = approvalManager.handleMessage(payload.conversationId, {
+            senderId: m.senderId,
+            text: m.text ?? undefined,
+            metadata: m.metadata,
+        });
+        if (consumed) {
+            console.error(`[canon] Approval reply consumed from ${m.senderName || m.senderId}`);
+            return;
+        }
+    }
+    // meta must be Record<string, string> — non-string values cause silent drops
+    const meta = {
+        conversation_id: payload.conversationId,
+        sender_id: m.senderId,
+        sender_name: m.senderName || m.senderId,
+        sender_type: m.senderType || 'human',
+        is_owner: String(m.isOwner ?? false),
+        chat_type: convo?.type || 'direct',
+        content_type: m.contentType || 'text',
+        ts: new Date().toISOString(),
+    };
+    if (m.imageUrl)
+        meta.image_url = m.imageUrl;
+    if (m.audioUrl)
+        meta.audio_url = m.audioUrl;
+    console.error(`[canon] Inbound message from ${meta.sender_name}: "${m.text}"`);
+    try {
+        await server.notification({
+            method: 'notifications/claude/channel',
+            params: {
+                content: m.text || '',
+                meta,
+            },
+        });
+        console.error('[canon] Notification sent to Claude Code');
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`[canon] Failed to send notification: ${msg}`);
+    }
+}
+// ── Start ──────────────────────────────────────────────────────────────
+async function startChannel() {
+    let apiKey;
+    let profile;
+    try {
+        const resolved = resolveCanonAgent({ logPrefix: '[canon]' });
+        apiKey = resolved.apiKey;
+        profile = resolved.profile;
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : err);
+        return;
+    }
+    if (profile) {
+        console.error(`[canon] Using agent profile: ${profile}`);
+    }
+    client = new CanonClient(apiKey);
+    // Get agent identity — try /agents/me first, fall back to /agents/auth-token
+    let agentId;
+    try {
+        agentContext = await client.getAgentMe();
+        agentId = agentContext.agentId;
+        console.error(`[canon] Connected as ${agentContext.displayName || agentId}`);
+    }
+    catch {
+        // /agents/me may not be deployed — fall back to auth-token exchange
+        try {
+            const auth = await client.getAuthToken();
+            agentId = auth.agentId;
+            console.error(`[canon] Authenticated as ${agentId}`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`[canon] Failed to authenticate: ${msg}`);
+            return;
+        }
+    }
+    // Initialize RTDB auth for session state reporting
+    initRTDBAuth(client);
+    // Populate conversation cache
+    try {
+        const convos = await client.getConversations();
+        for (const c of convos)
+            conversationCache.set(c.id, c);
+        console.error(`[canon] Loaded ${convos.length} conversations`);
+    }
+    catch {
+        // Non-fatal — will be populated as messages arrive
+    }
+    // Write initial session state
+    const initialState = { cwd: process.cwd(), isActive: true };
+    for (const convoId of conversationCache.keys()) {
+        writeSessionState(convoId, agentId, initialState).catch((err) => console.error(`[canon] Failed to write initial state for ${convoId}:`, err));
+    }
+    // Start SSE stream
+    stream = new CanonStream({
+        apiKey,
+        agentId,
+        handler: {
+            onMessage: handleInboundMessage,
+            onAgentContext: (ctx) => {
+                agentContext = ctx;
+            },
+            onConnected: () => {
+                console.error('[canon] SSE stream connected');
+            },
+            onDisconnected: () => {
+                console.error('[canon] SSE stream disconnected');
+            },
+            onError: (err) => {
+                console.error(`[canon] SSE error: ${err.message}`);
+            },
+        },
+    });
+    stream.start().catch((err) => {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`[canon] SSE start error: ${msg}`);
+    });
+    // Start approval system
+    if (agentContext?.ownerId) {
+        approvalManager = new ApprovalManager(client, agentId, agentContext.ownerId);
+        approvalServer = new ApprovalHttpServer(approvalManager, () => triggerConversationId);
+        approvalServer.start().catch((err) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`[canon] Approval server error: ${msg}`);
+        });
+    }
+}
+// ── Main ───────────────────────────────────────────────────────────────
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Start the Canon channel after MCP connection is established
+    await startChannel();
+    // Graceful shutdown — release agent lock and clear session state
+    const shutdown = () => {
+        // Mark all conversations as inactive
+        if (agentContext) {
+            for (const convoId of conversationCache.keys()) {
+                clearSessionState(convoId, agentContext.agentId).catch(() => { });
+            }
+        }
+        approvalManager?.dispose();
+        approvalServer?.stop().catch(() => { });
+        stream?.stop();
+        const ap = getActiveProfile();
+        if (ap)
+            releaseLock(ap);
+        process.exit(0);
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+}
+main().catch((err) => {
+    console.error('[canon] Fatal error:', err);
+    process.exit(1);
+});

package/dist/setup.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * Setup script for the Canon Claude Code plugin.
+ *
+ * Run after `npm install -g @canon/claude-code-plugin` to:
+ * 1. Install the /canon-register and /canon-configure skills
+ * 2. Show the user how to add the MCP server to their .mcp.json
+ */
+export {};