@canonmsg/codex-plugin 0.18.10 → 0.18.12

package/dist/app-server-adapter.d.ts

@@ -1,4 +1,5 @@
 import type { CodexApprovalPolicy, CodexEvent, CodexRunTurnOptions, CodexSandboxMode, CodexTurnResult } from './adapter.js';
+export type JsonRecord = Record<string, unknown>;
 export interface CodexSkillMetadata {
     name: string;
     path: string;
@@ -18,6 +19,7 @@ export declare class CodexAppServerAdapter {
     private readonly configOverrides;
     private readonly fullAuto;
     private readonly bypassApprovalsAndSandbox;
+    private readonly dynamicTools;
     private child;
     private threadId;
     private loadedThreadId;
@@ -49,6 +51,7 @@ export declare class CodexAppServerAdapter {
         configOverrides?: string[];
         fullAuto?: boolean;
         bypassApprovalsAndSandbox?: boolean;
+        dynamicTools?: readonly JsonRecord[];
     });
     getThreadId(): string | null;
     clearThreadId(): void;
@@ -64,6 +67,8 @@ export declare class CodexAppServerAdapter {
     setReasoningEffort(effort: string | null): void;
     isRunning(): boolean;
     interrupt(): Promise<void>;
+    compactThread(): Promise<void>;
+    requestAppServer(method: string, params: unknown): Promise<unknown>;
     close(): void;
     runTurn(prompt: string, onEvent: (event: CodexEvent) => void, onLog?: (line: string) => void, imagePaths?: readonly string[], _extraAddDirs?: readonly string[], options?: CodexRunTurnOptions): Promise<CodexTurnResult>;
     private resolveApprovalPolicy;
@@ -79,6 +84,7 @@ export declare class CodexAppServerAdapter {
     private handleLine;
     private handleServerRequest;
     private handleNotification;
+    private isCurrentThreadNotification;
     private resolveCurrentTurn;
     private clearActiveTurn;
     private sendRequest;

package/dist/app-server-adapter.js

@@ -11,6 +11,7 @@ export class CodexAppServerAdapter {
     configOverrides;
     fullAuto;
     bypassApprovalsAndSandbox;
+    dynamicTools;
     child = null;
     threadId;
     loadedThreadId = null;
@@ -42,6 +43,7 @@ export class CodexAppServerAdapter {
         this.configOverrides = opts.configOverrides ?? [];
         this.fullAuto = opts.fullAuto ?? false;
         this.bypassApprovalsAndSandbox = opts.bypassApprovalsAndSandbox ?? false;
+        this.dynamicTools = opts.dynamicTools ?? [];
     }
     getThreadId() {
         return this.threadId;
@@ -83,6 +85,19 @@ export class CodexAppServerAdapter {
             turnId: this.currentTurnId,
         }).catch(() => { });
     }
+    async compactThread() {
+        if (!this.threadId) {
+            throw new Error('No Codex thread to compact');
+        }
+        await this.ensureStarted();
+        await this.sendRequest('thread/compact/start', {
+            threadId: this.threadId,
+        });
+    }
+    async requestAppServer(method, params) {
+        await this.ensureStarted();
+        return await this.sendRequest(method, params);
+    }
     close() {
         this.child?.kill('SIGTERM');
         this.child = null;
@@ -113,6 +128,7 @@ export class CodexAppServerAdapter {
                     approvalPolicy: this.resolveApprovalPolicy(),
                     excludeTurns: true,
                     persistExtendedHistory: true,
+                    ...(this.dynamicTools.length ? { dynamicTools: this.dynamicTools } : {}),
                 });
                 this.loadedThreadId = this.threadId;
                 this.rememberResolvedModel(resumed);
@@ -124,6 +140,7 @@ export class CodexAppServerAdapter {
                     ...(this.sandbox ? { sandbox: this.sandbox } : {}),
                     ...this.configPayload(),
                     approvalPolicy: this.resolveApprovalPolicy(),
+                    ...(this.dynamicTools.length ? { dynamicTools: this.dynamicTools } : {}),
                     experimentalRawEvents: false,
                     persistExtendedHistory: true,
                 });
@@ -349,16 +366,18 @@ export class CodexAppServerAdapter {
         }
     }
     handleNotification(method, params) {
-        if (method === 'turn/started') {
-            this.currentTurnId = readString(params.turn, 'id') ?? this.currentTurnId;
-            this.currentOnEvent?.({ type: 'turn.started' });
-            return;
-        }
         if (method === 'skills/changed') {
             this.skillsCache = null;
             this.currentOnEvent?.({ type: 'skills.changed' });
             return;
         }
+        if (!this.isCurrentThreadNotification(params))
+            return;
+        if (method === 'turn/started') {
+            this.currentTurnId = readString(params.turn, 'id') ?? this.currentTurnId;
+            this.currentOnEvent?.({ type: 'turn.started' });
+            return;
+        }
         if (method === 'thread/status/changed') {
             const status = params.status;
             if (status?.type === 'active' && Array.isArray(status.activeFlags)) {
@@ -467,6 +486,15 @@ export class CodexAppServerAdapter {
             this.currentErrorText = stringifyPreview(params);
         }
     }
+    isCurrentThreadNotification(params) {
+        const threadId = readNotificationThreadId(params);
+        if (threadId && this.threadId && threadId !== this.threadId)
+            return false;
+        const turnId = readNotificationTurnId(params);
+        if (turnId && this.currentTurnId && turnId !== this.currentTurnId)
+            return false;
+        return true;
+    }
     resolveCurrentTurn() {
         const result = {
             threadId: this.threadId,
@@ -529,6 +557,18 @@ function readRawString(record, key) {
     const value = record?.[key];
     return typeof value === 'string' ? value : undefined;
 }
+function readNotificationThreadId(params) {
+    return readString(params, 'threadId')
+        ?? readString(params.thread, 'id')
+        ?? readString(params.turn, 'threadId')
+        ?? readString(params.item, 'threadId')
+        ?? readString(params.status, 'threadId');
+}
+function readNotificationTurnId(params) {
+    return readString(params, 'turnId')
+        ?? readString(params.turn, 'id')
+        ?? readString(params.item, 'turnId');
+}
 function readNullableString(record, key) {
     const value = record?.[key];
     return typeof value === 'string' && value.trim() ? value.trim() : undefined;

package/dist/codex-app-tools.d.ts

@@ -0,0 +1,42 @@
+type JsonRecord = Record<string, unknown>;
+interface DynamicToolSpec {
+    [key: string]: unknown;
+    namespace: 'codex_app';
+    name: string;
+    description: string;
+    inputSchema: JsonRecord;
+    deferLoading?: boolean;
+}
+export interface CodexAppToolAdapter {
+    requestAppServer(method: string, params: unknown): Promise<unknown>;
+}
+export interface CodexAppToolWorkspace {
+    id: string;
+    label: string;
+    cwd: string;
+}
+export interface CodexAppToolRuntime {
+    adapter: CodexAppToolAdapter;
+    currentThreadId: string | null;
+    currentCwd: string;
+    workspaces: ReadonlyArray<CodexAppToolWorkspace>;
+    model?: string | null;
+    effort?: string | null;
+}
+export interface CodexAppToolCallParams {
+    arguments?: unknown;
+    namespace?: unknown;
+    tool?: unknown;
+}
+type DynamicToolCallResponse = {
+    success: boolean;
+    contentItems: Array<{
+        type: 'inputText';
+        text: string;
+    }>;
+};
+export declare const CODEX_APP_DYNAMIC_TOOLS: ReadonlyArray<DynamicToolSpec>;
+export declare function isCodexAppToolCall(params: Record<string, unknown>): boolean;
+export declare function deniedCodexAppToolResult(reason: string): DynamicToolCallResponse;
+export declare function handleCodexAppToolCall(runtime: CodexAppToolRuntime, params: CodexAppToolCallParams): Promise<DynamicToolCallResponse>;
+export {};

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

@@ -5,8 +5,9 @@
  * codex host characterization profile (the "codex host profile" describe
  * block in core's control-poller.test.ts is the contract):
  *
- * - Keys: `session` + `signal` (never `primitive`), read sequentially per
- *   conversation, conversations polled one at a time.
+ * - 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
@@ -15,7 +16,7 @@
  * - Dedupe is primed eagerly via `poller.baseline([conversationId])` at
  *   session creation — the second legacy poll site.
  */
-import { ControlChannelPoller, type ControlChannelRTDB, type ControlHandlerResult, type ControlPollerError, type ControlSessionEvent, type ControlSignalEvent } from '@canonmsg/core';
+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;
@@ -38,6 +39,12 @@ export interface CodexControlChannelInput {
      * 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;

package/dist/control-channel.js

@@ -5,8 +5,9 @@
  * codex host characterization profile (the "codex host profile" describe
  * block in core's control-poller.test.ts is the contract):
  *
- * - Keys: `session` + `signal` (never `primitive`), read sequentially per
- *   conversation, conversations polled one at a time.
+ * - 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
@@ -41,6 +42,13 @@ export function createCodexControlPoller(input) {
             signal: {
                 handle: input.onSignal,
             },
+            ...(input.onPrimitive
+                ? {
+                    primitive: {
+                        handle: input.onPrimitive,
+                    },
+                }
+                : {}),
         },
         ...(input.onError ? { onError: input.onError } : {}),
         ...(input.random ? { random: input.random } : {}),

package/dist/host.d.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { type CanonRuntimeCommandDescriptor, type ExecutionEnvironmentMode } from '@canonmsg/core';
+import { type CanonRuntimeCommandDescriptor, type CanonRuntimeDescriptor, type CanonRuntimePresentationPolicy, type ExecutionEnvironmentMode, type WorkspaceOption, type CanonWorkspaceRootMetadata } from '@canonmsg/core';
 import { type CodexSkillMetadata } from './app-server-adapter.js';
 interface HostSessionState {
     lastError?: string;
@@ -51,5 +51,24 @@ export declare const CODEX_EFFORT_OPTIONS: readonly [{
 }];
 export declare const CODEX_SESSION_CONFIG_FIELDS: readonly ["permissionMode", "effort"];
 export declare function buildCodexSkillCommands(skills: ReadonlyArray<CodexSkillMetadata>): CanonRuntimeCommandDescriptor[];
+export declare function buildCodexRuntimeDescriptor(input: {
+    models: Array<{
+        value: string;
+        label: string;
+    }>;
+    workspaces: WorkspaceOption[];
+    workspaceRoots?: CanonWorkspaceRootMetadata[];
+    executionModes: ExecutionEnvironmentMode[];
+    permissionModes: Array<{
+        value: string;
+        label: string;
+    }>;
+    defaultPermissionMode?: string;
+    presentation?: CanonRuntimePresentationPolicy;
+    supportsPlanMode: boolean;
+    supportsCompact?: boolean;
+    supportsRichCards?: boolean;
+    skills?: ReadonlyArray<CodexSkillMetadata>;
+}): CanonRuntimeDescriptor;
 export declare function main(): Promise<void>;
 export {};

package/dist/host.js

@@ -10,6 +10,7 @@ import { RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_
 import { decideAutoReply, } from './inbound-policy.js';
 import { CodexConversationAdapter, } from './adapter.js';
 import { CodexAppServerAdapter } from './app-server-adapter.js';
+import { CODEX_APP_DYNAMIC_TOOLS, deniedCodexAppToolResult, handleCodexAppToolCall, isCodexAppToolCall, } from './codex-app-tools.js';
 import { mapCanonApprovalResultToCodexDecision, mapCodexAppServerApprovalRequest, } from './app-server-approval.js';
 import { clearStoredThreadId, buildCodexThreadPolicyFingerprint, loadStoredThreadId, saveStoredThreadId, } from './session-store.js';
 import { deriveCodexPermissionEnvelope, mapCanonPermissionToCodex, } from './permission-mode.js';
@@ -126,7 +127,7 @@ export function buildCodexSkillCommands(skills) {
         };
     });
 }
-function buildCodexRuntimeDescriptor(input) {
+export function buildCodexRuntimeDescriptor(input) {
     const commands = [
         {
             id: 'runtime-status',
@@ -146,6 +147,20 @@ function buildCodexRuntimeDescriptor(input) {
         RUNTIME_STOP_ACTION,
         RUNTIME_STOP_AND_DROP_ACTION,
     ];
+    if (input.supportsCompact) {
+        commands.push({
+            id: 'codex-compact-context',
+            label: 'Compact',
+            description: 'Ask Codex to compact the current thread context.',
+            primitive: 'context.compact',
+            aliases: ['compact'],
+            category: 'session',
+            placements: ['composer_slash', 'command_palette'],
+            availability: ['idle'],
+            ownerOnly: true,
+            dispatch: { kind: 'primitive', primitive: 'context.compact' },
+        });
+    }
     const skillCommands = input.skills?.length ? buildCodexSkillCommands(input.skills) : [];
     if (skillCommands.length) {
         commands.push(...skillCommands);
@@ -835,6 +850,7 @@ export async function main() {
             session.currentTurnId = null;
             session.currentTurnOpenedAt = null;
             session.currentTurnUpdatedAt = null;
+            session.currentTurnCanUseCodexAppTools = false;
             session.lastAcceptedIntent = null;
             session.resetRequested = false;
         }
@@ -909,6 +925,7 @@ export async function main() {
                         configOverrides: args.config ?? [],
                         fullAuto: policy.fullAuto,
                         bypassApprovalsAndSandbox: policy.bypassApprovalsAndSandbox,
+                        dynamicTools: CODEX_APP_DYNAMIC_TOOLS,
                     })
                     : new CodexConversationAdapter({
                         cwd: sessionCwd,
@@ -941,6 +958,7 @@ export async function main() {
                     currentTurnId: null,
                     currentTurnOpenedAt: null,
                     currentTurnUpdatedAt: null,
+                    currentTurnCanUseCodexAppTools: false,
                     activeSelfContextId: null,
                     lastAcceptedIntent: null,
                     resetRequested: false,
@@ -971,7 +989,7 @@ export async function main() {
             pendingSessionCreations.delete(conversationId);
         }
     }
-    function enqueuePrompt(session, prompt, intent = 'queue', toFront = false, sourceMessageId, markAccepted = false, imagePaths = [], mediaAddDirs = [], planMode = false, artifactRoutingMode = 'disabled') {
+    function enqueuePrompt(session, prompt, intent = 'queue', toFront = false, sourceMessageId, markAccepted = false, imagePaths = [], mediaAddDirs = [], planMode = false, artifactRoutingMode = 'disabled', canUseCodexAppTools = false) {
         const nextPrompt = {
             prompt,
             intent,
@@ -981,6 +999,7 @@ export async function main() {
             mediaAddDirs,
             planMode,
             artifactRoutingMode,
+            canUseCodexAppTools,
         };
         if (toFront) {
             session.queue.unshift(nextPrompt);
@@ -1084,6 +1103,22 @@ export async function main() {
         const requestId = String(request.id);
         const params = request.params;
         const expiresAt = Date.now() + 30 * 60_000;
+        if (request.method === 'item/tool/call' && isCodexAppToolCall(params)) {
+            if (!(session.adapter instanceof CodexAppServerAdapter)) {
+                return deniedCodexAppToolResult('codex_app tools require the Codex app-server transport.');
+            }
+            if (!session.currentTurnCanUseCodexAppTools) {
+                return deniedCodexAppToolResult('Only the Canon owner can use codex_app tools.');
+            }
+            return await handleCodexAppToolCall({
+                adapter: session.adapter,
+                currentThreadId: session.adapter.getThreadId(),
+                currentCwd: session.cwd,
+                workspaces: workspaceOptions,
+                model: session.state.model ?? null,
+                effort: session.state.effort ?? null,
+            }, params);
+        }
         const runtimeCardPayload = runtimeCardRequestPayload(request.method, params);
         if (runtimeCardPayload) {
             const card = parseRuntimeCardV1(runtimeCardPayload);
@@ -1273,7 +1308,7 @@ export async function main() {
                 : decision === 'reject'
                     ? `The plan was declined — keep planning and wait for guidance before implementing.${feedback ? `\n\nNotes:\n${feedback}` : ''}`
                     : `Please revise the plan.${feedback ? `\n\nRevision feedback:\n${feedback}` : ''}`;
-            enqueuePrompt(session, prompt, 'queue', false, input.message.id, false, [], [], decision !== 'approve');
+            enqueuePrompt(session, prompt, 'queue', false, input.message.id, false, [], [], decision !== 'approve', 'disabled', input.isOwner);
             return;
         }
         let materialized = [];
@@ -1370,7 +1405,7 @@ export async function main() {
         });
         if (session.running && deliveryIntent === 'interrupt') {
             const artifactRoutingMode = resolveArtifactRoutingMode(participantContext);
-            enqueuePrompt(session, prompt, deliveryIntent, true, input.message.id, shouldMarkAccepted, imagePaths, mediaAddDirs, planCommand.planMode, artifactRoutingMode);
+            enqueuePrompt(session, prompt, deliveryIntent, true, input.message.id, shouldMarkAccepted, imagePaths, mediaAddDirs, planCommand.planMode, artifactRoutingMode, participantContext.isOwner);
             console.error(`[canon-codex] [${input.conversationId.slice(0, 8)}] Interrupting current turn for explicit human send-now`);
             await session.adapter.interrupt().catch(() => { });
             clearStreaming(input.conversationId);
@@ -1378,7 +1413,7 @@ export async function main() {
             return;
         }
         const artifactRoutingMode = resolveArtifactRoutingMode(participantContext);
-        enqueuePrompt(session, prompt, deliveryIntent, false, input.message.id, shouldMarkAccepted, imagePaths, mediaAddDirs, planCommand.planMode, artifactRoutingMode);
+        enqueuePrompt(session, prompt, deliveryIntent, false, input.message.id, shouldMarkAccepted, imagePaths, mediaAddDirs, planCommand.planMode, artifactRoutingMode, participantContext.isOwner);
     }
     function sendTurnArtifactFile(session, file) {
         return sendMediaFileMessage(client, session.conversationId, file.path, '', {
@@ -1436,6 +1471,7 @@ export async function main() {
         session.turnCommandBlocks = createCommandBlockTracker();
         session.currentTurnOpenedAt = Date.now();
         session.currentTurnUpdatedAt = session.currentTurnOpenedAt;
+        session.currentTurnCanUseCodexAppTools = nextTurn.canUseCodexAppTools === true;
         session.lastAcceptedIntent = nextTurn.intent;
         session.turnState = 'thinking';
         session.lastActivity = Date.now();
@@ -1701,6 +1737,7 @@ export async function main() {
             session.currentTurnId = null;
             session.currentTurnOpenedAt = null;
             session.currentTurnUpdatedAt = null;
+            session.currentTurnCanUseCodexAppTools = false;
             session.lastAcceptedIntent = null;
             session.resetRequested = false;
             session.lastActivity = Date.now();
@@ -1742,6 +1779,7 @@ export async function main() {
             defaultPermissionMode: codexPermissionEnvelope.defaultPermissionMode,
             presentation: runtimePresentation,
             supportsPlanMode: useAppServer,
+            supportsCompact: useAppServer,
             supportsRichCards: useAppServer,
             skills: codexSkills,
         }),
@@ -1838,6 +1876,34 @@ export async function main() {
         clearStreaming(conversationId);
         typingSignals.clear(conversationId).catch(() => { });
     }
+    async function handleControlPrimitive(event) {
+        const { conversationId, value } = event;
+        const primitiveId = typeof value.id === 'string' ? value.id : '';
+        if (primitiveId !== 'context.compact') {
+            console.error(`[canon-codex] [${conversationId.slice(0, 8)}] Ignoring unsupported primitive (${primitiveId || 'unknown'})`);
+            return;
+        }
+        const session = sessions.get(conversationId);
+        if (!session || session.closed) {
+            console.error(`[canon-codex] [${conversationId.slice(0, 8)}] Cannot compact context: no live Codex session`);
+            return;
+        }
+        if (!(session.adapter instanceof CodexAppServerAdapter)) {
+            console.error(`[canon-codex] [${conversationId.slice(0, 8)}] Cannot compact context: compact is only available for Codex app-server sessions`);
+            return;
+        }
+        try {
+            await session.adapter.compactThread();
+            console.error(`[canon-codex] [${conversationId.slice(0, 8)}] Compact requested`);
+            writeState(session);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            session.state.lastError = `Could not compact Codex context: ${message}`;
+            console.error(`[canon-codex] [${conversationId.slice(0, 8)}] ${session.state.lastError}`);
+            writeState(session);
+        }
+    }
     const controlPoller = createCodexControlPoller({
         rtdb,
         agentId,
@@ -1848,6 +1914,7 @@ export async function main() {
             applySessionControl(conversationId, control);
         },
         onSignal: handleControlSignal,
+        onPrimitive: handleControlPrimitive,
         onError: (error) => {
             // The legacy loop ignored transient RTDB failures; keep read/consume
             // errors quiet but surface handler failures.

package/dist/session-store.js

@@ -17,7 +17,7 @@ function saveStore(store) {
 }
 export function buildCodexThreadPolicyFingerprint(input) {
     return createHash('sha256').update(JSON.stringify({
-        version: 1,
+        version: 2,
         baseCwd: input.baseCwd,
         executionMode: input.executionMode ?? null,
         permissionMode: input.permissionMode ?? null,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/codex-plugin",
-  "version": "0.18.10",
+  "version": "0.18.12",
   "description": "Canon host integration for Codex CLI",
   "type": "module",
   "main": "dist/index.js",
@@ -29,9 +29,9 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@canonmsg/agent-sdk": "^3.4.1",
+    "@canonmsg/agent-sdk": "^3.4.2",
     "@canonmsg/coding-agent-host": "^0.2.2",
-    "@canonmsg/core": "^2.9.2"
+    "@canonmsg/core": "^3.0.0"
   },
   "engines": {
     "node": ">=18.0.0"