@canonmsg/claude-code-plugin 0.15.1 → 0.19.0

package/dist/mcp-args.d.ts

@@ -1,4 +1,4 @@
-import type { SendContextualMessageOptions } from '@canonmsg/core';
+import type { DirectSessionSelection, SendContextualMessageOptions } from '@canonmsg/core';
 export type McpParseResult<T> = {
     ok: true;
     value: T;
@@ -32,6 +32,7 @@ export interface SendContextualMessageArgs {
     targetUserId?: string;
     text: string;
     selfContext: SendContextualMessageOptions['selfContext'];
+    sessionSelection?: DirectSessionSelection;
     messageOptions?: SendContextualMessageOptions['messageOptions'];
 }
 export declare function parseSendContextualMessageArgs(value: unknown): McpParseResult<SendContextualMessageArgs>;

package/dist/mcp-args.js

@@ -87,6 +87,28 @@ export function parseSendMessageArgs(value) {
         },
     };
 }
+function parseSessionSelection(value) {
+    if (value == null)
+        return { ok: true, value: undefined };
+    const raw = typeof value === 'string'
+        ? value
+        : isRecord(value) && typeof value.mode === 'string'
+            ? value.mode
+            : null;
+    const mode = raw?.trim().toLowerCase().replace(/-/g, '_');
+    if (!mode)
+        return { ok: false, error: 'Invalid session_selection' };
+    if (mode === 'new' || mode === 'fresh' || mode === 'start_new') {
+        return { ok: true, value: { mode: 'new' } };
+    }
+    if (mode === 'continue_latest' || mode === 'latest' || mode === 'continue') {
+        return { ok: true, value: { mode: 'continue_latest' } };
+    }
+    if (mode === 'continue_or_create' || mode === 'auto' || mode === 'reuse_or_create') {
+        return { ok: true, value: { mode: 'continue_or_create' } };
+    }
+    return { ok: false, error: 'session_selection must be new, continue_latest, or continue_or_create' };
+}
 export function parseSendContextualMessageArgs(value) {
     if (!isRecord(value))
         return { ok: false, error: 'Arguments must be an object' };
@@ -111,6 +133,9 @@ export function parseSendContextualMessageArgs(value) {
     if (type !== 'cross_session') {
         return { ok: false, error: 'self_context.type must be cross_session' };
     }
+    const sessionSelection = parseSessionSelection(value.session_selection);
+    if (!sessionSelection.ok)
+        return sessionSelection;
     const messageOptions = isRecord(value.message_options)
         ? value.message_options
         : undefined;
@@ -125,6 +150,7 @@ export function parseSendContextualMessageArgs(value) {
                 type: 'cross_session',
                 context: context.value,
             },
+            ...(sessionSelection.value ? { sessionSelection: sessionSelection.value } : {}),
             ...(messageOptions ? { messageOptions } : {}),
         },
     };

