@meistrari/agent-core 0.0.0 → 0.1.0

package/src/agents/codex/codex-run.ts

@@ -0,0 +1,404 @@
+import type {
+    AgentAuthor,
+    AgentPrompt,
+    AgentReasoningEffort,
+    AgentRunMetadata,
+    InterruptAgentCommand,
+    RespondUserInputAgentCommand,
+    SendPromptCommand,
+    StopAgentCommand,
+} from '../../protocol'
+import type { AgentEventDraft } from '../agent-event-stream'
+import type { AgentOperationOptions } from '../agent-operation'
+import type { AgentPromptAcceptance, AgentRun, AgentUserInputSubmission } from '../agent-run'
+import type { UserInputRequestInput, UserInputRequestStore } from '../user-input-request'
+import type { CodexEventMapperState } from './codex-event-mapper'
+import type { CodexJsonRpcClient } from './codex-json-rpc-client'
+import type { ClientRequestResponsesByMethod, CodexTurnStartParams, CodexUserInput } from './codex-protocol'
+import { AgentEventStream } from '../agent-event-stream'
+import { AgentDeliveryUnknownError, AgentNotAcceptedError, AgentPromptDeferredError, AgentRunStateError } from '../agent-runtime-error'
+import { deriveMessageId } from '../message-id'
+import { codexEffort, prepareCodexUserInput, toCodexUserInput } from './codex-command-mapper'
+import { CodexJsonRpcResponseError } from './codex-json-rpc-client'
+import { CodexSkillCatalog } from './codex-skill-catalog'
+import { catalogRepositorySkillRoots, workspaceSkillRoots } from './codex-skill-roots'
+import { CodexJsonRpcTransportClosedError } from './codex.errors'
+
+const codexReasoningSummary: CodexTurnStartParams['summary'] = 'auto'
+
+interface CodexRunAuthFailureInput {
+    reason: 'codex_auth_refresh_failed'
+    error: { message: string, name?: string, stack?: string }
+}
+
+interface PreparedCodexTurn {
+    input: CodexUserInput[]
+    commandId: string
+    origin: 'user' | 'supervisor'
+}
+
+interface CodexRunInput {
+    metadata: AgentRunMetadata
+    reasoningEffort?: AgentReasoningEffort
+    client: CodexJsonRpcClient
+    requestedCwd: string
+    workspaceRepositoryRoots: readonly string[]
+    registeredSkillRoots: readonly string[]
+    repositorySkillRoots: readonly string[]
+    reconcileInstructionBridge: (repositoryRoots: readonly string[]) => Promise<void>
+    userInputRequests: UserInputRequestStore
+    eventMapperState: CodexEventMapperState
+    abortSignal: AbortSignal
+    onStop: () => void
+}
+
+export class CodexRun implements AgentRun {
+    readonly events: AgentEventStream
+    readonly metadata: AgentRunMetadata
+    private readonly client: CodexJsonRpcClient
+    private readonly reasoningEffort: AgentReasoningEffort | undefined
+    private readonly onStop: () => void
+    private readonly userInputRequests: UserInputRequestStore
+    private readonly eventMapperState: CodexEventMapperState
+    private readonly skillCatalog: CodexSkillCatalog
+    private readonly requestedCwd: string
+    private readonly reconcileInstructionBridge: (repositoryRoots: readonly string[]) => Promise<void>
+    private workspaceRepositoryRoots: readonly string[]
+    private registeredSkillRoots: readonly string[]
+    private workspacePrepared = false
+    private stopped = false
+    private stoppingTask: Promise<void> | undefined
+    private activeTurnId: string | undefined
+    private readonly interruptingTurnIds = new Set<string>()
+
+    constructor(input: CodexRunInput) {
+        this.metadata = input.metadata
+        this.client = input.client
+        this.reasoningEffort = input.reasoningEffort
+        this.onStop = input.onStop
+        this.userInputRequests = input.userInputRequests
+        this.eventMapperState = input.eventMapperState
+        this.requestedCwd = input.requestedCwd
+        this.workspaceRepositoryRoots = [...input.workspaceRepositoryRoots]
+        this.registeredSkillRoots = input.registeredSkillRoots
+        this.reconcileInstructionBridge = input.reconcileInstructionBridge
+        this.events = new AgentEventStream({
+            provider: 'codex',
+            sessionId: input.metadata.sessionId,
+            providerSessionId: input.metadata.providerSessionId,
+        })
+        this.skillCatalog = new CodexSkillCatalog({
+            client: input.client,
+            cwd: input.metadata.cwd,
+            repositorySkillRoots: input.repositorySkillRoots,
+            emitSnapshot: draft => this.pushEvent(draft),
+            emitError: draft => this.pushEvent(draft),
+        })
+        input.abortSignal.addEventListener('abort', () => void this.stop({
+            type: 'agent.stop',
+            provider: 'codex',
+            sessionId: this.metadata.sessionId,
+            providerSessionId: this.metadata.providerSessionId,
+            reason: 'aborted',
+        }))
+    }
+
+    pushEvent(draft: AgentEventDraft): void {
+        if (this.stopped)
+            return
+        const decorated = this.userInputRequests.decorateTurnEnded(draft)
+        if (decorated.type === 'session.state.changed' && decorated.payload.state === 'idle' && this.userInputRequests.shouldHoldIdle()) {
+            this.events.push({ type: 'session.state.changed', payload: { state: 'waiting_for_user_input' } })
+            return
+        }
+        this.events.push(decorated)
+    }
+
+    async prepareWorkspace(options: AgentOperationOptions = {}): Promise<void> {
+        this.assertRunning()
+        if (this.workspacePrepared)
+            return
+
+        const abort = () => void this.stop({
+            type: 'agent.stop',
+            provider: 'codex',
+            sessionId: this.metadata.sessionId,
+            providerSessionId: this.metadata.providerSessionId,
+            reason: 'workspace_preparation_aborted',
+        }).catch(() => undefined)
+        if (options.signal?.aborted)
+            abort()
+        else
+            options.signal?.addEventListener('abort', abort, { once: true })
+        try {
+            options.signal?.throwIfAborted()
+            await this.client.request('skills/extraRoots/set', {
+                extraRoots: [...this.registeredSkillRoots],
+            })
+            options.signal?.throwIfAborted()
+        }
+        catch (error) {
+            await this.stop({
+                type: 'agent.stop',
+                provider: 'codex',
+                sessionId: this.metadata.sessionId,
+                providerSessionId: this.metadata.providerSessionId,
+                reason: 'workspace_preparation_failed',
+            }).catch(() => undefined)
+            options.signal?.throwIfAborted()
+            throw error
+        }
+        finally {
+            options.signal?.removeEventListener('abort', abort)
+        }
+        this.workspacePrepared = true
+        this.skillCatalog.requestRefresh()
+    }
+
+    async addWorkspaceRepositoryRoot(root: string, options: AgentOperationOptions = {}): Promise<void> {
+        this.assertRunning()
+        options.signal?.throwIfAborted()
+        if (this.workspaceRepositoryRoots.includes(root))
+            return
+        const repositoryRoots = [...this.workspaceRepositoryRoots, root]
+        await this.reconcileInstructionBridge(repositoryRoots)
+        options.signal?.throwIfAborted()
+        const registeredSkillRoots = workspaceSkillRoots(repositoryRoots)
+        await this.client.request('skills/extraRoots/set', { extraRoots: registeredSkillRoots })
+        this.workspaceRepositoryRoots = repositoryRoots
+        this.registeredSkillRoots = registeredSkillRoots
+        this.skillCatalog.setRepositorySkillRoots(catalogRepositorySkillRoots({
+            repositoryRoots,
+            requestedCwd: this.requestedCwd,
+            runtimeCwd: this.metadata.cwd,
+        }))
+        this.skillCatalog.requestRefresh()
+    }
+
+    requestSkillsRefresh(): void {
+        if (!this.stopped && this.workspacePrepared)
+            this.skillCatalog.requestRefresh()
+    }
+
+    async requestUserInput(input: UserInputRequestInput): Promise<{ requestId: string }> {
+        this.assertRunning()
+        const request = this.userInputRequests.create(input)
+        this.pushEvent(request.event)
+        return { requestId: request.requestId }
+    }
+
+    setActiveTurn(turnId: string | undefined): void {
+        this.activeTurnId = turnId
+    }
+
+    clearActiveTurn(): void {
+        this.activeTurnId = undefined
+        this.interruptingTurnIds.clear()
+    }
+
+    async failActiveTurnAndEndRun(input: CodexRunAuthFailureInput): Promise<void> {
+        if (this.stopped)
+            return
+        this.pushEvent({ type: 'error', payload: { message: 'Codex auth refresh failed.', fatal: false, source: 'provider', error: input.error } })
+        if (this.activeTurnId) {
+            this.pushEvent({
+                type: 'turn.ended',
+                turnId: this.activeTurnId,
+                actor: { type: 'main', actorId: 'main' },
+                payload: { status: 'failed', reason: input.reason, error: input.error },
+            })
+            this.activeTurnId = undefined
+            this.interruptingTurnIds.clear()
+        }
+        this.pushEvent({ type: 'session.state.changed', payload: { state: 'failed' } })
+        this.stopped = true
+        // Pinned Codex forwards preceding stdin lines before EOF, preserving the refresh error ordering.
+        await this.client.closeInputAndStop()
+        this.events.push({ type: 'session.ended', payload: { reason: 'failed', error: input.error } })
+        this.events.end()
+    }
+
+    async sendPrompt(command: SendPromptCommand, options: AgentOperationOptions = {}): Promise<AgentPromptAcceptance> {
+        this.assertCommandTargetsRun(command)
+        this.assertRunning()
+        // Released 0.145.0 accepts turn/start during an active turn by silently steering the input
+        // and answering a phantom turn id, so the next-vs-active race must be refused from adapter
+        // state before any request — nothing is prepared or retained.
+        this.deferNextWhileTurnActive(command.mode)
+        const prepared = await this.prepareTurn({
+            prompt: command.prompt,
+            commandId: command.commandId,
+            origin: command.origin,
+            author: command.author,
+            options,
+        })
+        // A turn/started fact may have reduced during attachment preparation.
+        this.deferNextWhileTurnActive(command.mode)
+
+        const activeTurnId = this.activeTurnId
+        if (command.mode === 'next' || !activeTurnId)
+            return await this.startPreparedTurn(prepared)
+
+        const clientUserMessageId = this.rememberPromptCommand(prepared.commandId, prepared.origin)
+        let result: ClientRequestResponsesByMethod['turn/steer']
+        try {
+            result = await this.client.request('turn/steer', {
+                threadId: this.metadata.providerSessionId,
+                expectedTurnId: activeTurnId,
+                input: prepared.input,
+                clientUserMessageId,
+            })
+        }
+        catch (error) {
+            if (isSteerNotAcceptedResponse(error)) {
+                throw new AgentPromptDeferredError({
+                    message: 'Codex rejected the steer at a turn boundary race.',
+                    cause: error,
+                })
+            }
+            throw mapTurnTransportLoss(error)
+        }
+        return { kind: 'turn', turnId: result.turnId, placement: 'steered' }
+    }
+
+    private deferNextWhileTurnActive(mode: SendPromptCommand['mode']): void {
+        if (mode !== 'next' || !this.activeTurnId)
+            return
+        throw new AgentPromptDeferredError({
+            message: 'Codex turn is active; a next prompt cannot start a turn.',
+        })
+    }
+
+    async respondUserInput(command: RespondUserInputAgentCommand, options: AgentOperationOptions = {}): Promise<AgentUserInputSubmission> {
+        this.assertCommandTargetsRun(command)
+        this.assertRunning()
+        options.signal?.throwIfAborted()
+        const resolved = this.userInputRequests.resolve(command)
+        if (!resolved)
+            return 'already_delivered'
+        if (resolved.event)
+            this.pushEvent(resolved.event)
+        const prepared = await this.prepareTurn({ prompt: resolved.prompt, commandId: command.commandId, options })
+        await this.startPreparedTurn(prepared)
+        this.userInputRequests.markDelivered(command.requestId)
+        return 'submitted'
+    }
+
+    async interrupt(command: InterruptAgentCommand, options: AgentOperationOptions = {}): Promise<void> {
+        this.assertCommandTargetsRun(command)
+        this.assertRunning()
+        options.signal?.throwIfAborted()
+        const turnId = command.turnId ?? this.activeTurnId
+        if (!turnId)
+            return
+        // codex never answers a second turn/interrupt for a turn already being interrupted; the duplicate await would hang forever.
+        if (this.interruptingTurnIds.has(turnId))
+            return
+        this.interruptingTurnIds.add(turnId)
+        try {
+            await this.client.request('turn/interrupt', { threadId: this.metadata.providerSessionId, turnId })
+        }
+        catch (error) {
+            this.interruptingTurnIds.delete(turnId)
+            throw mapTurnTransportLoss(error)
+        }
+    }
+
+    async stop(command: StopAgentCommand, options: AgentOperationOptions = {}): Promise<void> {
+        this.assertCommandTargetsRun(command)
+        if (this.stoppingTask) {
+            await this.stoppingTask
+            return
+        }
+        if (this.stopped)
+            return
+        options.signal?.throwIfAborted()
+        this.stopped = true
+        this.events.push({ type: 'session.state.changed', payload: { state: 'stopping' } })
+        this.onStop()
+        this.stoppingTask = (async () => {
+            await this.client.stop()
+            this.events.push({ type: 'session.ended', payload: { reason: 'stopped' } })
+            this.events.push({ type: 'session.state.changed', payload: { state: 'stopped' } })
+            this.events.end()
+        })()
+        await this.stoppingTask
+    }
+
+    private async prepareTurn({ prompt, commandId, origin = 'user', author, options }: { prompt: AgentPrompt, commandId: string, origin?: 'user' | 'supervisor', author?: AgentAuthor, options: AgentOperationOptions }): Promise<PreparedCodexTurn> {
+        options.signal?.throwIfAborted()
+        const mapperInput = { prompt, origin, author, senderContext: options.senderContext }
+        const input = options.inputAttachmentPreparation
+            ? await prepareCodexUserInput({ ...mapperInput, preparation: options.inputAttachmentPreparation })
+            : toCodexUserInput(mapperInput)
+        options.signal?.throwIfAborted()
+        return { input, commandId, origin }
+    }
+
+    private async startPreparedTurn(prepared: PreparedCodexTurn): Promise<AgentPromptAcceptance> {
+        const clientUserMessageId = this.rememberPromptCommand(prepared.commandId, prepared.origin)
+        let result: ClientRequestResponsesByMethod['turn/start']
+        try {
+            result = await this.client.request('turn/start', {
+                threadId: this.metadata.providerSessionId,
+                input: prepared.input,
+                cwd: this.metadata.cwd,
+                model: this.metadata.model,
+                effort: codexEffort(this.reasoningEffort),
+                summary: codexReasoningSummary,
+                approvalPolicy: 'never',
+                sandboxPolicy: { type: 'dangerFullAccess' },
+                clientUserMessageId,
+            })
+        }
+        catch (error) {
+            throw mapTurnTransportLoss(error)
+        }
+        this.activeTurnId = result.turn.id
+        return { kind: 'turn', turnId: result.turn.id, placement: 'started' }
+    }
+
+    private rememberPromptCommand(commandId: string, origin: 'user' | 'supervisor'): string {
+        const clientUserMessageId = deriveMessageId(commandId)
+        this.eventMapperState.promptCommandByClientUserMessageId.set(clientUserMessageId, { commandId, origin })
+        return clientUserMessageId
+    }
+
+    private assertRunning(): void {
+        if (this.stopped) {
+            throw new AgentRunStateError({ message: 'Codex run has stopped.' })
+        }
+    }
+
+    private assertCommandTargetsRun(command: { provider: string, sessionId: string, providerSessionId: string }): void {
+        if (command.provider !== 'codex' || command.sessionId !== this.metadata.sessionId || command.providerSessionId !== this.metadata.providerSessionId) {
+            throw new AgentRunStateError({ message: 'Command does not target this Codex run.' })
+        }
+    }
+}
+
+// Only the proven not-accepted fact may defer a steer: on the pinned runtime every turn/steer
+// -32600 means the input was not accepted. Other codes (-32001 included) are not blanket
+// overload/deferral facts and keep their honest provider error.
+function isSteerNotAcceptedResponse(error: unknown): error is CodexJsonRpcResponseError {
+    return error instanceof CodexJsonRpcResponseError && error.method === 'turn/steer' && error.responseErrorCode === -32600
+}
+
+// Transport loss on an input-carrying request maps to write-state truth: possible_write means the
+// input may already be in the provider thread (delivery unknown, never blind-retryable);
+// before_write is proven non-delivery and safe to retry. Anything else passes through unchanged.
+function mapTurnTransportLoss(error: unknown): unknown {
+    if (!(error instanceof CodexJsonRpcTransportClosedError))
+        return error
+    if (error.writeState === 'possible_write') {
+        return new AgentDeliveryUnknownError({
+            message: 'Codex app-server connection was lost after the input may have been written.',
+            cause: error,
+        })
+    }
+    return new AgentNotAcceptedError({
+        message: 'Codex app-server connection was closed before the input was written.',
+        recovery: { kind: 'retry', reason: 'provider_connection_lost' },
+        cause: error,
+    })
+}

