@canonmsg/codex-plugin 0.29.4 → 0.30.1

package/dist/host.js

@@ -18,11 +18,16 @@ import { detectCodexCliVersion } from './codex-cli-version.js';
 import { buildCodexModelGuardMessage, formatCodexTurnFailure, isRecoverableCodexThreadError, } from './error-format.js';
 import { startCodexStreamInBackground } from './host-lifecycle.js';
 import { createCodexControlPoller } from './control-channel.js';
-import { runCli } from '@canonmsg/core';
+import { runCli, acquireLock } from '@canonmsg/core';
+import { runCodexWorkSessionHost } from './work-session-cli.js';
+import { CODEX_WORK_SESSION_HELP, codexAccountLockKey, isSharedWorkSessionCommand } from './work-session-options.js';
 import { applyTextSegmentBlock, beginCommandBlock, buildCodexFinalTurnTrail, claimCommandBlock, createCommandBlockTracker, } from './turn-activity.js';
 import { FALLBACK_CODEX_EFFORT_OPTIONS, buildCodexEffortOptions, buildCodexModelOptions, readCodexConfiguredEffort, resolveCodexDefaultModel, resolveCodexEffortForModel, } from './model-catalog.js';
+let managedAccountLock;
 const HELP = `canon-codex — run a local Codex agent host for Canon
 
+${CODEX_WORK_SESSION_HELP}
+
 USAGE
   canon-codex [flags]
 
@@ -601,6 +606,10 @@ export function shouldRouteCodexTurnArtifacts(input) {
 }
 export async function main() {
     setDefaultResultOrder('ipv4first');
+    if (isSharedWorkSessionCommand(process.argv.slice(2))) {
+        await runCodexWorkSessionHost(process.argv.slice(2));
+        return;
+    }
     const { values: args } = parseArgs({
         options: {
             cwd: { type: 'string' },
@@ -704,6 +713,9 @@ export async function main() {
         }
         console.error(`[canon-codex] Authenticated as ${agentId}`);
     }
+    // One local owner across managed, standalone attach and multi-room shared modes,
+    // including profile aliases and directly supplied credentials for this account.
+    managedAccountLock = acquireLock(codexAccountLockKey({ environmentId: resolvedAgent.environmentId, agentId }));
     let codexDynamicTools = filterCodexCommunicationTools(baseCodexDynamicTools, outboundPolicy);
     // Shared poll/timeout engine. Built-in `input`/`card` descriptors own
     // create+poll (codex passes native/responder policy via payload/options).
@@ -2820,6 +2832,7 @@ export async function main() {
             closeSession(session.conversationId);
         }
         markLocalRuntimeStopped(runtimeId);
+        managedAccountLock?.release();
         (lockHandle ?? getActiveProfileLock())?.release();
         process.exit(0);
     };
@@ -2832,6 +2845,7 @@ export async function main() {
 runCli(import.meta.url, main, (error) => {
     const message = error instanceof Error ? error.message : String(error);
     console.error(`[canon-codex] ${message}`);
+    managedAccountLock?.release();
     getActiveProfileLock()?.release();
     process.exit(1);
 }, {

package/dist/index.d.ts

@@ -1,5 +1,10 @@
 export { main as hostMain } from './host.js';
 export { main as registerMain } from './register.js';
 export { main as setupMain } from './setup.js';
+export { main as attachMain } from './attach.js';
+export { CodexAttachedSessionAdapter, listLoadedCodexSessions } from './attached-session-adapter.js';
+export type { CodexAttachedSessionOptions } from './attached-session-adapter.js';
+export { CodexWorkSessionProvider } from './work-session-provider.js';
+export type { CodexWorkSessionProviderOptions } from './work-session-provider.js';
 export { extractCodexApprovalDiff, mapCanonApprovalResultToCodexDecision, mapCodexAppServerApprovalRequest, } from './app-server-approval.js';
 export type { CanonCodexApprovalRequest, CodexAppServerApprovalMethod, CodexApprovalDecision, CodexNativeApprovalRequest, } from './app-server-approval.js';

package/dist/index.js

@@ -1,4 +1,7 @@
 export { main as hostMain } from './host.js';
 export { main as registerMain } from './register.js';
 export { main as setupMain } from './setup.js';
+export { main as attachMain } from './attach.js';
+export { CodexAttachedSessionAdapter, listLoadedCodexSessions } from './attached-session-adapter.js';
+export { CodexWorkSessionProvider } from './work-session-provider.js';
 export { extractCodexApprovalDiff, mapCanonApprovalResultToCodexDecision, mapCodexAppServerApprovalRequest, } from './app-server-approval.js';

package/dist/setup.js

@@ -37,6 +37,11 @@ export function main() {
     console.log('     A git repo is not required; any readable directory works.');
     console.log('     Use --workspace-root to let Canon offer discovered projects inside an approved root.');
     console.log('');
+    console.log('  To share an existing native CLI thread instead, see:');
+    console.log('     canon-codex-attach --help');
+    console.log('     This experimental mode requires an explicitly shared local app-server.');
+    console.log('     Private Codex Desktop servers cannot currently be attached.');
+    console.log('');
     console.log('Optional flags:');
     console.log('  --model gpt-5.4');
     console.log('  --sandbox workspace-write');

package/dist/work-session-cli.d.ts

@@ -0,0 +1,2 @@
+/** Opt-in shared native runtime; never starts or takes ownership of the native server. */
+export declare function runCodexWorkSessionHost(argv: string[]): Promise<void>;

package/dist/work-session-cli.js

@@ -0,0 +1,75 @@
+import { CANON_DIR, CanonClient, acquireLock, createFileAttachedSessionStore, resolveCanonAgent, resolveCanonProfile, verifyResolvedAgentEnvironment, } from '@canonmsg/core';
+import { createCanonWorkSessionHost, createFileWorkSessionHostStore } from '@canonmsg/agent-sdk';
+import { attachedSessionStatePath } from './attach-options.js';
+import { CodexWorkSessionProvider } from './work-session-provider.js';
+import { codexAccountLockKey, codexNativeSessionLockKey, parseCodexWorkSessionOptions, resolveWorkSessionInstallation, } from './work-session-options.js';
+/** Opt-in shared native runtime; never starts or takes ownership of the native server. */
+export async function runCodexWorkSessionHost(argv) {
+    const options = parseCodexWorkSessionOptions(argv);
+    const resolution = { logPrefix: '[canon-codex]', expectedClientType: 'codex', lock: true };
+    const profile = options.profile ? resolveCanonProfile(options.profile, resolution) : resolveCanonAgent(resolution);
+    let accountLock;
+    let provider;
+    let host;
+    let stopping = false;
+    let resolveShutdown = () => { };
+    const shutdown = new Promise((resolve) => { resolveShutdown = resolve; });
+    const stop = () => {
+        stopping = true;
+        void host?.stop().catch((error) => console.error('[canon-codex]', error));
+        resolveShutdown();
+    };
+    process.once('SIGINT', stop);
+    process.once('SIGTERM', stop);
+    process.once('SIGHUP', stop);
+    try {
+        await verifyResolvedAgentEnvironment(profile);
+        const agentId = profile.agentId ?? (await new CanonClient(profile.apiKey, profile.baseUrl).getAuthToken()).agentId;
+        accountLock = acquireLock(codexAccountLockKey({ environmentId: profile.environmentId, agentId }));
+        const installation = resolveWorkSessionInstallation(CANON_DIR, { environmentId: profile.environmentId, agentId });
+        provider = new CodexWorkSessionProvider({ ...options,
+            onError: (error) => console.error('[canon-codex] Native server:', error.message),
+        });
+        host = createCanonWorkSessionHost({ connection: { ...profile, agentId },
+            hostId: installation.hostId, displayName: profile.agentName ?? 'Codex work sessions', provider,
+            store: createFileWorkSessionHostStore(installation.journalPath),
+            createSessionStore: (binding) => createFileAttachedSessionStore(attachedSessionStatePath(CANON_DIR, binding)),
+            acquireNativeSession: (binding) => {
+                const lock = acquireLock(codexNativeSessionLockKey(binding.nativeSessionId));
+                return () => lock.release();
+            },
+            onStatus: (event) => {
+                if (event.status === 'available')
+                    console.error('[canon-codex] Ready. In Canon choose Start or add work session. Keep this terminal and the shared Codex server running.');
+                else if (event.status === 'stopped') {
+                    stopping = true;
+                    resolveShutdown();
+                }
+                else
+                    console.error('[canon-codex]', event.conversationId, event.session?.status);
+            },
+            onError: (error, operation) => console.error(`[canon-codex] ${operation}:`, error instanceof Error ? error.message : String(error)),
+        });
+        if (!stopping)
+            await host.start();
+        if (!stopping)
+            await shutdown;
+    }
+    finally {
+        process.removeListener('SIGINT', stop);
+        process.removeListener('SIGTERM', stop);
+        process.removeListener('SIGHUP', stop);
+        try {
+            await host?.stop();
+        }
+        finally {
+            try {
+                await provider?.close();
+            }
+            finally {
+                accountLock?.release();
+                profile.lockHandle?.release();
+            }
+        }
+    }
+}

package/dist/work-session-options.d.ts

@@ -0,0 +1,33 @@
+export declare const CODEX_WORK_SESSION_HELP = "SHARED WORK SESSIONS (experimental; Codex 0.154 or newer)\n  canon-codex --shared-server ws://127.0.0.1:4500 --cwd /path/to/project\n\n  --shared-server <url>                Explicit local WebSocket app-server\n  --profile <name>                     Canon profile (or use CANON_AGENT)\n  --cwd <path>                         Default permitted project\n  --workspace <path>                   Additional permitted project; repeatable\n  --workspace-root <path>              Discover projects under a permitted root\n  --model <id>                        Default model from native model/list\n  --reasoning-effort <id>              Default effort supported by that model\n  --default-permission-mode <mode>     readonly or workspace (default workspace)\n  --permission-mode <mode>             Allowed permission choices; repeatable\n  --default-execution-mode <mode>      locked or worktree (default worktree)\n  --execution-mode <mode>              Allowed execution choices; repeatable\n\nIn Canon choose Start or add work session. New sessions use on-request approval;\nthe account owner can answer native approvals and questions in Canon. Existing\nloaded sessions preserve their native settings. Native clients can keep using\nthe same thread. Ctrl-C stops sharing without stopping the native server.\nDesktop's private server is unsupported. Managed-host flags do not apply here.";
+export declare function isSharedWorkSessionCommand(argv: string[]): boolean;
+export declare function parseCodexWorkSessionOptions(argv: string[]): {
+    endpoint: string;
+    profile: string | undefined;
+    cwd: string;
+    workspaces: string[] | undefined;
+    workspaceRoots: string[] | undefined;
+    defaultModel: string | undefined;
+    defaultReasoningEffort: string | undefined;
+    defaultPermissionMode: "workspace" | "readonly";
+    defaultExecutionMode: "locked" | "worktree";
+    permissionModes: ("workspace" | "readonly")[] | undefined;
+    executionModes: ("locked" | "worktree")[] | undefined;
+};
+export declare function codexAccountKey(identity: {
+    environmentId: string;
+    agentId: string;
+}): string;
+/** Preserve the standalone attach key so older attachment processes also exclude a new host. */
+export declare function codexAccountLockKey(identity: {
+    environmentId: string;
+    agentId: string;
+}): string;
+export declare function codexNativeSessionLockKey(nativeSessionId: string): string;
+/** Call while owning the account lock; malformed existing state must never get a new identity. */
+export declare function resolveWorkSessionInstallation(directory: string, identity: {
+    environmentId: string;
+    agentId: string;
+}): {
+    hostId: string;
+    journalPath: string;
+};

package/dist/work-session-options.js

@@ -0,0 +1,100 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseArgs } from 'node:util';
+import { validateAttachedSessionEndpoint } from './attached-session-adapter.js';
+export const CODEX_WORK_SESSION_HELP = `SHARED WORK SESSIONS (experimental; Codex 0.154 or newer)
+  canon-codex --shared-server ws://127.0.0.1:4500 --cwd /path/to/project
+
+  --shared-server <url>                Explicit local WebSocket app-server
+  --profile <name>                     Canon profile (or use CANON_AGENT)
+  --cwd <path>                         Default permitted project
+  --workspace <path>                   Additional permitted project; repeatable
+  --workspace-root <path>              Discover projects under a permitted root
+  --model <id>                        Default model from native model/list
+  --reasoning-effort <id>              Default effort supported by that model
+  --default-permission-mode <mode>     readonly or workspace (default workspace)
+  --permission-mode <mode>             Allowed permission choices; repeatable
+  --default-execution-mode <mode>      locked or worktree (default worktree)
+  --execution-mode <mode>              Allowed execution choices; repeatable
+
+In Canon choose Start or add work session. New sessions use on-request approval;
+the account owner can answer native approvals and questions in Canon. Existing
+loaded sessions preserve their native settings. Native clients can keep using
+the same thread. Ctrl-C stops sharing without stopping the native server.
+Desktop's private server is unsupported. Managed-host flags do not apply here.`;
+export function isSharedWorkSessionCommand(argv) {
+    return argv.some((arg) => arg === '--shared-server' || arg.startsWith('--shared-server='));
+}
+export function parseCodexWorkSessionOptions(argv) {
+    const { values } = parseArgs({ args: argv, strict: true, allowPositionals: false, options: {
+            'shared-server': { type: 'string' }, profile: { type: 'string' }, cwd: { type: 'string' },
+            workspace: { type: 'string', multiple: true }, 'workspace-root': { type: 'string', multiple: true },
+            model: { type: 'string' }, 'reasoning-effort': { type: 'string' },
+            'default-permission-mode': { type: 'string' }, 'permission-mode': { type: 'string', multiple: true },
+            'default-execution-mode': { type: 'string' }, 'execution-mode': { type: 'string', multiple: true },
+        } });
+    function clean(value, label) {
+        if (value === undefined)
+            return undefined;
+        if (!value.trim() || /[\u0000-\u001f\u007f]/.test(value))
+            throw new Error(`${label} must be non-empty and contain no control characters.`);
+        return value.trim();
+    }
+    function choices(raw, allowed, label) {
+        if (!raw)
+            return undefined;
+        return [...new Set(raw.map((value) => {
+                if (!allowed.includes(value))
+                    throw new Error(`${label} must be ${allowed.join(' or ')}.`);
+                return value;
+            }))];
+    }
+    const permissionModes = choices(values['permission-mode'], ['readonly', 'workspace'], '--permission-mode');
+    const executionModes = choices(values['execution-mode'], ['locked', 'worktree'], '--execution-mode');
+    const defaultPermissionMode = choices([values['default-permission-mode'] ?? 'workspace'], ['readonly', 'workspace'], '--default-permission-mode')[0];
+    const defaultExecutionMode = choices([values['default-execution-mode'] ?? 'worktree'], ['locked', 'worktree'], '--default-execution-mode')[0];
+    if ((permissionModes && !permissionModes.includes(defaultPermissionMode)) || (executionModes && !executionModes.includes(defaultExecutionMode))) {
+        throw new Error('Default work-session policies must be included in the allowed choices.');
+    }
+    return {
+        endpoint: validateAttachedSessionEndpoint(clean(values['shared-server'], '--shared-server') ?? ''),
+        profile: clean(values.profile, '--profile'), cwd: clean(values.cwd, '--cwd') ?? process.cwd(),
+        workspaces: values.workspace?.map((value) => clean(value, '--workspace')),
+        workspaceRoots: values['workspace-root']?.map((value) => clean(value, '--workspace-root')),
+        defaultModel: clean(values.model, '--model'), defaultReasoningEffort: clean(values['reasoning-effort'], '--reasoning-effort'),
+        defaultPermissionMode, defaultExecutionMode, permissionModes, executionModes,
+    };
+}
+export function codexAccountKey(identity) {
+    return createHash('sha256').update(JSON.stringify([identity.environmentId, identity.agentId])).digest('hex');
+}
+/** Preserve the standalone attach key so older attachment processes also exclude a new host. */
+export function codexAccountLockKey(identity) {
+    return `attached-${codexAccountKey(identity)}`;
+}
+export function codexNativeSessionLockKey(nativeSessionId) {
+    return `attached-native-${createHash('sha256').update(JSON.stringify(['codex', nativeSessionId])).digest('hex')}`;
+}
+/** Call while owning the account lock; malformed existing state must never get a new identity. */
+export function resolveWorkSessionInstallation(directory, identity) {
+    const stateDirectory = join(directory, 'work-session-hosts', codexAccountKey(identity));
+    mkdirSync(stateDirectory, { recursive: true, mode: 0o700 });
+    const path = join(stateDirectory, 'installation.json');
+    let value;
+    try {
+        value = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw new Error('Work-session installation identity cannot be read; retain its state for recovery.', { cause: error });
+        value = { schema: 'canon.codex-work-session-installation.v1', ...identity, hostId: randomUUID() };
+        writeFileSync(path, JSON.stringify(value), { flag: 'wx', mode: 0o600 });
+    }
+    const saved = value;
+    if (saved?.schema !== 'canon.codex-work-session-installation.v1' || saved.environmentId !== identity.environmentId
+        || saved.agentId !== identity.agentId || typeof saved.hostId !== 'string' || !/^[a-f0-9-]{36}$/.test(saved.hostId)) {
+        throw new Error('Work-session installation identity is invalid; retain its state for recovery.');
+    }
+    return { hostId: saved.hostId, journalPath: join(stateDirectory, 'journal.json') };
+}