package/dist/outbox.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Turn-end media outbox for Canon coding hosts.
+ *
+ * The host advertises a per-conversation outbox directory inside the session
+ * working directory (`<cwd>/.canon/outbox/`). When the runtime wants a file
+ * (screenshot, plot, artifact) delivered to the Canon conversation it writes
+ * the file there — an explicit channel, never inferred from reply prose. At
+ * turn end the host scans the outbox, uploads each regular file as a Canon
+ * media attachment, and removes files that were delivered. Failed uploads
+ * stay in place for a later turn; subdirectories, symlinks, and dotfiles are
+ * ignored.
+ *
+ * This module is intentionally identical in packages/claude-code-plugin and
+ * packages/codex-plugin — keep both copies in sync (future consolidation
+ * candidate).
+ */
+export declare const OUTBOX_MAX_FILES_PER_TURN = 8;
+export declare const OUTBOX_MAX_FILE_BYTES: number;
+export interface OutboxFile {
+    path: string;
+    fileName: string;
+    sizeBytes: number;
+}
+export type OutboxSkipReason = 'not-regular-file' | 'hidden' | 'too-large' | 'file-cap';
+export interface OutboxScanResult {
+    /** Regular files eligible for upload this turn, ordered by file name. */
+    files: OutboxFile[];
+    skipped: Array<{
+        fileName: string;
+        reason: OutboxSkipReason;
+    }>;
+}
+export interface OutboxFlushResult {
+    sent: Array<{
+        file: OutboxFile;
+        messageId: string;
+        removeFailed?: true;
+    }>;
+    failed: Array<{
+        file: OutboxFile;
+        error: string;
+    }>;
+    skipped: OutboxScanResult['skipped'];
+}
+export declare function resolveOutboxDir(sessionCwd: string): string;
+/**
+ * Create the outbox directory for a session and drop a `.gitignore` into the
+ * host-managed `.canon/` dir (only when absent) so outbox state never shows
+ * up as untracked dirt inside project checkouts or conversation worktrees.
+ */
+export declare function ensureOutboxDir(sessionCwd: string): Promise<string>;
+/**
+ * The one terse paragraph injected into the runtime's Canon context so the
+ * agent knows the outbox exists. Hosts may append their own extra sentence
+ * (e.g. an immediate-send tool) but must not paraphrase the convention.
+ */
+export declare function buildOutboxContextLine(sessionCwd: string): string;
+/**
+ * Discover the outbox files eligible for upload this turn. A missing outbox
+ * directory is an empty result. Entries are ordered by file name so multi-file
+ * turns deliver deterministically; everything past the per-turn cap (or over
+ * the size cap) is left in place and reported as skipped.
+ */
+export declare function scanOutbox(outboxDir: string, options?: {
+    maxFiles?: number;
+    maxFileBytes?: number;
+}): Promise<OutboxScanResult>;
+/**
+ * Upload-and-consume pass over the outbox. Each eligible file is handed to
+ * `send`; on success the file is removed (consumed), on failure it is left in
+ * place for a later turn. A failed removal after a successful send is still
+ * reported as sent (flagged `removeFailed`) so callers can warn about a
+ * potential duplicate next turn instead of re-reporting a delivery failure.
+ */
+export declare function flushOutbox(input: {
+    outboxDir: string;
+    send: (file: OutboxFile) => Promise<{
+        messageId: string;
+    }>;
+    maxFiles?: number;
+    maxFileBytes?: number;
+    remove?: (path: string) => Promise<void>;
+}): Promise<OutboxFlushResult>;

package/dist/outbox.js