package/src/agents/codex/codex-skill-catalog.ts

@@ -0,0 +1,158 @@
+import type { AgentSkill } from '../../protocol'
+import type { AgentEventDraft } from '../agent-event-stream'
+import type { CodexJsonRpcClient } from './codex-json-rpc-client'
+import type { ClientRequestResponsesByMethod } from './codex-protocol'
+import { createHash } from 'node:crypto'
+import { realpath } from 'node:fs/promises'
+import { isAbsolute, relative, sep } from 'node:path'
+
+type SessionSkillsUpdatedDraft = Extract<AgentEventDraft, { type: 'session.skills.updated' }>
+type ErrorDraft = Extract<AgentEventDraft, { type: 'error' }>
+type SkillsListResponse = ClientRequestResponsesByMethod['skills/list']
+
+interface CodexSkillCatalogInput {
+    client: CodexJsonRpcClient
+    cwd: string
+    repositorySkillRoots: readonly string[]
+    emitSnapshot: (draft: SessionSkillsUpdatedDraft) => void
+    emitError: (draft: ErrorDraft) => void
+}
+
+export class CodexSkillCatalog {
+    private readonly client: CodexJsonRpcClient
+    private readonly cwd: string
+    private repositorySkillRoots: readonly string[]
+    private readonly emitSnapshot: CodexSkillCatalogInput['emitSnapshot']
+    private readonly emitError: CodexSkillCatalogInput['emitError']
+    private refreshInFlight = false
+    private refreshRequested = false
+    private refreshScheduled = false
+    private lastSnapshot: string | undefined
+
+    constructor({ client, cwd, repositorySkillRoots, emitSnapshot, emitError }: CodexSkillCatalogInput) {
+        this.client = client
+        this.cwd = cwd
+        this.repositorySkillRoots = repositorySkillRoots
+        this.emitSnapshot = emitSnapshot
+        this.emitError = emitError
+    }
+
+    setRepositorySkillRoots(repositorySkillRoots: readonly string[]): void {
+        this.repositorySkillRoots = repositorySkillRoots
+    }
+
+    requestRefresh(): void {
+        this.refreshRequested = true
+        if (this.refreshInFlight || this.refreshScheduled)
+            return
+
+        this.refreshScheduled = true
+        const immediate = setImmediate(() => {
+            this.refreshScheduled = false
+            void this.refreshUntilCurrent()
+        })
+        immediate.unref?.()
+    }
+
+    private async refreshUntilCurrent(): Promise<void> {
+        if (this.refreshInFlight)
+            return
+
+        this.refreshInFlight = true
+        try {
+            while (this.refreshRequested) {
+                this.refreshRequested = false
+                await this.refreshWithOneRetry()
+            }
+        }
+        finally {
+            this.refreshInFlight = false
+            if (this.refreshRequested)
+                this.requestRefresh()
+        }
+    }
+
+    private async refreshWithOneRetry(): Promise<void> {
+        if (await this.refreshOnce())
+            return
+
+        // The force-reloaded retry also satisfies invalidations received during the failed request.
+        this.refreshRequested = false
+        await this.refreshOnce()
+    }
+
+    private async refreshOnce(): Promise<boolean> {
+        try {
+            const repositorySkillRoots = await repositorySkillRootAliases(this.repositorySkillRoots)
+            const response = await this.client.request('skills/list', {
+                cwds: [this.cwd],
+                forceReload: true,
+            })
+            const skills = availableSkills(response, repositorySkillRoots)
+            const snapshot = JSON.stringify(skills)
+            if (snapshot === this.lastSnapshot)
+                return true
+
+            this.lastSnapshot = snapshot
+            this.emitSnapshot({ type: 'session.skills.updated', payload: { skills } })
+            return true
+        }
+        catch {
+            this.emitError({
+                type: 'error',
+                payload: {
+                    message: 'Codex skills catalog refresh failed.',
+                    fatal: false,
+                    source: 'provider',
+                },
+            })
+            return false
+        }
+    }
+}
+
+async function repositorySkillRootAliases(roots: readonly string[]): Promise<string[]> {
+    const physicalRoots = (await Promise.allSettled(roots.map(async root => await realpath(root))))
+        .flatMap(result => result.status === 'fulfilled' ? [result.value] : [])
+    return [...new Set([...roots, ...physicalRoots])]
+}
+
+function availableSkills(response: SkillsListResponse, repositorySkillRoots: readonly string[]): AgentSkill[] {
+    return response.data.flatMap(entry => entry.skills
+        .filter(skill => skill.enabled)
+        .map(skill => ({
+            id: skillId(skill.path),
+            name: skill.name,
+            description: skill.description,
+            scope: canonicalSkillScope({ providerScope: skill.scope, path: skill.path, repositorySkillRoots }),
+        })))
+}
+
+function canonicalSkillScope(input: {
+    providerScope: SkillsListResponse['data'][number]['skills'][number]['scope']
+    path: string
+    repositorySkillRoots: readonly string[]
+}): AgentSkill['scope'] {
+    // Codex 0.145 labels runtime extra roots as user-scoped even when we registered them for selected repositories.
+    if (input.providerScope === 'user' && input.repositorySkillRoots.some(root => isPathInside(root, input.path)))
+        return 'repository'
+
+    switch (input.providerScope) {
+        case 'user':
+        case 'system':
+        case 'admin':
+            return input.providerScope
+        case 'repo':
+            return 'repository'
+    }
+}
+
+function isPathInside(root: string, candidate: string): boolean {
+    const pathFromRoot = relative(root, candidate)
+    return pathFromRoot === '' || (!isAbsolute(pathFromRoot) && pathFromRoot !== '..' && !pathFromRoot.startsWith(`..${sep}`))
+}
+
+function skillId(path: string): string {
+    const digest = createHash('sha256').update(`codex-skill\0${path}`).digest('hex')
+    return `skill_${digest}`
+}

