@canonmsg/codex-plugin 0.18.11 → 0.19.0

package/dist/codex-app-tools.js

@@ -0,0 +1,519 @@
+const emptyObjectSchema = {
+    type: 'object',
+    properties: {},
+    additionalProperties: false,
+};
+const modelProperties = {
+    model: {
+        type: 'string',
+        description: 'Optional model override. Omit unless the user explicitly asks for a specific model.',
+    },
+    thinking: {
+        type: 'string',
+        description: 'Optional reasoning effort override.',
+        enum: ['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max', 'ultra'],
+    },
+};
+const createThreadTargetSchema = {
+    description: 'Where to create the thread. Canon currently supports local project targets only.',
+    anyOf: [
+        {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                type: { type: 'string', enum: ['project'] },
+                projectId: { type: 'string', description: 'Canon workspace id.' },
+                environment: {
+                    anyOf: [
+                        {
+                            type: 'object',
+                            additionalProperties: false,
+                            properties: {
+                                type: { type: 'string', enum: ['local'] },
+                            },
+                            required: ['type'],
+                        },
+                        {
+                            type: 'object',
+                            additionalProperties: true,
+                            properties: {
+                                type: { type: 'string', enum: ['worktree'] },
+                            },
+                            required: ['type'],
+                        },
+                    ],
+                },
+            },
+            required: ['type', 'projectId', 'environment'],
+        },
+        {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                type: { type: 'string', enum: ['projectless'] },
+                directoryName: { type: 'string' },
+            },
+            required: ['type'],
+        },
+    ],
+};
+const forkEnvironmentSchema = {
+    description: 'Where the fork should run. Canon currently supports same-directory forks only.',
+    anyOf: [
+        {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                type: { type: 'string', enum: ['same-directory'] },
+            },
+            required: ['type'],
+        },
+        {
+            type: 'object',
+            additionalProperties: true,
+            properties: {
+                type: { type: 'string', enum: ['worktree'] },
+            },
+            required: ['type'],
+        },
+    ],
+};
+function tool(name, description, inputSchema, deferLoading = true) {
+    return { namespace: 'codex_app', name, description, inputSchema, deferLoading };
+}
+export const CODEX_APP_DYNAMIC_TOOLS = [
+    tool('automation_update', 'Create, update, view, or delete Codex app automations. Canon exposes the name for compatibility, but does not manage Desktop automations.', {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            id: { type: 'string' },
+            mode: { type: 'string' },
+            kind: { type: 'string' },
+            name: { type: 'string' },
+            prompt: { type: 'string' },
+            rrule: { type: 'string' },
+            cwds: {
+                anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }],
+            },
+            destination: { type: 'string' },
+            executionEnvironment: { type: 'string' },
+            localEnvironmentConfigPath: { type: ['string', 'null'] },
+            model: { type: 'string' },
+            reasoningEffort: { type: 'string' },
+            targetThreadId: { type: 'string' },
+            status: { type: 'string' },
+        },
+    }),
+    tool('navigate_to_codex_page', 'Navigate the Codex Desktop UI. Canon exposes the name for compatibility, but has no Codex Desktop page to navigate.', { type: 'object', additionalProperties: true, properties: {} }),
+    tool('read_thread_terminal', 'Read the Codex Desktop terminal output for this thread. Canon exposes the name for compatibility, but has no Desktop terminal pane.', emptyObjectSchema, false),
+    tool('load_workspace_dependencies', 'Locate bundled Desktop workspace dependency runtimes. Canon exposes the name for compatibility, but does not provide Desktop bundle paths.', emptyObjectSchema, false),
+    tool('fork_thread', 'Fork a Codex thread. Omit threadId to fork the calling thread. Canon supports same-directory forks.', {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            threadId: { type: 'string' },
+            environment: forkEnvironmentSchema,
+        },
+    }),
+    tool('handoff_thread', 'Move a Codex thread between a checkout and worktree. Canon exposes the name for compatibility, but does not manage Desktop handoffs.', {
+        type: 'object',
+        additionalProperties: false,
+        properties: { threadId: { type: 'string' } },
+        required: ['threadId'],
+    }),
+    tool('get_handoff_status', 'Read Codex Desktop handoff status. Canon exposes the name for compatibility, but does not manage Desktop handoffs.', {
+        type: 'object',
+        additionalProperties: false,
+        properties: { threadId: { type: 'string' } },
+    }),
+    tool('list_projects', 'List Canon workspaces available to Codex app tools.', emptyObjectSchema),
+    tool('create_thread', 'Create a separate Codex thread only when the user explicitly asks for a new or separate thread. Canon supports local project targets.', {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            prompt: { type: 'string', description: 'Initial prompt for the new thread.' },
+            target: createThreadTargetSchema,
+            ...modelProperties,
+        },
+        required: ['prompt'],
+    }),
+    tool('list_threads', 'List recent Codex threads in Canon-configured workspaces.', {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            query: { type: 'string' },
+            limit: { type: 'number' },
+            archived: { type: 'boolean' },
+        },
+    }),
+    tool('read_thread', 'Read recent status and turn summaries for one Codex thread without opening it.', {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            threadId: { type: 'string' },
+        },
+        required: ['threadId'],
+    }),
+    tool('send_message_to_thread', 'Send a follow-up prompt to an existing Codex thread in the background.', {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            threadId: { type: 'string' },
+            prompt: { type: 'string' },
+            ...modelProperties,
+        },
+        required: ['threadId', 'prompt'],
+    }),
+    tool('set_thread_pinned', 'Pin or unpin a Codex thread. Canon exposes the name for compatibility, but pinned state is Desktop-only.', {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            threadId: { type: 'string' },
+            pinned: { type: 'boolean' },
+        },
+        required: ['threadId', 'pinned'],
+    }),
+    tool('set_thread_archived', 'Archive or unarchive a Codex thread.', {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            threadId: { type: 'string' },
+            archived: { type: 'boolean' },
+        },
+        required: ['archived'],
+    }),
+    tool('set_thread_title', 'Rename a Codex thread.', {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            threadId: { type: 'string' },
+            title: { type: 'string' },
+        },
+        required: ['threadId', 'title'],
+    }),
+];
+const CODEX_APP_TOOL_NAMES = new Set(CODEX_APP_DYNAMIC_TOOLS.map((entry) => String(entry.name)));
+const UNSUPPORTED_TOOLS = new Map([
+    ['automation_update', 'Canon does not manage Codex Desktop automations.'],
+    ['navigate_to_codex_page', 'Canon has no Codex Desktop page to navigate.'],
+    ['read_thread_terminal', 'Canon has no Codex Desktop terminal pane to read.'],
+    ['load_workspace_dependencies', 'Canon does not provide Codex Desktop bundled dependency paths.'],
+    ['handoff_thread', 'Canon does not manage Codex Desktop handoffs.'],
+    ['get_handoff_status', 'Canon does not manage Codex Desktop handoffs.'],
+    ['set_thread_pinned', 'Pinned thread state is Codex Desktop-only.'],
+]);
+export function isCodexAppToolCall(params) {
+    const namespace = typeof params.namespace === 'string' ? params.namespace : null;
+    const rawTool = typeof params.tool === 'string' ? params.tool.trim() : '';
+    const toolName = normalizeToolName(params.tool);
+    if (namespace && namespace !== 'codex_app')
+        return rawTool.startsWith('codex_app.');
+    return namespace === 'codex_app'
+        || rawTool.startsWith('codex_app.')
+        || (toolName ? CODEX_APP_TOOL_NAMES.has(toolName) : false);
+}
+export function deniedCodexAppToolResult(reason) {
+    return toolResult(false, { error: reason });
+}
+export async function handleCodexAppToolCall(runtime, params) {
+    const toolName = normalizeToolName(params.tool);
+    if (!toolName || !CODEX_APP_TOOL_NAMES.has(toolName)) {
+        return toolResult(false, { error: `Unsupported codex_app tool: ${String(params.tool ?? 'unknown')}` });
+    }
+    const unsupportedReason = UNSUPPORTED_TOOLS.get(toolName);
+    if (unsupportedReason) {
+        return toolResult(false, { tool: toolName, error: unsupportedReason });
+    }
+    const args = parseToolArguments(params.arguments);
+    try {
+        switch (toolName) {
+            case 'list_projects':
+                return toolResult(true, {
+                    projects: listToolWorkspaces(runtime).map((workspace) => ({
+                        id: workspace.id,
+                        label: workspace.label,
+                        cwd: workspace.cwd,
+                        environments: ['local'],
+                    })),
+                    unsupported: {
+                        worktreeEnvironments: 'Canon host app-server tools only create local project threads.',
+                    },
+                });
+            case 'create_thread':
+                return await createThread(runtime, args);
+            case 'fork_thread':
+                return await forkThread(runtime, args);
+            case 'list_threads':
+                return await listThreads(runtime, args);
+            case 'read_thread':
+                return await readThread(runtime, args);
+            case 'send_message_to_thread':
+                return await sendMessageToThread(runtime, args);
+            case 'set_thread_archived':
+                return await setThreadArchived(runtime, args);
+            case 'set_thread_title':
+                return await setThreadTitle(runtime, args);
+            default:
+                return toolResult(false, { tool: toolName, error: 'Tool is registered but has no Canon handler.' });
+        }
+    }
+    catch (error) {
+        return toolResult(false, {
+            tool: toolName,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+async function createThread(runtime, args) {
+    const prompt = readString(args, 'prompt');
+    if (!prompt)
+        throw new Error('create_thread requires a non-empty prompt.');
+    const cwd = resolveCreateThreadCwd(runtime, args);
+    const started = await runtime.adapter.requestAppServer('thread/start', {
+        cwd,
+        ...(readString(args, 'model') ?? runtime.model ? { model: readString(args, 'model') ?? runtime.model } : {}),
+        dynamicTools: CODEX_APP_DYNAMIC_TOOLS,
+        experimentalRawEvents: false,
+        persistExtendedHistory: true,
+    });
+    const threadId = readThreadId(started);
+    if (!threadId)
+        throw new Error('Codex app-server did not return a thread id for the new thread.');
+    const turnStarted = await runtime.adapter.requestAppServer('turn/start', buildTurnStartParams({
+        threadId,
+        prompt,
+        model: readString(args, 'model') ?? null,
+        effort: readString(args, 'thinking') ?? readString(args, 'effort') ?? runtime.effort ?? null,
+    }));
+    return toolResult(true, {
+        threadId,
+        turnId: readTurnId(turnStarted) ?? null,
+        status: 'submitted',
+        cwd,
+    });
+}
+async function forkThread(runtime, args) {
+    const environment = isRecord(args.environment) ? args.environment : null;
+    const environmentType = readString(environment, 'type');
+    if (environmentType && environmentType !== 'same-directory') {
+        throw new Error('Canon only supports same-directory codex_app.fork_thread calls.');
+    }
+    const sourceThreadId = readString(args, 'threadId') ?? runtime.currentThreadId;
+    if (!sourceThreadId)
+        throw new Error('fork_thread requires a source thread id.');
+    const source = await assertThreadAllowed(runtime, sourceThreadId);
+    const forked = await runtime.adapter.requestAppServer('thread/fork', {
+        threadId: sourceThreadId,
+        cwd: source.cwd ?? runtime.currentCwd,
+        excludeTurns: true,
+        persistExtendedHistory: true,
+    });
+    const threadId = readThreadId(forked);
+    if (!threadId)
+        throw new Error('Codex app-server did not return a forked thread id.');
+    return toolResult(true, {
+        threadId,
+        sourceThreadId,
+        status: 'forked',
+        cwd: source.cwd ?? runtime.currentCwd,
+    });
+}
+async function listThreads(runtime, args) {
+    const limit = clampLimit(readNumber(args, 'limit'));
+    const result = await runtime.adapter.requestAppServer('thread/list', {
+        cwd: allowedCwds(runtime),
+        limit,
+        searchTerm: readString(args, 'query') ?? readString(args, 'searchTerm') ?? null,
+        archived: typeof args.archived === 'boolean' ? args.archived : false,
+    });
+    return toolResult(true, result);
+}
+async function readThread(runtime, args) {
+    const threadId = readString(args, 'threadId');
+    if (!threadId)
+        throw new Error('read_thread requires threadId.');
+    await assertThreadAllowed(runtime, threadId);
+    const result = await runtime.adapter.requestAppServer('thread/read', {
+        threadId,
+        includeTurns: true,
+    });
+    return toolResult(true, result);
+}
+async function sendMessageToThread(runtime, args) {
+    const threadId = readString(args, 'threadId');
+    const prompt = readString(args, 'prompt');
+    if (!threadId)
+        throw new Error('send_message_to_thread requires threadId.');
+    if (!prompt)
+        throw new Error('send_message_to_thread requires a non-empty prompt.');
+    await assertThreadAllowed(runtime, threadId);
+    const result = await runtime.adapter.requestAppServer('turn/start', buildTurnStartParams({
+        threadId,
+        prompt,
+        model: readString(args, 'model') ?? null,
+        effort: readString(args, 'thinking') ?? readString(args, 'effort') ?? null,
+    }));
+    return toolResult(true, {
+        threadId,
+        turnId: readTurnId(result) ?? null,
+        status: 'submitted',
+    });
+}
+async function setThreadArchived(runtime, args) {
+    const threadId = readString(args, 'threadId') ?? runtime.currentThreadId;
+    if (!threadId)
+        throw new Error('set_thread_archived requires threadId outside the calling thread.');
+    if (typeof args.archived !== 'boolean')
+        throw new Error('set_thread_archived requires archived boolean.');
+    await assertThreadAllowed(runtime, threadId);
+    const result = await runtime.adapter.requestAppServer(args.archived ? 'thread/archive' : 'thread/unarchive', { threadId });
+    return toolResult(true, { threadId, archived: args.archived, result });
+}
+async function setThreadTitle(runtime, args) {
+    const threadId = readString(args, 'threadId');
+    const title = readString(args, 'title');
+    if (!threadId)
+        throw new Error('set_thread_title requires threadId.');
+    if (!title)
+        throw new Error('set_thread_title requires a non-empty title.');
+    await assertThreadAllowed(runtime, threadId);
+    const result = await runtime.adapter.requestAppServer('thread/name/set', {
+        threadId,
+        name: title,
+    });
+    return toolResult(true, { threadId, title, result });
+}
+function resolveCreateThreadCwd(runtime, args) {
+    const target = isRecord(args.target) ? args.target : null;
+    const environment = isRecord(target?.environment) ? target.environment : null;
+    const environmentType = readString(environment, 'type');
+    if (environmentType === 'worktree') {
+        throw new Error('Canon does not create codex_app threads in new worktrees yet.');
+    }
+    if (readString(target, 'type') === 'projectless') {
+        throw new Error('Canon does not support projectless codex_app threads yet.');
+    }
+    const projectId = readString(target, 'projectId')
+        ?? readString(args, 'projectId')
+        ?? readString(args, 'workspaceId');
+    if (!projectId)
+        return runtime.currentCwd;
+    const workspace = listToolWorkspaces(runtime).find((entry) => entry.id === projectId);
+    if (!workspace)
+        throw new Error(`Unknown Canon workspace/project id: ${projectId}`);
+    return workspace.cwd;
+}
+async function assertThreadAllowed(runtime, threadId) {
+    if (threadId === runtime.currentThreadId) {
+        return { cwd: runtime.currentCwd, raw: null };
+    }
+    const result = await runtime.adapter.requestAppServer('thread/read', {
+        threadId,
+        includeTurns: false,
+    });
+    const cwd = readThreadCwd(result);
+    if (!cwd || !allowedCwdSet(runtime).has(cwd)) {
+        throw new Error(`Thread ${threadId} is not in a Canon-configured workspace.`);
+    }
+    return { cwd, raw: result };
+}
+function buildTurnStartParams(input) {
+    return {
+        threadId: input.threadId,
+        input: [{ type: 'text', text: input.prompt, text_elements: [] }],
+        ...(input.model ? { model: input.model } : {}),
+        ...(input.effort ? { effort: input.effort } : {}),
+    };
+}
+function listToolWorkspaces(runtime) {
+    const seen = new Set();
+    const workspaces = [];
+    for (const workspace of runtime.workspaces) {
+        if (!workspace.cwd || seen.has(workspace.cwd))
+            continue;
+        seen.add(workspace.cwd);
+        workspaces.push(workspace);
+    }
+    if (runtime.currentCwd && !seen.has(runtime.currentCwd)) {
+        workspaces.unshift({
+            id: 'current',
+            label: 'Current session',
+            cwd: runtime.currentCwd,
+        });
+    }
+    return workspaces;
+}
+function allowedCwds(runtime) {
+    return listToolWorkspaces(runtime).map((workspace) => workspace.cwd);
+}
+function allowedCwdSet(runtime) {
+    return new Set(allowedCwds(runtime));
+}
+function clampLimit(value) {
+    if (!value || !Number.isFinite(value))
+        return 20;
+    return Math.max(1, Math.min(100, Math.floor(value)));
+}
+function parseToolArguments(value) {
+    if (isRecord(value))
+        return value;
+    if (typeof value === 'string' && value.trim()) {
+        try {
+            const parsed = JSON.parse(value);
+            return isRecord(parsed) ? parsed : {};
+        }
+        catch {
+            return {};
+        }
+    }
+    return {};
+}
+function normalizeToolName(value) {
+    if (typeof value !== 'string' || !value.trim())
+        return null;
+    const trimmed = value.trim();
+    return trimmed.startsWith('codex_app.') ? trimmed.slice('codex_app.'.length) : trimmed;
+}
+function readThreadId(value) {
+    if (!isRecord(value))
+        return undefined;
+    return readString(value, 'threadId')
+        ?? readString(value, 'id')
+        ?? readString(isRecord(value.thread) ? value.thread : undefined, 'id');
+}
+function readTurnId(value) {
+    if (!isRecord(value))
+        return undefined;
+    return readString(value, 'turnId')
+        ?? readString(value, 'id')
+        ?? readString(isRecord(value.turn) ? value.turn : undefined, 'id');
+}
+function readThreadCwd(value) {
+    if (!isRecord(value))
+        return null;
+    const thread = isRecord(value.thread) ? value.thread : undefined;
+    return readString(thread, 'cwd')
+        ?? readString(thread, 'workingDirectory')
+        ?? readString(value, 'cwd')
+        ?? null;
+}
+function readString(record, key) {
+    const value = record?.[key];
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+function readNumber(record, key) {
+    const value = record[key];
+    return typeof value === 'number' ? value : undefined;
+}
+function isRecord(value) {
+    return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+function toolResult(success, payload) {
+    return {
+        success,
+        contentItems: [{
+                type: 'inputText',
+                text: typeof payload === 'string' ? payload : JSON.stringify(payload, null, 2),
+            }],
+    };
+}

package/dist/control-channel.d.ts

@@ -1,52 +1,32 @@
 /**
- * Codex host RTDB `/control/{conversationId}/{agentId}` channel wiring.
+ * Codex host control-channel wiring (bridge notifications).
  *
- * Configures the shared `ControlChannelPoller` from `@canonmsg/core` to the
- * codex host characterization profile (the "codex host profile" describe
- * block in core's control-poller.test.ts is the contract):
+ * Phase 6: the host-side RTDB `/control` poller is DELETED — the Bridge is
+ * the single authoritative consumer for this identity (one adaptive poller
+ * per daemon; cadence, jitter, baselines and consume semantics live there)
+ * and pushes `onSessionControl` / `onControlSignal` / `onControlPrimitive`
+ * notifications instead. This module keeps the codex-shaped handler wiring:
+ * session + signal ride the shared agent-host router; the primitive channel
+ * (context.compact) subscribes alongside them.
  *
- * - Keys: `session` + `signal`, plus `primitive` when a primitive handler is
- *   configured; read sequentially per conversation, conversations polled one
- *   at a time.
- * - Cadence: immediate first cycle, then active/idle delays + jitter with
- *   the activity probe sampled BEFORE the cycle runs.
- * - Session controls are always consumed once newer (default consume), even
- *   when no live session applied them; signals are NOT consumed when the
- *   handler throws (consumeOnError stays false).
- * - Dedupe is primed eagerly via `poller.baseline([conversationId])` at
- *   session creation — the second legacy poll site.
+ * Consume semantics note (deliberate Phase-6 change, plan §2): the node is
+ * consumed bridge-side BEFORE dispatch, so handler return values are
+ * advisory-only and a throwing handler is logged, never retried — the legacy
+ * leave-in-place-on-error behavior is gone with the host poller.
  */
-import { ControlChannelPoller, type ControlChannelRTDB, type ControlHandlerResult, type ControlPollerError, type ControlPrimitiveEvent, type ControlSessionEvent, type ControlSignalEvent } from '@canonmsg/core';
-export declare const CONTROL_POLL_MS = 2000;
-export declare const IDLE_CONTROL_POLL_MS = 10000;
-export declare const CONTROL_POLL_JITTER_MS = 1000;
+import type { ControlPrimitiveEventRecord, ControlSessionEventRecord, ControlSignalEventRecord } from '@canonmsg/backend-contracts';
+import { type ControlNotificationSource, type HostControlHandlerResult } from '@canonmsg/agent-host';
 export interface CodexControlChannelInput {
-    /** Scoped RTDB handle from `initRTDBAuth` — never the module-global default. */
-    rtdb: ControlChannelRTDB;
-    agentId: string;
-    /** Live session conversation ids, snapshotted at the start of every cycle. */
-    conversationIds: () => Iterable<string>;
-    /** Sampled before each cycle to choose the active vs idle delay. */
-    hasActiveWork: () => boolean;
-    /**
-     * Applies a newer `/session` control node. The node is always consumed
-     * after the handler resolves; a thrown error leaves it in place (with
-     * dedupe already advanced, so it is never retried).
-     */
-    onSessionControl: (event: ControlSessionEvent) => Promise<ControlHandlerResult> | ControlHandlerResult;
-    /**
-     * Handles a newer `/signal` node. Return `{ consume: false }` to leave the
-     * node in place; thrown errors also leave it (consumeOnError stays false).
-     */
-    onSignal: (event: ControlSignalEvent) => Promise<ControlHandlerResult> | ControlHandlerResult;
-    /**
-     * Handles a newer `/primitive` node. Primitive commands are consumed by
-     * default after the handler resolves or throws, matching core's command
-     * semantics so one failed command cannot replay forever.
-     */
-    onPrimitive?: (event: ControlPrimitiveEvent) => Promise<ControlHandlerResult> | ControlHandlerResult;
-    onError?: (error: ControlPollerError) => void;
-    /** Injectable jitter source (tests). */
-    random?: () => number;
+    /** Buffered notification source (registered before the hello completes). */
+    source: ControlNotificationSource;
+    /** Applies a `/session` control (model/effort; permission is start-only). */
+    onSessionControl: (event: ControlSessionEventRecord) => Promise<HostControlHandlerResult> | HostControlHandlerResult;
+    /** Handles a `/signal` node (interrupt / stop_and_drop / new_session). */
+    onSignal: (event: ControlSignalEventRecord) => Promise<HostControlHandlerResult> | HostControlHandlerResult;
+    /** Handles a `/primitive` command (context.compact). */
+    onPrimitive?: (event: ControlPrimitiveEventRecord) => Promise<HostControlHandlerResult> | HostControlHandlerResult;
+    /** Error sink for throwing handlers (default: console.error). */
+    onError?: (error: unknown, kind: 'session' | 'signal' | 'primitive', conversationId: string | null) => void;
 }
-export declare function createCodexControlPoller(input: CodexControlChannelInput): ControlChannelPoller;
+/** Wire the codex control handlers to the bridge notifications; returns detach. */
+export declare function attachCodexControlNotifications(input: CodexControlChannelInput): () => void;