diff --git a/packages/plugin/src/codex/virtual-harness.ts b/packages/plugin/src/codex/virtual-harness.ts new file mode 100644 index 0000000..26513a2 --- /dev/null +++ b/packages/plugin/src/codex/virtual-harness.ts @@ -0,0 +1,1027 @@ +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'