package/src/agents/codex/codex-skill-roots.ts

@@ -0,0 +1,19 @@
+import { join, relative, resolve } from 'node:path'
+
+export function workspaceSkillRoots(repositoryRoots: readonly string[]): string[] {
+    return stableRepositoryRoots(repositoryRoots).map(root => join(root, '.agents', 'skills'))
+}
+
+export function catalogRepositorySkillRoots(input: {
+    repositoryRoots: readonly string[]
+    requestedCwd: string
+    runtimeCwd: string
+}): string[] {
+    const requestedRoots = workspaceSkillRoots(input.repositoryRoots)
+    const runtimeRepositoryRoots = input.repositoryRoots.map(root => resolve(input.runtimeCwd, relative(input.requestedCwd, root)))
+    return [...new Set([...requestedRoots, ...workspaceSkillRoots(runtimeRepositoryRoots)])]
+}
+
+export function stableRepositoryRoots(repositoryRoots: readonly string[]): string[] {
+    return [...new Set(repositoryRoots)].sort()
+}

package/src/agents/codex/codex-tool-mapper.ts

@@ -0,0 +1,55 @@
+import type { JsonValue } from '../../protocol'
+import type { AgentTool, AgentToolContext } from '../agent-tool'
+import type {
+    CodexDynamicToolCallParams,
+    CodexDynamicToolCallResponse,
+    CodexDynamicToolOutputContentItem,
+    CodexDynamicToolSpec,
+} from './codex-protocol'
+import { isAppError } from '../../errors'
+import { runAgentTool } from '../agent-tool-runner'
+
+const UNEXPECTED_TOOL_FAILURE_MESSAGE = 'The tool could not be executed.'
+
+export function toCodexDynamicTools(tools: readonly AgentTool[]): CodexDynamicToolSpec[] {
+    return tools.map(runtimeTool => ({
+        type: 'function',
+        name: runtimeTool.name,
+        description: runtimeTool.description,
+        inputSchema: runtimeTool.definition().inputSchema,
+    }))
+}
+
+export async function runCodexDynamicTool(input: {
+    tool: AgentTool
+    params: CodexDynamicToolCallParams
+    context: AgentToolContext
+}): Promise<CodexDynamicToolCallResponse> {
+    try {
+        const result = await runAgentTool({
+            tool: input.tool,
+            actor: input.params.threadId === input.context.providerSessionId ? 'main' : 'subagent',
+            rawInput: input.params.arguments as JsonValue,
+            context: input.context,
+        })
+
+        return {
+            success: result.success,
+            contentItems: result.content.map(toCodexToolContent),
+        }
+    }
+    catch (error) {
+        if (isAppError(error))
+            throw error
+        return {
+            success: false,
+            contentItems: [{ type: 'inputText', text: UNEXPECTED_TOOL_FAILURE_MESSAGE }],
+        }
+    }
+}
+
+function toCodexToolContent(content: { type: 'text', text: string } | { type: 'image', data: string, mimeType: string }): CodexDynamicToolOutputContentItem {
+    if (content.type === 'text')
+        return { type: 'inputText', text: content.text }
+    return { type: 'inputImage', imageUrl: `data:${content.mimeType};base64,${content.data}` }
+}