@astrosheep/square 0.3.91 → 0.3.93

package/dist/packages/agent-delivery/src/codex-queue.js

@@ -0,0 +1,58 @@
+import { execFile } from 'node:child_process';
+export { codexQueueEndpoint } from './codex-endpoint.js';
+import { validSignal, validTimeout } from './deadline.js';
+/** Once the child starts, a timeout or unexplained exit does not establish non-delivery. */
+export class CodexQueueSendError extends Error {
+    kind;
+    code;
+    constructor(kind, code) {
+        super(kind === 'unknown' ? 'Codex queue outcome is unknown.' : 'Codex queue is unavailable or rejected the request.');
+        this.kind = kind;
+        this.code = code;
+        this.name = 'CodexQueueSendError';
+    }
+    get maybeDelivered() { return this.kind === 'unknown'; }
+}
+/** Internal CLI transport. Lifecycle checking belongs to the bound CLI client. */
+export async function sendCodexQueue(request, options = {}) {
+    const text = (value) => typeof value === 'string' && value.trim().length > 0 && !value.includes('\0');
+    if (!request || !text(request.threadId) || !text(request.message) || !validTimeout(options.timeoutMs) || !validSignal(options.signal) ||
+        (options.bin !== undefined && !text(options.bin)) ||
+        (options.args !== undefined && (!Array.isArray(options.args) || options.args.some((arg) => typeof arg !== 'string' || arg.includes('\0')))) ||
+        (options.endpoint !== undefined && !text(options.endpoint)))
+        throw new TypeError('Invalid Codex queue arguments.');
+    if (options.signal?.aborted)
+        throw new CodexQueueSendError('transient', 'aborted');
+    await new Promise((resolve, reject) => {
+        execFile(options.bin ?? 'codex', [...(options.args ?? []), 'queue', ...(options.endpoint === undefined ? [] : ['--remote', options.endpoint]),
+            '--thread', request.threadId, '--message', request.message], { encoding: 'utf8', env: options.env ?? process.env, timeout: options.timeoutMs ?? 5000,
+            signal: options.signal, killSignal: 'SIGKILL' }, (error, stdout, stderr) => {
+            if (!error) {
+                resolve();
+                return;
+            }
+            const code = error.code;
+            const output = `${stderr}${stdout}`;
+            if (code === 'ENOENT' || code === 'EACCES' || code === 'ENOEXEC') {
+                reject(new CodexQueueSendError('transient', 'unavailable'));
+            }
+            else if (code === 'ABORT_ERR') {
+                reject(new CodexQueueSendError('unknown', 'aborted'));
+            }
+            else if (error.killed && code == null) {
+                reject(new CodexQueueSendError('unknown', 'timeout'));
+            }
+            else if (/^Error: failed to connect (?:to socket|to remote app server)|^Error: failed to upgrade /m.test(output)) {
+                reject(new CodexQueueSendError('transient', 'unavailable'));
+            }
+            else if (/does not support thread\/queue\/add|unrecognized subcommand/.test(output)) {
+                reject(new CodexQueueSendError('rejected', 'unsupported_version'));
+            }
+            else if (/unknown thread|thread not found:|session .*not found|No active session|invalid thread id|ephemeral thread does not support queued submissions|unexpected argument/.test(output)) {
+                reject(new CodexQueueSendError('rejected', 'rejected'));
+            }
+            else
+                reject(new CodexQueueSendError('unknown', 'transport'));
+        });
+    });
+}

package/dist/packages/agent-delivery/src/codex.d.ts

@@ -0,0 +1,7 @@
+import type { CodexAppServerConnectOptions, CodexDeliveryResult, CodexSendTextOptions, CodexTarget } from './types.js';
+/** Address an existing thread on an already running app-server. Never starts a
+ * service, resumes a thread, or claims ownership of a standalone CLI session. */
+export declare function connectCodex(options: CodexAppServerConnectOptions): Promise<CodexTarget>;
+/** A UUID correlates the native user input; it is not an idempotency key. A
+ * successful RPC means admission only, not consumption or model completion. */
+export declare function sendCodexText(target: CodexTarget, text: string, options?: CodexSendTextOptions): Promise<CodexDeliveryResult>;

package/dist/packages/agent-delivery/src/codex.js

