@tduyng/pi-opencode-z 0.0.0-stage → 0.0.2

package/src/stream.ts

@@ -0,0 +1,1013 @@
+import { writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import { Validator } from 'ata-validator'
+import { t } from 'ata-validator/t'
+
+import {
+    calculateCost,
+    createAssistantMessageEventStream,
+    type Api,
+    type AssistantMessage,
+    type AssistantMessageEventStream,
+    type ImageContent,
+    type Message,
+    type Model,
+    type SimpleStreamOptions,
+    type TextContent,
+    type Tool,
+    type ToolCall
+} from '@earendil-works/pi-ai'
+import type { ToolAnnotations } from '@earendil-works/pi-coding-agent'
+
+import { api, type OpenCodeEvent } from './client.js'
+import type {
+    JsonObject,
+    JsonValue,
+    McpContent,
+    McpResult,
+    McpServerHandle,
+    McpToolAnnotations,
+    McpToolDef
+} from './mcp.js'
+import { variantFor } from './models.js'
+import {
+    BRIDGE_AGENT,
+    bridgeSession,
+    createSessionStore,
+    ensureProjectDir,
+    findByOpencodeId,
+    messageFingerprint,
+    releaseParked,
+    resetOpencodeSession,
+    TOOL_PREFIX,
+    toolsKey,
+    type BridgeSession,
+    type BridgeSessionStore,
+    type TokenTotals
+} from './session.js'
+const isString = new Validator(t.string()).isValidObject
+const isNumber = new Validator(t.number()).isValidObject
+
+const DEFAULT_TURN_TIMEOUT_MS = 300_000
+const PARK_GRACE_MS = 15_000
+const TOOLS_RELOAD_MS = 250
+const MAX_NUDGES = 2
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
+
+export type BridgeContext = { messages: Message[] }
+
+export type TranscriptState = {
+    systemPrompt: string
+    tools: Tool[]
+    conversation: Message[]
+}
+
+export function replayTranscript(messages: Message[]): TranscriptState {
+    const sections = new Map<string, string>()
+    const tools = new Map<string, Tool>()
+    const conversation: Message[] = []
+    const additions: string[] = []
+    let base = ''
+    let leading = true
+
+    for (const message of messages) {
+        if (message.role !== 'system') {
+            conversation.push(message)
+            continue
+        }
+        const text = contentText(message.content)
+        if (leading) {
+            base = text
+            leading = false
+        } else if (text) {
+            additions.push(text)
+        }
+        for (const [name, value] of Object.entries(message.sections ?? {})) {
+            if (value === null) sections.delete(name)
+            else sections.set(name, value)
+        }
+        for (const tool of message.toolsAdded ?? []) tools.set(tool.name, tool)
+        for (const reference of message.toolsRemoved ?? []) tools.delete(reference.name)
+    }
+
+    return {
+        systemPrompt: [base, ...sections.values(), ...additions].filter(Boolean).join('\n\n'),
+        tools: [...tools.values()],
+        conversation
+    }
+}
+const PROVIDER_ID = 'opencode'
+
+type SessionListener = (event: OpenCodeEvent) => void
+type RecoveryReason = 'refused' | 'empty'
+
+export type BridgeRuntime = {
+    sessions: BridgeSessionStore
+    listeners: Map<string, SessionListener>
+    mcp?: McpServerHandle
+    toolHints?: ToolHints
+}
+
+export type ToolHints = (name: string) => McpToolAnnotations | undefined
+
+export const NO_TOOL_HINTS: ToolHints = () => undefined
+
+export function createBridgeRuntime(): BridgeRuntime {
+    return { sessions: createSessionStore(), listeners: new Map() }
+}
+
+export function toolHintsFrom(getAllTools: () => { name: string; annotations?: ToolAnnotations }[]): ToolHints {
+    return (name) => getAllTools().find((tool) => tool.name === name)?.annotations
+}
+
+export function attachMcpServer(runtime: BridgeRuntime, handle: McpServerHandle): void {
+    runtime.mcp = handle
+}
+
+type BridgeEvent =
+    | { type: 'session.step.started'; sessionID: string }
+    | { type: 'session.step.streamed'; sessionID: string }
+    | { type: 'session.execution.succeeded'; sessionID: string }
+    | { type: 'session.reasoning.delta' | 'session.text.delta'; sessionID: string; delta: string }
+    | { type: 'session.reasoning.ended' | 'session.text.ended'; sessionID: string; text: string }
+    | { type: 'session.tool.input.started'; sessionID: string; name: string; id?: string }
+    | { type: 'session.tool.success' | 'session.tool.failed'; sessionID: string; id: string }
+    | {
+          type: 'session.step.failed' | 'session.execution.interrupted' | 'session.execution.failed'
+          sessionID: string
+          failure?: string
+      }
+    | { type: 'session.step.ended'; sessionID: string; tokens?: TokenTotals }
+    | { type: 'permission.asked'; sessionID: string; id: string; action: string }
+    | { type: 'bridge.tool.parked'; sessionID: string; callId: string }
+    | { type: 'other'; sessionID: string; failure?: string }
+
+function decodeEvent(event: OpenCodeEvent): BridgeEvent {
+    const cached = decodedEvents.get(event)
+    if (cached !== undefined) return cached
+    const decoded = decodeUncached(event)
+    decodedEvents.set(event, decoded)
+    return decoded
+}
+
+const decodedEvents = new WeakMap<OpenCodeEvent, BridgeEvent>()
+
+function decodeUncached(event: OpenCodeEvent): BridgeEvent {
+    const data = event.data ?? {}
+    const sessionID = isString(data['sessionID']) ? data['sessionID'] : ''
+    switch (event.type) {
+        case 'session.step.started':
+        case 'session.step.streamed':
+        case 'session.execution.succeeded':
+            return { type: event.type, sessionID }
+        case 'session.reasoning.delta':
+        case 'session.text.delta': {
+            const delta = data['delta']
+            if (isString(delta)) return { type: event.type, sessionID, delta }
+            break
+        }
+        case 'session.reasoning.ended':
+        case 'session.text.ended': {
+            const text = data['text']
+            return { type: event.type, sessionID, text: isString(text) ? text : '' }
+        }
+        case 'session.tool.input.started': {
+            const name = data['name']
+            if (!isString(name)) break
+            const id = data['id']
+            return { type: event.type, sessionID, name, id: isString(id) ? id : undefined }
+        }
+        case 'session.tool.success':
+        case 'session.tool.failed': {
+            const id = data['id']
+            if (isString(id)) return { type: event.type, sessionID, id }
+            break
+        }
+        case 'session.step.failed':
+        case 'session.execution.interrupted':
+        case 'session.execution.failed':
+            return { type: event.type, sessionID, failure: failureOf(event) }
+        case 'session.step.ended':
+            return { type: event.type, sessionID, tokens: decodeStepTokens(event) }
+        case 'permission.asked': {
+            const id = data['id']
+            if (!isString(id)) break
+            const action = data['action']
+            return { type: event.type, sessionID, id, action: isString(action) ? action : 'unknown' }
+        }
+        case 'bridge.tool.parked': {
+            const callId = data['callId']
+            if (isString(callId)) return { type: event.type, sessionID, callId }
+            break
+        }
+    }
+    return { type: 'other', sessionID, failure: failureOf(event) }
+}
+
+function failureOf(event: OpenCodeEvent): string | undefined {
+    const data = event.data
+    const errorMessage = data?.['errorMessage']
+    const message = data?.['message']
+    const error = data?.['error']
+    const direct =
+        (isString(errorMessage) && errorMessage.trim()) ||
+        (isString(message) && message.trim()) ||
+        (isString(error) && error.trim())
+    if (direct) return direct
+    if (!isErrorObjectSchema(error)) return undefined
+    const parsed = error
+    return parsed.message?.trim() || parsed.errorMessage?.trim() || parsed.reason?.trim() || undefined
+}
+
+function isObject(value: unknown): value is JsonObject {
+    return isJsonObjectSchema(value)
+}
+
+function decodeStepTokens(event: OpenCodeEvent): TokenTotals | undefined {
+    const tokens = event.data?.['tokens']
+    if (!tokens) return undefined
+    if (Array.isArray(tokens)) return emptyTokenTotals()
+    if (!isObject(tokens)) return undefined
+    const cache = isObject(tokens['cache']) ? tokens['cache'] : undefined
+    return {
+        input: tokenCount(tokens['input']),
+        output: tokenCount(tokens['output']) + tokenCount(tokens['reasoning']),
+        cacheRead: tokenCount(cache?.['read']),
+        cacheWrite: tokenCount(cache?.['write'])
+    }
+}
+
+function tokenCount(value: JsonValue | undefined): number {
+    return isNumber(value) && Number.isFinite(value) && value > 0 ? value : 0
+}
+
+function emptyTokenTotals(): TokenTotals {
+    return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }
+}
+
+export function routeEvent(runtime: BridgeRuntime, event: OpenCodeEvent): void {
+    const decoded = decodeEvent(event)
+    if (!decoded.sessionID) return
+
+    if (decoded.type === 'session.step.ended') {
+        const session = findByOpencodeId(runtime.sessions, decoded.sessionID)
+        if (session) parkLateUsage(session, decoded.tokens)
+        return
+    }
+
+    if (decoded.type === 'permission.asked') {
+        const { sessionID, id, action } = decoded
+        void answerPermission(runtime.sessions, sessionID, id, action).catch(() => undefined)
+        return
+    }
+    runtime.listeners.get(decoded.sessionID)?.(event)
+}
+
+async function answerPermission(
+    sessions: BridgeSessionStore,
+    sessionId: string,
+    requestId: string,
+    action: string
+): Promise<void> {
+    const session = findByOpencodeId(sessions, sessionId)
+    if (!session) return
+    if (session.answeredPermissions.has(requestId)) return
+
+    const reply: { decision: 'once' | 'reject'; message?: string } = action.startsWith(TOOL_PREFIX)
+        ? { decision: 'once' }
+        : {
+              decision: 'reject',
+              message: `Your built-in ${action} tool is disabled here. Call the matching pi_ tool instead.`
+          }
+    session.answeredPermissions.add(requestId)
+    if (reply.decision === 'reject') session.refusedTools.push(action)
+    const send = () => api('POST', `/api/session/${sessionId}/permission/${requestId}/reply`, reply)
+    try {
+        await send()
+    } catch {
+        try {
+            await send()
+        } catch {
+            session.answeredPermissions.delete(requestId)
+        }
+    }
+}
+
+function parkLateUsage(session: BridgeSession, step: TokenTotals | undefined): void {
+    if (!step) return
+    session.lateUsage.input += step.input
+    session.lateUsage.output += step.output
+    session.lateUsage.cacheRead += step.cacheRead
+    session.lateUsage.cacheWrite += step.cacheWrite
+    session.latestStep = step
+}
+
+function takeLateUsage(session: BridgeSession | undefined, usage: AssistantMessage['usage']): void {
+    if (!session) return
+    usage.input += session.lateUsage.input
+    usage.output += session.lateUsage.output
+    usage.cacheRead += session.lateUsage.cacheRead
+    usage.cacheWrite += session.lateUsage.cacheWrite
+    const step = session.latestStep
+    usage.totalTokens = step.input + step.output + step.cacheRead + step.cacheWrite
+    session.lateUsage = emptyTokenTotals()
+    session.latestStep = emptyTokenTotals()
+}
+
+function emptyUsage(): AssistantMessage['usage'] {
+    return {
+        input: 0,
+        output: 0,
+        cacheRead: 0,
+        cacheWrite: 0,
+        totalTokens: 0,
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 }
+    }
+}
+
+function contentText(content: string | (TextContent | ImageContent)[]): string {
+    if (Array.isArray(content)) {
+        return content
+            .map((part) => (part.type === 'text' ? part.text : `[image: ${part.mimeType}]`))
+            .join('\n')
+            .trim()
+    }
+    return content
+}
+
+function imagesIn(messages: Message[]): ImageContent[] {
+    const images: ImageContent[] = []
+    for (const message of messages) {
+        if (message.role === 'assistant' || !Array.isArray(message.content)) continue
+        for (const part of message.content) if (part.type === 'image') images.push(part)
+    }
+    return images
+}
+
+export function serializeHistory(messages: Message[]): string {
+    const parts: string[] = []
+    for (const message of messages) {
+        if (message.role === 'user') {
+            parts.push(`USER:\n${contentText(message.content)}`)
+            continue
+        }
+        if (message.role === 'toolResult') {
+            parts.push(
+                `RESULT of ${TOOL_PREFIX}${message.toolName}${message.isError ? ' (failed)' : ''}:\n${contentText(message.content)}`
+            )
+            continue
+        }
+        const rendered = Array.isArray(message.content)
+            ? message.content
+                  .map((part) => {
+                      if (part.type === 'text') return part.text
+                      if (part.type === 'thinking') return ''
+                      return `CALLED ${TOOL_PREFIX}${part.name}(${JSON.stringify(part.arguments)})`
+                  })
+                  .filter(Boolean)
+                  .join('\n')
+            : message.content
+        if (rendered) parts.push(`ASSISTANT:\n${rendered}`)
+    }
+    return parts.join('\n\n')
+}
+
+export function preamble(systemPrompt: string): string {
+    return systemPrompt.trim() ? `<system>\n${systemPrompt.trim()}\n</system>` : ''
+}
+
+const LEAKED_CALL_MARKER = /<\/?(?:invoke|parameter|tool_call)\b/
+
+function leakedToolCall(text: string): boolean {
+    return LEAKED_CALL_MARKER.test(text.replaceAll('\u200b', '')) && text.includes(TOOL_PREFIX)
+}
+
+function refusalNudge(refused: string[]): string {
+    const names = [...new Set(refused)].join(', ')
+    return [
+        `Your built-in ${names} call was refused and opencode stopped the step. Built-in tools are disabled here.`,
+        'Redo that work with the matching pi_ tool, such as pi_read, pi_bash, pi_edit or pi_write.'
+    ].join('\n')
+}
+
+const EMPTY_TURN_NUDGE = [
+    'Your turn ended after reasoning without a tool call or final answer.',
+    'Call one of the declared pi_ tools now. A functions. namespace label is not part of the tool name.'
+].join('\n')
+
+export function mcpToolDefs(tools: Tool[], hints: ToolHints): McpToolDef[] {
+    return tools.map((tool) => {
+        const annotations = hints(tool.name)
+        const def: McpToolDef = {
+            name: tool.name,
+            description: tool.description,
+            inputSchema: mcpInputSchema(tool.parameters as JsonObject)
+        }
+        if (annotations) def.annotations = annotations
+        return def
+    })
+}
+
+const JsonObjectSchema = t.object({}, { additionalProperties: true })
+const isJsonObjectSchema = new Validator(JsonObjectSchema).isValidObject
+const RequiredArraySchema = t.array(t.string())
+const isRequiredArraySchema = new Validator(RequiredArraySchema).isValidObject
+const RequiredObjectSchema = t.object({}, { additionalProperties: true })
+const isRequiredObjectSchema = new Validator(RequiredObjectSchema).isValidObject
+
+export function mcpInputSchema(parameters: JsonObject | undefined): JsonObject {
+    if (!isJsonObjectSchema(parameters)) return { type: 'object' }
+    const parsed = parameters
+    const required = parsed['required']
+    if (isRequiredArraySchema(required)) {
+        return parsed as JsonObject
+    }
+    if (isRequiredObjectSchema(required)) {
+        return { ...parsed, required: Object.keys(required) } as JsonObject
+    }
+    return { ...parsed, required: [] } as JsonObject
+}
+
+function piToolResult(message: { content: (TextContent | ImageContent)[]; isError: boolean }): McpResult {
+    const content: McpContent[] = message.content.map((part) =>
+        part.type === 'text'
+            ? { type: 'text', text: part.text }
+            : { type: 'image', data: part.data, mimeType: part.mimeType }
+    )
+    return {
+        content: content.length > 0 ? content : [{ type: 'text', text: '(no output)' }],
+        isError: message.isError
+    }
+}
+
+function turnTimeoutMs(value: number | undefined): number {
+    return value !== undefined && Number.isFinite(value) && value > 0 ? value : DEFAULT_TURN_TIMEOUT_MS
+}
+
+function transcriptDrifted(session: BridgeSession, messages: Message[]): boolean {
+    if (messages.length < session.fingerprints.length) return true
+    for (let index = 0; index < session.fingerprints.length; index++) {
+        const message = messages[index]
+        if (!message || session.fingerprints[index] !== messageFingerprint(message)) return true
+    }
+    return false
+}
+
+export function streamOpenCodeBridge(
+    runtime: BridgeRuntime,
+    model: Model<Api>,
+    context: BridgeContext,
+    options?: SimpleStreamOptions
+): AssistantMessageEventStream {
+    const stream = createAssistantMessageEventStream()
+    void runTurn(runtime, stream, model, context, options)
+    return stream
+}
+
+async function runTurn(
+    runtime: BridgeRuntime,
+    stream: AssistantMessageEventStream,
+    model: Model<Api>,
+    context: BridgeContext,
+    options?: SimpleStreamOptions
+): Promise<void> {
+    const output: AssistantMessage = {
+        role: 'assistant',
+        content: [],
+        api: model.api,
+        provider: model.provider,
+        model: model.id,
+        usage: emptyUsage(),
+        stopReason: 'stop',
+        timestamp: Date.now()
+    }
+
+    const piSessionId = options?.sessionId || `ephemeral-${Math.random().toString(36).slice(2)}`
+    const session = bridgeSession(runtime.sessions, piSessionId)
+    let listenerKey: string | undefined
+    let timer: ReturnType<typeof setTimeout> | undefined
+    let onAbort: (() => void) | undefined
+
+    try {
+        if (options?.signal?.aborted) {
+            output.stopReason = 'aborted'
+            output.errorMessage = 'opencode request aborted before dispatch'
+            stream.push({ type: 'error', reason: 'aborted', error: output })
+            stream.end()
+            return
+        }
+        if (!runtime.mcp) throw new Error('the opencode bridge MCP server is not running')
+        stream.push({ type: 'start', partial: output })
+
+        const transcript = replayTranscript(context.messages)
+        session.tools = transcript.tools
+        runtime.mcp.register(session.token, {
+            listTools: () => mcpToolDefs(session.tools, runtime.toolHints ?? NO_TOOL_HINTS),
+            callTool: (name, args) => parkToolCall(runtime, session, name, args)
+        })
+
+        const variant = variantFor(model.thinkingLevelMap, options?.reasoning)
+        const messages = transcript.conversation
+
+        if (session.opencodeSessionId && (session.modelId !== model.id || transcriptDrifted(session, messages))) {
+            await resetOpencodeSession(session)
+        }
+
+        if (session.opencodeSessionId && session.toolsKey !== toolsKey(transcript.tools)) {
+            const refreshed = await runtime.mcp.notifyToolsChanged(session.token)
+            if (refreshed) await sleep(TOOLS_RELOAD_MS)
+            else await resetOpencodeSession(session)
+        }
+
+        const tail = messages.slice(session.syncedCount)
+        const resuming = canResume(session, tail)
+
+        if (!resuming && session.opencodeSessionId && tail.some((message) => message.role !== 'user')) {
+            releaseParked(session, 'Pi did not complete the previous call. Rebuilding the opencode session.')
+            await api('POST', `/api/session/${session.opencodeSessionId}/interrupt`).catch(() => undefined)
+            await resetOpencodeSession(session)
+        }
+
+        if (!resuming && session.parked.size > 0) {
+            releaseParked(session, 'Pi did not run this call. Ask again if you still need it.')
+            await api('POST', `/api/session/${session.opencodeSessionId}/interrupt`).catch(() => undefined)
+            await resetOpencodeSession(session)
+        }
+
+        const opencodeSessionId = resuming
+            ? session.opencodeSessionId
+            : await ensureOpencodeSession(runtime, session, model, variant)
+        if (!opencodeSessionId) throw new Error('could not open an opencode session')
+
+        listenerKey = opencodeSessionId
+        let nudges = 0
+        const turn = createTurn(
+            runtime.sessions,
+            stream,
+            output,
+            model,
+            (reason) => {
+                if (nudges >= MAX_NUDGES || options?.signal?.aborted) return false
+                const refused = session.refusedTools
+                if (reason === 'refused' && refused.length === 0) return false
+                nudges++
+                session.refusedTools = []
+                if (reason === 'refused') {
+                    releaseParked(session, 'opencode stopped this step; the call was dropped.')
+                }
+                const text = reason === 'empty' ? EMPTY_TURN_NUDGE : refusalNudge(refused)
+                void (async () => {
+                    try {
+                        await api('POST', `/api/session/${opencodeSessionId}/prompt`, { text })
+                    } catch (nudgeError) {
+                        turn.fail(nudgeError instanceof Error ? nudgeError.message : String(nudgeError))
+                    }
+                })()
+                return true
+            },
+            options?.signal
+        )
+        runtime.listeners.set(listenerKey, turn.handle)
+
+        const onAbortTurn = () => {
+            const sessionId = session.opencodeSessionId
+            if (sessionId) {
+                void api('POST', `/api/session/${sessionId}/interrupt`).catch(() => undefined)
+            }
+            turn.fail('opencode request aborted')
+        }
+        onAbort = onAbortTurn
+        if (options?.signal?.aborted) {
+            onAbortTurn()
+        } else {
+            options?.signal?.addEventListener('abort', onAbortTurn, { once: true })
+        }
+        const limit = turnTimeoutMs(options?.timeoutMs)
+        timer = setTimeout(() => {
+            if (session.opencodeSessionId) {
+                void api('POST', `/api/session/${session.opencodeSessionId}/interrupt`).catch(() => undefined)
+            }
+            turn.fail(
+                `opencode did not answer within ${Math.round(limit / 1000)}s (model ${model.id}). ` +
+                    'The bridge dropped the stuck session, so just retry the prompt.'
+            )
+        }, limit)
+
+        if (resuming) {
+            for (const [callId, parked] of session.parked) {
+                const result = tail.find((message) => message.role === 'toolResult' && message.toolCallId === callId)
+                parked.resolve(
+                    result && result.role === 'toolResult'
+                        ? piToolResult(result)
+                        : { content: [{ type: 'text', text: '(no result)' }], isError: true }
+                )
+            }
+            session.parked.clear()
+        } else {
+            if (variant && session.variant !== variant) {
+                await api('POST', `/api/session/${opencodeSessionId}/model`, {
+                    model: { providerID: PROVIDER_ID, id: model.id, variant }
+                }).catch(() => undefined)
+                session.variant = variant
+            }
+            await sendPrompt(session, transcript, tail, opencodeSessionId)
+        }
+
+        await turn.done
+
+        if (output.stopReason === 'error' || output.stopReason === 'aborted') {
+            releaseParked(session, 'The bridge stopped before this call completed.')
+            if (session.opencodeSessionId) {
+                await api('POST', `/api/session/${session.opencodeSessionId}/interrupt`).catch(() => undefined)
+            }
+        } else {
+            session.syncedCount = syncedCountAfter(messages, output)
+            session.fingerprints = messages.map(messageFingerprint)
+            session.modelId = model.id
+            session.toolsKey = toolsKey(transcript.tools)
+        }
+    } catch (error) {
+        output.stopReason = options?.signal?.aborted ? 'aborted' : 'error'
+        output.errorMessage = error instanceof Error ? error.message : String(error)
+        if (output.content.length === 0) output.content.push({ type: 'text', text: output.errorMessage })
+        releaseParked(session, 'The bridge turn failed.')
+        if (session.opencodeSessionId) {
+            await api('POST', `/api/session/${session.opencodeSessionId}/interrupt`).catch(() => undefined)
+        }
+        stream.push({ type: 'error', reason: output.stopReason, error: output })
+        stream.end()
+    } finally {
+        if (timer) clearTimeout(timer)
+        if (listenerKey) runtime.listeners.delete(listenerKey)
+        if (onAbort) options?.signal?.removeEventListener('abort', onAbort)
+    }
+}
+
+export function syncedCountAfter(messages: Message[], output: AssistantMessage): number {
+    return output.content.length > 0 ? messages.length + 1 : messages.length
+}
+
+function canResume(session: BridgeSession, tail: Message[]): boolean {
+    if (!session.opencodeSessionId || session.parked.size === 0) return false
+    if (tail.some((message) => message.role === 'user')) return false
+    const answered = new Set(
+        tail.filter((message) => message.role === 'toolResult').map((message) => message.toolCallId)
+    )
+    for (const callId of session.parked.keys()) if (!answered.has(callId)) return false
+    return true
+}
+
+async function ensureOpencodeSession(
+    runtime: BridgeRuntime,
+    session: BridgeSession,
+    model: Model<Api>,
+    variant: string | undefined
+): Promise<string> {
+    if (session.opencodeSessionId) return session.opencodeSessionId
+    if (!runtime.mcp) throw new Error('the opencode bridge MCP server is not running')
+
+    const dir = await ensureProjectDir(session, runtime.mcp.urlFor(session.token))
+    const created = await api<{ data?: { id?: string } }>('POST', '/api/session', {
+        title: 'pi bridge',
+        agent: BRIDGE_AGENT,
+        model: { providerID: PROVIDER_ID, id: model.id, variant },
+        location: { directory: dir }
+    })
+    const id = created?.data?.id
+    if (!id) throw new Error('opencode did not return a session id')
+    session.opencodeSessionId = id
+    session.variant = variant
+    return id
+}
+
+async function sendPrompt(
+    session: BridgeSession,
+    transcript: TranscriptState,
+    tail: Message[],
+    opencodeSessionId: string
+): Promise<void> {
+    const firstPrompt = session.syncedCount === 0
+    const blocks: string[] = []
+
+    if (firstPrompt) {
+        blocks.push(preamble(transcript.systemPrompt))
+        const history = serializeHistory(transcript.conversation)
+        if (history) blocks.push(history)
+    } else {
+        if (transcript.systemPrompt !== (session.systemPrompt ?? '')) {
+            blocks.push(`<system-update>\n${transcript.systemPrompt.trim()}\n</system-update>`)
+        }
+        const fresh = tail
+            .filter((message) => message.role === 'user')
+            .map((message) => (message.role === 'user' ? contentText(message.content) : ''))
+        blocks.push(...fresh.filter(Boolean))
+    }
+    session.refusedTools = []
+
+    const files = await writeImages(session, imagesIn(tail))
+    const text = blocks.filter(Boolean).join('\n\n') || '(continue)'
+    const payload = { text, files: files.length > 0 ? files : undefined }
+    await api('POST', `/api/session/${opencodeSessionId}/prompt`, payload)
+    session.systemPrompt = transcript.systemPrompt
+}
+
+async function writeImages(session: BridgeSession, images: ImageContent[]): Promise<{ uri: string }[]> {
+    if (images.length === 0 || !session.dir) return []
+    const written: { uri: string }[] = []
+    for (const [index, image] of images.entries()) {
+        const extension = image.mimeType.split('/')[1]?.replace(/[^a-z0-9]/gi, '') || 'bin'
+        const path = join(session.dir, `image-${Date.now()}-${index}.${extension}`)
+        await writeFile(path, Buffer.from(image.data, 'base64'))
+        written.push({ uri: `file://${path}` })
+    }
+    return written
+}
+
+function parkToolCall(
+    runtime: BridgeRuntime,
+    session: BridgeSession,
+    prefixed: string,
+    args: JsonObject
+): Promise<McpResult> {
+    const name = prefixed.startsWith(TOOL_PREFIX) ? prefixed.slice(TOOL_PREFIX.length) : prefixed
+    if (!session.tools.some((tool) => tool.name === name)) {
+        return Promise.resolve({
+            content: [{ type: 'text', text: `${name} is not available in this session anymore.` }],
+            isError: true
+        })
+    }
+    const callId = `oc_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`
+    return new Promise<McpResult>((resolve) => {
+        session.parked.set(callId, { name, args, resolve })
+        const owner = session.opencodeSessionId ?? ''
+        const notify = runtime.listeners.get(owner)
+        if (!notify) {
+            session.parked.delete(callId)
+            resolve({
+                content: [{ type: 'text', text: 'The bridge turn ended before this call arrived.' }],
+                isError: true
+            })
+            return
+        }
+        notify({ type: 'bridge.tool.parked', data: { callId, sessionID: owner } })
+    })
+}
+
+type Turn = {
+    handle: SessionListener
+    done: Promise<void>
+    fail(message: string): void
+}
+
+export function createTurn(
+    sessions: BridgeSessionStore,
+    stream: AssistantMessageEventStream,
+    output: AssistantMessage,
+    model: Model<Api>,
+    recover: (reason: RecoveryReason) => boolean = () => false,
+    signal?: AbortSignal
+): Turn {
+    let settle: () => void = () => undefined
+    const done = new Promise<void>((resolve) => {
+        settle = resolve
+    })
+
+    let textIndex: number | undefined
+    let thinkingIndex: number | undefined
+    let finished = false
+    let stepStreamed = false
+    let owner: BridgeSession | undefined
+    const piCalls = new Map<string, string>()
+    const parkedCallIds: string[] = []
+    const ready = () => stepStreamed && piCalls.size > 0 && parkedCallIds.length >= piCalls.size
+    let failure: string | undefined
+    let parkTimer: ReturnType<typeof setTimeout> | undefined
+    const clearPark = () => {
+        if (!parkTimer) return
+        clearTimeout(parkTimer)
+        parkTimer = undefined
+    }
+    const resetExecution = () => {
+        stepStreamed = false
+        piCalls.clear()
+        parkedCallIds.length = 0
+        failure = undefined
+        clearPark()
+    }
+
+    const openText = () => {
+        if (textIndex !== undefined) return textIndex
+        textIndex = output.content.length
+        output.content.push({ type: 'text', text: '' })
+        stream.push({ type: 'text_start', contentIndex: textIndex, partial: output })
+        return textIndex
+    }
+    const closeText = (text: string) => {
+        if (textIndex === undefined) return
+        const block = output.content[textIndex]
+        if (block?.type === 'text') block.text = text
+        stream.push({ type: 'text_end', contentIndex: textIndex, content: text, partial: output })
+        textIndex = undefined
+    }
+    const openThinking = () => {
+        if (thinkingIndex !== undefined) return thinkingIndex
+        thinkingIndex = output.content.length
+        output.content.push({ type: 'thinking', thinking: '' })
+        stream.push({ type: 'thinking_start', contentIndex: thinkingIndex, partial: output })
+        return thinkingIndex
+    }
+    const closeThinking = (text: string) => {
+        if (thinkingIndex === undefined) return
+        const block = output.content[thinkingIndex]
+        if (block?.type === 'thinking') block.thinking = text
+        stream.push({ type: 'thinking_end', contentIndex: thinkingIndex, content: text, partial: output })
+        thinkingIndex = undefined
+    }
+
+    const finish = (reason: 'stop' | 'toolUse') => {
+        if (finished) return
+        finished = true
+        clearPark()
+        takeLateUsage(owner, output.usage)
+        closeText(textIndex !== undefined ? textOf(output, textIndex) : '')
+        closeThinking(thinkingIndex !== undefined ? thinkingOf(output, thinkingIndex) : '')
+        calculateCost(model, output.usage)
+        output.stopReason = reason
+        stream.push({ type: 'done', reason, message: output })
+        stream.end()
+        settle()
+    }
+
+    const fail = (message: string) => {
+        if (finished) return
+        finished = true
+        clearPark()
+        takeLateUsage(owner, output.usage)
+        const reason = signal?.aborted ? 'aborted' : 'error'
+        output.stopReason = reason
+        output.errorMessage = message
+        if (output.content.length === 0) output.content.push({ type: 'text', text: message })
+        stream.push({ type: 'error', reason, error: output })
+        stream.end()
+        settle()
+    }
+
+    const emitToolCalls = (session: BridgeSession) => {
+        clearPark()
+        for (const callId of parkedCallIds) {
+            const parked = session.parked.get(callId)
+            if (!parked) continue
+            const toolCall: ToolCall = {
+                type: 'toolCall',
+                id: callId,
+                name: parked.name,
+                arguments: parked.args
+            }
+            const contentIndex = output.content.length
+            output.content.push(toolCall)
+            stream.push({ type: 'toolcall_start', contentIndex, partial: output })
+            stream.push({
+                type: 'toolcall_delta',
+                contentIndex,
+                delta: JSON.stringify(toolCall.arguments),
+                partial: output
+            })
+            stream.push({ type: 'toolcall_end', contentIndex, toolCall, partial: output })
+        }
+        finish('toolUse')
+    }
+
+    const handle: SessionListener = (event) => {
+        if (finished) return
+        const decoded = decodeEvent(event)
+        const session = findByOpencodeId(sessions, decoded.sessionID)
+        if (session) owner = session
+
+        switch (decoded.type) {
+            case 'session.step.started':
+                stepStreamed = false
+                piCalls.clear()
+                clearPark()
+                return
+            case 'session.reasoning.delta': {
+                const index = openThinking()
+                const block = output.content[index]
+                if (block?.type === 'thinking') block.thinking += decoded.delta
+                stream.push({ type: 'thinking_delta', contentIndex: index, delta: decoded.delta, partial: output })
+                return
+            }
+            case 'session.reasoning.ended':
+                closeThinking(decoded.text)
+                return
+            case 'session.text.delta': {
+                const index = openText()
+                const block = output.content[index]
+                if (block?.type === 'text') block.text += decoded.delta
+                stream.push({ type: 'text_delta', contentIndex: index, delta: decoded.delta, partial: output })
+                return
+            }
+            case 'session.text.ended':
+                closeText(decoded.text)
+                return
+            case 'session.tool.input.started': {
+                if (decoded.name.startsWith(TOOL_PREFIX)) {
+                    piCalls.set(decoded.id ?? `${decoded.name}#${piCalls.size}`, decoded.name)
+                }
+                return
+            }
+            case 'session.tool.success':
+            case 'session.tool.failed': {
+                if (!piCalls.delete(decoded.id)) return
+                if (parkedCallIds.length >= piCalls.size) clearPark()
+                if (session && ready()) emitToolCalls(session)
+                return
+            }
+            case 'session.step.failed': {
+                if (decoded.failure) failure = decoded.failure
+                piCalls.clear()
+                clearPark()
+                return
+            }
+            case 'session.step.streamed':
+                stepStreamed = true
+                if (session && ready()) {
+                    emitToolCalls(session)
+                    return
+                }
+                if (piCalls.size > parkedCallIds.length && !parkTimer) {
+                    const missing = piCalls.size - parkedCallIds.length
+                    const total = piCalls.size
+                    const names = [...piCalls.values()].join(', ')
+                    parkTimer = setTimeout(
+                        () =>
+                            fail(
+                                `opencode started ${names || 'a pi_ tool'} but ${missing} of ${total} call(s) ` +
+                                    `never reached the bridge within ${PARK_GRACE_MS / 1000}s`
+                            ),
+                        PARK_GRACE_MS
+                    )
+                }
+                return
+            case 'bridge.tool.parked':
+                parkedCallIds.push(decoded.callId)
+                if (session && ready()) emitToolCalls(session)
+                return
+            case 'session.execution.succeeded': {
+                const hasResult = output.content.some(
+                    (block) =>
+                        block.type === 'toolCall' ||
+                        (block.type === 'text' && block.text.trim().length > 0 && !leakedToolCall(block.text))
+                )
+                if (!hasResult && recover('empty')) {
+                    const leaked = textIndex === undefined ? undefined : output.content[textIndex]
+                    closeText(leaked?.type === 'text' ? leaked.text : '')
+                    resetExecution()
+                    return
+                }
+                finish('stop')
+                return
+            }
+            case 'session.execution.interrupted':
+            case 'session.execution.failed': {
+                if (decoded.failure) failure = decoded.failure
+                if (recover('refused')) {
+                    resetExecution()
+                    return
+                }
+                fail(
+                    failure ??
+                        (decoded.type === 'session.execution.failed'
+                            ? 'opencode could not finish the request'
+                            : 'opencode interrupted the request')
+                )
+                return
+            }
+            case 'session.step.ended':
+            case 'permission.asked':
+                return
+            case 'other':
+                if (decoded.failure) failure = decoded.failure
+        }
+    }
+
+    return { handle, done, fail }
+}
+
+const ErrorObjectSchema = t.object({
+    message: t.optional(t.string()),
+    errorMessage: t.optional(t.string()),
+    reason: t.optional(t.string())
+})
+const isErrorObjectSchema = new Validator(ErrorObjectSchema).isValidObject
+
+function textOf(output: AssistantMessage, index: number): string {
+    const block = output.content[index]
+    return block?.type === 'text' ? block.text : ''
+}
+
+function thinkingOf(output: AssistantMessage, index: number): string {
+    const block = output.content[index]
+    return block?.type === 'thinking' ? block.thinking : ''
+}