@canonmsg/codex-plugin 0.14.1 → 0.18.1

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/codex-plugin",
-  "version": "0.14.1",
+  "version": "0.18.1",
   "description": "Canon host integration for Codex CLI",
   "type": "module",
   "main": "dist/index.js",
@@ -21,7 +21,7 @@
     "scripts"
   ],
   "scripts": {
-    "prepare:workspace-deps": "npm --prefix ../core run build && npm --prefix ../agent-sdk run build",
+    "prepare:workspace-deps": "node ../../scripts/run-workspace-prep.mjs ../core ../agent-sdk",
     "build": "npm run prepare:workspace-deps && node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc",
     "dev": "npm run prepare:workspace-deps && tsc --watch",
     "smoke": "node scripts/smoke-test.mjs",
@@ -29,8 +29,8 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@canonmsg/agent-sdk": "^3.1.0",
-    "@canonmsg/core": "^2.1.0"
+    "@canonmsg/agent-sdk": "^3.2.3",
+    "@canonmsg/core": "^2.6.0"
   },
   "engines": {
     "node": ">=18.0.0"