@astrosheep/square 0.3.90 → 0.3.92

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

@@ -0,0 +1,10 @@
+import type { CodexCliConnectOptions, CodexSendTextOptions } from './types.js';
+/** Bind once; no subprocess or lifecycle read until queue(). The receiver's
+ * hooks and this client share one lifecycle source, never a Square default. */
+export declare function connectCodexCli(options: CodexCliConnectOptions): Promise<{
+    coordinate: string;
+    send(text: string, value: CodexSendTextOptions): Promise<{
+        state: string;
+        inputId: `${string}-${string}-${string}-${string}-${string}`;
+    }>;
+}>;

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

@@ -0,0 +1,69 @@
+import { randomUUID } from 'node:crypto';
+import { resolveCodexHome } from './codex-endpoint.js';
+import { sendCodexQueue, CodexQueueSendError } from './codex-queue.js';
+import { deadline, DEFAULT_TIMEOUT_MS, validSignal, validTimeout } from './deadline.js';
+import { ConnectionError, DeliveryError } from './errors.js';
+import { isIdentity, isRecord } from './guards.js';
+/** Bind once; no subprocess or lifecycle read until queue(). The receiver's
+ * hooks and this client share one lifecycle source, never a Square default. */
+export async function connectCodexCli(options) {
+    const text = (value) => isIdentity(value) && !value.includes('\0');
+    if (!isRecord(options) || options.harness !== 'codex' || options.transport !== 'cli' ||
+        !text(options.sessionId) || !isRecord(options.boundaries) || typeof options.boundaries.queueEligible !== 'function' ||
+        !validTimeout(options.timeoutMs) || !validSignal(options.signal) ||
+        (options.codexHome !== undefined && !text(options.codexHome)) ||
+        (options.endpoint !== undefined && !text(options.endpoint)) || (options.bin !== undefined && !text(options.bin)) ||
+        (options.args !== undefined && (!Array.isArray(options.args) || options.args.some((arg) => typeof arg !== 'string' || arg.includes('\0')))) ||
+        (options.env !== undefined && (!isRecord(options.env) || Object.entries(options.env).some(([key, v]) => key.includes('\0') || (v !== undefined && (typeof v !== 'string' || v.includes('\0'))))))) {
+        throw new ConnectionError('invalid_arguments');
+    }
+    if (options.signal?.aborted)
+        throw new ConnectionError('aborted');
+    const env = { ...(options.env ?? process.env) };
+    try {
+        env.CODEX_HOME = resolveCodexHome(options.codexHome === undefined ? env : { ...env, CODEX_HOME: options.codexHome });
+    }
+    catch {
+        throw new ConnectionError('invalid_arguments');
+    }
+    const sessionId = options.sessionId;
+    const eligible = options.boundaries.queueEligible.bind(options.boundaries);
+    const cli = { env, bin: options.bin, args: options.args === undefined ? undefined : [...options.args], endpoint: options.endpoint };
+    return {
+        coordinate: sessionId,
+        async send(text, value) {
+            if (typeof text !== 'string' || !text.trim() || text.includes('\0') || !isRecord(value) ||
+                value.delivery !== 'queue' || value.inputId !== undefined || !validTimeout(value.timeoutMs) || !validSignal(value.signal)) {
+                throw new TypeError('Invalid Codex queue arguments.');
+            }
+            const inputId = randomUUID(); // Local attempt correlation; the CLI does not accept a client message id.
+            const scope = deadline(value.timeoutMs, value.signal);
+            const until = Date.now() + (value.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+            let launched = false;
+            try {
+                scope.check();
+                // One check, immediately before launching the CLI. SessionEnd/late Stop
+                // suppression belongs to the bound source, not every sending caller.
+                if (!await scope.wait(eligible(sessionId)))
+                    throw new DeliveryError('session_inactive', false, inputId);
+                scope.check();
+                const remaining = until - Date.now();
+                if (remaining <= 0)
+                    throw new DeliveryError('timeout', false, inputId);
+                launched = true;
+                await sendCodexQueue({ threadId: sessionId, message: text }, { ...cli, timeoutMs: remaining, signal: scope.signal });
+                return { state: 'admitted', inputId };
+            }
+            catch (error) {
+                if (error instanceof DeliveryError)
+                    throw error;
+                if (error instanceof CodexQueueSendError)
+                    throw new DeliveryError(scope.code ?? error.code, error.maybeDelivered, inputId);
+                throw new DeliveryError(scope.code ?? (launched ? 'transport' : 'unavailable'), launched, inputId);
+            }
+            finally {
+                scope.close();
+            }
+        },
+    };
+}

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

@@ -0,0 +1,3 @@
+/** Capture the recipient's home before another process delivers. No service discovery I/O. */
+export declare function resolveCodexHome(env?: NodeJS.ProcessEnv): string;
+export declare function codexQueueEndpoint(env?: NodeJS.ProcessEnv): string;

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

@@ -0,0 +1,14 @@
+import os from 'node:os';
+import path from 'node:path';
+/** Capture the recipient's home before another process delivers. No service discovery I/O. */
+export function resolveCodexHome(env = process.env) {
+    const userHome = env.HOME || os.homedir();
+    const raw = env.CODEX_HOME || path.join(userHome, '.codex');
+    const home = raw === '~' ? userHome : raw.startsWith('~/') ? path.join(userHome, raw.slice(2)) : raw;
+    if (!path.isAbsolute(home) || home.includes('\0'))
+        throw new TypeError('Invalid Codex home.');
+    return home;
+}
+export function codexQueueEndpoint(env = process.env) {
+    return `unix://${path.join(resolveCodexHome(env), 'app-server-control', 'app-server-control.sock')}`;
+}

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

@@ -0,0 +1,26 @@
+import type { CodexBoundaryStore } from './codex-boundary.js';
+export { createCodexBoundaryStore } from './codex-boundary.js';
+export type { CodexBoundary, CodexBoundaryStore } from './codex-boundary.js';
+export interface CodexHookResponse {
+    readonly hookSpecificOutput: {
+        readonly hookEventName: 'PostToolUse';
+        readonly additionalContext: string;
+    };
+}
+export interface CodexHookOptions {
+    readonly boundaries: CodexBoundaryStore;
+    /** The host owns pending text, claims and cancellation. Honor signal before presenting;
+     * if cancelled before an effect, release custody and resolve undefined or reject.
+     * After presenting, finish any cancellation-independent settlement and return its text,
+     * even if signal aborts meanwhile. This callback is awaited, never raced or abandoned. */
+    readonly pull?: (sessionId: string, signal: AbortSignal) => Promise<string | undefined>;
+    /** Dispatch the host's pending work; Stop merely makes queue eligible. */
+    readonly sweep?: (cwd: string | undefined, deadline: number, signal: AbortSignal) => Promise<void>;
+    readonly end?: (sessionId: string, signal: AbortSignal) => Promise<void>;
+    readonly trace?: (stage: string, detail?: string) => void;
+    readonly timeoutMs?: number;
+    readonly sweepTimeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+/** Stateless hook protocol. No message source, session identity or service is invented here. */
+export declare function handleCodexHook(input: unknown, options: CodexHookOptions): Promise<CodexHookResponse | undefined>;

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

@@ -0,0 +1,58 @@
+import { deadline, validSignal, validTimeout } from './deadline.js';
+import { isRecord } from './guards.js';
+export { createCodexBoundaryStore } from './codex-boundary.js';
+/** Stateless hook protocol. No message source, session identity or service is invented here. */
+export async function handleCodexHook(input, options) {
+    if (!isRecord(input) || typeof input.session_id !== 'string' || !input.session_id.trim())
+        return;
+    const event = input.hook_event_name;
+    if (!['SessionStart', 'SessionResume', 'UserPromptSubmit', 'SessionEnd', 'PostToolUse', 'Stop'].includes(event))
+        return;
+    if (!validTimeout(options.timeoutMs) || !validTimeout(options.sweepTimeoutMs) || !validSignal(options.signal)) {
+        throw new TypeError('Invalid hook control.');
+    }
+    const scope = deadline(options.timeoutMs ?? 4500, options.signal);
+    const sweepDeadline = Date.now() + Math.min(options.sweepTimeoutMs ?? 3000, options.timeoutMs ?? 4500);
+    const id = input.session_id;
+    try {
+        scope.check();
+        if (event === 'SessionEnd') {
+            await scope.wait(options.boundaries.record(id, 'end', scope.signal));
+            await scope.wait(options.end?.(id, scope.signal) ?? Promise.resolve()).catch(() => { });
+            return;
+        }
+        await scope.wait(options.boundaries.record(id, event === 'SessionStart' || event === 'SessionResume' ? 'start' : event === 'Stop' ? 'Stop' : 'non-stop', scope.signal));
+        options.trace?.('boundary-record');
+        if (event !== 'Stop' && event !== 'PostToolUse')
+            return;
+        let context;
+        if (event === 'PostToolUse') {
+            try {
+                // A host's successful presentation settlement may outlive this signal. Retain
+                // its output instead of leaving background work to consume it without a response.
+                context = await options.pull?.(id, scope.signal);
+                options.trace?.('presentation');
+            }
+            catch (error) {
+                options.trace?.('presentation', `error=${error instanceof Error ? error.name : 'Error'}`);
+            }
+        }
+        if (!scope.signal.aborted && Date.now() < sweepDeadline) {
+            await scope.wait(options.sweep?.(typeof input.cwd === 'string' ? input.cwd : undefined, sweepDeadline, scope.signal) ?? Promise.resolve()).catch(() => { });
+        }
+        options.trace?.('sweep', scope.signal.aborted ? 'aborted=true' : '');
+        // A successful pull may already have committed host presentation evidence.
+        // A later, unrelated sweep timeout must not discard its completed output.
+        if (context !== undefined) {
+            return { hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: context } };
+        }
+    }
+    catch (error) {
+        if (scope.signal.aborted)
+            throw scope.signal.reason;
+        throw error;
+    }
+    finally {
+        scope.close();
+    }
+}

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

@@ -0,0 +1,24 @@
+export { codexQueueEndpoint } from './codex-endpoint.js';
+import type { DeliveryErrorCode } from './errors.js';
+export interface CodexQueueRequest {
+    readonly threadId: string;
+    readonly message: string;
+}
+export interface CodexQueueOptions {
+    readonly bin?: string;
+    readonly args?: readonly string[];
+    readonly env?: NodeJS.ProcessEnv;
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+    readonly endpoint?: string;
+}
+export type CodexQueueFailureKind = 'transient' | 'rejected' | 'unknown';
+/** Once the child starts, a timeout or unexplained exit does not establish non-delivery. */
+export declare class CodexQueueSendError extends Error {
+    readonly kind: CodexQueueFailureKind;
+    readonly code: DeliveryErrorCode;
+    constructor(kind: CodexQueueFailureKind, code: DeliveryErrorCode);
+    get maybeDelivered(): boolean;
+}
+/** Internal CLI transport. Lifecycle checking belongs to the bound CLI client. */
+export declare function sendCodexQueue(request: CodexQueueRequest, options?: CodexQueueOptions): Promise<void>;

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>;