@@ -0,0 +1,332 @@
+import { randomUUID } from 'node:crypto';
+import { connect as connectSocket } from 'node:net';
+import { codexQueueEndpoint } from './codex-endpoint.js';
+import { deadline, validSignal, validTimeout } from './deadline.js';
+import { ConnectionError } from './errors.js';
+import { isIdentity, isRecord } from './guards.js';
+class Fault extends Error {
+    code;
+    constructor(code) {
+        // Never retain native messages, endpoints, credentials or input in errors.
+        super('Codex delivery failed.');
+        this.code = code;
+    }
+}
+const connections = new WeakMap();
+function resolveConnection(options) {
+    let endpoint = options.endpoint;
+    if (endpoint === undefined) {
+        try {
+            endpoint = codexQueueEndpoint(options.codexHome === undefined ? process.env : { ...process.env, CODEX_HOME: options.codexHome });
+        }
+        catch {
+            throw new ConnectionError('invalid_arguments');
+        }
+    }
+    const socketPath = endpoint.startsWith('unix://') ? endpoint.slice(7) : endpoint.startsWith('/') ? endpoint : undefined;
+    if (socketPath !== undefined) {
+        if (process.platform === 'win32')
+            throw new ConnectionError('unsupported_platform');
+        if (!socketPath.startsWith('/') || socketPath.includes('\0'))
+            throw new ConnectionError('invalid_arguments');
+        // The custom connector avoids ws+unix URL escaping/delimiter ambiguities in
+        // filesystem paths. This is still an HTTP WebSocket handshake over UDS.
+        return { url: 'ws://localhost/', socketPath, token: options.token };
+    }
+    let url;
+    try {
+        url = new URL(endpoint);
+    }
+    catch {
+        throw new ConnectionError('invalid_arguments');
+    }
+    if (!['ws:', 'wss:'].includes(url.protocol) || url.username || url.password || url.hash) {
+        throw new ConnectionError('invalid_arguments');
+    }
+    return { url: url.href, token: options.token };
+}
+/** Only documented request refusals prove non-admission. An internal server
+ * error may follow a write and must not be turned into a safe-to-retry refusal. */
+function rpcError(value, method) {
+    if (!isRecord(value) || !Number.isInteger(value.code) || typeof value.message !== 'string')
+        return new Fault('invalid_response');
+    if (value.code === -32601)
+        return new Fault('unsupported_version');
+    if (value.code === -32600 || value.code === -32602) {
+        const message = value.message.replace(/^Invalid request:\s*/i, '');
+        const variant = /^unknown variant [`'"]([^`'"]+)[`'"]/i.exec(message);
+        if (variant?.[1] === method || /^(?:unknown method\b|method not found\b)/i.test(message))
+            return new Fault('unsupported_version');
+        if (/^(?:thread not found:|thread not loaded:|no rollout found for thread id )/.test(value.message))
+            return new Fault('not_found');
+        return new Fault('refused');
+    }
+    return new Fault('transport');
+}
+/** One connection, sequential RPCs, no subscriptions, reconnection or retries. */
+class Peer {
+    socket;
+    sequence = 0;
+    failure;
+    pending;
+    opened;
+    closed;
+    rejectOpen;
+    onOpen;
+    onClose;
+    onError = () => this.fail(new Fault('transport'));
+    onUnexpectedResponse = (_request, response) => {
+        this.fail(new Fault(response.statusCode === 401 || response.statusCode === 403 ? 'authentication_failed' : 'transport'));
+        response.resume();
+        // Installing unexpected-response transfers handshake cleanup to us.
+        this.socket.terminate();
+    };
+    onMessage = (raw) => {
+        let value;
+        try {
+            value = JSON.parse(raw.toString());
+        }
+        catch {
+            this.fail(new Fault('invalid_response'));
+            return;
+        }
+        if (!isRecord(value)) {
+            this.fail(new Fault('invalid_response'));
+            return;
+        }
+        // Server notifications and requests do not acknowledge our mutation. This
+        // sender never resumes a thread or takes over its approval/tool requests.
+        if (typeof value.method === 'string' && !('result' in value) && !('error' in value))
+            return;
+        const pending = this.pending;
+        if (!pending || value.id !== pending.id || ('result' in value) === ('error' in value)) {
+            this.fail(new Fault('invalid_response'));
+            return;
+        }
+        this.pending = undefined;
+        if ('error' in value)
+            pending.reject(rpcError(value.error, pending.method));
+        else
+            pending.resolve(value.result);
+    };
+    constructor(socket) {
+        this.socket = socket;
+        this.opened = new Promise((resolve, reject) => {
+            this.rejectOpen = reject;
+            this.onOpen = resolve;
+        });
+        this.closed = new Promise((resolve) => {
+            this.onClose = () => { this.fail(new Fault('transport')); resolve(); };
+        });
+        // Opening can fail while the caller's deadline is expiring.
+        void this.opened.catch(() => { });
+        socket.on('open', this.onOpen);
+        socket.on('close', this.onClose);
+        socket.on('error', this.onError);
+        socket.on('unexpected-response', this.onUnexpectedResponse);
+        socket.on('message', this.onMessage);
+    }
+    fail(error) {
+        this.failure ??= error;
+        this.rejectOpen(this.failure);
+        this.pending?.reject(this.failure);
+        this.pending = undefined;
+    }
+    async initialize(scope) {
+        await scope.wait(this.opened);
+        const result = await this.call('initialize', {
+            clientInfo: { name: 'agent-delivery', version: '0.1.0' },
+            capabilities: { experimentalApi: true },
+        }, scope);
+        if (!isRecord(result) || !isIdentity(result.userAgent) || !isIdentity(result.codexHome) ||
+            !isIdentity(result.platformFamily) || !isIdentity(result.platformOs))
+            throw new Fault('invalid_response');
+        scope.check();
+        this.socket.send(JSON.stringify({ method: 'initialized' }));
+    }
+    call(method, params, scope, dispatch) {
+        scope.check();
+        if (this.failure)
+            throw this.failure;
+        if (this.socket.readyState !== 1)
+            throw new Fault('transport');
+        const id = ++this.sequence;
+        const body = JSON.stringify({ id, method, params });
+        const response = new Promise((resolve, reject) => {
+            this.pending = { id, method, resolve, reject };
+            // From the instant send is attempted the peer may have received bytes;
+            // callbacks and timeouts cannot prove otherwise.
+            dispatch?.();
+            try {
+                this.socket.send(body, (error) => { if (error)
+                    this.fail(new Fault('transport')); });
+            }
+            catch {
+                this.fail(new Fault('transport'));
+            }
+        });
+        return scope.wait(response);
+    }
+    async close() {
+        this.fail(new Fault('transport'));
+        // Immediate destruction, not a graceful-close timer that keeps a one-shot
+        // caller alive. Keep error handling until close, including failed handshakes.
+        this.socket.terminate();
+        await this.closed;
+        this.socket.off('open', this.onOpen);
+        this.socket.off('close', this.onClose);
+        this.socket.off('error', this.onError);
+        this.socket.off('unexpected-response', this.onUnexpectedResponse);
+        this.socket.off('message', this.onMessage);
+    }
+}
+async function open(connection, scope) {
+    scope.check();
+    const { default: Socket } = await scope.wait(import('ws'));
+    scope.check();
+    return new Peer(new Socket(connection.url, {
+        ...(connection.socketPath === undefined ? {} : { createConnection: () => connectSocket({ path: connection.socketPath }) }),
+        ...(connection.token === undefined ? {} : { headers: { Authorization: `Bearer ${connection.token}` } }),
+        followRedirects: false,
+        perMessageDeflate: false,
+    }));
+}
+async function readThread(peer, sessionId, scope, includeTurns = false) {
+    const value = await peer.call('thread/read', { threadId: sessionId, includeTurns }, scope);
+    if (!isRecord(value) || !isRecord(value.thread) || value.thread.id !== sessionId)
+        throw new Fault('invalid_response');
+    return value.thread;
+}
+function activeTurn(turns) {
+    if (!Array.isArray(turns) || turns.some((turn) => !isRecord(turn) || !isIdentity(turn.id) || typeof turn.status !== 'string' ||
+        !['inProgress', 'completed', 'interrupted', 'failed'].includes(turn.status)))
+        throw new Fault('invalid_response');
+    const active = turns.filter((turn) => turn.status === 'inProgress');
+    if (active.length > 1)
+        throw new Fault('invalid_response');
+    return active[0]?.id;
+}
+async function discoverTurn(peer, metadata, sessionId, scope) {
+    // A new idle thread can have no materialized history at all (0.160.1 returns
+    // list_turns-not-supported). Metadata already proves it cannot be steered.
+    if (isRecord(metadata.status) && ['idle', 'notLoaded'].includes(metadata.status.type))
+        return undefined;
+    // Live history includes turns that have not reached paginated storage yet.
+    // Always prefer it, irrespective of the thread's historyMode.
+    const thread = await readThread(peer, sessionId, scope, true);
+    const liveId = activeTurn(thread.turns);
+    if (liveId !== undefined || !isRecord(thread.status) || thread.status.type !== 'active')
+        return liveId;
+    // Only an active thread with no live turn needs the persisted-page fallback.
+    // Native ThreadStatus spells an in-progress thread { type: 'active', ... }.
+    const cursors = new Set();
+    let cursor;
+    for (;;) {
+        const page = await peer.call('thread/turns/list', {
+            threadId: sessionId, sortDirection: 'desc', itemsView: 'summary', limit: 100,
+            ...(cursor === undefined ? {} : { cursor }),
+        }, scope);
+        if (!isRecord(page) || !(page.nextCursor === null || isIdentity(page.nextCursor)))
+            throw new Fault('invalid_response');
+        const id = activeTurn(page.data);
+        if (id !== undefined)
+            return id;
+        if (page.nextCursor === null)
+            return undefined;
+        if (cursors.has(page.nextCursor))
+            throw new Fault('invalid_response');
+        cursor = page.nextCursor;
+        cursors.add(cursor);
+    }
+}
+/** Address an existing thread on an already running app-server. Never starts a
+ * service, resumes a thread, or claims ownership of a standalone CLI session. */
+export async function connectCodex(options) {
+    if (!isRecord(options) || options.harness !== 'codex' ||
+        (options.transport !== undefined && options.transport !== 'app-server') || !isIdentity(options.sessionId) ||
+        !validTimeout(options.timeoutMs) || !validSignal(options.signal) ||
+        (options.endpoint !== undefined && !isIdentity(options.endpoint)) ||
+        (options.codexHome !== undefined && !isIdentity(options.codexHome)) ||
+        (options.token !== undefined && (!isIdentity(options.token) || /[\r\n]/.test(options.token)))) {
+        throw new ConnectionError('invalid_arguments');
+    }
+    const connection = resolveConnection(options);
+    const scope = deadline(options.timeoutMs, options.signal);
+    let peer;
+    try {
+        peer = await open(connection, scope);
+        await peer.initialize(scope);
+        await readThread(peer, options.sessionId, scope);
+        const target = Object.freeze({ harness: 'codex', sessionId: options.sessionId });
+        connections.set(target, connection);
+        return target;
+    }
+    catch (error) {
+        if (scope.code !== undefined)
+            throw new ConnectionError(scope.code);
+        const code = error instanceof Fault ? error.code : 'transport';
+        throw new ConnectionError(code === 'not_found' ? 'session_not_found' : code === 'refused' ? 'rejected' : code);
+    }
+    finally {
+        scope.close();
+        await peer?.close();
+    }
+}
+/** A UUID correlates the native user input; it is not an idempotency key. A
+ * successful RPC means admission only, not consumption or model completion. */
+export async function sendCodexText(target, text, options = {}) {
+    const connection = connections.get(target);
+    if (connection === undefined || typeof text !== 'string' || text.length === 0 || !isRecord(options) ||
+        !validTimeout(options.timeoutMs) || !validSignal(options.signal) || options.inputId !== undefined ||
+        (options.delivery !== undefined && options.delivery !== 'steer' && options.delivery !== 'queue')) {
+        throw new TypeError('Invalid sendText arguments.');
+    }
+    const inputId = randomUUID();
+    const attempt = { harness: 'codex', sessionId: target.sessionId, inputId };
+    const scope = deadline(options.timeoutMs, options.signal);
+    let peer;
+    let dispatched = false;
+    try {
+        peer = await open(connection, scope);
+        await peer.initialize(scope);
+        const thread = await readThread(peer, target.sessionId, scope);
+        const delivery = options.delivery ?? 'steer';
+        const expectedTurnId = delivery === 'steer' ? await discoverTurn(peer, thread, target.sessionId, scope) : undefined;
+        if (delivery === 'steer' && expectedTurnId === undefined)
+            return { ...attempt, state: 'rejected', code: 'refused' };
+        const input = [{ type: 'text', text, text_elements: [] }];
+        const result = await peer.call(delivery === 'steer' ? 'turn/steer' : 'thread/queue/add', {
+            threadId: target.sessionId, clientUserMessageId: inputId, input,
+            ...(delivery === 'steer' ? { expectedTurnId } : {}),
+        }, scope, () => { dispatched = true; });
+        if (!isRecord(result))
+            throw new Fault('invalid_response');
+        if (delivery === 'steer') {
+            if (result.turnId !== expectedTurnId)
+                throw new Fault('invalid_response');
+        }
+        else {
+            const queued = result.queuedSubmission;
+            if (!isRecord(queued) || !isIdentity(queued.id) || queued.clientUserMessageId !== inputId ||
+                !Array.isArray(queued.input) || queued.input.length !== 1 || !isRecord(queued.input[0]) ||
+                queued.input[0].type !== 'text' || queued.input[0].text !== text ||
+                !Array.isArray(queued.input[0].text_elements) || queued.input[0].text_elements.length !== 0)
+                throw new Fault('invalid_response');
+        }
+        return { ...attempt, state: 'admitted' };
+    }
+    catch (error) {
+        const code = scope.code ?? (error instanceof Fault ? error.code : 'transport');
+        if (code === 'not_found' || code === 'refused' || code === 'unsupported_version')
+            return { ...attempt, state: 'rejected', code };
+        if (dispatched)
+            return { ...attempt, state: 'unknown', code: code === 'authentication_failed' ? 'transport' : code };
+        // The public contract has no unavailable/invalid_response variant. A bad
+        // setup/read response is a known-unsent transport precondition failure.
+        return { ...attempt, state: 'unavailable', code: code === 'invalid_response' ? 'transport' : code };
+    }
+    finally {
+        scope.close();
+        await peer?.close();
+    }
+}

package/dist/packages/agent-delivery/src/errors.d.ts

@@ -1,4 +1,4 @@
-export type DeliveryErrorCode = 'invalid_arguments' | 'unsupported_platform' | 'unavailable' | 'authentication_failed' | 'session_not_found' | 'rejected' | 'unsupported_version' | 'invalid_response' | 'timeout' | 'aborted' | 'transport';
+export type DeliveryErrorCode = 'invalid_arguments' | 'unsupported_platform' | 'unavailable' | 'authentication_failed' | 'session_not_found' | 'session_inactive' | 'rejected' | 'unsupported_version' | 'invalid_response' | 'timeout' | 'aborted' | 'transport';
 /** Diagnostics intentionally contain no endpoint, credentials, body, or SDK cause. */
 export declare class DeliveryError extends Error {
     readonly code: DeliveryErrorCode;

package/dist/packages/agent-delivery/src/errors.js

@@ -4,6 +4,7 @@ const messages = {
     unavailable: 'The delivery endpoint is unavailable.',
     authentication_failed: 'Delivery authentication failed.',
     session_not_found: 'The requested session was not found.',
+    session_inactive: 'The session has no current delivery boundary.',
     rejected: 'The delivery was rejected.',
     unsupported_version: 'The receiving service version is unsupported.',
     invalid_response: 'The receiving service returned an invalid response.',

package/dist/packages/agent-delivery/src/file-lock.d.ts

@@ -0,0 +1,17 @@
+export interface FileLockOptions {
+    retryMs: number;
+    signal?: AbortSignal;
+    createParent?: boolean;
+    /** Optional discovery may skip a busy lock; ordinary lock users still wait. */
+    skipIfBusy?: boolean;
+}
+export declare class FileLockError extends Error {
+    readonly code: "not_a_database";
+    constructor(lockPath: string, cause?: unknown);
+}
+export declare function withFileLock<T>(lockPath: string, options: FileLockOptions & {
+    skipIfBusy: true;
+}, fn: () => T | Promise<T>): Promise<T | undefined>;
+export declare function withFileLock<T>(lockPath: string, options: FileLockOptions & {
+    skipIfBusy?: false;
+}, fn: () => T | Promise<T>): Promise<T>;

package/dist/packages/agent-delivery/src/file-lock.js

@@ -0,0 +1,64 @@
+import { DatabaseSync } from 'node:sqlite';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+export class FileLockError extends Error {
+    code = 'not_a_database';
+    constructor(lockPath, cause) {
+        super(`File lock is not a database: ${lockPath}`);
+        this.name = 'FileLockError';
+        if (cause !== undefined)
+            this.cause = cause;
+    }
+}
+function isBusy(error) {
+    return error instanceof Error && /database is locked|SQLITE_BUSY/i.test(error.message);
+}
+function isNotADatabase(error) {
+    return error instanceof Error && /not a database|file is not a database/i.test(error.message);
+}
+export async function withFileLock(lockPath, options, fn) {
+    if (options.createParent !== false)
+        await fs.mkdir(path.dirname(lockPath), { recursive: true });
+    while (true) {
+        if (options.signal?.aborted)
+            throw options.signal.reason ?? new Error('File lock acquisition aborted');
+        let database;
+        try {
+            database = new DatabaseSync(lockPath);
+            database.exec(`PRAGMA busy_timeout = 0;
+        BEGIN EXCLUSIVE;
+        CREATE TABLE IF NOT EXISTS __agent_delivery_lock (id INTEGER PRIMARY KEY CHECK (id = 1));`);
+        }
+        catch (error) {
+            try {
+                database?.close();
+            }
+            catch { }
+            if (isBusy(error)) {
+                if (options.skipIfBusy)
+                    return undefined;
+                await sleep(options.retryMs, undefined, { signal: options.signal });
+                continue;
+            }
+            if (isNotADatabase(error))
+                throw new FileLockError(lockPath, error);
+            throw error;
+        }
+        try {
+            const result = await fn();
+            database.exec('COMMIT;');
+            return result;
+        }
+        catch (error) {
+            try {
+                database.exec('ROLLBACK;');
+            }
+            catch { }
+            throw error;
+        }
+        finally {
+            database.close();
+        }
+    }
+}

package/dist/packages/agent-delivery/src/index.d.ts

@@ -1,6 +1,6 @@
 import { DeliveryError } from './errors.js';
-import type { OpenCodeConnectOptions, ClaudeConnectOptions, PiConnectOptions, PaseoConnectOptions } from './types.js';
-export type { OpenCodeConnectOptions, ClaudeConnectOptions, PiConnectOptions, PaseoConnectOptions } from './types.js';
+import type { OpenCodeConnectOptions, ClaudeConnectOptions, PiConnectOptions, PaseoConnectOptions, CodexConnectOptions, CodexAppServerConnectOptions, CodexCliConnectOptions } from './types.js';
+export type { OpenCodeConnectOptions, ClaudeConnectOptions, PiConnectOptions, PaseoConnectOptions, CodexConnectOptions, CodexAppServerConnectOptions, CodexCliConnectOptions } from './types.js';
 export interface SendOptions {
     readonly timeoutMs?: number;
     readonly signal?: AbortSignal;
@@ -34,10 +34,24 @@ export type PaseoAgent = Steerable<KeyedSendOptions> & {
     readonly harness: 'paseo';
     readonly agentId: string;
 };
-export type Agent = OpenCodeAgent | ClaudeAgent | PiAgent | PaseoAgent;
+export type CodexAppServerAgent = Steerable & Queueable & {
+    readonly harness: 'codex';
+    readonly transport: 'app-server';
+    readonly sessionId: string;
+};
+export type CodexCliAgent = Queueable & {
+    readonly harness: 'codex';
+    readonly transport: 'cli';
+    readonly sessionId: string;
+};
+export type CodexAgent = CodexAppServerAgent | CodexCliAgent;
+export type Agent = OpenCodeAgent | ClaudeAgent | PiAgent | PaseoAgent | CodexAgent;
 export declare function connect(options: OpenCodeConnectOptions): Promise<OpenCodeAgent>;
 export declare function connect(options: ClaudeConnectOptions): Promise<ClaudeAgent>;
 export declare function connect(options: PiConnectOptions): Promise<PiAgent>;
 export declare function connect(options: PaseoConnectOptions): Promise<PaseoAgent>;
+export declare function connect(options: CodexCliConnectOptions): Promise<CodexCliAgent>;
+export declare function connect(options: CodexAppServerConnectOptions): Promise<CodexAppServerAgent>;
+export declare function connect(options: CodexConnectOptions): Promise<CodexAgent>;
 export { DeliveryError };
 export type { DeliveryErrorCode } from './errors.js';

package/dist/packages/agent-delivery/src/index.js

@@ -25,11 +25,30 @@ function failure(error, phase, id) {
     const code = attempt.state === 'unavailable'
         ? attempt.code === 'aborted' ? 'aborted' : attempt.code === 'timeout' ? 'timeout'
             : attempt.code === 'authentication_failed' ? 'authentication_failed' : 'unavailable'
-        : attempt.state === 'rejected' ? attempt.code === 'not_found' ? 'session_not_found' : 'rejected'
+        : attempt.state === 'rejected' ? attempt.code === 'not_found' ? 'session_not_found'
+            : attempt.code === 'unsupported_version' ? 'unsupported_version' : 'rejected'
             : codes[attempt.code ?? 'transport'] ?? 'transport';
     return new DeliveryError(code, attempt.state === 'unknown', id ?? attempt.inputId, attempt.status);
 }
 const harnesses = {
+    'codex-cli': {
+        harness: 'codex', transport: 'cli', proof: 'admitted', accepted: 'admitted', coordinate: 'sessionId', keyed: false, queue: true, steer: false,
+        id: (result) => result.inputId,
+        open: async (options) => {
+            const { connectCodexCli } = await import('./codex-cli.js');
+            const target = await connectCodexCli(options);
+            return { coordinate: target.coordinate, send: (text, value) => target.send(text, value) };
+        },
+    },
+    codex: {
+        harness: 'codex', transport: 'app-server', proof: 'admitted', accepted: 'admitted', coordinate: 'sessionId', keyed: false, queue: true,
+        id: (result) => result.inputId,
+        open: async (options) => {
+            const { connectCodex, sendCodexText } = await import('./codex.js');
+            const target = await connectCodex(options);
+            return { coordinate: target.sessionId, send: (text, value) => sendCodexText(target, text, value) };
+        },
+    },
     opencode: {
         harness: 'opencode', proof: 'admitted', accepted: 'accepted', coordinate: 'sessionId', keyed: true, queue: true,
         id: (result) => result.inputId,
@@ -70,8 +89,9 @@ const harnesses = {
 export async function connect(options) {
     const harness = isRecord(options) && typeof options.harness === 'string' ? options.harness : undefined;
     // An own-key check keeps Object.prototype names out of the transport table.
-    const spec = harness !== undefined && Object.hasOwn(harnesses, harness) ? harnesses[harness] : undefined;
-    if (spec === undefined)
+    const key = harness === 'codex' && isRecord(options) && options.transport === 'cli' ? 'codex-cli' : harness;
+    const spec = key !== undefined && Object.hasOwn(harnesses, key) ? harnesses[key] : undefined;
+    if (spec === undefined || spec.harness !== harness)
         throw new DeliveryError('invalid_arguments');
     let opened;
     try {
@@ -86,6 +106,8 @@ export async function connect(options) {
             throw new DeliveryError('invalid_arguments');
         // An unusable caller id is an argument precondition; the native sender rejects it.
         const id = options.id;
+        if (!spec.keyed && id !== undefined)
+            throw new DeliveryError('invalid_arguments');
         try {
             const result = await opened.send(text, spec.keyed
                 ? { delivery, inputId: id, timeoutMs: options.timeoutMs, signal: options.signal }
@@ -101,8 +123,11 @@ export async function connect(options) {
     const agent = {
         harness: spec.harness,
         [spec.coordinate]: opened.coordinate,
-        steer: (text, value) => send(text, value, 'steer'),
     };
+    if (spec.transport)
+        agent.transport = spec.transport;
+    if (spec.steer !== false)
+        agent.steer = (text, value) => send(text, value, 'steer');
     if (spec.queue)
         agent.queue = (text, value) => send(text, value, 'queue');
     return Object.freeze(agent);