package/dist/work-session-provider.d.ts

@@ -0,0 +1,40 @@
+import { prepareConversationEnvironment, type NativeWorkSessionProvider, type NativeWorkSessionCreateContext, type NativeWorkSessionCreated, type NativeSessionInteractionBridge, type WorkSessionCatalog, type WorkSessionSelection } from '@canonmsg/core';
+import { CodexAttachedSessionAdapter, type CodexSharedServerOptions } from './attached-session-adapter.js';
+export interface CodexWorkSessionProviderOptions extends CodexSharedServerOptions {
+    cwd: string;
+    workspaces?: string[];
+    workspaceRoots?: string[];
+    defaultModel?: string;
+    defaultReasoningEffort?: string;
+    defaultPermissionMode?: 'readonly' | 'workspace';
+    defaultExecutionMode?: 'locked' | 'worktree';
+    /** Local policy ceiling. Never populated from a remote session request. */
+    permissionModes?: Array<'readonly' | 'workspace'>;
+    executionModes?: Array<'locked' | 'worktree'>;
+    /** Native worktrees remain on disk after the provider closes. */
+    prepareEnvironment?: typeof prepareConversationEnvironment;
+}
+/** One shared native server; all selections are resolved locally from the advertised catalog. */
+export declare class CodexWorkSessionProvider implements NativeWorkSessionProvider {
+    private readonly options;
+    private readonly connection;
+    private readonly projects;
+    private readonly permissionModes;
+    private readonly executionModes;
+    private readonly observers;
+    private readonly environments;
+    private readonly createdSettings;
+    private readonly creationAttempts;
+    private readonly creationFingerprints;
+    private closed;
+    constructor(options: CodexWorkSessionProviderOptions);
+    catalog(): Promise<WorkSessionCatalog>;
+    create(selection: Extract<WorkSessionSelection, {
+        mode: 'create';
+    }>, context: NativeWorkSessionCreateContext): Promise<NativeWorkSessionCreated>;
+    private createOnce;
+    open(nativeSessionId: string, interactionBridge?: NativeSessionInteractionBridge): Promise<CodexAttachedSessionAdapter>;
+    close(): Promise<void>;
+    private assertOpen;
+    private models;
+}

