@canonmsg/codex-plugin 0.29.3 → 0.30.1

package/README.md

@@ -1,6 +1,6 @@
 # Canon Plugin for Codex
 
-Connect the local Codex CLI to [Canon](https://github.com/HeyBobChan/canon) so a Canon user can message your coding agent from the app.
+Connect the local Codex CLI to [Canon](https://canonmail.com/agents) so a Canon user can message your coding agent from the app.
 
 The plugin uses the local user's existing Codex authentication by default. That means Canon follows whatever plan or login mode the user has configured in Codex itself, instead of asking for a separate Canon-side OpenAI credential.
 
@@ -46,6 +46,156 @@ Public docs: <https://canonmail.com/agents/integrations>. Coding-host concepts:
 
 You do not need a git repo for host mode. Any readable working directory is valid.
 
+## Start or add work sessions from Canon (experimental)
+
+One shared Codex server and one Canon host can serve several conversations under
+the same Canon account. In Canon, choose **Start or add work session**, then
+**New session** to choose a permitted project, model, reasoning effort, permissions,
+and execution mode, or **Existing session** to select a loaded native thread.
+The existing thread keeps its native settings. Each native thread has one Canon
+conversation audience at a time.
+
+Register the account once using the quick start above. Stop any existing
+`canon-codex` or `canon-codex-attach` process for that account, then run:
+
+```bash
+# Terminal 1: explicitly start the native shared server (Codex 0.154 or newer).
+cd /path/to/project
+codex app-server --listen ws://127.0.0.1:4500
+
+# Terminal 2: publish the permitted projects and native model catalog to Canon.
+CANON_AGENT=my-codex canon-codex \
+  --shared-server ws://127.0.0.1:4500 \
+  --cwd /path/to/project \
+  --workspace-root /path/to/approved-projects
+```
+
+The catalog is private to the account owner and contains project labels and choice
+IDs, not local paths or conversation transcripts. `--cwd`, repeated `--workspace`,
+and repeated `--workspace-root` define projects that Canon may use for creation.
+Choose **Project folder** for a non-Git project; the default **Git worktree** option
+requires successful isolation and fails if the worktree cannot be created.
+Detachment never deletes a native worktree.
+
+New sessions default to **Workspace write** with Codex's `on-request` approval
+policy. Command/file/permission approvals and supported questions are mirrored to
+the account owner in Canon, so the first Canon turn works before a native UI is
+open. A native client can answer the same request first; that cancels its Canon
+mirror. Unsupported native requests require attention in a native client.
+This mode does not enable unrestricted execution or install Canon dynamic tools.
+
+Local policy can narrow the choices. For example, a host that only offers read-only
+access in the selected project folders can use:
+
+```bash
+CANON_AGENT=my-codex canon-codex \
+  --shared-server ws://127.0.0.1:4500 --cwd /path/to/project \
+  --permission-mode readonly --default-permission-mode readonly \
+  --execution-mode locked --default-execution-mode locked
+```
+
+Use `--model` and `--reasoning-effort` for defaults supported by the native model
+catalog. Existing loaded sessions may use settings outside the creation choices;
+adding them never changes those settings. Managed-host options such as `--config`,
+`--full-auto`, and bypass flags are rejected in shared-server mode.
+
+Keep using the same session from the native CLI:
+
+```bash
+# Discover exact loaded thread IDs without contacting Canon.
+canon-codex-attach --list --server ws://127.0.0.1:4500
+
+# Continue the chosen thread in the native UI.
+codex resume --remote ws://127.0.0.1:4500 <native-thread-id>
+```
+
+A newly created empty thread must receive its first real Canon message before a
+second native client can resume it. The host retains the creating connection for
+that input; it does not inject a warmup turn. To add a pre-existing saved thread,
+resume it in the native CLI on this shared server first, then select it in Canon.
+The current Codex Desktop app's private server remains unsupported.
+
+Sharing includes new completed local user and assistant text. Earlier private
+history, tool output, and reasoning are excluded. Canon input can join an active
+native turn. Responses use Canon's proactive delivery policy because a turn can
+combine input from both surfaces; rejected delivery remains visible.
+
+Ctrl-C stops the Canon host and leaves the native server and its sessions running.
+Restart the same command to recover using the installation identity and journal
+under `~/.canon/work-session-hosts`, plus per-conversation delivery state under
+`~/.canon/attached-sessions`. Retain those files when recovering an interrupted or
+uncertain creation; the host does not blindly create another native session.
+Normal detachment excludes private work done while detached; crash recovery may
+deliver outstanding output from the previously shared period. Only one local
+runtime mode may own the same Canon account at once, including profile aliases.
+
+The provider contract and native interaction types live in `@canonmsg/core`.
+`@canonmsg/agent-sdk` owns the shared Canon connection, broker, room observers,
+approval routing, and durable coordination. Other runtimes can implement the same
+provider interface.
+
+## Share one native session with a command (experimental)
+
+`canon-codex-attach` makes one existing native thread available in a Canon
+conversation while you continue using it in the Codex CLI. It uses the same Canon
+account profile. Register once using the steps above and add that account to the
+intended conversation before attaching.
+
+Use Codex **0.154 or newer**, with app-server WebSocket transport and CLI `--remote`
+support. Older servers reconstruct message IDs differently between live events
+and history and are rejected before attachment:
+
+```bash
+# Keep a shared server running in the project's directory.
+cd /path/to/project
+codex app-server --listen ws://127.0.0.1:4500
+
+# In another terminal, use the native Codex CLI through that server.
+codex --remote ws://127.0.0.1:4500
+
+# Find its exact thread ID (metadata only; does not contact Canon).
+canon-codex-attach --list --server ws://127.0.0.1:4500
+
+# In another terminal, attach the exact loaded thread to its Canon audience.
+canon-codex-attach \
+  --profile my-codex \
+  --conversation <canon-conversation-id> \
+  --thread <native-thread-id> \
+  --server ws://127.0.0.1:4500
+```
+
+To continue a known thread through the shared server, use
+`codex resume --remote ws://127.0.0.1:4500 <native-thread-id>` before attaching.
+The attach command refuses a thread that is not already loaded on that server.
+It never starts a replacement or modifies the native workspace, model, or
+permission policy. Keep a native UI connected to handle approvals and questions.
+
+After attachment, completed local user and assistant text is shared. Earlier
+private history, reasoning, and tool output are excluded. Local human text is
+labelled as agent-reported context. Canon text input is added to the same native
+conversation and can join an active turn, as ordinary Codex input does. Native
+output uses Canon's proactive messaging policy because one response may combine
+local and Canon input. A policy denial remains a visible delivery problem.
+
+Ctrl-C detaches Canon and leaves Codex running. Graceful detachment excludes later
+private work when sharing resumes; a lost connection instead retains recovery
+state. Saved completed output retries with stable message IDs. An uncertain input
+submission is reconciled from native history, never blindly submitted again.
+History is paginated; a single native item over 8 MiB still exceeds the connection
+limit and stops attachment with an error.
+
+This mode currently supports one attachment process per profile and one native
+thread per Canon conversation. It does not create separate group members for
+multiple sessions of the same account. The current Codex Desktop app's private
+server has no supported attachment endpoint; this command supports explicitly
+shared local CLI servers. Shared-server mode above supports Canon-created sessions
+and multiple room attachments. The existing `canon-codex` managed host retains
+its queued turns, dynamic tools, and richer runtime controls.
+
+The reusable controller, journal, and adapter contract live in `@canonmsg/core`;
+`@canonmsg/agent-sdk` exports the Canon connection and publishing composition.
+Other runtimes can implement that contract without depending on this package.
+
 ## What the host supports
 
 - Canon messages routed into Codex turns

package/dist/adapter.d.ts

@@ -45,6 +45,8 @@ export interface CodexServerRequest {
     params: Record<string, unknown>;
 }
 export interface CodexRunTurnOptions {
+    /** Original human text, before Canon adds conversation/reply context. */
+    skillInvocationText?: string;
     planMode?: boolean;
     onServerRequest?: (request: CodexServerRequest) => Promise<unknown>;
 }

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

@@ -36,6 +36,7 @@ export declare class CodexAppServerAdapter {
     private threadId;
     private loadedThreadId;
     private resolvedModel;
+    private observedSettings;
     private resolvedReasoningEffort;
     private currentTurnId;
     private requestSeq;
@@ -67,6 +68,10 @@ export declare class CodexAppServerAdapter {
     });
     getThreadId(): string | null;
     getResolvedModel(): string | null;
+    getObservedSettings(): Readonly<{
+        model?: string;
+        effort?: string;
+    }>;
     getResolvedReasoningEffort(): string | null;
     clearThreadId(): void;
     setModel(model: string | null): void;

package/dist/app-server-adapter.js

@@ -17,6 +17,8 @@ export class CodexAppServerAdapter {
     threadId;
     loadedThreadId = null;
     resolvedModel = null;
+    // Public observations never inherit requested settings or fallback defaults.
+    observedSettings = {};
     resolvedReasoningEffort;
     currentTurnId = null;
     requestSeq = 1;
@@ -53,16 +55,21 @@ export class CodexAppServerAdapter {
     getResolvedModel() {
         return this.resolvedModel ?? this.model;
     }
+    getObservedSettings() {
+        return { ...this.observedSettings };
+    }
     getResolvedReasoningEffort() {
         return this.resolvedReasoningEffort ?? this.reasoningEffort;
     }
     clearThreadId() {
+        this.observedSettings = {};
         this.threadId = null;
         this.loadedThreadId = null;
         this.resolvedModel = null;
         this.resolvedReasoningEffort = this.reasoningEffort;
     }
     setModel(model) {
+        this.observedSettings = {};
         this.model = model;
         this.resolvedModel = model;
     }
@@ -78,6 +85,7 @@ export class CodexAppServerAdapter {
         const next = effort && effort.trim() ? effort.trim() : null;
         if (next === this.reasoningEffort && next === this.resolvedReasoningEffort)
             return;
+        this.observedSettings = { model: this.observedSettings.model };
         this.reasoningEffort = next;
         this.resolvedReasoningEffort = next;
         if (this.threadId && this.loadedThreadId === this.threadId) {
@@ -110,6 +118,7 @@ export class CodexAppServerAdapter {
         return await this.sendRequest(method, params);
     }
     close() {
+        this.observedSettings = {};
         this.child?.kill('SIGTERM');
         this.child = null;
         this.initialized = false;
@@ -171,7 +180,7 @@ export class CodexAppServerAdapter {
             turnPromise.catch(() => { });
             const turnStarted = await this.sendRequest('turn/start', {
                 threadId: this.threadId,
-                input: await this.buildTurnInput(prompt, imagePaths),
+                input: await this.buildTurnInput(prompt, imagePaths, options.skillInvocationText),
                 ...(this.model ? { model: this.model } : {}),
                 ...this.sandboxPolicyPayload(_extraAddDirs),
                 collaborationMode: {
@@ -216,7 +225,9 @@ export class CodexAppServerAdapter {
     }
     rememberResolvedModel(result) {
         const thread = result.thread;
-        this.resolvedModel = readString(thread, 'model') ?? readString(result, 'model') ?? this.resolvedModel;
+        const model = readString(thread, 'model') ?? readString(result, 'model');
+        this.observedSettings = { ...this.observedSettings, model: model ?? undefined };
+        this.resolvedModel = model ?? this.resolvedModel;
     }
     sandboxPolicyPayload(extraAddDirs) {
         if (this.bypassApprovalsAndSandbox || this.sandbox === 'danger-full-access') {
@@ -290,22 +301,27 @@ export class CodexAppServerAdapter {
         } while (cursor);
         return models;
     }
-    async buildTurnInput(prompt, imagePaths) {
-        const skillPrompt = parseSkillSlashPrompt(prompt);
+    async buildTurnInput(prompt, imagePaths, skillInvocationText) {
+        const skillPrompt = parseSkillSlashPrompt(skillInvocationText ?? prompt);
         const input = [];
         if (skillPrompt) {
             const skills = await this.listSkills().catch(() => []);
             const selected = skills.find((skill) => skill.name.toLowerCase() === skillPrompt.name.toLowerCase());
             if (selected) {
                 input.push({ type: 'skill', name: selected.name, path: selected.path });
-                if (skillPrompt.prompt.trim()) {
-                    input.push({ type: 'text', text: skillPrompt.prompt, text_elements: [] });
+                // Resolve the native skill from the actual message, retaining the
+                // framed prompt as context instead of parsing quoted/history text.
+                const text = skillInvocationText === undefined ? skillPrompt.prompt : prompt;
+                if (text.trim()) {
+                    input.push({ type: 'text', text, text_elements: [] });
                 }
             }
             else {
                 input.push({
                     type: 'text',
-                    text: `$${skillPrompt.name}${skillPrompt.prompt.trim() ? ` ${skillPrompt.prompt.trim()}` : ''}`,
+                    text: skillInvocationText === undefined
+                        ? `$${skillPrompt.name}${skillPrompt.prompt.trim() ? ` ${skillPrompt.prompt.trim()}` : ''}`
+                        : prompt,
                     text_elements: [],
                 });
             }
@@ -333,6 +349,7 @@ export class CodexAppServerAdapter {
                 this.currentOnLog?.(trimmed);
         });
         child.on('close', (code) => {
+            this.observedSettings = {};
             const message = `Codex app-server exited${code === null ? '' : ` with code ${code}`}`;
             this.initialized = false;
             this.child = null;
@@ -428,6 +445,7 @@ export class CodexAppServerAdapter {
             const settings = isRecord(params.threadSettings) ? params.threadSettings : {};
             const model = readString(settings, 'model') ?? null;
             const effort = readString(settings, 'effort') ?? null;
+            this.observedSettings = { model: model ?? undefined, effort: effort ?? undefined };
             this.resolvedModel = model ?? this.resolvedModel;
             this.resolvedReasoningEffort = effort;
             this.currentOnEvent?.({ type: 'settings.updated', model, effort });
@@ -435,6 +453,7 @@ export class CodexAppServerAdapter {
         }
         if (method === 'model/rerouted') {
             const model = readString(params, 'toModel') ?? null;
+            this.observedSettings = { model: model ?? undefined };
             this.resolvedModel = model ?? this.resolvedModel;
             this.currentOnEvent?.({
                 type: 'settings.updated',

package/dist/attach-options.d.ts

@@ -0,0 +1,21 @@
+export interface CodexAttachOptions {
+    list?: false;
+    profile: string;
+    conversationId: string;
+    threadId: string;
+    serverUrl: string;
+}
+export type CodexAttachCommand = CodexAttachOptions | {
+    list: true;
+    serverUrl: string;
+};
+export declare const CODEX_ATTACH_HELP = "canon-codex-attach \u2014 share an existing native Codex thread with Canon\n\nUSAGE\n  canon-codex-attach --profile <name> --conversation <id> --thread <id> --server <url>\n  canon-codex-attach --list --server <url>\n\nREQUIRED FLAGS\n  --profile         Existing Canon Codex account profile\n  --conversation    Canon conversation this account already belongs to\n  --thread          Exact native thread ID, already loaded on the shared server\n  --server          Explicit loopback WebSocket app-server URL (experimental)\n\nOTHER FLAGS\n  --list            List exact loaded thread IDs and names without contacting Canon\n  --help, -h        Show this help\n  --version, -V     Show package version\n\nKeep using the same thread through a Codex CLI connected with --remote.\nThe shared server must be Codex 0.154 or newer, with stable native message IDs.\nNew local user and assistant text is shared; private earlier history is excluded.\nCanon input may join a turn already in progress. Shared output follows the\naccount's proactive messaging policy. Native permissions and approvals stay local.\n\nCtrl-C detaches Canon without stopping the native server. Restart with the same\narguments to reuse saved delivery state. Only one attachment process per profile\nis supported. This command cannot attach to a private Codex Desktop server.";
+export declare function parseCodexAttachOptions(argv: string[]): CodexAttachCommand;
+/** The account and audience, never a bearer credential, identify persisted state. */
+export declare function attachedSessionStatePath(directory: string, binding: {
+    environmentId: string;
+    agentId: string;
+    conversationId: string;
+    provider: string;
+    nativeSessionId: string;
+}): string;

package/dist/attach-options.js

@@ -0,0 +1,71 @@
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import { parseArgs } from 'node:util';
+export const CODEX_ATTACH_HELP = `canon-codex-attach — share an existing native Codex thread with Canon
+
+USAGE
+  canon-codex-attach --profile <name> --conversation <id> --thread <id> --server <url>
+  canon-codex-attach --list --server <url>
+
+REQUIRED FLAGS
+  --profile         Existing Canon Codex account profile
+  --conversation    Canon conversation this account already belongs to
+  --thread          Exact native thread ID, already loaded on the shared server
+  --server          Explicit loopback WebSocket app-server URL (experimental)
+
+OTHER FLAGS
+  --list            List exact loaded thread IDs and names without contacting Canon
+  --help, -h        Show this help
+  --version, -V     Show package version
+
+Keep using the same thread through a Codex CLI connected with --remote.
+The shared server must be Codex 0.154 or newer, with stable native message IDs.
+New local user and assistant text is shared; private earlier history is excluded.
+Canon input may join a turn already in progress. Shared output follows the
+account's proactive messaging policy. Native permissions and approvals stay local.
+
+Ctrl-C detaches Canon without stopping the native server. Restart with the same
+arguments to reuse saved delivery state. Only one attachment process per profile
+is supported. This command cannot attach to a private Codex Desktop server.`;
+export function parseCodexAttachOptions(argv) {
+    const { values } = parseArgs({
+        args: argv,
+        options: {
+            profile: { type: 'string' },
+            conversation: { type: 'string' },
+            thread: { type: 'string' },
+            server: { type: 'string' },
+            list: { type: 'boolean' },
+        },
+        strict: true,
+        allowPositionals: false,
+    });
+    function required(name) {
+        const raw = values[name];
+        const value = typeof raw === 'string' ? raw.trim() : '';
+        if (!value || /[\u0000-\u001f\u007f]/.test(value)) {
+            throw new Error(`--${name} must be an explicit non-empty value without control characters`);
+        }
+        return value;
+    }
+    if (values.list) {
+        if (values.profile || values.conversation || values.thread) {
+            throw new Error('--list takes only --server; omit attachment account and conversation flags');
+        }
+        return { list: true, serverUrl: required('server') };
+    }
+    return {
+        profile: required('profile'),
+        conversationId: required('conversation'),
+        threadId: required('thread'),
+        serverUrl: required('server'),
+    };
+}
+/** The account and audience, never a bearer credential, identify persisted state. */
+export function attachedSessionStatePath(directory, binding) {
+    const key = createHash('sha256').update(JSON.stringify([
+        binding.environmentId, binding.agentId, binding.conversationId,
+        binding.provider, binding.nativeSessionId,
+    ])).digest('hex');
+    return join(directory, 'attached-sessions', `${key}.json`);
+}

package/dist/attach.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function main(): Promise<void>;

package/dist/attach.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+import { CANON_DIR, acquireLock, createFileAttachedSessionStore, resolveCanonProfile, runCli, } from '@canonmsg/core';
+import { createCanonAttachedSession } from '@canonmsg/agent-sdk';
+import { CodexAttachedSessionAdapter, listLoadedCodexSessions, validateAttachedSessionEndpoint } from './attached-session-adapter.js';
+import { attachedSessionStatePath, CODEX_ATTACH_HELP, parseCodexAttachOptions, } from './attach-options.js';
+import { codexAccountLockKey, codexNativeSessionLockKey } from './work-session-options.js';
+export async function main() {
+    const args = parseCodexAttachOptions(process.argv.slice(2));
+    // Validate configuration before claiming a profile or contacting either service.
+    const endpoint = validateAttachedSessionEndpoint(args.serverUrl);
+    if (args.list) {
+        console.log(JSON.stringify(await listLoadedCodexSessions({ endpoint }), null, 2));
+        return;
+    }
+    const profile = resolveCanonProfile(args.profile, {
+        lock: true,
+        expectedClientType: 'codex',
+        logPrefix: '[canon-codex-attach]',
+    });
+    let accountLock;
+    let nativeLock;
+    let attachment;
+    let adapter;
+    let requestedStop;
+    let shutdownRequested = false;
+    let signalShutdown = () => { };
+    const shutdown = new Promise((resolve) => { signalShutdown = resolve; });
+    const requestShutdown = () => {
+        if (shutdownRequested)
+            return;
+        shutdownRequested = true;
+        requestedStop = attachment?.stop();
+        // Cleanup awaits this promise; handle rejection immediately during startup.
+        void requestedStop?.catch(() => { });
+        signalShutdown();
+    };
+    process.once('SIGINT', requestShutdown);
+    process.once('SIGTERM', requestShutdown);
+    try {
+        if (!profile.agentId)
+            throw new Error('The selected profile has no Canon agent ID.');
+        // Aliases of the same account must not create competing attached runtimes.
+        accountLock = acquireLock(codexAccountLockKey({ environmentId: profile.environmentId, agentId: profile.agentId }));
+        nativeLock = acquireLock(codexNativeSessionLockKey(args.threadId));
+        const binding = {
+            environmentId: profile.environmentId,
+            agentId: profile.agentId,
+            conversationId: args.conversationId,
+            provider: 'codex',
+            nativeSessionId: args.threadId,
+        };
+        adapter = new CodexAttachedSessionAdapter({ endpoint, threadId: args.threadId });
+        attachment = createCanonAttachedSession({
+            connection: { ...profile, agentId: profile.agentId },
+            binding,
+            native: adapter,
+            store: createFileAttachedSessionStore(attachedSessionStatePath(CANON_DIR, binding)),
+            onStatus: (status) => {
+                console.error('[canon-codex-attach]', status);
+                if (status.status === 'stopped') {
+                    shutdownRequested = true;
+                    signalShutdown();
+                }
+            },
+            onError: (error) => {
+                console.error('[canon-codex-attach]', error instanceof Error ? error.message : String(error));
+            },
+        });
+        await attachment.start();
+        if (!shutdownRequested) {
+            console.error(`[canon-codex-attach] Sharing thread ${args.threadId} with Canon conversation ${args.conversationId} as ${args.profile}.`);
+            console.error('[canon-codex-attach] Keep using this thread in Codex. Ctrl-C detaches Canon.');
+            await shutdown;
+        }
+    }
+    finally {
+        process.removeListener('SIGINT', requestShutdown);
+        process.removeListener('SIGTERM', requestShutdown);
+        try {
+            await requestedStop;
+            await attachment?.stop();
+        }
+        finally {
+            try {
+                await adapter?.close();
+            }
+            finally {
+                nativeLock?.release();
+                accountLock?.release();
+                profile.lockHandle?.release();
+            }
+        }
+    }
+}
+runCli(import.meta.url, main, (error) => {
+    console.error('[canon-codex-attach]', error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+}, {
+    name: 'canon-codex-attach',
+    help: CODEX_ATTACH_HELP,
+});

package/dist/attached-session-adapter.d.ts

@@ -0,0 +1,112 @@
+import type { AttachedNativeSessionAdapter, NativeSessionEvent, NativeSessionSnapshot, NativeSessionInteractionBridge } from '@canonmsg/core';
+type JsonObject = Record<string, unknown>;
+/** The small part of ws used here; also permits an in-memory transport in tests. */
+export interface AttachedSessionSocket {
+    readonly readyState: number;
+    on(event: string, listener: (...args: any[]) => void): this;
+    send(data: string, callback?: (error?: Error) => void): void;
+    close(code?: number, reason?: string): void;
+    terminate(): void;
+}
+export interface CodexSharedServerOptions {
+    endpoint: string;
+    requestTimeoutMs?: number;
+    onError?: (error: Error) => void;
+    createSocket?: (endpoint: string, timeoutMs: number) => AttachedSessionSocket;
+}
+export interface CodexAttachedSessionOptions extends CodexSharedServerOptions {
+    threadId: string;
+    /** Borrow a provider-owned connection; closing an observer leaves it alive. */
+    sharedConnection?: CodexSharedConnection;
+    interactionBridge?: NativeSessionInteractionBridge;
+}
+export declare class CodexAttachedSessionError extends Error {
+    readonly submissionUncertain: boolean;
+    constructor(message: string, submissionUncertain?: boolean);
+}
+export declare class CodexSharedRpcError extends Error {
+    readonly code: number | null;
+    constructor(message: string, code: number | null);
+}
+/** Explicit local endpoints only. Never discover or fall back to a private runner. */
+export declare function validateAttachedSessionEndpoint(value: string): string;
+export declare class CodexSharedConnection {
+    protected readonly options: CodexSharedServerOptions;
+    private readonly shared?;
+    private readonly endpoint;
+    private readonly timeoutMs;
+    private readonly pending;
+    private socket;
+    private connecting;
+    private rejectOpen;
+    private sequence;
+    private closed;
+    private fault;
+    private readonly observers;
+    private readonly createdThreads;
+    private readonly pendingNativeRequests;
+    constructor(options: CodexSharedServerOptions, shared?: CodexSharedConnection | undefined);
+    connect(): Promise<void>;
+    close(): Promise<void>;
+    private open;
+    assertAvailable(): void;
+    request(method: string, params: unknown, submission?: boolean): Promise<unknown>;
+    createThread(params: JsonObject): Promise<unknown>;
+    hasCreatedThread(threadId: string): boolean;
+    isPristineCreatedThread(threadId: string): boolean;
+    protected respond(id: string | number, result: unknown): void;
+    protected replayPendingRequests(threadId: string): void;
+    private write;
+    private handleMessage;
+    protected onNotification(_method: string, _params: JsonObject): void;
+    protected onServerRequest(_id: string | number, _method: string, _params: JsonObject): void;
+    protected onDisconnected(_error: Error): void;
+    private rejectAll;
+    protected fail(error: Error): void;
+    protected report(error: Error): void;
+}
+export interface LoadedCodexSession {
+    threadId: string;
+    name?: string;
+    cwd?: string;
+    status?: 'idle' | 'running';
+    model?: string;
+    reasoningEffort?: string;
+}
+/** Read only live-thread metadata. No transcript, resume, or Canon credentials. */
+export declare function listLoadedCodexSessions(options: CodexSharedServerOptions, sharedConnection?: CodexSharedConnection): Promise<LoadedCodexSession[]>;
+/**
+ * Experimental second client of an explicitly shared, already-running server.
+ * It observes a native thread without owning its process, settings, or approvals.
+ */
+export declare class CodexAttachedSessionAdapter extends CodexSharedConnection implements AttachedNativeSessionAdapter {
+    private readonly threadId;
+    private readonly listeners;
+    private attachment;
+    private submitting;
+    private inspecting;
+    private readonly terminalTurns;
+    private turnOrder;
+    private historyRevision;
+    private eventRevision;
+    private readonly interactions;
+    private readonly interactionBridge?;
+    constructor(options: CodexAttachedSessionOptions);
+    subscribe(listener: (event: NativeSessionEvent) => void): Promise<void>;
+    inspect(): Promise<NativeSessionSnapshot>;
+    submit(text: string): ReturnType<AttachedNativeSessionAdapter['submit']>;
+    close(): Promise<void>;
+    private attach;
+    private ready;
+    private readThread;
+    private snapshot;
+    private readTurnManifest;
+    private readTurnItems;
+    private pages;
+    protected onNotification(method: string, params: JsonObject): void;
+    private emit;
+    protected onDisconnected(error: Error): void;
+    private abortInteractions;
+    protected onServerRequest(id: string | number, method: string, params: JsonObject): void;
+}
+export {};