import type { DisplaySession } from '@dsh-remote/client-core' import { CodexRemoteClient, projectCodexThread } from '@dsh-remote/client-core' import type { CodexPermissionPreset } from '@dsh-remote/protocol' import type { HarnessSessionGeneration } from '../harness-version.js' import { CodexSessionHistoryCache } from '../session-history-cache.js' import type { RemoteTypertGatewayTarget, TypertGatewayRequest, TypertRpcResult } from '../typert-gateway-contract.js' import { codexPermissionPresetFromResponse } from './permissions.js' import type { CatalogState, CodexModelDirectory, CodexModelSelection, CodexVirtualWorkspaceView, } from './virtual-catalog.js' import { CODEX_PROVIDER, codexModelParams, containsPath, displayTitle, isCodexDirectoryListing, loadCatalog, loadModelDirectory, modelCatalog, modelSelection, modelSelectionProjection, nativeVisibleWorkspaces, nativeWorkspace, } from './virtual-catalog.js' import type { CodexImageAttachmentEntry, FollowState, PendingApproval } from './virtual-contract.js' import { AsyncValueQueue, business, carrierArgs, CODEX_DEFAULT_PERMISSION, CODEX_IMAGE_ATTACHMENT_PREFIX, codexImageLimitsProjection, codexPermissionsProjection, codexPromptInput, fail, failFrom, failure, isCodexPermissionPreset, isHostWorkspaceEndpoint, isHostWorkspaceStreamEndpoint, isLegacySessionHistoryUnsupported, ok, requestArg, SESSION_SEARCH_RESULT_LIMIT, SESSION_SEARCH_SNIPPET_CODE_POINTS, sessionIdFromAddress, success, truncateCodePoints, } from './virtual-contract.js' import { CodexEventCarrier } from './virtual-event-carrier.js' import type { CodexNativeHistory, CodexNativeHistoryPage } from './virtual-history.js' import { adaptCodexHistoryPage, isCodexNativeHistoryPage, paginateCodexNativeHistory, projectCodexNativeHistory, } from './virtual-history.js' import { CodexLiveProjection } from './virtual-live.js' import type { CodexClientLike, JsonRecord } from './virtual-values.js' import { array, boundedCodexHistoryPageSize, errorCode, nativeThreadId, optionalInteger, optionalNonNegativeInteger, optionalPositiveInteger, record, requiredString, string, } from './virtual-values.js' // Workspace/session catalog reads are shared by several native controllers // during Web startup. Keep the short-lived snapshot so opening a Workspace and // its Session does not issue the same project/thread pages back-to-back. const CODEX_CATALOG_CACHE_MS = 2_000 /** * A plugin-owned virtual Harness target. It projects CodeX Thread/Turn data at * the existing Typert carrier boundary, so every UI layer above the * official Workspace and Session controllers remains native DSH. */ export class CodexVirtualHarness implements RemoteTypertGatewayTarget { private readonly live: CodexLiveProjection private readonly events: CodexEventCarrier private catalog?: CatalogState private readonly workspaceStreams = new Set() private readonly controlStreams = new Set() private readonly eventStreams = new Map() private readonly follows = new Set() private readonly pendingRequestIds = new Map() private readonly pendingApprovals = new Map() private readonly pendingThreads = new Map() private readonly blankThreads = new Set() private readonly selectedModels = new Map() private readonly selectedPermissions = new Map() private readonly imageAttachments = new Map() private modelDirectory?: CodexModelDirectory private modelDirectoryPromise?: Promise private catalogPromise?: Promise private catalogLoadedAt = 0 private lastProjectionSeq = 0 private commandSeq = 0 private selectedWorkspaceId?: string private lastOpenedSessionId?: string private readonly openedWorkspaceSessions = new Map() private closed = false constructor( private readonly client: CodexClientLike, private readonly host: { deviceId: string; name: string }, private readonly sessionGeneration: HarnessSessionGeneration = 'legacy', private readonly hostCarrier?: RemoteTypertGatewayTarget, private readonly historyCache: CodexSessionHistoryCache = new CodexSessionHistoryCache(), ) { const owner = this this.live = new CodexLiveProjection({ readHistoryPage: (...args) => owner.readHistoryPage(...args), models: (...args) => owner.models(...args), get pendingRequestIds() { return owner.pendingRequestIds }, get follows() { return owner.follows }, sessionTitle: (...args) => owner.sessionTitle(...args), modelSelection: (...args) => owner.modelSelection(...args), permissionSelection: (...args) => owner.permissionSelection(...args), get sessionGeneration() { return owner.sessionGeneration }, get client() { return owner.client }, get closed() { return owner.closed }, rememberOpenedSession: (...args) => owner.rememberOpenedSession(...args), nextProjectionSeq: (...args) => owner.nextProjectionSeq(...args), updateThreadName: (...args) => owner.updateThreadName(...args), publishProjection: (...args) => owner.events.publishProjection(...args), setPermissionSelection: (...args) => owner.setPermissionSelection(...args), emitRemoteEvent: (...args) => owner.events.emitRemoteEvent(...args), get selectedModels() { return owner.selectedModels }, refreshAndPublishWorkspaces: (...args) => owner.refreshAndPublishWorkspaces(...args), get pendingApprovals() { return owner.pendingApprovals }, emitApproval: (...args) => owner.events.emitApproval(...args), get imageAttachments() { return owner.imageAttachments }, invalidateThreadHistory: threadId => owner.historyCache.invalidateThread(threadId), }) this.events = new CodexEventCarrier({ get workspaceStreams() { return owner.workspaceStreams }, refreshCatalog: (...args) => owner.refreshCatalog(...args), get selectedWorkspaceId() { return owner.selectedWorkspaceId }, get controlStreams() { return owner.controlStreams }, get host() { return owner.host }, get eventStreams() { return owner.eventStreams }, currentCatalog: (...args) => owner.currentCatalog(...args), get pendingApprovals() { return owner.pendingApprovals }, get client() { return owner.client }, }) } static remote( core: ConstructorParameters[0], host: { deviceId: string; name: string }, sessionGeneration: HarnessSessionGeneration = 'legacy', hostCarrier?: RemoteTypertGatewayTarget, historyCache?: CodexSessionHistoryCache, ): CodexVirtualHarness { return new CodexVirtualHarness(new CodexRemoteClient(core), host, sessionGeneration, hostCarrier, historyCache) } async workspaces(signal?: AbortSignal): Promise { return (await this.refreshCatalog(signal)).workspaces } async selectWorkspace(workspaceId: string, signal?: AbortSignal): Promise { const catalog = await this.refreshCatalog(signal) const workspace = catalog.workspaces.find(item => item.workspaceId === workspaceId) if (workspace === undefined) throw new Error('The selected CodeX workspace is no longer available.') this.selectedWorkspaceId = workspace.workspaceId this.catalog = catalog return workspace } get openedSessionId(): string | undefined { return this.lastOpenedSessionId } get openedSessions(): ReadonlyMap { return new Map(this.openedWorkspaceSessions) } private rememberOpenedSession(sessionId: string): void { if (this.closed) return this.lastOpenedSessionId = sessionId // Native navigation can open another visible Workspace without replacing // this carrier. Remember the actual catalog membership, not its entry URL. for (const workspace of this.catalog?.workspaces ?? []) { if (!workspace.sessionIds.includes(sessionId)) continue this.openedWorkspaceSessions.delete(workspace.workspaceId) this.openedWorkspaceSessions.set(workspace.workspaceId, sessionId) if (this.openedWorkspaceSessions.size > 64) { this.openedWorkspaceSessions.delete(this.openedWorkspaceSessions.keys().next().value!) } } } async preferredSessionId( signal?: AbortSignal, preferredSessionId = this.openedWorkspaceSessions.get(this.selectedWorkspaceId ?? ''), ): Promise { signal?.throwIfAborted() const catalog = this.catalog const selected = catalog?.workspaces.find(workspace => workspace.workspaceId === this.selectedWorkspaceId) const selectedSessionIds = new Set(selected?.sessionIds ?? []) const sessions = (catalog?.sessions ?? []).filter(session => selectedSessionIds.has(session.id)) if (sessions.some(session => session.id === preferredSessionId)) return preferredSessionId // The Host catalog already validated these IDs. Restore the latest Thread // regardless of title or busy status; transient history-read failures must // not redirect navigation to an older Thread or a new blank Session. // Do not probe Threads here: one busy read can stall workspace recovery. return sessions.reduce((latest, session) => latest === undefined || session.updatedAt > latest.updatedAt ? session : latest, undefined)?.id } async invoke(request: TypertGatewayRequest): Promise { const result = await this.dispatch( `${request.namespace}/${request.method}`, { args: request.args }, request.signal ?? new AbortController().signal, ) if (result.ok) return result.value throw Object.assign(new Error(result.error.message), { isDSHRemoteError: true as const, code: result.error.code, details: result.error.details, }) } async dispatch(endpoint: string, payload: unknown, signal: AbortSignal): Promise { try { if (isHostWorkspaceEndpoint(endpoint)) { if (this.hostCarrier === undefined) return fail('method-not-found', `CodeX virtual Harness does not implement ${endpoint}.`) return await this.hostCarrier.dispatch(endpoint, payload, signal) } const args = carrierArgs(payload) switch (endpoint) { case '$events/result': return business(await this.events.answerRemoteEvent(args, signal)) case 'workspace/list': { const catalog = await this.refreshCatalog(signal) return business(success({ items: nativeVisibleWorkspaces(catalog, this.selectedWorkspaceId).map(nativeWorkspace), archivedSessionIds: catalog.sessions.filter(item => item.archived).map(item => item.id), pinnedSessionIds: [], })) } case 'workspace/create': return business(await this.createWorkspace(requestArg(args), signal)) case 'workspace/rename': return business(await this.renameWorkspace(requestArg(args))) case 'workspace/delete': return business(failure('workspace-read-only', 'CodeX virtual Workspaces cannot be deleted.')) case 'workspace/insertBefore': return business({ workspaceIds: nativeVisibleWorkspaces(await this.currentCatalog(signal), this.selectedWorkspaceId).map(item => item.workspaceId), }) case 'workspace/insertSessionBefore': return business(await this.workspaceForSession(requestArg(args), signal)) case 'workspace/archiveSession': return business(await this.archiveSession(requestArg(args), signal)) case 'session/list': return business(success({ items: await this.sessionSummaries(signal) })) case 'session/projections': return business(await this.sessionProjections(requestArg(args), signal)) case 'session/search': return business(await this.searchSessions(requestArg(args), signal)) case 'session/create': return business(await this.createSession(requestArg(args), signal)) case 'session/fork': return business(await this.forkSession(requestArg(args), signal)) case 'session/history': return business(await this.sessionHistory(requestArg(args), signal)) case 'session/events': case 'session/page': return business(await this.sessionPage(requestArg(args), signal)) case 'session/prompt': return business(await this.prompt(requestArg(args), signal)) case 'session/cancel': return business(await this.cancel(requestArg(args), signal)) case 'session/rename': return business(await this.renameSession(requestArg(args), signal)) case 'session/updateQueue': return business(failure('queue-item-not-found', 'CodeX does not expose a DSH inbox queue.')) case 'session/attachment': return business(await this.attachment(requestArg(args), signal)) case 'session/modelCatalog': return business(success(modelCatalog(await this.models(signal)))) case 'session/models': { const sessionId = requiredString(requestArg(args).sessionId, 'sessionId') nativeThreadId(sessionId) const directory = await this.models(signal) return business(success({ current: this.modelSelection(sessionId, directory), routable: true, groups: directory.groups, failures: [], })) } case 'session/selectModel': return business(await this.selectModel(requestArg(args), signal)) case 'session/canOpenWorkspacePath': return business(this.selectedWorkspaceId !== undefined) case 'session/openWorkspacePath': return business(failure('bad-request', 'Opening Host paths is unavailable in CodeX mode.')) case 'host/describe': return business(success(await this.describeHost(signal))) case 'host/listDirectory': return business(await this.listDirectory(requestArg(args), signal)) case 'directoryPicker/list': return business(await this.listDirectory(requestArg(args), signal)) case 'skills/list': return business(success({ items: [] })) case 'job/kill': return this.hostCarrier === undefined ? business(success({ outcome: 'already-finished' })) : await this.hostCarrier.dispatch(endpoint, payload, signal) case 'commands/list': return ok(this.commandList(args)) case 'commands/execute': return ok(await this.executeCommand(args, signal)) default: return this.hostCarrier === undefined ? fail('method-not-found', `CodeX virtual Harness does not implement ${endpoint}.`) : await this.hostCarrier.dispatch(endpoint, payload, signal) } } catch (error) { return failFrom(error) } } async open(endpoint: string, payload: unknown, signal: AbortSignal): Promise> { if (isHostWorkspaceStreamEndpoint(endpoint)) { if (this.hostCarrier === undefined) { throw Object.assign(new Error(`CodeX virtual Harness does not implement stream ${endpoint}.`), { isDSHRemoteError: true as const, code: 'method-not-found', details: {}, }) } return this.hostCarrier.open(endpoint, payload, signal) } const args = carrierArgs(payload) if (endpoint === 'workspace/follow') return this.events.workspaceFollow(signal) if (endpoint === 'session/control') return this.events.sessionControl(signal) if (endpoint === 'session/follow') return this.live.sessionFollow(requestArg(args), signal) if (endpoint === '$events') return this.events.remoteEvents(signal) if (endpoint === 'job/list' || endpoint === 'job/follow') return this.events.emptyJobStream(endpoint, signal) if (this.hostCarrier !== undefined) return this.hostCarrier.open(endpoint, payload, signal) throw Object.assign(new Error(`CodeX virtual Harness does not implement stream ${endpoint}.`), { isDSHRemoteError: true as const, code: 'method-not-found', details: {}, }) } async close(): Promise { if (this.closed) return this.closed = true for (const stream of this.workspaceStreams) stream.close() for (const stream of this.controlStreams) stream.close() for (const stream of this.eventStreams.values()) stream.close() this.workspaceStreams.clear() this.controlStreams.clear() this.eventStreams.clear() const follows = [...this.follows] this.follows.clear() for (const follow of follows) { follow.queue.close() await follow.close?.().catch(() => undefined) } this.pendingApprovals.clear() this.pendingRequestIds.clear() this.pendingThreads.clear() this.blankThreads.clear() this.selectedModels.clear() this.selectedPermissions.clear() this.imageAttachments.clear() } private async refreshCatalog(signal?: AbortSignal, force = false): Promise { signal?.throwIfAborted() const fresh = this.catalog !== undefined && Date.now() - this.catalogLoadedAt < CODEX_CATALOG_CACHE_MS if (!force && fresh) return this.catalog! // A forced refresh follows an in-flight read (for example a mutation that // completed while the initial catalog was loading), then starts a fresh // read so the mutation is reflected in the snapshot. if (force && this.catalogPromise !== undefined) { try { await awaitWithAbort(this.catalogPromise, signal) } catch { signal?.throwIfAborted() // The pending read may have failed because the transport was // transiently unavailable. A forced mutation refresh still gets one // fresh attempt instead of inheriting that failure. } } const pending = this.catalogPromise if (!force && pending !== undefined) return awaitWithAbort(pending, signal) const current = loadCatalog(this.client, undefined, this.pendingThreads).then(catalog => { if (this.selectedWorkspaceId !== undefined && !catalog.workspaces.some(workspace => workspace.workspaceId === this.selectedWorkspaceId)) { this.selectedWorkspaceId = undefined } this.catalog = catalog this.catalogLoadedAt = Date.now() return catalog }) this.catalogPromise = current void current.finally(() => { if (this.catalogPromise === current) this.catalogPromise = undefined }).catch(() => undefined) return awaitWithAbort(current, signal) } private async currentCatalog(signal?: AbortSignal): Promise { return this.refreshCatalog(signal) } private models(signal?: AbortSignal): Promise { if (this.modelDirectory !== undefined) return Promise.resolve(this.modelDirectory) this.modelDirectoryPromise ??= loadModelDirectory(this.client, signal) .then(directory => { this.modelDirectory = directory return directory }) .finally(() => { this.modelDirectoryPromise = undefined }) return this.modelDirectoryPromise } private modelSelection(sessionId: string, directory?: CodexModelDirectory): CodexModelSelection { const selected = this.selectedModels.get(sessionId) if (selected !== undefined) return selected const session = this.catalog?.sessions.find(item => item.id === sessionId) if (session?.model !== undefined) { return { provider: CODEX_PROVIDER, model: session.model, ...(session.reasoningEffort === undefined ? {} : { reasoningEffort: session.reasoningEffort }), } } return directory?.default ?? modelSelection() } private permissionSelection(sessionId: string): CodexPermissionPreset | undefined { return this.selectedPermissions.get(sessionId) } private setPermissionSelection(sessionId: string, preset: CodexPermissionPreset | undefined): void { if (preset === undefined) this.selectedPermissions.delete(sessionId) else this.selectedPermissions.set(sessionId, preset) this.events.publishProjection(sessionId, 'permissions', codexPermissionsProjection(preset), this.nextProjectionSeq()) } private commandList(args: JsonRecord): unknown[] { nativeThreadId(requiredString(args.agentId, 'agentId')) return [{ name: 'permission', description: 'Switch the CodeX Remote sandbox mode and approval policy', input: { hint: '' }, }] } private async executeCommand(args: JsonRecord, signal: AbortSignal): Promise { const sessionId = requiredString(args.agentId, 'agentId') const threadId = nativeThreadId(sessionId) const line = requiredString(args.line, 'command line').trim() if (!Array.isArray(args.images)) throw new Error('The CodeX command image list is required.') const match = /^\/permission(?:\s+([\s\S]*))?$/u.exec(line) if (match === null) return undefined const commandId = `codex-permission:${++this.commandSeq}` if (args.images.length > 0) return { commandId, result: { kind: 'error', text: 'CodeX Remote permission commands do not accept attachments.' }, } const requested = (match[1] ?? '').trim() if (requested === '') { await this.readHistoryPage(threadId, { maxMessages: 1 }, signal) return { commandId, result: { kind: 'success', text: `current preset ${this.permissionSelection(sessionId) ?? 'Host settings (not reported)'}` }, } } if (!isCodexPermissionPreset(requested)) return { commandId, result: { kind: 'error', text: `unknown preset "${requested}" (available: workspace-write, danger-full-access)` }, } const result = await this.client.request('thread/resume', { threadId, permissionPreset: requested }, signal) const effective = codexPermissionPresetFromResponse(result) if (effective === undefined) throw new Error('The Host did not confirm the CodeX permission preset.') this.setPermissionSelection(sessionId, effective) if (effective !== requested) throw new Error('The Host did not apply the requested CodeX permission preset.') return { commandId, result: { kind: 'success', text: `preset ${effective}` } } } private sessionTitle(sessionId: string): string | null { const session = this.catalog?.sessions.find(item => item.id === sessionId) return session === undefined ? null : displayTitle(session) } private async selectModel(request: JsonRecord, signal: AbortSignal): Promise { const sessionId = requiredString(request.sessionId, 'sessionId') nativeThreadId(sessionId) const provider = requiredString(request.provider, 'provider') const model = requiredString(request.model, 'model') const reasoningEffort = string(request.reasoningEffort) const directory = await this.models(signal) const available = directory.models.get(model) if (provider !== CODEX_PROVIDER || available === undefined) { return failure('model-unavailable', 'The selected CodeX model is unavailable on this Host.') } const supportedEfforts = available.reasoning?.efforts.map(effort => effort.id) ?? [] if (reasoningEffort !== undefined && !supportedEfforts.includes(reasoningEffort)) { return failure('model-unavailable', 'The selected reasoning effort is unavailable for this CodeX model.') } const selected: CodexModelSelection = { provider, model, ...(reasoningEffort === undefined ? {} : { reasoningEffort }), } this.selectedModels.set(sessionId, selected) const seq = Date.now() this.events.publishProjection(sessionId, 'modelSelection', modelSelectionProjection(selected), seq) return success({ selected }) } private nextProjectionSeq(): number { const seq = Math.max(Date.now(), this.lastProjectionSeq + 1) this.lastProjectionSeq = seq return seq } private updateThreadName(threadId: string, name: string): void { const pending = this.pendingThreads.get(threadId) if (pending !== undefined) this.pendingThreads.set(threadId, { ...pending, name }) if (this.catalog === undefined) return const threads = this.catalog.threads.map(thread => string(thread.id) === threadId ? { ...thread, name } : thread) const sessions = this.catalog.sessions.map(session => { if (session.nativeId !== threadId) return session const { title: _title, ...rest } = session return name.trim() === '' ? rest : { ...rest, title: name } }) this.catalog = { ...this.catalog, threads, sessions } } private async sessionSummaries(signal?: AbortSignal): Promise { const catalog = await this.refreshCatalog(signal) const directory = await this.models(signal).catch(() => undefined) return catalog.sessions.map(session => { const blank = this.blankThreads.has(session.nativeId) || this.pendingThreads.has(session.nativeId) return this.sessionSummary(session, { blank, modelSelection: this.modelSelection(session.id, directory), lastPromptAt: session.updatedAt || null, }) }) } private sessionSummary( session: DisplaySession, options: { blank: boolean; modelSelection: CodexModelSelection; lastPromptAt: number | null; asOfSeq?: number }, ): unknown { return { sessionId: session.id, updatedAt: session.updatedAt, running: session.status === 'running' || session.status === 'waiting', blank: options.blank, ...(session.cwd === undefined ? {} : { cwd: session.cwd }), projections: { kind: 'sequenced', asOfSeq: options.asOfSeq ?? 0, values: { title: displayTitle(session), sessionListMetadata: { blank: options.blank, lastPromptAt: options.lastPromptAt }, modelSelection: modelSelectionProjection(options.modelSelection), permissions: codexPermissionsProjection(this.permissionSelection(session.id)), imageLimits: codexImageLimitsProjection(), }, }, } } private async searchSessions(request: JsonRecord, signal: AbortSignal): Promise { const query = requiredString(request.query, 'query').trim() if (query.length === 0 || query.length > 500 || query.includes('\0')) { return failure('bad-request', 'The CodeX Session search query is invalid.') } const catalog = await this.currentCatalog(signal) const needle = query.toLocaleLowerCase() const matches = catalog.threads.flatMap(thread => { const session = projectCodexThread(thread) if (session === undefined) return [] const candidates = [session.title, session.preview, session.cwd, session.nativeId] .filter((value): value is string => value !== undefined && value.length > 0) const snippet = candidates.find(value => value.toLocaleLowerCase().includes(needle)) if (snippet === undefined) return [] return [{ sessionId: session.id, snippet: truncateCodePoints(snippet, SESSION_SEARCH_SNIPPET_CODE_POINTS) }] }) return success({ items: matches.slice(0, SESSION_SEARCH_RESULT_LIMIT), hasMore: matches.length > SESSION_SEARCH_RESULT_LIMIT, }) } private async createWorkspace(request: JsonRecord, signal: AbortSignal): Promise { const path = string(request.path) if (path === undefined || path.trim() === '') return failure('bad-request', 'A CodeX working directory is required.') const catalog = await this.currentCatalog(signal) const existing = catalog.workspaces.find(item => item.path === path) if (existing !== undefined) return success({ workspace: nativeWorkspace(existing), created: false }) return failure('workspace-not-found', 'The selected directory is not visible to CodeX Remote.') } private async renameWorkspace(request: JsonRecord): Promise { return failure('workspace-read-only', `CodeX virtual Workspace ${string(request.workspaceId) ?? ''} cannot be renamed.`) } private async workspaceForSession(request: JsonRecord, signal: AbortSignal): Promise { const sessionId = string(request.sessionId) const catalog = await this.currentCatalog(signal) const workspace = catalog.workspaces.find(item => sessionId !== undefined && item.sessionIds.includes(sessionId)) return workspace === undefined ? failure('workspace-not-found', 'The CodeX virtual Workspace was not found.') : success({ workspace: nativeWorkspace(workspace) }) } private selectedWorkspace(catalog: CatalogState): CodexVirtualWorkspaceView | undefined { return this.selectedWorkspaceId === undefined ? undefined : catalog.workspaces.find(item => item.workspaceId === this.selectedWorkspaceId) } private async describeHost(signal: AbortSignal): Promise { const catalog = await this.currentCatalog(signal) const workspace = this.selectedWorkspace(catalog) const models = await this.models(signal).catch(() => undefined) return { version: 'CodeX Remote', cwd: workspace?.path ?? '', home: workspace?.path ?? '', provider: 'CodeX', ...(models === undefined ? {} : { model: models.default.model }), attachedSessions: catalog.sessions.length, canOpenPath: workspace !== undefined, } } private async listDirectory(request: JsonRecord, signal: AbortSignal): Promise { const catalog = await this.currentCatalog(signal) const workspace = this.selectedWorkspace(catalog) if (workspace === undefined) return failure('workspace-not-found', 'The CodeX virtual Workspace was not found.') const path = string(request.path) ?? workspace.path if (!containsPath(workspace.path, path)) { return failure('workspace-not-found', 'The selected directory is outside the current CodeX virtual Workspace.') } const listing = record(await this.client.request('dsh/directoryList', { path }, signal)) if (!isCodexDirectoryListing(listing)) { return failure('internal', 'CodeX Remote returned an invalid directory listing.') } const listedPaths = [ listing.path, listing.home, ...listing.crumbs.map(item => item.path), ...listing.entries.map(item => item.path), ] if (listedPaths.some(path => !containsPath(workspace.path, path))) { return failure('internal', 'CodeX Remote returned a directory outside the current Workspace.') } return success(listing) } private async archiveSession(request: JsonRecord, signal: AbortSignal): Promise { const sessionId = requiredString(request.sessionId, 'sessionId') const threadId = nativeThreadId(sessionId) await this.client.request('thread/archive', { threadId }, signal) this.historyCache.removeThread(threadId) const catalog = await this.refreshCatalog(signal, true) this.publishWorkspaceBaseline(catalog) return success({ archivedSessionIds: [sessionId] }) } private async createSession(request: JsonRecord, signal: AbortSignal): Promise { const catalog = await this.currentCatalog(signal) const workspaceId = string(request.workspaceId) ?? this.selectedWorkspaceId const workspace = workspaceId === undefined ? undefined : catalog.workspaces.find(item => item.workspaceId === workspaceId) const cwd = string(request.cwd) ?? workspace?.path if (cwd === undefined) return failure('workspace-not-found', 'The CodeX virtual Workspace was not found.') if (workspace !== undefined && !containsPath(workspace.path, cwd)) { return failure('workspace-not-found', 'The selected directory is outside the current CodeX virtual Workspace.') } const directory = await this.models(signal) const selection = directory.default const requestedPreset = CODEX_DEFAULT_PERMISSION const result = record(await this.client.request('thread/start', { cwd, model: selection.model, permissionPreset: requestedPreset, }, signal)) const permissionPreset = codexPermissionPresetFromResponse(result) ?? requestedPreset const thread = { ...record(result.thread), cwd, turns: array(record(result.thread).turns) } const projected = projectCodexThread(thread) if (projected === undefined) return failure('internal', 'CodeX returned an invalid Thread.') this.pendingThreads.set(projected.nativeId, thread) this.blankThreads.add(projected.nativeId) this.selectedModels.set(projected.id, selection) this.selectedPermissions.set(projected.id, permissionPreset) // A new Thread is not materialized in the upstream index until its first // user message. Do not make the create response wait for a full // project/thread rescan that cannot observe the new Thread yet. The // pending thread is retained locally and the baseline catches up in the // background while the composer can send the first prompt immediately. void this.refreshAndPublishWorkspaces(true).catch(() => undefined) const seq = this.nextProjectionSeq() this.events.emitRemoteEvent('api-session/added', [this.sessionSummary(projected, { blank: true, modelSelection: selection, lastPromptAt: null, asOfSeq: seq, })]) this.events.publishProjection(projected.id, 'title', displayTitle(projected), seq) return success({ sessionId: projected.id }) } private async forkSession(request: JsonRecord, signal: AbortSignal): Promise { const sessionId = requiredString(request.sessionId, 'sessionId') const result = record(await this.client.request('thread/fork', { threadId: nativeThreadId(sessionId), }, signal)) const permissionPreset = codexPermissionPresetFromResponse(result) const projected = projectCodexThread(record(result.thread)) if (projected === undefined) return failure('internal', 'CodeX returned an invalid forked Thread.') this.selectedModels.set(projected.id, this.modelSelection(sessionId, await this.models(signal))) this.setPermissionSelection(projected.id, permissionPreset) await this.refreshAndPublishWorkspaces(true) const seq = this.nextProjectionSeq() this.events.publishProjection(projected.id, 'title', displayTitle(projected), seq) return success({ sessionId: projected.id }) } private async prompt(request: JsonRecord, signal: AbortSignal): Promise { const sessionId = requiredString(request.sessionId, 'sessionId') const content = array(request.content) const input = codexPromptInput(content) if (input === undefined) return failure('attachment-error', 'CodeX virtual Sessions accept text and pasted PNG, JPEG, WebP, or GIF images only.') const threadId = nativeThreadId(sessionId) // Session follow/history normally hydrates this selection before the // composer can send. Reuse that state (and the selection captured by // session/create) instead of cold-loading the whole model catalog on the // first prompt. Only an entirely cold prompt needs model/list. const knownSelection = this.selectedModels.get(sessionId) ?? (() => { const session = this.catalog?.sessions.find(item => item.id === sessionId) return session?.model === undefined ? undefined : { provider: CODEX_PROVIDER, model: session.model, ...(session.reasoningEffort === undefined ? {} : { reasoningEffort: session.reasoningEffort }), } })() const selection = knownSelection ?? this.modelSelection(sessionId, await this.models(signal)) const isFreshBlankThread = this.blankThreads.has(threadId) || this.pendingThreads.has(threadId) if (!isFreshBlankThread) { const resumeResult = await this.client.request('thread/resume', { threadId, model: selection.model, }, signal) const serverPreset = codexPermissionPresetFromResponse(resumeResult) if (serverPreset !== undefined) { this.setPermissionSelection(sessionId, serverPreset) } } this.pendingRequestIds.set(sessionId, string(request.requestId) ?? '') const mode = request.mode === 'steer' ? 'turn/steer' : 'turn/start' if (mode === 'turn/steer') { const active = this.activeTurnId(threadId) if (active === undefined) return failure('steer-unavailable', 'The CodeX Thread has no active turn to steer.') await this.client.request(mode, { threadId, expectedTurnId: active, input }, signal) } else { await this.client.request(mode, { threadId, input, ...codexModelParams(selection), }, signal) } this.blankThreads.delete(threadId) this.historyCache.invalidateThread(threadId) return success({ accepted: true }) } private async attachment(request: JsonRecord, signal: AbortSignal): Promise { const sessionId = requiredString(request.sessionId, 'sessionId') // 0.2.2 sends the full ImageAttachmentRef; older clients send only its id. const attachmentId = string(request.attachmentId) ?? string(record(request.attachment).attachmentId) if (attachmentId === undefined) { return failure('attachment-error', 'The CodeX image is not available in this virtual Session.', { reason: 'invalid' }) } if (!attachmentId.startsWith(CODEX_IMAGE_ATTACHMENT_PREFIX)) { return failure('attachment-error', 'The CodeX image is not available in this virtual Session.', { reason: 'not-referenced' }) } nativeThreadId(sessionId) const cached = this.imageAttachments.get(attachmentId) if (cached?.sessionId === sessionId) return success({ attachment: cached.attachment, data: cached.data }) await this.hydrateImageAttachments(sessionId, signal) const hydrated = this.imageAttachments.get(attachmentId) return hydrated?.sessionId === sessionId ? success({ attachment: hydrated.attachment, data: hydrated.data }) : failure('attachment-error', 'The CodeX image is not available in this virtual Session.', { reason: 'not-referenced' }) } private async hydrateImageAttachments(sessionId: string, signal: AbortSignal): Promise { const threadId = nativeThreadId(sessionId) const result = record(await this.client.request('thread/read', { threadId, includeTurns: true }, signal)) const thread = record(result.thread) if (string(thread.id) !== threadId) throw new Error('CodeX returned an invalid Thread history.') this.cacheHistoryImages(projectCodexNativeHistory(thread, sessionId)) } private async cancel(request: JsonRecord, signal: AbortSignal): Promise { const sessionId = requiredString(request.sessionId, 'sessionId') const threadId = nativeThreadId(sessionId) const turnId = this.activeTurnId(threadId) if (turnId !== undefined) await this.client.request('turn/interrupt', { threadId, turnId }, signal) this.historyCache.invalidateThread(threadId) return success({ accepted: true }) } private async renameSession(request: JsonRecord, signal: AbortSignal): Promise { const sessionId = requiredString(request.sessionId, 'sessionId') const title = requiredString(request.title, 'title') await this.client.request('thread/name/set', { threadId: nativeThreadId(sessionId), name: title }, signal) const seq = this.nextProjectionSeq() this.updateThreadName(nativeThreadId(sessionId), title) this.events.publishProjection(sessionId, 'title', title, seq) await this.refreshAndPublishWorkspaces(true) return success({ title, seq }) } private async sessionProjections(request: JsonRecord, signal: AbortSignal): Promise { const sessionId = requiredString(request.sessionId, 'sessionId') const catalog = await this.currentCatalog(signal) const session = catalog.sessions.find(item => item.id === sessionId) if (session === undefined) return success(null) const threadId = nativeThreadId(sessionId) const cachedCursor = this.historyCache.getFreshTailCursor(threadId, this.sessionGeneration, session.updatedAt) const cursor = cachedCursor ?? (await this.readHistoryPage(threadId, { maxMessages: 1 }, signal)).cursor const directory = await this.models(signal).catch(() => undefined) return success(record(this.sessionSummary(session, { blank: cursor < 0, modelSelection: this.modelSelection(sessionId, directory), lastPromptAt: session.updatedAt || null, asOfSeq: cursor, })).projections) } private async sessionPage(request: JsonRecord, signal: AbortSignal): Promise { const sessionId = sessionIdFromAddress(record(request.address)) const page = await this.readHistoryPage(nativeThreadId(sessionId), { beforeSeq: optionalNonNegativeInteger(request.beforeSeq), throughSeq: optionalInteger(request.throughSeq), maxMessages: optionalPositiveInteger(request.maxMessages), }, signal) return success({ records: page.records, hasMore: page.hasMore, cursor: page.cursor }) } private activeTurnId(threadId: string): string | undefined { for (const follow of this.follows) if (follow.threadId === threadId && follow.stepOpen) return follow.activeTurnId return undefined } private async readHistoryPage( threadId: string, page: { beforeSeq?: number; throughSeq?: number; maxMessages?: number }, signal?: AbortSignal, ): Promise { const boundedPage = { ...page, maxMessages: boundedCodexHistoryPageSize(page.maxMessages), } const knownUpdatedAt = this.catalog?.sessions.find(item => item.id === `codex:${threadId}`)?.updatedAt if (!this.blankThreads.has(threadId)) { const cached = this.historyCache.getFreshPage(threadId, this.sessionGeneration, boundedPage, knownUpdatedAt) if (cached !== undefined) { this.applyHistoryMetadata(threadId, cached) return cached } } const resolved = await this.historyCache.runSingleFlightPage( threadId, this.sessionGeneration, boundedPage, signal, async sharedSignal => { const readEpoch = this.historyCache.beginReadEpoch() let value: unknown try { value = record(await this.client.request('dsh/sessionHistory', { threadId, ...(boundedPage.beforeSeq === undefined ? {} : { beforeSeq: boundedPage.beforeSeq }), ...(boundedPage.throughSeq === undefined ? {} : { throughSeq: boundedPage.throughSeq }), ...(boundedPage.maxMessages === undefined ? {} : { maxMessages: boundedPage.maxMessages }), }, sharedSignal)) } catch (error) { if (!isLegacySessionHistoryUnsupported(error)) { if (!sharedSignal.aborted) { const stale = this.historyCache.getStalePage(threadId, this.sessionGeneration, boundedPage) if (stale !== undefined) return stale } throw error } let thread: JsonRecord try { const result = record(await this.client.request('thread/read', { threadId, includeTurns: true }, sharedSignal)) thread = record(result.thread) } catch (historyError) { // A Host old enough to lack paginated history cannot read a Thread that // current Codex has not materialized yet. Only a Thread this client just // created is known blank, and only an upstream rejection (not a timeout // or disconnect) may be projected as its empty baseline. const code = historyError instanceof Error ? errorCode(historyError) : undefined if (!this.blankThreads.has(threadId) || code !== 'CODEX_UPSTREAM_ERROR') { if (!sharedSignal.aborted) { const stale = this.historyCache.getStalePage(threadId, this.sessionGeneration, boundedPage) if (stale !== undefined) return stale } throw historyError } thread = { id: threadId, turns: [] } } if (string(thread.id) !== threadId) throw new Error('CodeX returned an invalid Thread history.') value = paginateCodexNativeHistory( projectCodexNativeHistory(thread, `codex:${threadId}`, this.sessionGeneration), { beforeSeq: page.beforeSeq, throughSeq: page.throughSeq, maxMessages: boundedPage.maxMessages, }, ) } value = adaptCodexHistoryPage(value, this.sessionGeneration) if (!isCodexNativeHistoryPage(value, `codex:${threadId}`)) { throw new Error('CodeX Remote returned an invalid paginated History.') } if (!this.blankThreads.has(threadId)) { this.historyCache.setPage(threadId, this.sessionGeneration, boundedPage, value, knownUpdatedAt, readEpoch) } return value }, ) this.applyHistoryMetadata(threadId, resolved) return resolved } private applyHistoryMetadata(threadId: string, value: CodexNativeHistoryPage): void { const historyModel = string(value.header.model) if (historyModel !== undefined) { this.selectedModels.set(`codex:${threadId}`, { provider: CODEX_PROVIDER, model: historyModel, ...(string(value.header.reasoningEffort) === undefined ? {} : { reasoningEffort: string(value.header.reasoningEffort) }), }) } if (Object.hasOwn(value, 'permissionPreset')) { const preset = value.permissionPreset this.setPermissionSelection(`codex:${threadId}`, preset === 'workspace-write' || preset === 'danger-full-access' ? preset : undefined) } this.cacheHistoryImages(value) } private cacheHistoryImages(history: CodexNativeHistoryPage | CodexNativeHistory): void { const sessionId = history.header.id const entries = 'entries' in history ? history.entries : history.records for (const entry of entries) this.live.cacheImageBlocks(sessionId, entry.event.data) } private async sessionHistory(request: JsonRecord, signal: AbortSignal): Promise { const sessionId = requiredString(request.sessionId, 'sessionId') const beforeSeq = optionalNonNegativeInteger(request.beforeSeq) const history = await this.readHistoryPage(nativeThreadId(sessionId), { beforeSeq, maxMessages: optionalPositiveInteger(request.maxMessages), }, signal) const directory = await this.models(signal).catch(() => undefined) if (beforeSeq === undefined) { signal.throwIfAborted() if (this.closed) throw new Error('The CodeX virtual Harness is closed.') this.rememberOpenedSession(sessionId) } return success({ events: history.records.map(entry => ({ event: entry.event, ...(entry.view === undefined ? {} : { view: entry.view }), })), hasMore: history.hasMore, ...(beforeSeq !== undefined ? {} : { projections: { asOfSeq: history.cursor, values: { title: this.sessionTitle(sessionId), sessionListMetadata: { blank: history.cursor < 0, lastPromptAt: null }, modelSelection: modelSelectionProjection(this.modelSelection(sessionId, directory)), permissions: codexPermissionsProjection(this.permissionSelection(sessionId)), imageLimits: codexImageLimitsProjection(), }, }, }), }) } private async refreshAndPublishWorkspaces(force = false): Promise { const catalog = await this.refreshCatalog(undefined, force).catch(() => undefined) if (catalog !== undefined) this.publishWorkspaceBaseline(catalog) } private publishWorkspaceBaseline(catalog: CatalogState): void { for (const queue of this.workspaceStreams) { for (const workspace of nativeVisibleWorkspaces(catalog, this.selectedWorkspaceId)) { queue.push({ type: 'upsert', workspace: nativeWorkspace(workspace) }) } queue.push({ type: 'archived', archivedSessionIds: catalog.sessions.filter(item => item.archived).map(item => item.id) }) } } } function awaitWithAbort(promise: Promise, signal?: AbortSignal): Promise { if (signal === undefined) return promise signal.throwIfAborted() return new Promise((resolve, reject) => { const onAbort = () => reject(signal.reason) signal.addEventListener('abort', onAbort, { once: true }) promise.then( value => { signal.removeEventListener('abort', onAbort); resolve(value) }, error => { signal.removeEventListener('abort', onAbort); reject(error) }, ) }) } // Keep existing Host and Client imports stable. export { codexProjectWorkspaceId, discoverCodexVirtualWorkspaces } from './virtual-catalog.js' export type { CodexVirtualWorkspaceView } from './virtual-catalog.js' export { paginateCodexNativeHistory, projectCodexNativeHistory } from './virtual-history.js' export type { CodexNativeHistory, CodexNativeHistoryPage } from './virtual-history.js'