package/dist/work-session-provider.js

@@ -0,0 +1,234 @@
+import { createHash } from 'node:crypto';
+import { realpathSync } from 'node:fs';
+import { basename } from 'node:path';
+import { buildConfiguredWorkspaceOptionsWithRoots, prepareConversationEnvironment, releaseConversationEnvironment, NativeWorkSessionCreateError, } from '@canonmsg/core';
+import { CodexAttachedSessionAdapter, CodexAttachedSessionError, CodexSharedConnection, CodexSharedRpcError, listLoadedCodexSessions, } from './attached-session-adapter.js';
+import { CODEX_PERMISSION_OPTIONS, mapCanonPermissionToCodex } from './permission-mode.js';
+/** One shared native server; all selections are resolved locally from the advertised catalog. */
+export class CodexWorkSessionProvider {
+    options;
+    connection;
+    projects;
+    permissionModes;
+    executionModes;
+    observers = new Set();
+    environments = new Set();
+    createdSettings = new Map();
+    creationAttempts = new Map();
+    creationFingerprints = new Map();
+    closed = false;
+    constructor(options) {
+        this.options = options;
+        this.connection = new CodexSharedConnection(options);
+        this.projects = buildConfiguredWorkspaceOptionsWithRoots({
+            primaryCwd: options.cwd, configuredWorkspaces: options.workspaces ?? [], workspaceRoots: options.workspaceRoots ?? [],
+        }).workspaceOptions;
+        this.permissionModes = [...new Set(options.permissionModes ?? ['readonly', 'workspace'])];
+        this.executionModes = [...new Set(options.executionModes ?? ['locked', 'worktree'])];
+        if (!this.permissionModes.length || this.permissionModes.some((mode) => !['readonly', 'workspace'].includes(mode))
+            || !this.executionModes.length || this.executionModes.some((mode) => !['locked', 'worktree'].includes(mode))) {
+            throw new Error('Configure at least one supported permission and execution mode.');
+        }
+        if (!this.permissionModes.includes(options.defaultPermissionMode ?? 'workspace')
+            || !this.executionModes.includes(options.defaultExecutionMode ?? 'worktree')) {
+            throw new Error('Default work-session policy must be allowed by this provider.');
+        }
+    }
+    async catalog() {
+        this.assertOpen();
+        await this.connection.connect();
+        const models = await this.models();
+        const loaded = await listLoadedCodexSessions(this.options, this.connection);
+        const configuredModel = models.find((model) => model.id === this.options.defaultModel || model.model === this.options.defaultModel);
+        if (this.options.defaultModel && !configuredModel)
+            throw new Error('The configured default model is not available on the shared server.');
+        const defaultModel = configuredModel
+            ?? models.find((model) => model.isDefault) ?? models[0];
+        const defaultEffort = this.options.defaultReasoningEffort ?? defaultModel?.defaultEffort;
+        if (defaultEffort && !defaultModel?.efforts.some((effort) => effort.id === defaultEffort))
+            throw new Error('The configured reasoning effort is not supported by the default model.');
+        const defaults = {
+            ...(this.projects[0] ? { projectId: this.projects[0].id } : {}),
+            ...(defaultModel ? { modelId: defaultModel.id } : {}),
+            ...(defaultEffort ? { reasoningEffort: defaultEffort } : {}),
+            permissionMode: this.options.defaultPermissionMode ?? 'workspace', executionMode: this.options.defaultExecutionMode ?? 'worktree',
+        };
+        const catalog = {
+            provider: 'codex', canCreate: this.projects.length > 0 && models.length > 0, canAttach: true,
+            projects: this.projects.map(({ id, label }) => ({ id, label: catalogLabel(label, 'Project') })),
+            models: models.map((model) => ({ id: model.id, label: model.label, reasoningEfforts: model.efforts,
+                ...(model.defaultEffort ? { defaultReasoningEffort: model.defaultEffort } : {}),
+            })),
+            permissionModes: this.permissionModes.map((id) => ({ id, label: CODEX_PERMISSION_OPTIONS.find((entry) => entry.value === id).label })),
+            executionModes: this.executionModes.map((id) => ({ id, label: id === 'worktree' ? 'Git worktree' : 'Project folder' })),
+            defaults,
+            sessions: loaded.map((session) => {
+                const project = this.projects.find((project) => session.cwd && samePath(project.cwd, session.cwd));
+                const model = models.find((model) => model.model === session.model || model.id === session.model);
+                const saved = this.createdSettings.get(session.threadId);
+                return {
+                    id: session.threadId, title: catalogLabel(session.name, 'Untitled Codex session'), status: session.status ?? 'idle',
+                    settings: { ...(saved ?? {}), ...(project ? { projectId: project.id } : {}),
+                        ...(session.model ? { modelId: model?.id ?? modelChoiceId(session.model) } : {}),
+                        ...(session.reasoningEffort ? { reasoningEffort: session.reasoningEffort } : {}),
+                    },
+                    ...(session.cwd ? { projectLabel: catalogLabel(project?.label ?? basename(session.cwd), 'Project') } : {}),
+                    ...(session.model ? { modelLabel: model?.label ?? catalogLabel(session.model, 'Native model') } : {}),
+                };
+            }),
+        };
+        // A revision identifies the entire published catalog, including native
+        // activity and settings. The broker rejects different content at one revision.
+        return { revision: createHash('sha256').update(JSON.stringify(catalog)).digest('hex').slice(0, 24), ...catalog };
+    }
+    create(selection, context) {
+        const fingerprint = JSON.stringify([selection, context]);
+        const prior = this.creationAttempts.get(context.requestId);
+        if (prior)
+            return this.creationFingerprints.get(context.requestId) === fingerprint ? prior
+                : Promise.reject(new NativeWorkSessionCreateError('A work-session request ID was reused with different settings.', 'not_created'));
+        const attempt = this.createOnce(selection, context);
+        this.creationAttempts.set(context.requestId, attempt);
+        this.creationFingerprints.set(context.requestId, fingerprint);
+        return attempt;
+    }
+    async createOnce(selection, context) {
+        let nativeWritten = false;
+        try {
+            this.assertOpen();
+            if (!context.requestId || !context.conversationId || !context.agentId)
+                throw new Error('A stable work-session request context is required.');
+            if (selection.mode !== 'create' || Object.keys(selection).some((key) => !['mode', 'projectId', 'modelId', 'reasoningEffort', 'permissionMode', 'executionMode'].includes(key))) {
+                throw new Error('Unsupported native session creation settings.');
+            }
+            const project = this.projects.find((project) => project.id === selection.projectId);
+            if (!project)
+                throw new Error('The selected project is not configured on this host.');
+            const permissionMode = selection.permissionMode ?? this.options.defaultPermissionMode ?? 'workspace';
+            const executionMode = selection.executionMode ?? this.options.defaultExecutionMode ?? 'worktree';
+            if (!this.permissionModes.includes(permissionMode) || !this.executionModes.includes(executionMode)) {
+                throw new Error('The selected native permission or execution mode is not allowed.');
+            }
+            await this.connection.connect();
+            const models = await this.models();
+            const modelId = selection.modelId ?? this.options.defaultModel;
+            const model = modelId ? models.find((entry) => entry.id === modelId || entry.model === modelId)
+                : models.find((entry) => entry.isDefault) ?? models[0];
+            if (!model)
+                throw new Error('The selected model is not available on this shared server.');
+            const reasoningEffort = selection.reasoningEffort ?? this.options.defaultReasoningEffort ?? model.defaultEffort;
+            if (reasoningEffort && !model.efforts.some((effort) => effort.id === reasoningEffort))
+                throw new Error('The selected reasoning effort is not supported by this model.');
+            const environment = (this.options.prepareEnvironment ?? prepareConversationEnvironment)({
+                agentId: context.agentId, conversationId: `work-session:${context.requestId}`,
+                workspaceCwd: project.cwd, allowWorktrees: executionMode === 'worktree',
+            });
+            this.environments.add(environment);
+            if (environment.mode !== executionMode)
+                throw new Error('The requested Git worktree could not be created. Select Project folder explicitly to use the base project.');
+            this.assertOpen();
+            const policy = mapCanonPermissionToCodex(permissionMode);
+            nativeWritten = true;
+            const result = object(await this.connection.createThread({
+                cwd: environment.cwd, model: model.model, sandbox: policy.sandbox, approvalPolicy: 'on-request',
+                ephemeral: false, allowProviderModelFallback: false,
+                ...(reasoningEffort ? { config: { model_reasoning_effort: reasoningEffort } } : {}),
+            }));
+            const thread = object(result?.thread);
+            const nativeSessionId = string(thread?.id);
+            const actualModel = string(result?.model) ?? string(thread?.model);
+            const actualEffort = string(result?.reasoningEffort) ?? string(thread?.reasoningEffort);
+            const actualSandbox = string(object(result?.sandbox)?.type) ?? string(result?.sandbox);
+            const expectedSandbox = permissionMode === 'readonly' ? ['readOnly', 'read-only'] : ['workspaceWrite', 'workspace-write'];
+            if (!nativeSessionId || !actualModel || !expectedSandbox.includes(actualSandbox ?? '') || result?.approvalPolicy !== 'on-request') {
+                throw new Error('The native server returned an incomplete or unexpected creation policy; review the created session before sharing it.');
+            }
+            const actualSettings = {
+                projectId: project.id, modelId: models.find((entry) => entry.model === actualModel)?.id ?? modelChoiceId(actualModel),
+                ...(actualEffort ? { reasoningEffort: actualEffort } : {}), permissionMode, executionMode: environment.mode,
+            };
+            this.createdSettings.set(nativeSessionId, actualSettings);
+            return { nativeSessionId, settings: { ...actualSettings } };
+        }
+        catch (error) {
+            if (error instanceof NativeWorkSessionCreateError)
+                throw error;
+            const rejected = error instanceof CodexSharedRpcError && [-32600, -32601, -32602].includes(error.code ?? 0);
+            const definitelyUnwritten = error instanceof CodexAttachedSessionError && !error.submissionUncertain;
+            throw new NativeWorkSessionCreateError(error instanceof Error ? error.message : String(error), !nativeWritten || rejected || definitelyUnwritten ? 'not_created' : 'uncertain', { cause: error });
+        }
+    }
+    async open(nativeSessionId, interactionBridge) {
+        this.assertOpen();
+        const adapter = new CodexAttachedSessionAdapter({ ...this.options, threadId: nativeSessionId, sharedConnection: this.connection, interactionBridge });
+        this.observers.add(adapter);
+        return adapter;
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        await Promise.allSettled([...this.observers].map((observer) => observer.close()));
+        this.observers.clear();
+        await this.connection.close();
+        // Only advisory usage records are released. Never remove a native worktree.
+        for (const environment of this.environments)
+            releaseConversationEnvironment(environment);
+    }
+    assertOpen() { if (this.closed)
+        throw new Error('The native work-session provider is closed.'); }
+    async models() {
+        const models = [];
+        const modelIds = new Set();
+        const seen = new Set();
+        let cursor;
+        do {
+            const page = object(await this.connection.request('model/list', { limit: 100, includeHidden: false, ...(cursor ? { cursor } : {}) }));
+            if (!page || !Array.isArray(page.data))
+                throw new Error('The shared server returned an invalid model catalog.');
+            for (const raw of page.data) {
+                const entry = object(raw);
+                const id = string(entry?.id);
+                const model = string(entry?.model) ?? id;
+                if (!entry || !id || !model || entry.hidden === true)
+                    continue;
+                const choiceId = modelChoiceId(id);
+                if (modelIds.has(choiceId))
+                    continue;
+                modelIds.add(choiceId);
+                const efforts = Array.isArray(entry.supportedReasoningEfforts) ? entry.supportedReasoningEfforts.flatMap((raw) => {
+                    const value = string(object(raw)?.reasoningEffort);
+                    return value ? [{ id: value, label: value[0].toUpperCase() + value.slice(1) }] : [];
+                }) : [];
+                models.push({ id: choiceId, model, label: catalogLabel(string(entry.displayName) ?? model, 'Native model'), efforts, isDefault: entry.isDefault === true,
+                    ...(string(entry.defaultReasoningEffort) ? { defaultEffort: entry.defaultReasoningEffort } : {}),
+                });
+            }
+            if (page.nextCursor != null && !string(page.nextCursor))
+                throw new Error('The shared server returned an invalid model cursor.');
+            cursor = string(page.nextCursor);
+            if (cursor && seen.has(cursor))
+                throw new Error('The shared server repeated a model cursor.');
+            if (cursor)
+                seen.add(cursor);
+        } while (cursor);
+        return models;
+    }
+}
+function object(value) { return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : null; }
+function string(value) { return typeof value === 'string' && value.length ? value : undefined; }
+function samePath(left, right) {
+    try {
+        return realpathSync(left) === realpathSync(right);
+    }
+    catch {
+        return left === right;
+    }
+}
+function modelChoiceId(value) {
+    return /^[A-Za-z0-9_.:-]{1,160}$/.test(value) ? value
+        : `model-${createHash('sha256').update(value).digest('hex').slice(0, 32)}`;
+}
+function catalogLabel(value, fallback) {
+    return value?.replace(/[\u0000-\u001f\u007f]/g, ' ').trim().slice(0, 160) || fallback;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/codex-plugin",
-  "version": "0.29.4",
+  "version": "0.30.1",
   "description": "Canon host integration for Codex CLI",
   "type": "module",
   "main": "dist/index.js",
@@ -13,6 +13,7 @@
   },
   "bin": {
     "canon-codex": "dist/host.js",
+    "canon-codex-attach": "dist/attach.js",
     "canon-codex-register": "dist/register.js",
     "canon-codex-setup": "dist/setup.js"
   },