@@ -0,0 +1,132 @@
+/**
+ * Turn-end media outbox for Canon coding hosts.
+ *
+ * The host advertises a per-conversation outbox directory inside the session
+ * working directory (`<cwd>/.canon/outbox/`). When the runtime wants a file
+ * (screenshot, plot, artifact) delivered to the Canon conversation it writes
+ * the file there — an explicit channel, never inferred from reply prose. At
+ * turn end the host scans the outbox, uploads each regular file as a Canon
+ * media attachment, and removes files that were delivered. Failed uploads
+ * stay in place for a later turn; subdirectories, symlinks, and dotfiles are
+ * ignored.
+ *
+ * This module is intentionally identical in packages/claude-code-plugin and
+ * packages/codex-plugin — keep both copies in sync (future consolidation
+ * candidate).
+ */
+import { mkdir, readdir, stat, unlink, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+export const OUTBOX_MAX_FILES_PER_TURN = 8;
+export const OUTBOX_MAX_FILE_BYTES = 25 * 1024 * 1024;
+export function resolveOutboxDir(sessionCwd) {
+    return join(sessionCwd, '.canon', 'outbox');
+}
+/**
+ * Create the outbox directory for a session and drop a `.gitignore` into the
+ * host-managed `.canon/` dir (only when absent) so outbox state never shows
+ * up as untracked dirt inside project checkouts or conversation worktrees.
+ */
+export async function ensureOutboxDir(sessionCwd) {
+    const dir = resolveOutboxDir(sessionCwd);
+    await mkdir(dir, { recursive: true });
+    try {
+        // The `*` pattern ignores everything under .canon, including this file.
+        await writeFile(join(sessionCwd, '.canon', '.gitignore'), '*\n', { flag: 'wx' });
+    }
+    catch {
+        // Already present (or unwritable) — never block session startup on it.
+    }
+    return dir;
+}
+/**
+ * The one terse paragraph injected into the runtime's Canon context so the
+ * agent knows the outbox exists. Hosts may append their own extra sentence
+ * (e.g. an immediate-send tool) but must not paraphrase the convention.
+ */
+export function buildOutboxContextLine(sessionCwd) {
+    const maxMb = Math.floor(OUTBOX_MAX_FILE_BYTES / (1024 * 1024));
+    return `Media outbox: to deliver a file (screenshot, plot, artifact) to this Canon conversation, write it into ${resolveOutboxDir(sessionCwd)} — when your turn ends the host uploads each regular file there as a chat attachment and then deletes it. Limits: ${OUTBOX_MAX_FILES_PER_TURN} files per turn and ${maxMb}MB per file; subdirectories, symlinks, and dotfiles are ignored.`;
+}
+/**
+ * Discover the outbox files eligible for upload this turn. A missing outbox
+ * directory is an empty result. Entries are ordered by file name so multi-file
+ * turns deliver deterministically; everything past the per-turn cap (or over
+ * the size cap) is left in place and reported as skipped.
+ */
+export async function scanOutbox(outboxDir, options) {
+    const maxFiles = options?.maxFiles ?? OUTBOX_MAX_FILES_PER_TURN;
+    const maxFileBytes = options?.maxFileBytes ?? OUTBOX_MAX_FILE_BYTES;
+    let entries;
+    try {
+        entries = await readdir(outboxDir, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return { files: [], skipped: [] };
+        }
+        throw error;
+    }
+    const files = [];
+    const skipped = [];
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        // `readdir` does not follow symlinks, so a symlinked file reports
+        // isSymbolicLink(), not isFile() — links and directories both land here.
+        if (!entry.isFile()) {
+            skipped.push({ fileName: entry.name, reason: 'not-regular-file' });
+            continue;
+        }
+        if (entry.name.startsWith('.')) {
+            skipped.push({ fileName: entry.name, reason: 'hidden' });
+            continue;
+        }
+        const path = join(outboxDir, entry.name);
+        const info = await stat(path);
+        if (info.size > maxFileBytes) {
+            skipped.push({ fileName: entry.name, reason: 'too-large' });
+            continue;
+        }
+        if (files.length >= maxFiles) {
+            skipped.push({ fileName: entry.name, reason: 'file-cap' });
+            continue;
+        }
+        files.push({ path, fileName: entry.name, sizeBytes: info.size });
+    }
+    return { files, skipped };
+}
+/**
+ * Upload-and-consume pass over the outbox. Each eligible file is handed to
+ * `send`; on success the file is removed (consumed), on failure it is left in
+ * place for a later turn. A failed removal after a successful send is still
+ * reported as sent (flagged `removeFailed`) so callers can warn about a
+ * potential duplicate next turn instead of re-reporting a delivery failure.
+ */
+export async function flushOutbox(input) {
+    const { files, skipped } = await scanOutbox(input.outboxDir, {
+        ...(input.maxFiles != null ? { maxFiles: input.maxFiles } : {}),
+        ...(input.maxFileBytes != null ? { maxFileBytes: input.maxFileBytes } : {}),
+    });
+    const remove = input.remove ?? ((path) => unlink(path));
+    const sent = [];
+    const failed = [];
+    for (const file of files) {
+        let messageId;
+        try {
+            ({ messageId } = await input.send(file));
+        }
+        catch (error) {
+            failed.push({
+                file,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            continue;
+        }
+        try {
+            await remove(file.path);
+            sent.push({ file, messageId });
+        }
+        catch {
+            sent.push({ file, messageId, removeFailed: true });
+        }
+    }
+    return { sent, failed, skipped };
+}

package/dist/server.js

@@ -163,6 +163,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                         type: 'object',
                         description: 'Required { type: "cross_session", context: "why I am saying this here" }',
                     },
+                    session_selection: {
+                        type: 'string',
+                        enum: ['new', 'continue_latest', 'continue_or_create'],
+                        description: 'Optional direct-agent session behavior when target_user_id is used',
+                    },
                     message_options: {
                         type: 'object',
                         description: 'Optional Canon send options for the contextual outbound message',
@@ -321,7 +326,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const parsed = parseSendContextualMessageArgs(args);
             if (!parsed.ok)
                 return toolArgumentError(parsed.error);
-            const { sourceConversationId, targetConversationId, targetUserId, text, selfContext, messageOptions, } = parsed.value;
+            const { sourceConversationId, targetConversationId, targetUserId, text, selfContext, sessionSelection, messageOptions, } = parsed.value;
             const contextualMessageOptions = messageOptions;
             const result = await client.sendContextualMessage({
                 sourceConversationId,
@@ -329,6 +334,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 ...(targetUserId ? { targetUserId } : {}),
                 text,
                 selfContext,
+                ...(sessionSelection ? { sessionSelection } : {}),
                 ...(contextualMessageOptions
                     ? {
                         messageOptions: {

package/dist/startup-recovery.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Startup recovery for inbound messages missed while the host was offline.
+ *
+ * The host persists a `lastInboundMessageId` cursor per conversation. On
+ * startup we paginate `getMessagesPage` (newest-first pages, older pages via
+ * its `before` message-id parameter) until the cursor is found or a hard
+ * per-conversation bound is hit, then replay everything after the cursor.
+ *
+ * This module is intentionally identical in packages/claude-code-plugin and
+ * packages/codex-plugin — keep both copies in sync (future consolidation
+ * candidate).
+ */
+export declare const STARTUP_RECOVERY_PAGE_SIZE = 25;
+export declare const STARTUP_RECOVERY_MAX_MESSAGES = 500;
+export interface StartupRecoveryMessage {
+    id: string;
+    senderId: string;
+    createdAt?: string;
+}
+export interface StartupRecoveryPage {
+    messages: StartupRecoveryMessage[];
+}
+export type StartupRecoveryMode = 
+/** Cursor found — `messages` is everything strictly after it. */
+'after-cursor'
+/** Cursor present but not found within the bound — `messages` is the bounded recent window. */
+ | 'truncated-window'
+/**
+ * No usable cursor (fresh runtime file, or the cursor message no longer
+ * exists in history) — only the newest inbound message is recovered, since
+ * a full-history replay could fire mass duplicate turns.
+ */
+ | 'latest-only';
+export interface StartupRecoveryResult<TPage extends StartupRecoveryPage> {
+    mode: StartupRecoveryMode;
+    /** Missed inbound messages (own messages excluded), oldest first. */
+    messages: TPage['messages'];
+    /** First page fetched — reusable as hydration context for recovered turns. */
+    newestPage: TPage;
+}
+export declare function collectMissedInboundMessages<TPage extends StartupRecoveryPage>(input: {
+    fetchPage: (before?: string) => Promise<TPage>;
+    cursor: string | null | undefined;
+    agentId: string;
+    maxMessages?: number;
+}): Promise<StartupRecoveryResult<TPage>>;

package/dist/startup-recovery.js

@@ -0,0 +1,59 @@
+/**
+ * Startup recovery for inbound messages missed while the host was offline.
+ *
+ * The host persists a `lastInboundMessageId` cursor per conversation. On
+ * startup we paginate `getMessagesPage` (newest-first pages, older pages via
+ * its `before` message-id parameter) until the cursor is found or a hard
+ * per-conversation bound is hit, then replay everything after the cursor.
+ *
+ * This module is intentionally identical in packages/claude-code-plugin and
+ * packages/codex-plugin — keep both copies in sync (future consolidation
+ * candidate).
+ */
+export const STARTUP_RECOVERY_PAGE_SIZE = 25;
+export const STARTUP_RECOVERY_MAX_MESSAGES = 500;
+export async function collectMissedInboundMessages(input) {
+    const maxMessages = input.maxMessages ?? STARTUP_RECOVERY_MAX_MESSAGES;
+    const newestPage = await input.fetchPage();
+    const collected = [...newestPage.messages];
+    const seenIds = new Set(collected.map((message) => message.id));
+    const hasCursor = (messages) => input.cursor != null && messages.some((message) => message.id === input.cursor);
+    let cursorFound = hasCursor(collected);
+    if (input.cursor != null) {
+        while (!cursorFound && collected.length < maxMessages) {
+            // Pages are newest-first, so the last collected message is the oldest.
+            const before = collected[collected.length - 1]?.id;
+            if (!before)
+                break;
+            const page = await input.fetchPage(before);
+            const fresh = page.messages.filter((message) => !seenIds.has(message.id));
+            // No pagination progress (history exhausted, or the server ignored the
+            // `before` cursor because that message was hard-deleted) — stop here.
+            if (fresh.length === 0)
+                break;
+            for (const message of fresh)
+                seenIds.add(message.id);
+            collected.push(...fresh);
+            cursorFound = hasCursor(fresh);
+        }
+    }
+    const ascending = [...collected].sort((a, b) => String(a.createdAt ?? '').localeCompare(String(b.createdAt ?? '')));
+    const inboundOnly = (messages) => messages.filter((message) => message.senderId !== input.agentId);
+    let mode;
+    let missed;
+    if (cursorFound) {
+        const cursorIndex = ascending.findIndex((message) => message.id === input.cursor);
+        mode = 'after-cursor';
+        missed = inboundOnly(ascending.slice(cursorIndex + 1));
+    }
+    else if (input.cursor != null && collected.length >= maxMessages) {
+        mode = 'truncated-window';
+        missed = inboundOnly(ascending.slice(-maxMessages));
+    }
+    else {
+        mode = 'latest-only';
+        missed = inboundOnly(ascending).slice(-1);
+    }
+    // Safe: `missed` only holds elements of pages returned by `fetchPage`.
+    return { mode, messages: missed, newestPage };
+}

package/dist/tool-policy.d.ts

@@ -1,4 +1,4 @@
-import type { ApprovalManager, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRisk } from '@canonmsg/core';
+import type { ApprovalManager, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRisk, CanonUnifiedDiff } from '@canonmsg/core';
 export type ClaudeToolPolicyDecision = {
     behavior: 'allow';
 } | {
@@ -27,4 +27,10 @@ export declare function decideClaudeToolPermissionForMode(input: {
     approvalManager?: ApprovalManager | null;
     canRequestApproval?: () => Promise<boolean>;
     allowedNonOwnerTools?: Iterable<string>;
+    /**
+     * Lazy file-change preview for the approval card (Edit/Write-class tools).
+     * Invoked only once the call is headed for an owner approval; best-effort —
+     * a throw or undefined simply omits the diff, never blocks the approval.
+     */
+    buildApprovalDiff?: () => Promise<CanonUnifiedDiff | undefined>;
 }): Promise<ClaudeToolPolicyDecision>;

package/dist/tool-policy.js

@@ -174,6 +174,15 @@ export async function decideClaudeToolPermissionForMode(input) {
             message: NATIVE_APPROVAL_UNAVAILABLE_MESSAGE,
         };
     }
+    let diff;
+    if (input.buildApprovalDiff) {
+        try {
+            diff = await input.buildApprovalDiff();
+        }
+        catch {
+            diff = undefined;
+        }
+    }
     let result;
     try {
         const risk = classifyClaudeApprovalRisk(input.toolName, input.toolInput);
@@ -188,6 +197,7 @@ export async function decideClaudeToolPermissionForMode(input) {
                 method: 'canUseTool',
             },
             details: buildClaudeApprovalDetails(input.toolName, input.toolInput),
+            ...(diff ? { diff } : {}),
             ignoreSessionRules: !input.isOwnerTurn,
             allowSessionRule: input.isOwnerTurn,
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/claude-code-plugin",
-  "version": "0.15.1",
+  "version": "0.19.0",
   "description": "Canon channel plugin for Claude Code — messaging where AI agents are first-class citizens",
   "type": "module",
   "main": "dist/index.js",
@@ -31,9 +31,10 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.141",
-    "@canonmsg/agent-sdk": "^3.1.0",
-    "@canonmsg/core": "^2.1.0",
-    "@modelcontextprotocol/sdk": "^1.29.0"
+    "@canonmsg/agent-sdk": "^3.2.1",
+    "@canonmsg/core": "^2.5.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.0.0"
   },
   "engines": {
     "node": ">=18.0.0"