@taskforcehq/taskforce 0.3.328 → 0.3.330

package/dist/services/codexAppServerModelGateway.js

@@ -0,0 +1,663 @@
+import { spawn } from 'child_process';
+import { existsSync, realpathSync } from 'fs';
+import { tmpdir } from 'os';
+import { dirname, isAbsolute, join, resolve } from 'path';
+import { createRequire } from 'module';
+import readline from 'readline';
+import { ModelGatewayConfigurationError } from './modelGateway.js';
+import { TASKFORCE_AGENT_MODEL_OPTIONS, isTaskforceAgentSubscriptionDevModelsEnabled } from '../shared/taskforceAgentModels.js';
+const CODEX_APP_SERVER_STDERR_LIMIT = 4_096;
+export const PINNED_CODEX_APP_SERVER_VERSION = '0.148.0-alpha.9';
+const require = createRequire(import.meta.url);
+export class CodexAppServerCompatibilityError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+        this.name = 'CodexAppServerCompatibilityError';
+    }
+}
+export function resolveBundledCodexCommand() {
+    try {
+        const packageVersion = String(require('@openai/codex/package.json')?.version || '');
+        if (packageVersion !== PINNED_CODEX_APP_SERVER_VERSION)
+            throw new Error('version mismatch');
+        const target = (() => {
+            if (process.platform === 'linux' && process.arch === 'x64') {
+                return ['@openai/codex-linux-x64', 'x86_64-unknown-linux-musl'];
+            }
+            if (process.platform === 'linux' && process.arch === 'arm64') {
+                return ['@openai/codex-linux-arm64', 'aarch64-unknown-linux-musl'];
+            }
+            if (process.platform === 'darwin' && process.arch === 'x64') {
+                return ['@openai/codex-darwin-x64', 'x86_64-apple-darwin'];
+            }
+            if (process.platform === 'darwin' && process.arch === 'arm64') {
+                return ['@openai/codex-darwin-arm64', 'aarch64-apple-darwin'];
+            }
+            if (process.platform === 'win32' && process.arch === 'x64') {
+                return ['@openai/codex-win32-x64', 'x86_64-pc-windows-msvc'];
+            }
+            if (process.platform === 'win32' && process.arch === 'arm64') {
+                return ['@openai/codex-win32-arm64', 'aarch64-pc-windows-msvc'];
+            }
+            throw new Error('unsupported platform');
+        })();
+        const platformPackageJson = require.resolve(`${target[0]}/package.json`);
+        const platformVersion = String(require(platformPackageJson)?.version || '');
+        const expectedPlatformVersion = `${PINNED_CODEX_APP_SERVER_VERSION}-${target[0].slice('@openai/codex-'.length)}`;
+        if (platformVersion !== expectedPlatformVersion)
+            throw new Error('platform version mismatch');
+        const executable = join(dirname(platformPackageJson), 'vendor', target[1], 'bin', process.platform === 'win32' ? 'codex.exe' : 'codex');
+        if (!existsSync(executable))
+            throw new Error('binary missing');
+        return executable;
+    }
+    catch {
+        throw new CodexAppServerCompatibilityError('version', `Unsupported Codex app-server version; Taskforce requires ${PINNED_CODEX_APP_SERVER_VERSION}.`);
+    }
+}
+function normalizedPath(value) {
+    try {
+        return realpathSync(value);
+    }
+    catch {
+        return resolve(value);
+    }
+}
+export function assertCodexAppServerCompatibility(result, expectedCodexHome) {
+    const userAgent = readStringPath(result, ['userAgent']);
+    const codexHome = readStringPath(result, ['codexHome']);
+    const version = userAgent.match(/\/([0-9]+\.[0-9]+\.[0-9]+(?:-[A-Za-z0-9.-]+)?)(?:\s|\()/)?.[1];
+    if (version !== PINNED_CODEX_APP_SERVER_VERSION) {
+        throw new CodexAppServerCompatibilityError('version', `Unsupported Codex app-server version; Taskforce requires ${PINNED_CODEX_APP_SERVER_VERSION}.`);
+    }
+    if (!codexHome || !isAbsolute(codexHome)) {
+        throw new CodexAppServerCompatibilityError('credential_home', 'Unsupported Codex app-server credential home response.');
+    }
+    const expected = String(expectedCodexHome || '').trim();
+    if (expected && normalizedPath(codexHome) !== normalizedPath(expected)) {
+        throw new CodexAppServerCompatibilityError('credential_home', 'Unsupported Codex app-server credential home response.');
+    }
+}
+export const DEFAULT_CODEX_APP_SERVER_MODEL_KEY_IDS = {
+    ...Object.fromEntries(TASKFORCE_AGENT_MODEL_OPTIONS
+        .filter((model) => model.runtime === 'subscription-dev' && model.providerKey === 'openai')
+        .map((model) => [model.key, model.runtimeModelId])),
+};
+const CODEX_APP_SERVER_ENV_ALLOWLIST = [
+    'HOME',
+    'USER',
+    'LOGNAME',
+    'PATH',
+    'SHELL',
+    'TMPDIR',
+    'TEMP',
+    'TMP',
+    'LANG',
+    'LC_ALL',
+    'LC_CTYPE',
+    'TERM',
+    'COLORTERM',
+    'NO_COLOR',
+    'CODEX_HOME',
+    'XDG_CONFIG_HOME',
+    'XDG_CACHE_HOME',
+    'XDG_DATA_HOME',
+];
+export function buildCodexAppServerEnv(source = process.env) {
+    const env = {};
+    for (const key of CODEX_APP_SERVER_ENV_ALLOWLIST) {
+        const value = source[key];
+        if (typeof value === 'string' && value.length > 0)
+            env[key] = value;
+    }
+    return env;
+}
+export function sanitizeCodexAppServerStderr(value, credentialPaths = []) {
+    let sanitized = String(value || '')
+        .replace(/\\+(?=["'])/g, '')
+        .replace(/(["']?(?:api[_-]?key|access[_-]?token|refresh[_-]?token|id[_-]?token|client[_-]?secret)["']?\s*[:=]\s*)(["'])[^"'\r\n]*\2/gi, '$1$2[redacted]$2')
+        .replace(/((?:api[_-]?key|access[_-]?token|refresh[_-]?token|id[_-]?token|client[_-]?secret)\s*[:=]\s*)[^\s,}\]]+/gi, '$1[redacted]')
+        .replace(/sk-[A-Za-z0-9_-]{8,}/g, '[redacted OpenAI credential]')
+        .replace(/(Bearer\s+)[^\s]+/gi, '$1[redacted]')
+        .replace(/\beyJ[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}\b/g, '[redacted JWT]')
+        .replace(/[^\x09\x0A\x0D\x20-\x7E]/g, '?');
+    for (const credentialPath of credentialPaths) {
+        const normalized = String(credentialPath || '').trim();
+        if (normalized)
+            sanitized = sanitized.split(normalized).join('[redacted credential path]');
+    }
+    return sanitized.slice(0, CODEX_APP_SERVER_STDERR_LIMIT);
+}
+export function collectCodexAppServerStderr(current, chunk) {
+    return (current + String(chunk || '')).slice(-CODEX_APP_SERVER_STDERR_LIMIT);
+}
+export function assertCodexChatGptSubscriptionAccount(result) {
+    const accountType = readStringPath(result, ['account', 'type']);
+    if (accountType !== 'chatgpt') {
+        throw new ModelGatewayConfigurationError('Codex is not signed in with a ChatGPT subscription. Run codex login on this machine and choose Sign in with ChatGPT.', 'MODEL_SOURCE_UNAVAILABLE');
+    }
+}
+export function extractCodexAccountLoginCompletion(messages, loginId, credentialPaths = []) {
+    for (const message of messages) {
+        if (message.method !== 'account/login/completed')
+            continue;
+        const completedLoginId = readStringPath(message.params, ['loginId']);
+        if (completedLoginId !== loginId)
+            continue;
+        const params = message.params;
+        const success = params?.success === true;
+        const error = sanitizeCodexAppServerStderr(params?.error, credentialPaths).trim();
+        return {
+            loginId,
+            success,
+            ...(error ? { error } : {}),
+        };
+    }
+    return null;
+}
+export function isCodexSubscriptionDevRuntimeAllowed(source = process.env) {
+    const runtimeMode = String(source.TASKFORCE_RUNTIME_MODE || '').trim().toLowerCase();
+    return runtimeMode === 'local';
+}
+function resolveCodexAppServerCwd(cwd) {
+    return String(cwd || process.env.TASKFORCE_CODEX_APP_SERVER_CWD || tmpdir()).trim() || tmpdir();
+}
+function buildCodexAppServerRuntimePolicy(cwd) {
+    return {
+        cwd,
+        approvalPolicy: 'never',
+        sandbox: 'read-only',
+        sandboxPolicy: {
+            type: 'readOnly',
+            networkAccess: false,
+        },
+    };
+}
+export function extractCodexTurnCompletion(messages, credentialPaths = []) {
+    const jsonMessages = messages;
+    const completed = jsonMessages.find((message) => message.method === 'turn/completed');
+    if (!completed)
+        return null;
+    const stopReason = readStringPath(completed.params, ['turn', 'status'])
+        || readStringPath(completed.params, ['status'])
+        || 'completed';
+    if (stopReason !== 'completed') {
+        const errorMessage = readStringPath(completed.params, ['turn', 'error', 'message'])
+            || readStringPath(completed.params, ['error', 'message'])
+            || `Codex app-server turn ended with status ${stopReason}.`;
+        throw new Error(sanitizeCodexAppServerStderr(errorMessage, credentialPaths));
+    }
+    return {
+        text: extractAgentText(jsonMessages),
+        stopReason,
+    };
+}
+export class CodexAppServerJsonRpcClient {
+    process;
+    pending = new Map();
+    notifications = [];
+    nextId = 1;
+    initialized = false;
+    lineReader;
+    requestTimeoutMs;
+    terminalRejectors = new Set();
+    loginNotificationStart = new Map();
+    terminalError = null;
+    stderrTail = '';
+    credentialPaths;
+    expectedCodexHome;
+    processExited;
+    closePromise = null;
+    constructor(options = {}) {
+        const command = options.command
+            || process.env.TASKFORCE_CODEX_APP_SERVER_COMMAND
+            || resolveBundledCodexCommand();
+        const args = options.args || ['app-server', '--listen', 'stdio://'];
+        const cwd = resolveCodexAppServerCwd(options.cwd);
+        this.requestTimeoutMs = options.requestTimeoutMs ?? 30_000;
+        this.credentialPaths = options.credentialPaths || [];
+        const childEnvironment = options.env || buildCodexAppServerEnv();
+        this.expectedCodexHome = String(childEnvironment.CODEX_HOME || '').trim();
+        this.process = spawn(command, args, {
+            stdio: ['pipe', 'pipe', 'pipe'],
+            env: childEnvironment,
+            cwd,
+        });
+        this.processExited = new Promise((resolveExit) => {
+            let settled = false;
+            const finish = () => {
+                if (settled)
+                    return;
+                settled = true;
+                resolveExit();
+            };
+            this.process.once('exit', finish);
+            this.process.once('error', finish);
+        });
+        this.lineReader = readline.createInterface({ input: this.process.stdout });
+        this.lineReader.on('line', (line) => this.handleLine(line));
+        this.process.on('error', (error) => {
+            this.fail(new Error(`Codex app-server failed to start: ${error.message}`));
+        });
+        this.process.on('exit', (code, signal) => {
+            const reason = signal ? `signal ${signal}` : `exit code ${code ?? 'unknown'}`;
+            const details = sanitizeCodexAppServerStderr(this.stderrTail, this.credentialPaths).trim();
+            this.fail(new Error(`Codex app-server stopped before completing the request (${reason}).${details ? ` ${details}` : ''}`));
+        });
+        this.process.stderr.on('data', (chunk) => {
+            this.stderrTail = collectCodexAppServerStderr(this.stderrTail, chunk);
+        });
+    }
+    async initialize() {
+        if (this.initialized)
+            return;
+        const result = await this.request('initialize', {
+            clientInfo: {
+                name: 'taskforce_dev',
+                title: 'Taskforce Dev',
+                version: '0.1.0',
+            },
+            capabilities: {
+                experimentalApi: true,
+                requestAttestation: false,
+            },
+        });
+        assertCodexAppServerCompatibility(result, this.expectedCodexHome);
+        this.sendNotification('initialized', {});
+        this.initialized = true;
+    }
+    async assertChatGptSubscriptionAuth() {
+        const result = await this.request('account/read', { refreshToken: false });
+        assertCodexChatGptSubscriptionAccount(result);
+    }
+    async startChatGptDeviceCodeLogin() {
+        const notificationStart = this.notifications.length;
+        const result = await this.request('account/login/start', { type: 'chatgptDeviceCode' });
+        const type = readStringPath(result, ['type']);
+        const loginId = readStringPath(result, ['loginId']);
+        const userCode = readStringPath(result, ['userCode']);
+        const verificationUrl = readStringPath(result, ['verificationUrl']);
+        if (type !== 'chatgptDeviceCode' || !loginId || !userCode || !verificationUrl) {
+            throw new Error('Codex app-server returned an invalid device-code login response.');
+        }
+        this.loginNotificationStart.set(loginId, notificationStart);
+        return { loginId, userCode, verificationUrl };
+    }
+    async waitForAccountLoginCompleted(input) {
+        const startIndex = this.loginNotificationStart.get(input.loginId) ?? 0;
+        try {
+            return await this.waitForNotification(() => extractCodexAccountLoginCompletion(this.notifications.slice(startIndex), input.loginId, this.credentialPaths), input.timeoutMs, 'Timed out waiting for Codex device-code authorization.', input.signal);
+        }
+        finally {
+            this.loginNotificationStart.delete(input.loginId);
+        }
+    }
+    async cancelAccountLogin(loginId) {
+        const result = await this.request('account/login/cancel', { loginId });
+        const status = readStringPath(result, ['status']);
+        return status === 'canceled' ? 'canceled' : 'notFound';
+    }
+    async readAccount(refreshToken = false) {
+        const result = await this.request('account/read', { refreshToken });
+        const type = readStringPath(result, ['account', 'type']);
+        if (!type)
+            return null;
+        const email = readStringPath(result, ['account', 'email']);
+        const planType = readStringPath(result, ['account', 'planType']);
+        return { type, ...(email ? { email } : {}), ...(planType ? { planType } : {}) };
+    }
+    async logoutAccount() {
+        await this.request('account/logout', {});
+    }
+    async startThread(input) {
+        const result = await this.request('thread/start', {
+            model: input.model,
+            cwd: input.cwd,
+            approvalPolicy: input.approvalPolicy,
+            sandbox: input.sandbox,
+            serviceName: 'taskforce_agent_manager_dev',
+            ...(input.developerInstructions
+                ? { developerInstructions: input.developerInstructions }
+                : {}),
+        });
+        const threadId = readStringPath(result, ['thread', 'id']) || readStringPath(result, ['id']);
+        if (!threadId)
+            throw new Error('Codex app-server did not return a thread id.');
+        return { threadId };
+    }
+    async startTurnAndCollectText(input) {
+        const startedAt = this.notifications.length;
+        await this.request('turn/start', {
+            threadId: input.threadId,
+            input: [{ type: 'text', text: input.prompt }],
+            cwd: input.cwd,
+            approvalPolicy: input.approvalPolicy,
+            sandboxPolicy: input.sandboxPolicy,
+            model: input.model,
+        });
+        return this.waitForTurnCompletion(startedAt, input.timeoutMs);
+    }
+    async close() {
+        if (this.closePromise)
+            return this.closePromise;
+        this.closePromise = (async () => {
+            this.lineReader.close();
+            if (this.process.exitCode !== null || this.process.signalCode !== null) {
+                await this.processExited;
+                return;
+            }
+            this.process.kill('SIGTERM');
+            let timeout;
+            const exitedGracefully = await Promise.race([
+                this.processExited.then(() => true),
+                new Promise((resolveTimeout) => {
+                    timeout = setTimeout(() => resolveTimeout(false), 2_000);
+                    timeout.unref?.();
+                }),
+            ]);
+            if (timeout)
+                clearTimeout(timeout);
+            if (!exitedGracefully && this.process.exitCode === null && this.process.signalCode === null) {
+                this.process.kill('SIGKILL');
+                await this.processExited;
+            }
+        })();
+        return this.closePromise;
+    }
+    request(method, params) {
+        const id = this.nextId++;
+        const message = { jsonrpc: '2.0', id, method, params };
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`Timed out waiting for Codex app-server ${method} response.`));
+            }, this.requestTimeoutMs);
+            this.pending.set(id, {
+                resolve: (value) => {
+                    clearTimeout(timeout);
+                    resolve(value);
+                },
+                reject: (error) => {
+                    clearTimeout(timeout);
+                    reject(error);
+                },
+            });
+            this.process.stdin.write(JSON.stringify(message) + '\n', (error) => {
+                if (error) {
+                    const pending = this.pending.get(id);
+                    if (!pending)
+                        return;
+                    this.pending.delete(id);
+                    pending.reject(error);
+                }
+            });
+        });
+    }
+    sendNotification(method, params) {
+        this.process.stdin.write(JSON.stringify({ jsonrpc: '2.0', method, params }) + '\n');
+    }
+    handleLine(line) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            return;
+        let message;
+        try {
+            message = JSON.parse(trimmed);
+        }
+        catch {
+            return;
+        }
+        if (typeof message.id === 'number') {
+            const pending = this.pending.get(message.id);
+            if (!pending) {
+                if (message.method) {
+                    this.sendResponseError(message.id, -32601, `Taskforce does not support Codex app-server request ${message.method}.`);
+                }
+                return;
+            }
+            this.pending.delete(message.id);
+            if (message.error) {
+                pending.reject(new Error(sanitizeCodexAppServerStderr(message.error.message || 'Codex app-server request failed.', this.credentialPaths)));
+            }
+            else {
+                pending.resolve(message.result);
+            }
+            return;
+        }
+        if (message.method)
+            this.notifications.push(message);
+    }
+    sendResponseError(id, code, message) {
+        this.process.stdin.write(JSON.stringify({
+            jsonrpc: '2.0',
+            id,
+            error: { code, message },
+        }) + '\n');
+    }
+    waitForTurnCompletion(startIndex, timeoutMs) {
+        const startedAt = Date.now();
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const rejectTurn = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                this.terminalRejectors.delete(rejectTurn);
+                reject(error);
+            };
+            const resolveTurn = (value) => {
+                if (settled)
+                    return;
+                settled = true;
+                this.terminalRejectors.delete(rejectTurn);
+                resolve(value);
+            };
+            this.terminalRejectors.add(rejectTurn);
+            if (this.terminalError) {
+                rejectTurn(this.terminalError);
+                return;
+            }
+            const poll = () => {
+                if (settled)
+                    return;
+                const messages = this.notifications.slice(startIndex);
+                try {
+                    const completion = extractCodexTurnCompletion(messages, this.credentialPaths);
+                    if (completion) {
+                        resolveTurn(completion);
+                        return;
+                    }
+                }
+                catch (error) {
+                    rejectTurn(error instanceof Error ? error : new Error(String(error)));
+                    return;
+                }
+                if (Date.now() - startedAt > timeoutMs) {
+                    rejectTurn(new Error('Timed out waiting for Codex app-server turn completion.'));
+                    return;
+                }
+                setTimeout(poll, 50);
+            };
+            poll();
+        });
+    }
+    waitForNotification(readValue, timeoutMs, timeoutMessage, signal) {
+        const startedAt = Date.now();
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const finish = (callback) => {
+                if (settled)
+                    return;
+                settled = true;
+                this.terminalRejectors.delete(rejectWaiter);
+                signal?.removeEventListener('abort', abortWaiter);
+                callback();
+            };
+            const rejectWaiter = (error) => finish(() => reject(error));
+            const abortWaiter = () => rejectWaiter(new Error('Codex device-code authorization was cancelled.'));
+            this.terminalRejectors.add(rejectWaiter);
+            signal?.addEventListener('abort', abortWaiter, { once: true });
+            if (signal?.aborted)
+                return abortWaiter();
+            if (this.terminalError)
+                return rejectWaiter(this.terminalError);
+            const poll = () => {
+                if (settled)
+                    return;
+                const value = readValue();
+                if (value !== null)
+                    return finish(() => resolve(value));
+                if (Date.now() - startedAt > timeoutMs)
+                    return rejectWaiter(new Error(timeoutMessage));
+                setTimeout(poll, 50);
+            };
+            poll();
+        });
+    }
+    rejectAll(error) {
+        for (const pending of this.pending.values())
+            pending.reject(error);
+        this.pending.clear();
+    }
+    fail(error) {
+        if (!this.terminalError)
+            this.terminalError = error;
+        this.rejectAll(this.terminalError);
+        for (const rejectWaiter of [...this.terminalRejectors])
+            rejectWaiter(this.terminalError);
+    }
+}
+export class CodexAppServerModelGateway {
+    client;
+    clientFactory;
+    modelKeyIds;
+    timeoutMs;
+    cwd;
+    constructor(options = {}) {
+        this.client = options.client;
+        this.cwd = resolveCodexAppServerCwd(options.cwd);
+        this.clientFactory = options.clientFactory || (() => new CodexAppServerJsonRpcClient({
+            command: options.command,
+            args: options.args,
+            cwd: this.cwd,
+            env: options.env,
+            requestTimeoutMs: options.requestTimeoutMs,
+            credentialPaths: options.credentialPaths,
+        }));
+        this.modelKeyIds = {
+            ...DEFAULT_CODEX_APP_SERVER_MODEL_KEY_IDS,
+            ...(options.modelKeyIds ?? {}),
+        };
+        this.timeoutMs = options.timeoutMs ?? 120_000;
+    }
+    async generate(input) {
+        if (!isTaskforceAgentSubscriptionDevModelsEnabled()) {
+            throw new ModelGatewayConfigurationError('OpenAI Codex subscription-dev models are disabled. Set TASKFORCE_AGENT_SUBSCRIPTION_DEV_MODELS=true for this development runtime.', 'MODEL_SOURCE_UNAVAILABLE');
+        }
+        if (!isCodexSubscriptionDevRuntimeAllowed()) {
+            throw new ModelGatewayConfigurationError('OpenAI Codex subscription-dev models are only available in the local Taskforce runtime.', 'MODEL_SOURCE_UNAVAILABLE');
+        }
+        const modelId = this.resolveModelId(input);
+        const client = this.client || this.clientFactory();
+        const shouldClose = !this.client;
+        const runtimePolicy = buildCodexAppServerRuntimePolicy(this.cwd);
+        const startedAt = Date.now();
+        try {
+            await client.initialize();
+            await client.assertChatGptSubscriptionAuth();
+            const thread = await client.startThread({
+                model: modelId,
+                developerInstructions: input.system,
+                ...runtimePolicy,
+            });
+            const result = await client.startTurnAndCollectText({
+                threadId: thread.threadId,
+                prompt: this.formatMessages(input),
+                model: modelId,
+                timeoutMs: this.timeoutMs,
+                ...runtimePolicy,
+            });
+            return {
+                text: result.text.trim(),
+                provider: 'openai-codex-subscription-dev',
+                modelId,
+                stopReason: result.stopReason,
+                latencyMs: Date.now() - startedAt,
+            };
+        }
+        finally {
+            if (shouldClose)
+                await client.close();
+        }
+    }
+    resolveModelId(input) {
+        const modelKey = String(input.modelKey || '').trim();
+        if (!modelKey)
+            throw new Error('No OpenAI Codex subscription-dev model selected.');
+        const modelId = this.modelKeyIds[modelKey];
+        if (!modelId)
+            throw new Error('No OpenAI Codex subscription-dev model configured for the selected model.');
+        return modelId;
+    }
+    formatMessages(input) {
+        return input.messages
+            .map((message) => `${message.role === 'assistant' ? 'Assistant' : 'User'}: ${message.content}`)
+            .join('\n\n');
+    }
+}
+function readStringPath(value, path) {
+    let cursor = value;
+    for (const segment of path) {
+        if (!cursor || typeof cursor !== 'object')
+            return '';
+        cursor = cursor[segment];
+    }
+    return typeof cursor === 'string' ? cursor.trim() : '';
+}
+function readTextPath(value, path) {
+    let cursor = value;
+    for (const segment of path) {
+        if (!cursor || typeof cursor !== 'object')
+            return '';
+        cursor = cursor[segment];
+    }
+    return typeof cursor === 'string' ? cursor : '';
+}
+function extractAgentText(messages) {
+    const deltaTextParts = [];
+    const finalAnswerTextParts = [];
+    const legacyCompletedTextParts = [];
+    for (const message of messages) {
+        if (message.method === 'item/agentMessage/delta') {
+            const text = readTextPath(message.params, ['delta'])
+                || readTextPath(message.params, ['text'])
+                || readTextPath(message.params, ['message', 'delta']);
+            if (text)
+                deltaTextParts.push(text);
+        }
+        if (message.method === 'item/completed') {
+            const itemType = readStringPath(message.params, ['item', 'type']);
+            if (itemType && itemType !== 'agentMessage')
+                continue;
+            const phase = readStringPath(message.params, ['item', 'phase']);
+            if (phase === 'commentary')
+                continue;
+            const text = readTextPath(message.params, ['item', 'text'])
+                || readTextPath(message.params, ['item', 'content', 'text']);
+            if (!text)
+                continue;
+            if (phase === 'final_answer')
+                finalAnswerTextParts.push(text);
+            else
+                legacyCompletedTextParts.push(text);
+        }
+    }
+    const textParts = finalAnswerTextParts.length > 0
+        ? finalAnswerTextParts
+        : legacyCompletedTextParts.length > 0
+            ? legacyCompletedTextParts
+            : deltaTextParts;
+    return textParts.join('').trim();
+}