@@ -25,15 +26,17 @@
     "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",
+    "smoke:attach": "node scripts/smoke-attach.mjs",
     "test": "vitest run",
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@canonmsg/agent-sdk": "^10.2.1",
-    "@canonmsg/agent-tools": "^0.9.0",
-    "@canonmsg/coding-agent-host": "^0.7.0",
-    "@canonmsg/core": "^12.3.1",
-    "@canonmsg/rich-cards": "^0.10.4"
+    "@canonmsg/agent-sdk": "^10.3.0",
+    "@canonmsg/agent-tools": "^0.9.1",
+    "@canonmsg/coding-agent-host": "^0.7.1",
+    "@canonmsg/core": "^12.4.0",
+    "@canonmsg/rich-cards": "^0.10.5",
+    "ws": "^8.21.3"
   },
   "engines": {
     "node": ">=18.0.0"
@@ -45,12 +48,7 @@
     "messaging",
     "host-mode"
   ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/HeyBobChan/canon",
-    "directory": "packages/codex-plugin"
-  },
-  "homepage": "https://github.com/HeyBobChan/canon/tree/main/packages/codex-plugin",
+  "homepage": "https://canonmail.com/agents/integrations#codex",
   "publishConfig": {
     "access": "public"
   },
@@ -59,5 +57,8 @@
     "typescript": "~5.7.0",
     "vitest": "^4.1.8"
   },
-  "license": "MIT"
+  "license": "MIT",
+  "bugs": {
+    "url": "https://canonmail.com/support"
+  }
 }