diff --git a/packages/plugin/src/harness-remote-bridge.ts b/packages/plugin/src/harness-remote-bridge.ts new file mode 100644 index 0000000..d24d03f --- /dev/null +++ b/packages/plugin/src/harness-remote-bridge.ts @@ -0,0 +1,1539 @@ +import { compactHistory } from './compact-history.js' +import { applyLiteMode, isLiteModeEnabled } from './lite-mode.js' +import { randomUUID } from 'node:crypto' +import { homedir } from 'node:os' +import { lstat, realpath, stat } from 'node:fs/promises' +import { dirname, isAbsolute, join, parse, relative, resolve, sep } from 'node:path' +import { TerminalCarrierCompat, usesDuplexTerminal } from './terminal-carrier-compat.js' +import type { + HarnessApiTransferChunkParams, + HarnessApiTransferCommitResult, + HarnessApiTransferOpenParams, + HarnessApiTransferReadParams, + HarnessApiTransferReadResult, + HarnessRemoteCallParams, + HarnessRemoteFrameData, + HarnessRemoteStreamClosedData, + HarnessRemoteStreamOpenParams, +} from '@dsh-remote/protocol' +import { + createEvent, + encodeMessage, + HARNESS_API_TRANSFER_CHUNK_BYTES, + MAX_ACTIVE_TRANSFERS_PER_DIRECTION, + MAX_ALPHA_STREAMS_PER_CONNECTION, + MAX_HARNESS_API_TRANSFER_BYTES, + MAX_SECURE_MESSAGE_BYTES, + TRANSFER_IDLE_MS, +} from '@dsh-remote/protocol' +import { z } from 'zod' +import { TerminalPolicy, TERMINAL_CALLS, TERMINAL_STREAMS } from './terminal-policy.js' +import { harnessSessionGeneration } from './harness-version.js' +import type { SafeLogger } from './logging.js' +import { ensureHostWorkspaceDirectory, listRemoteDirectory } from './remote-directory-browser.js' +import { RpcError } from './rpc-router.js' +import { workspaceFileFailure, workspaceFileFailureReason } from './safe-error.js' +import type { LocalTypertGateway, TypertRpcResult } from './typert-gateway-contract.js' +import { CodexWorkspaceBridge } from './codex-workspace-bridge.js' + +type PublishRemoteFrame = ( + event: 'harness.remote.frame' | 'harness.remote.stream.closed', + data: HarnessRemoteFrameData | HarnessRemoteStreamClosedData, +) => Promise + +interface ActiveRemoteStream { + controller: AbortController +} + +interface IncomingTransfer { + totalBytes: number + totalChunks: number + chunks: Uint8Array[] + receivedBytes: number + touchedAt: number +} + +interface OutgoingTransfer { + bytes: Uint8Array + totalChunks: number + nextIndex: number + touchedAt: number + finish?: (error?: Error) => void +} + +const endpointSchema = z.string().min(1).max(128).regex(/^(?:\$events(?:\/result)?|[A-Za-z0-9_$.-]+\/[A-Za-z0-9_$.-]+)$/) +const callSchema = z.object({ endpoint: endpointSchema, payload: z.unknown() }).strict() +const streamOpenSchema = z.object({ + streamId: z.string().min(1).max(128), + endpoint: endpointSchema, + payload: z.unknown(), + transferFrames: z.boolean().optional(), +}).strict() +const streamCloseSchema = z.object({ streamId: z.string().min(1).max(128) }).strict() +const commandExecuteArgsSchema = z.object({ + agentId: z.string().min(1).max(128), + line: z.string().min(1).max(2048), + // dsh-commands <= 0.1.2 calls this field `images`; dsh-commands 0.1.5 + // renamed it to `submittedAttachments`. Only empty arrays are exposed by + // the Remote bridge; command attachments are deliberately out of scope. + images: z.array(z.never()).length(0).optional(), + submittedAttachments: z.array(z.never()).length(0).optional(), +}).strict().superRefine((value, context) => { + if (value.images !== undefined && value.submittedAttachments !== undefined) { + context.addIssue({ + code: z.ZodIssueCode.custom, + message: 'Use either images or submittedAttachments, not both.', + path: ['submittedAttachments'], + }) + } +}) +const commandExecutePayloadSchema = z.object({ args: commandExecuteArgsSchema }).strict() +const transferOpenSchema = z.object({ + transferId: z.string().uuid(), + totalBytes: z.number().int().positive().max(MAX_HARNESS_API_TRANSFER_BYTES), + totalChunks: z.number().int().positive(), +}).strict() +const transferChunkSchema = z.object({ + transferId: z.string().uuid(), + index: z.number().int().nonnegative(), + data: z.string().min(1), +}).strict() +const transferIdSchema = z.object({ transferId: z.string().uuid() }).strict() +const transferReadSchema = z.object({ + transferId: z.string().uuid(), + index: z.number().int().nonnegative(), +}).strict() +const directoryListSchema = z.object({ + path: z.string().min(1).max(4096).optional(), +}).strict() + +const MAX_ACTIVE_STREAMS = MAX_ALPHA_STREAMS_PER_CONNECTION +const MAX_ACTIVE_TRANSFERS = MAX_ACTIVE_TRANSFERS_PER_DIRECTION +const INLINE_TRANSFER_RESPONSE_BYTES = 2 * 1024 * 1024 + +/** Fixed v0.1.2 Typert Remote subset exposed to authenticated peers. */ +export const HARNESS_REMOTE_ALLOWLIST = [ + '$events', + '$events/result', + 'agentPresets/list', + 'agentPresets/read', + 'agentPresets/select', + 'commands/execute', + 'commands/list', + 'credentials/describe', + 'credentials/set', + 'credentials/unset', + 'directoryPicker/list', + 'fileReferences/list', + 'goals/clear', + 'goals/complete', + 'goals/create', + 'goals/edit', + 'goals/pause', + 'goals/resume', + 'job/list', + 'job/follow', + 'job/kill', + 'llm/discoverModels', + 'llm/listConfigurableProviders', + 'llm/listProviders', + 'messageFeedback/delete', + 'messageFeedback/list', + 'messageFeedback/put', + 'pluginInventory/list', + 'pluginManager/listBundles', + 'pluginManager/listPlugins', + 'pluginManager/listVersions', + 'pluginManager/readBundleDetail', + 'pluginManager/setBundleEnabled', + 'pluginManager/setPluginEnabled', + 'pluginManager/updateBundle', + 'permissionPresets/catalog', + 'schedule/list', + 'schedule/catalog', + 'schedule/history', + 'schedule/create', + 'schedule/update', + 'schedule/delete', + 'schedule/deleteInactive', + 'schedule/deliveryLimits', + 'schedule/edit', + 'schedule/run', + 'session/attachment', + 'session/cancel', + 'session/canOpenWorkspacePath', + 'session/control', + 'session/create', + 'session/follow', + 'session/fork', + 'session/list', + 'session/events', + 'session/modelCatalog', + 'session/page', + 'session/prompt', + 'remoteAccess/follow', + 'session/projections', + 'session/initializeDefaultModel', + 'session/workspacePathApplications', + 'session/rename', + 'session/search', + 'session/selectModel', + 'session/updateQueue', + 'sessionReferenceResolver/candidates', + 'settings/describe', + 'settings/mutate', + 'settings/replace', + 'settings/update', + 'skills/list', + 'subagents/interruptByParent', + 'subagents/list', + 'subagents/prompt', + 'userQuestions/answer', + 'userQuestions/attachWait', + 'claudeCodeMods/watchBand', + 'claudeCodeMods/pressBand', + 'workspaceFiles/list', + 'workspaceFiles/stat', + 'workspaceFiles/read', + 'workspaceFiles/readBytes', + 'workspaceFiles/readAll', + 'workspaceFiles/readRelated', + 'workspaceFiles/changes', + 'officeToPdf/render', + 'officeToPdf/generation', + 'toolResults/watch', + 'workspace/archiveSession', + 'workspace/create', + 'workspace/delete', + 'workspace/follow', + 'workspace/insertBefore', + 'workspace/insertSessionBefore', + 'workspace/rename', + 'workspace/unarchiveSession', + 'workspace/initializeDefault', + 'workspace/pinSession', + 'workspace/unpinSession', +] as const + +export type NativeWorkspaceResolver = (sessionId: string, signal: AbortSignal) => Promise + +export const WORKSPACE_FILE_READ_ENDPOINTS = new Set([ + 'workspaceFiles/read', + 'workspaceFiles/readBytes', + 'workspaceFiles/readAll', + 'workspaceFiles/stat', +]) + +const MAX_READ_BYTES = 4 * 1024 * 1024 + +/** + * Host-owned reminder service (`ctx.schedule`). The official package exposes + * create() only to in-process callers; this bridge is the single place an + * authenticated Remote client may reach it, and it validates the untrusted + * request itself before delegating. + */ +export interface ScheduleCreateService { + create(sessionId: string, request: ScheduleCreateRequest, signal?: AbortSignal): Promise +} + +/** Locale-independent "HH:mm" / "HH:mm:ss" / "HH:mm:ss.SSS". */ +const LOCAL_TIME = /^\d{2}:\d{2}(:\d{2}(\.\d{1,3})?)?$/u + +const localTimeSchema = z.object({ + time: z.string().regex(LOCAL_TIME, 'expected HH:mm or HH:mm:ss'), + time_zone: z.string().min(1).max(64), +}).strict() + +const nonBlank = (max: number) => z.string().max(max).refine(value => value.trim().length > 0, 'must not be blank') +const scheduleCreateArgsSchema = z.object({ + sessionId: nonBlank(128), + title: nonBlank(120), + prompt: nonBlank(20_000), + after_seconds: z.number().int().positive().max(31_536_000).optional(), + at: z.union([ + z.string().min(1).max(64), + z.object({ date: nonBlank(32), time: nonBlank(32), time_zone: nonBlank(64) }).strict(), + ]).optional(), + every_seconds: z.number().int().min(60).max(31_536_000).optional(), + daily: localTimeSchema.optional(), + weekly: z.object({ + time: z.string().regex(LOCAL_TIME, 'expected HH:mm or HH:mm:ss'), + time_zone: z.string().min(1).max(64), + weekdays: z.array(z.number().int().min(1).max(7)).min(1).max(7) + .refine(days => new Set(days).size === days.length, 'weekdays must be unique'), + }).strict().optional(), + cron: z.object({ expression: nonBlank(128), time_zone: z.string().min(1).max(64) }).strict().optional(), +}).strict() + +export type ScheduleCreateRequest = Omit, 'sessionId'> + +/** + * Refusals the reminder service publishes to clients. Anything else (fs errors, + * storage faults, arbitrary thrown values) is reported as a generic failure so + * internal detail never reaches the wire. + */ +const PUBLIC_SCHEDULE_ERRORS: Record = { + invalid_prompt: 'The reminder prompt was rejected.', + invalid_selector: 'Exactly one reminder trigger is required.', + invalid_rule: 'The reminder rule was rejected.', + invalid_time_zone: 'The reminder time zone is not supported.', + subagent_session: 'The target session is controlled by a delegated child.', + session_not_found: 'The target session no longer exists.', + schedule_limit: 'This session already has the maximum number of reminders.', + schedule_ended: 'The reminder has already ended.', + schedule_conflict: 'The reminder changed on the Host. Reload and retry.', +} + +const allowedEndpoints = new Set(HARNESS_REMOTE_ALLOWLIST) + +/** Host-side adapter from the encrypted peer channel to the official alpha Gateway carrier. */ +export class HarnessRemoteBridge { + compactHistoryEnabled = false + private readonly streams = new Map() + private readonly incomingTransfers = new Map() + private readonly outgoingTransfers = new Map() + private warnedMissingRemoteEvents = false + + private readonly terminalCarrier: TerminalCarrierCompat | undefined + + constructor( + private readonly gateway: LocalTypertGateway, + private readonly publish: PublishRemoteFrame, + private readonly logger?: SafeLogger, + private readonly harnessVersion?: string, + private readonly terminal = new TerminalPolicy(() => false, "", new Map()), + private readonly codexWorkspace?: CodexWorkspaceBridge, + private readonly resolveWorkspaceRoot?: NativeWorkspaceResolver, + private readonly schedule?: ScheduleCreateService, + ) { + this.terminalCarrier = usesDuplexTerminal(harnessVersion) ? new TerminalCarrierCompat(gateway) : undefined + } + + async call(input: unknown): Promise { + const params = callSchema.parse(input) as HarnessRemoteCallParams + this.assertAllowed(params.endpoint) + if (TERMINAL_STREAMS.has(params.endpoint)) throw new RpcError('METHOD_NOT_ALLOWED', 'Use a stream for this terminal endpoint.') + if (['settings/update', 'settings/replace', 'settings/mutate'].includes(params.endpoint)) { + const args = requestArgs(params.payload) + if (args.ns === 'ds-harness-remote-fast' || args.ns === 'ds-harness-remote' || args.ns === 'dsh-remote') { + throw new RpcError('PERMISSION_DENIED', 'Remote access settings can only be changed locally on the Host.') + } + } + await this.checkPluginManagement(params.endpoint, params.payload) + const reservation = params.endpoint.startsWith('terminal/') ? this.terminal.check(params.endpoint, params.payload) : undefined + let codexResult: TypertRpcResult | undefined + if (this.codexWorkspace !== undefined) { + try { + codexResult = await this.codexWorkspace.call(params.endpoint, params.payload, AbortSignal.timeout(60_000)) + } catch (error) { + // Release failed allocations only after their process cleanup succeeds. + if (reservation !== undefined) { + this.terminal.result(params.endpoint, params.payload, { ok: false, error: { code: error instanceof RpcError ? error.code : 'FAILED', message: '', details: {} } }, reservation) + } + throw error + } + } + if (codexResult !== undefined) return reservation === undefined ? codexResult : this.terminal.result(params.endpoint, params.payload, codexResult, reservation) + if (params.endpoint === 'schedule/create') { + return this.createSchedule(params.payload) + } + if (params.endpoint === 'session/canOpenWorkspacePath') { + return { ok: true, value: true } + } + if (params.endpoint === 'workspace/create') { + const request = requestArgs(params.payload) + const folder = typeof request.path === 'string' ? request.path : '' + await ensureHostWorkspaceDirectory(folder) + } + const startedAt = performance.now() + const signal = AbortSignal.timeout(60_000) + try { + let nativePayload = normalizeWorkspaceRequestPayload(params.endpoint, params.payload, this.harnessVersion) + nativePayload = await normalizeSessionAttachmentPayload(params.endpoint, nativePayload, this.harnessVersion, this.gateway, signal) + if (this.resolveWorkspaceRoot !== undefined && WORKSPACE_FILE_READ_ENDPOINTS.has(params.endpoint)) { + nativePayload = await this.assertNativeWorkspaceFileCall(params.endpoint, nativePayload, signal) + } + const nativeResult = params.endpoint === 'commands/execute' + ? await dispatchCommandForHost(this.gateway, params.payload, signal, this.harnessVersion) + : this.terminalCarrier !== undefined && (params.endpoint === 'terminal/write' || params.endpoint === 'terminal/resize') + ? await this.terminalCarrier.call(params.endpoint, nativePayload, signal) + : await this.gateway.dispatch(params.endpoint, nativePayload, signal) + const result = params.endpoint === 'directoryPicker/list' && needsDirectoryFallback(nativeResult) + ? await this.directoryList(params.payload, signal) + : filterRemotePluginInventory(params.endpoint, nativeResult) + this.logger?.debug('harness remote call ok', { + endpoint: params.endpoint, + durationMs: Math.round(performance.now() - startedAt), + }) + // The native 0.2.x workspace APIs return binary payloads as Uint8Array. + // Remote calls cross a JSON-only encrypted frame, so keep the wire + // contract stable by converting only the two bounded preview responses + // to canonical base64. (Codex/ACP workspace bridges already return the + // wire shape and are left unchanged.) + const filteredResult = filterSessionListProjections(params.endpoint, result) + const wireResult = normalizeWorkspaceBinaryResult(params.endpoint, + this.compactHistoryEnabled && ['session/page', 'session/events', 'session/history', 'subagent/history'].includes(params.endpoint) + ? compactHistory(filteredResult) : filteredResult) + return reservation === undefined ? wireResult : this.terminal.result(params.endpoint, params.payload, wireResult, reservation) + } catch (error) { + if (reservation !== undefined) this.terminal.result(params.endpoint, params.payload, { ok: false, error: { code: 'FAILED', message: '', details: {} } }, reservation) + if (params.endpoint === 'directoryPicker/list') { + const result = await this.directoryList(params.payload, signal) + this.logger?.debug('harness remote call ok', { + endpoint: params.endpoint, + durationMs: Math.round(performance.now() - startedAt), + fallback: 'directory-browser', + }) + return result + } + const reason = workspaceFileFailureReason(error) + this.logger?.warn('harness remote call failed', { + endpoint: params.endpoint, + durationMs: Math.round(performance.now() - startedAt), + code: this.gateway.failure(error).code, + ...(reason === undefined ? {} : { reason }), + }) + throw error + } + } + + /** Validate one untrusted create request, then delegate to the Host schedule service. */ + private async createSchedule(payload: unknown): Promise { + if (this.schedule === undefined) { + return { + ok: false, + error: { code: 'FEATURE_NOT_SUPPORTED', message: 'This Host does not expose the schedule service.', details: {} }, + } + } + const args = requestArgs(payload) + const selectors = ['after_seconds', 'at', 'every_seconds', 'daily', 'weekly', 'cron'].filter(key => args[key] !== undefined) + if (selectors.length !== 1) { + return { + ok: false, + error: { code: 'invalid_selector', message: 'Exactly one reminder selector is required.', details: {} }, + } + } + const parsed = scheduleCreateArgsSchema.safeParse(args) + if (!parsed.success) { + const issue = parsed.error.issues[0] + return { + ok: false, + error: { + code: 'invalid_rule', + message: issue === undefined ? 'The reminder request is invalid.' : `${issue.path.join('.') || 'request'}: ${issue.message}`, + details: {}, + }, + } + } + const { sessionId, ...request } = parsed.data + try { + // The service is expected to honour the signal; the timeout bounds how long + // a stuck create can hold the bridge open, not the provider's own work. + const record = await this.schedule.create(sessionId, request, AbortSignal.timeout(60_000)) + return { ok: true, value: record } + } catch (error) { + const published = isRecord(error) && typeof error.code === 'string' ? PUBLIC_SCHEDULE_ERRORS[error.code] : undefined + if (published === undefined) { + return { + ok: false, + error: { code: 'FAILED', message: 'The Host could not create the reminder.', details: {} }, + } + } + const code = (error as { code: string }).code + return { ok: false, error: { code, message: published, details: {} } } + } + } + + private async directoryList(payload: unknown, signal: AbortSignal): Promise { + const args = requestArgs(payload) + const params = directoryListSchema.parse(args) + return { ok: true, value: await listRemoteDirectory(params.path, signal) } + } + + openTransfer(input: unknown): { opened: true; transferId: string } { + this.pruneTransfers() + const params = transferOpenSchema.parse(input) as HarnessApiTransferOpenParams + if (params.totalChunks !== Math.ceil(params.totalBytes / HARNESS_API_TRANSFER_CHUNK_BYTES)) { + throw new RpcError('INVALID_MESSAGE', 'The Harness Remote transfer chunk count is invalid.') + } + if (this.incomingTransfers.has(params.transferId) || this.outgoingTransfers.has(params.transferId)) { + throw new RpcError('REQUEST_CONFLICT', 'The Harness Remote transfer id is already active.') + } + if (this.incomingTransfers.size >= MAX_ACTIVE_TRANSFERS) { + throw new RpcError('RATE_LIMITED', 'Too many Harness Remote transfers are active.', undefined, true) + } + this.incomingTransfers.set(params.transferId, { + totalBytes: params.totalBytes, + totalChunks: params.totalChunks, + chunks: [], + receivedBytes: 0, + touchedAt: Date.now(), + }) + return { opened: true, transferId: params.transferId } + } + + appendTransfer(input: unknown): { accepted: true; transferId: string; index: number } { + this.pruneTransfers() + const params = transferChunkSchema.parse(input) as HarnessApiTransferChunkParams + const transfer = this.incomingTransfers.get(params.transferId) + if (transfer === undefined) throw new RpcError('TRANSFER_NOT_FOUND', 'The Harness Remote transfer is not active.') + if (params.index !== transfer.chunks.length || params.index >= transfer.totalChunks) { + this.incomingTransfers.delete(params.transferId) + throw new RpcError('INVALID_MESSAGE', 'Harness Remote transfer chunks must arrive exactly once and in order.') + } + const chunk = decodeCanonicalBase64(params.data) + const expectedBytes = Math.min( + HARNESS_API_TRANSFER_CHUNK_BYTES, + transfer.totalBytes - params.index * HARNESS_API_TRANSFER_CHUNK_BYTES, + ) + if (chunk.byteLength !== expectedBytes) { + this.incomingTransfers.delete(params.transferId) + throw new RpcError('INVALID_MESSAGE', 'The Harness Remote transfer chunk size is invalid.') + } + transfer.chunks.push(chunk) + transfer.receivedBytes += chunk.byteLength + transfer.touchedAt = Date.now() + return { accepted: true, transferId: params.transferId, index: params.index } + } + + async commitTransfer(input: unknown): Promise { + this.pruneTransfers() + const params = transferIdSchema.parse(input) + const transfer = this.incomingTransfers.get(params.transferId) + if (transfer === undefined) throw new RpcError('TRANSFER_NOT_FOUND', 'The Harness Remote transfer is not active.') + this.incomingTransfers.delete(params.transferId) + if (transfer.chunks.length !== transfer.totalChunks || transfer.receivedBytes !== transfer.totalBytes) { + throw new RpcError('INVALID_MESSAGE', 'The Harness Remote transfer is incomplete.') + } + let request: unknown + try { + request = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(concatChunks(transfer.chunks, transfer.totalBytes))) + } catch { + throw new RpcError('INVALID_MESSAGE', 'The Harness Remote transfer does not contain a valid request.') + } + const response = await this.call(callSchema.parse(request)) + const responseBytes = new TextEncoder().encode(JSON.stringify(response)) + if (responseBytes.byteLength <= INLINE_TRANSFER_RESPONSE_BYTES) return { kind: 'inline', response } + if (responseBytes.byteLength > MAX_HARNESS_API_TRANSFER_BYTES) { + throw new RpcError('RESPONSE_TOO_LARGE', 'The Harness Remote response exceeds the bounded transfer limit.') + } + if (this.outgoingTransfers.size >= MAX_ACTIVE_TRANSFERS) { + throw new RpcError('RATE_LIMITED', 'Too many Harness Remote response transfers are active.', undefined, true) + } + const totalChunks = Math.ceil(responseBytes.byteLength / HARNESS_API_TRANSFER_CHUNK_BYTES) + this.outgoingTransfers.set(params.transferId, { + bytes: responseBytes, + totalChunks, + nextIndex: 0, + touchedAt: Date.now(), + }) + return { kind: 'chunked', transferId: params.transferId, totalBytes: responseBytes.byteLength, totalChunks } + } + + readTransfer(input: unknown): HarnessApiTransferReadResult { + this.pruneTransfers() + const params = transferReadSchema.parse(input) as HarnessApiTransferReadParams + const transfer = this.outgoingTransfers.get(params.transferId) + if (transfer === undefined) throw new RpcError('TRANSFER_NOT_FOUND', 'The Harness Remote response transfer is not active.') + if (params.index !== transfer.nextIndex || params.index >= transfer.totalChunks) { + this.outgoingTransfers.delete(params.transferId) + transfer.finish?.(new Error('Invalid Harness Remote stream transfer order')) + throw new RpcError('INVALID_MESSAGE', 'Harness Remote response chunks must be read exactly once and in order.') + } + const start = params.index * HARNESS_API_TRANSFER_CHUNK_BYTES + const end = Math.min(start + HARNESS_API_TRANSFER_CHUNK_BYTES, transfer.bytes.byteLength) + transfer.nextIndex += 1 + transfer.touchedAt = Date.now() + return { + transferId: params.transferId, + index: params.index, + data: Buffer.from(transfer.bytes.subarray(start, end)).toString('base64'), + } + } + + closeTransfer(input: unknown): { closed: boolean; transferId: string } { + const params = transferIdSchema.parse(input) + const transfer = this.outgoingTransfers.get(params.transferId) + transfer?.finish?.(transfer.nextIndex === transfer.totalChunks ? undefined : new Error('Incomplete Harness Remote stream transfer')) + const closed = this.incomingTransfers.delete(params.transferId) || this.outgoingTransfers.delete(params.transferId) + return { closed, transferId: params.transferId } + } + + async openStream(input: unknown): Promise<{ opened: true; streamId: string }> { + const params = streamOpenSchema.parse(input) as HarnessRemoteStreamOpenParams + this.assertAllowed(params.endpoint) + if (params.endpoint.startsWith('pluginManager/')) throw new RpcError('METHOD_NOT_ALLOWED', 'Plugin management endpoints are not streams.') + if (params.endpoint.startsWith('settings/')) throw new RpcError('METHOD_NOT_ALLOWED', 'Settings endpoints are not streams.') + if (TERMINAL_CALLS.has(params.endpoint)) throw new RpcError('METHOD_NOT_ALLOWED', 'This terminal endpoint is not a stream.') + if (TERMINAL_STREAMS.has(params.endpoint)) this.terminal.check(params.endpoint, params.payload) + if (this.streams.has(params.streamId)) throw new RpcError('REQUEST_CONFLICT', 'The Harness Remote stream is already open.') + if (this.streams.size >= MAX_ACTIVE_STREAMS) { + throw new RpcError('RATE_LIMITED', 'Too many Harness Remote streams are open.', undefined, true) + } + const controller = new AbortController() + this.streams.set(params.streamId, { controller }) + let source: AsyncIterable + try { + source = (this.codexWorkspace === undefined ? undefined : await this.codexWorkspace.open(params.endpoint, params.payload, controller.signal)) + ?? await (params.endpoint === 'terminal/follow' && this.terminalCarrier !== undefined + ? this.terminalCarrier.open(params.payload, controller.signal) + : this.gateway.open(params.endpoint, normalizeWorkspaceChangesPayload(params.endpoint, params.payload, this.harnessVersion), controller.signal)) + controller.signal.throwIfAborted() + } catch (error) { + this.streams.delete(params.streamId) + controller.abort() + throw error + } + if (params.endpoint === '$events') source = this.remoteEventsWithFallback(source, controller.signal) + void this.pump(params.streamId, source, controller.signal, params.endpoint === 'session/follow', params.transferFrames) + return { opened: true, streamId: params.streamId } + } + + private async *remoteEventsWithFallback(source: AsyncIterable, signal: AbortSignal): AsyncGenerator { + const iterator = source[Symbol.asyncIterator]() + let first: IteratorResult + try { + first = await iterator.next() + } catch (error) { + if (!await this.canUseIdleRemoteEvents(error, signal)) throw error + yield { type: 'ready', clientId: randomUUID(), host: { home: homedir() } } + await new Promise(resolve => { + if (signal.aborted) { resolve(); return } + signal.addEventListener('abort', () => resolve(), { once: true }) + }) + return + } + try { + for (let item = first; !item.done; item = await iterator.next()) yield item.value + } finally { + await iterator.return?.() + } + } + + private async canUseIdleRemoteEvents(error: unknown, signal: AbortSignal): Promise { + if (signal.aborted || this.gateway.failure(error).code !== 'gateway/service-unavailable') return false + // Do not report a connected generation when the Host Session API is absent. + const sessions = await this.gateway.dispatch('session/list', { args: { _request: {} } }, signal).catch(() => undefined) + if (sessions?.ok !== true) { + this.warnMissingRemoteEvents(sessions?.ok === false && sessions.error.code === 'gateway/invocation-unavailable' + ? 'Host Remote API is incomplete. Install @deepseek-ai/dsh-api-remotes and its Host API packages.' + : 'Cannot verify the Host Session API. Remote events cannot start.') + return false + } + this.warnMissingRemoteEvents('Host Remote events are unavailable. Install @deepseek-ai/dsh-api-remotes and its Host API packages. Event updates are disabled.') + return true + } + + private warnMissingRemoteEvents(message: string): void { + if (this.warnedMissingRemoteEvents) return + this.warnedMissingRemoteEvents = true + this.logger?.warn(message) + } + + closeStream(input: unknown): { closed: boolean; streamId: string } { + const params = streamCloseSchema.parse(input) + const active = this.streams.get(params.streamId) + if (active !== undefined) { + this.streams.delete(params.streamId) + active.controller.abort('client-closed') + } + return { closed: active !== undefined, streamId: params.streamId } + } + + async closeAll(reason: HarnessRemoteStreamClosedData['reason'] = 'peer-disconnected'): Promise { + const streams = [...this.streams.entries()] + this.streams.clear() + this.incomingTransfers.clear() + this.outgoingTransfers.clear() + for (const [, stream] of streams) stream.controller.abort(reason) + await Promise.all([this.gateway.dispose?.(), this.codexWorkspace?.closeAll()]) + } + + private async checkPluginManagement(endpoint: string, payload: unknown): Promise { + if (endpoint === 'pluginManager/updateBundle') { + await this.checkRemoteBundleUpdate(payload) + return + } + if (endpoint !== 'pluginManager/setPluginEnabled' && endpoint !== 'pluginManager/setBundleEnabled') return + const plugin = endpoint === 'pluginManager/setPluginEnabled' + const key = plugin ? 'id' : 'name' + // Validate the actual Typert argument envelope; never authorize a nested alias + // while forwarding different top-level arguments to the official Gateway. + const parsed = z.object({ args: z.object({ + [key]: z.string().min(1).max(4096), + enabled: z.boolean(), + }).strict() }).strict().safeParse(payload) + if (!parsed.success) throw new RpcError('INVALID_MESSAGE', 'Invalid plugin enablement request.') + const args = parsed.data.args + const result = await this.gateway.dispatch(plugin ? 'pluginManager/listPlugins' : 'pluginManager/listBundles', { args: {} }, AbortSignal.timeout(60_000)) + if (!result.ok || !Array.isArray(result.value)) throw new RpcError('PERMISSION_DENIED', 'Cannot verify the Host plugin inventory.') + const row = result.value.find(value => isRecord(value) && value[plugin ? 'entryId' : 'name'] === args[key]) + if (!isRecord(row) || row.readOnlyReason !== undefined) throw new RpcError('PERMISSION_DENIED', 'The Host plugin cannot be changed remotely.') + if (remoteOwnedBundleRow(row, plugin)) { + throw new RpcError('PERMISSION_DENIED', 'The Remote plugin can only be enabled or disabled locally on the Host.') + } + } + + /** + * 0.2.2 adds official third-party bundle updates. Keep the mutation available + * to trusted devices but never let a Remote user replace this plugin (or a + * bundle owning it) from over the encrypted channel. + */ + private async checkRemoteBundleUpdate(payload: unknown): Promise { + const parsed = z.object({ + args: z.object({ + name: z.string().min(1).max(4096), + version: z.string().min(1).max(256), + }).strict(), + }).strict().safeParse(payload) + if (!parsed.success) throw new RpcError('INVALID_MESSAGE', 'Invalid plugin update request.') + const result = await this.gateway.dispatch('pluginManager/listBundles', { args: {} }, AbortSignal.timeout(60_000)) + if (!result.ok || !Array.isArray(result.value)) throw new RpcError('PERMISSION_DENIED', 'Cannot verify the Host plugin inventory.') + const row = result.value.find(value => isRecord(value) && value.name === parsed.data.args.name) + if (!isRecord(row) || row.readOnlyReason !== undefined || row.updatable !== true) { + throw new RpcError('PERMISSION_DENIED', 'The Host plugin cannot be updated remotely.') + } + if (remoteOwnedBundleRow(row, false)) { + throw new RpcError('PERMISSION_DENIED', 'The Remote plugin can only be updated locally on the Host.') + } + } + + private assertAllowed(endpoint: string): void { + if (!allowedEndpoints.has(endpoint) && !TERMINAL_CALLS.has(endpoint) && !TERMINAL_STREAMS.has(endpoint)) { + throw new RpcError('METHOD_NOT_ALLOWED', 'The requested Harness Remote endpoint is not allowed.') + } + if (endpoint === '$events' && !this.gateway.supportsCarrier) { + throw new RpcError('FEATURE_NOT_SUPPORTED', 'This Harness version does not support Remote event transport.') + } + } + + private async pump(streamId: string, source: AsyncIterable, signal: AbortSignal, historyFollow = false, transferFrames = false): Promise { + let reason: HarnessRemoteStreamClosedData['reason'] = 'completed' + let failure: HarnessRemoteStreamClosedData['failure'] + try { + for await (const value of source) { + if (signal.aborted) break + let frame: HarnessRemoteFrameData = { + streamId, + hasValue: true, + ...(value === undefined ? {} : { value: historyFollow && (this.compactHistoryEnabled || isLiteModeEnabled()) && isCompactSnapshot(value) ? compactHistory(value) : value }), + } + if (isLiteModeEnabled()) { + const shaped = applyLiteMode(frame) as HarnessRemoteFrameData | undefined + if (shaped === undefined) { + // Only unknown/cosmetic projections are dropped; log so a missing + // client update can be traced back to fast mode instead of guessed. + const layer = isJsonRecord(frame.value) ? frame.value : undefined + const bytes = layer === undefined ? 0 : Buffer.byteLength(JSON.stringify(layer.value ?? null)) + this.logger?.debug('fast mode dropped projection frame', { + streamId, + key: typeof layer?.key === 'string' ? layer.key : 'unknown', + bytes, + }) + continue + } + frame = shaped + } + const encoded = encodeMessage(createEvent('harness.remote.frame', frame)) + const bytes = encoded.byteLength + // Peak-only telemetry: fast mode is usually visible here, and logging + // every small frame would drown the log. + if (bytes >= FRAME_DIAGNOSTIC_MIN_BYTES) { + const value = isJsonRecord(frame.value) ? frame.value : undefined + this.logger?.info('outbound frame', { + type: typeof value?.type === 'string' ? value.type : 'unknown', + bytes, + lite: isLiteModeEnabled(), + transferFrames, + }) + } + if (bytes > MAX_SECURE_MESSAGE_BYTES) { + if (!transferFrames) throw new Error('Oversized Harness Remote frame') + await this.transferStreamFrame(frame, signal) + } else { + await this.publish('harness.remote.frame', frame) + } + } + if (signal.aborted) reason = 'cancelled' + } catch (error) { + reason = signal.aborted ? 'cancelled' : 'failed' + if (!signal.aborted) failure = this.gateway.failure(error) + } finally { + this.streams.delete(streamId) + await this.publish('harness.remote.stream.closed', { + streamId, + reason, + ...(failure === undefined ? {} : { failure }), + }).catch(() => undefined) + } + } + + /** Keep the source paused until the Client reads and releases this exact item. */ + private async transferStreamFrame(frame: HarnessRemoteFrameData, signal: AbortSignal): Promise { + signal.throwIfAborted() + this.pruneTransfers() + const bytes = new TextEncoder().encode(JSON.stringify(frame)) + if (bytes.byteLength > MAX_HARNESS_API_TRANSFER_BYTES) throw new Error('Harness Remote stream item exceeds the bounded transfer limit') + if (this.outgoingTransfers.size >= MAX_ACTIVE_TRANSFERS) throw new Error('Too many Harness Remote response transfers are active') + const transferId = randomUUID() + const totalChunks = Math.ceil(bytes.byteLength / HARNESS_API_TRANSFER_CHUNK_BYTES) + let finish!: (error?: Error) => void + const completed = new Promise((resolve, reject) => { finish = error => error === undefined ? resolve() : reject(error) }) + // Attach a rejection handler before publishing; cancellation may race the write. + void completed.catch(() => undefined) + const transfer: OutgoingTransfer = { bytes, totalChunks, nextIndex: 0, touchedAt: Date.now(), finish } + this.outgoingTransfers.set(transferId, transfer) + const onAbort = () => finish(new Error('Harness Remote stream transfer cancelled')) + signal.addEventListener('abort', onAbort, { once: true }) + const timer = setInterval(() => { + if (Date.now() - transfer.touchedAt >= TRANSFER_IDLE_MS) finish(new Error('Harness Remote stream transfer timed out')) + }, 1000) + timer.unref() + try { + await this.publish('harness.remote.frame', { + streamId: frame.streamId, hasValue: true, + transfer: { kind: 'chunked', transferId, totalBytes: bytes.byteLength, totalChunks }, + }) + await completed + } finally { + clearInterval(timer) + signal.removeEventListener('abort', onAbort) + this.outgoingTransfers.delete(transferId) + } + } + + private pruneTransfers(): void { + const cutoff = Date.now() - TRANSFER_IDLE_MS + for (const [id, transfer] of this.incomingTransfers) if (transfer.touchedAt < cutoff) this.incomingTransfers.delete(id) + for (const [id, transfer] of this.outgoingTransfers) if (transfer.touchedAt < cutoff) { + this.outgoingTransfers.delete(id) + transfer.finish?.(new Error('Harness Remote stream transfer timed out')) + } + } + + private async assertNativeWorkspaceFileCall( + endpoint: string, + payload: unknown, + signal: AbortSignal, + ): Promise { + const rootPayload = isRecord(payload) ? payload : {} + const args = requestArgs(payload) + const sessionId = typeof args.workspaceFileScopeId === 'string' + ? args.workspaceFileScopeId + : typeof args.sessionId === 'string' + ? args.sessionId + : typeof args.agentId === 'string' + ? args.agentId + : undefined + if (sessionId === undefined) { + throw workspaceFileFailure('WORKSPACE_UNAVAILABLE', 'The workspace identifier is missing.', 'scope-missing') + } + const sessionWorkspace = await this.resolveWorkspaceRootForSession(sessionId, signal) + if (!sessionWorkspace) { + throw workspaceFileFailure('WORKSPACE_UNAVAILABLE', 'The workspace is unavailable.', 'authority-unavailable') + } + + const options = isRecord(args.options) ? args.options : undefined + const rawBaseFile = endpoint === 'workspaceFiles/readBytes' + ? (typeof options?.baseFile === 'string' ? options.baseFile : (typeof args.baseFile === 'string' ? args.baseFile : undefined)) + : undefined + + if (endpoint === 'workspaceFiles/readBytes') { + if (options !== undefined && 'baseFile' in options && options.baseFile !== undefined && typeof options.baseFile !== 'string') { + throw workspaceFileFailure('WORKSPACE_PATH_DENIED', 'The requested workspace path is outside the workspace.', 'outside-root') + } + if ('baseFile' in args && args.baseFile !== undefined && typeof args.baseFile !== 'string') { + throw workspaceFileFailure('WORKSPACE_PATH_DENIED', 'The requested workspace path is outside the workspace.', 'outside-root') + } + } + + let safeRel: string + if (rawBaseFile !== undefined) { + const path = typeof args.path === 'string' ? args.path : '' + const relative = path.replaceAll('\\', '/') + if (relative.length === 0 || relative.startsWith('/') || /^[a-z][a-z\d+.-]*:/iu.test(relative) || relative.includes('\x00')) { + throw workspaceFileFailure('WORKSPACE_PATH_DENIED', 'The requested workspace path is outside the workspace.', 'outside-root') + } + const baseSegments = process.platform === 'win32' ? rawBaseFile.replaceAll('\\', '/').split('/') : rawBaseFile.split('/') + if (baseSegments.some(segment => segment === '..')) { + throw workspaceFileFailure('WORKSPACE_PATH_DENIED', 'The requested workspace path is outside the workspace.', 'outside-root') + } + const safeBaseRel = await this.verifyWorkspacePathContainment(sessionWorkspace.root, rawBaseFile, endpoint) + const baseCandidate = resolve(sessionWorkspace.root, safeBaseRel) + const baseDir = dirname(baseCandidate) + const targetCandidate = resolve(baseDir, path) + safeRel = await this.verifyWorkspacePathContainment(sessionWorkspace.root, targetCandidate, endpoint) + } else { + const path = typeof args.path === 'string' ? args.path : '.' + const pathSegments = process.platform === 'win32' ? path.replaceAll('\\', '/').split('/') : path.split('/') + if (pathSegments.some(segment => segment === '..')) { + throw workspaceFileFailure('WORKSPACE_PATH_DENIED', 'The requested workspace path is outside the workspace.', 'outside-root') + } + safeRel = await this.verifyWorkspacePathContainment(sessionWorkspace.root, path, endpoint) + } + + let finalArgs: Record = isRecord(rootPayload.args) + ? { ...rootPayload.args, path: safeRel } + : { ...rootPayload, path: safeRel } + + if (isRecord(finalArgs.options)) { + const { baseFile: _baseFile, ...restOptions } = finalArgs.options + finalArgs.options = restOptions + } + delete finalArgs.baseFile + if (endpoint === 'workspaceFiles/readBytes') { + const range = byteOrLineRange(finalArgs) + const offset = typeof range.offset === 'number' && Number.isInteger(range.offset) && range.offset >= 0 ? range.offset : 0 + const rawLength = typeof range.length === 'number' && Number.isInteger(range.length) && range.length > 0 ? range.length : MAX_READ_BYTES + const boundedLength = Math.min(rawLength, MAX_READ_BYTES) + const normalizedRange = { offset, length: boundedLength } + if (requiresWorkspaceChangePath(this.harnessVersion)) { + finalArgs.options = { ...(isRecord(finalArgs.options) ? finalArgs.options : {}), range: normalizedRange } + delete finalArgs.range + } else { + finalArgs.range = normalizedRange + if (isRecord(finalArgs.options)) { + finalArgs.options = { ...finalArgs.options, range: normalizedRange } + } + } + if ('offset' in finalArgs || 'length' in finalArgs) { + finalArgs.offset = offset + finalArgs.length = boundedLength + } + } + return isRecord(rootPayload.args) ? { ...rootPayload, args: finalArgs } : finalArgs + } + + private async resolveWorkspaceRootForSession( + sessionId: string, + signal: AbortSignal, + ): Promise<{ root: string; cwd: string } | undefined> { + signal.throwIfAborted() + if (this.resolveWorkspaceRoot === undefined) { + return undefined + } + const cwd = await this.resolveWorkspaceRoot(sessionId, signal) + if (!cwd) { + throw workspaceFileFailure('WORKSPACE_UNAVAILABLE', 'The workspace is unavailable.', 'authority-unavailable') + } + try { + const root = await realpath(cwd) + const info = await stat(root) + if (!info.isDirectory()) { + throw workspaceFileFailure('WORKSPACE_UNAVAILABLE', 'The workspace is unavailable.', 'root-invalid') + } + return { root, cwd } + } catch (error) { + if (error instanceof RpcError) throw error + throw workspaceFileFailure('WORKSPACE_UNAVAILABLE', 'The workspace is unavailable.', 'authority-unavailable') + } + } + + /** + * Containment is always evaluated against the canonical workspace root, not + * the raw `cwd`: a symlinked parent, a `..` segment or a Windows case variant + * must not turn an in-root file into a denial. The boundary itself is + * unchanged: the canonical target must stay inside the canonical root. + */ + private async verifyWorkspacePathContainment( + root: string, + path: string, + endpoint: string, + ): Promise { + const candidate = isAbsolute(path) ? resolve(path) : resolve(root, path) + if (process.platform === 'win32') { + const rootDrive = parse(root).root.toLowerCase() + const candDrive = parse(candidate).root.toLowerCase() + if (rootDrive !== candDrive) { + throw workspaceFileFailure('WORKSPACE_PATH_DENIED', 'The requested workspace path is outside the workspace.', 'outside-root') + } + } + if (isPathOutside(relative(root, candidate))) { + throw workspaceFileFailure('WORKSPACE_PATH_DENIED', 'The requested workspace path is outside the workspace.', 'outside-root') + } + + try { + const rootLstat = await lstat(root) + if (rootLstat.isSymbolicLink() || !rootLstat.isDirectory()) { + throw workspaceFileFailure('WORKSPACE_PATH_DENIED', 'The workspace root is invalid or a symlink.', 'root-invalid') + } + + const rel = relative(root, candidate) + const parts = rel.split(sep).filter(p => p.length > 0 && p !== '.') + let currentPath = root + for (let i = 0; i < parts.length - 1; i++) { + currentPath = join(currentPath, parts[i]!) + if (isPathOutside(relative(root, currentPath))) { + throw workspaceFileFailure('WORKSPACE_PATH_DENIED', 'The requested workspace path is outside the workspace.', 'outside-root') + } + const dirLstat = await lstat(currentPath) + if (dirLstat.isSymbolicLink()) { + throw workspaceFileFailure('WORKSPACE_PATH_DENIED', 'An ancestor directory is invalid or a symlink.', 'symlink') + } + if (!dirLstat.isDirectory()) { + throw workspaceFileFailure('WORKSPACE_PATH_DENIED', 'An ancestor directory is invalid or a symlink.', 'not-regular-file') + } + } + + const targetLstat = await lstat(candidate) + if (targetLstat.isSymbolicLink()) { + throw workspaceFileFailure('WORKSPACE_PATH_DENIED', 'The requested workspace path is not a regular file.', 'symlink') + } + + const canonical = await realpath(candidate) + if (process.platform === 'win32') { + const rootDrive = parse(root).root.toLowerCase() + const canonicalDrive = parse(canonical).root.toLowerCase() + if (rootDrive !== canonicalDrive) { + throw workspaceFileFailure('WORKSPACE_PATH_DENIED', 'The requested workspace path is outside the workspace.', 'outside-root') + } + } + const canonicalRel = relative(root, canonical) + if (isPathOutside(canonicalRel)) { + throw workspaceFileFailure('WORKSPACE_PATH_DENIED', 'The requested workspace path is outside the workspace.', 'outside-root') + } + + const info = await stat(canonical) + if (endpoint !== 'workspaceFiles/stat' && !info.isFile()) { + throw workspaceFileFailure('WORKSPACE_PATH_DENIED', 'The requested workspace path is not a regular file.', 'not-regular-file') + } + + if (endpoint === 'workspaceFiles/readAll' && Number(info.size) > MAX_READ_BYTES) { + throw workspaceFileFailure('WORKSPACE_TOO_LARGE', 'The requested workspace file is too large.', 'too-large') + } + + // On Windows normalize backslashes to slashes; on POSIX backslashes are valid filename characters and must not be mangled + const safeRel = canonicalRel === '' ? '.' : (process.platform === 'win32' ? canonicalRel.replaceAll('\\', '/') : canonicalRel) + + // Validate the exact path passed to the gateway resolves within workspace + const dispatchedCandidate = resolve(root, safeRel) + const dispatchedCanonical = await realpath(dispatchedCandidate) + const dispatchedRel = relative(root, dispatchedCanonical) + if (isPathOutside(dispatchedRel)) { + throw workspaceFileFailure('WORKSPACE_PATH_DENIED', 'The requested workspace path is outside the workspace.', 'outside-root') + } + + return safeRel + } catch (error) { + if (error instanceof RpcError) throw error + const reason = (error as NodeJS.ErrnoException)?.code === 'ENOENT' ? 'not-found' as const : 'io' as const + throw workspaceFileFailure('WORKSPACE_PATH_DENIED', 'The requested workspace path is unavailable.', reason) + } + } + +} + +function isPathOutside(rel: string): boolean { + if (rel === '..' || isAbsolute(rel)) return true + if (process.platform === 'win32') { + return rel.startsWith('..\\') || rel.startsWith('../') + } + return rel.startsWith('../') +} + +function byteOrLineRange(args: Record): Record { + const options = isRecord(args.options) ? args.options : undefined + if (options !== undefined && isRecord(options.range)) return options.range + return isRecord(args.range) ? args.range : args +} + +/** + * DSH 0.1.7 changed workspaceFiles/changes from a Session-wide feed to a + * target-scoped feed that requires `path`. Older Web/Client bundles still + * open the Session-wide form. Keep that request working on a 0.1.7 Host by + * watching the workspace root; the legacy client continues filtering frames + * by the file it has opened. Do not add the field to older Hosts, whose + * generated Typert schema rejects unknown arguments. + */ +function normalizeWorkspaceChangesPayload(endpoint: string, payload: unknown, harnessVersion?: string): unknown { + if (endpoint !== 'workspaceFiles/changes' || !requiresWorkspaceChangePath(harnessVersion)) return payload + if (!isRecord(payload) || !isRecord(payload.args) || Object.hasOwn(payload.args, 'path')) return payload + return { ...payload, args: { ...payload.args, path: '.' } } +} + +/** + * DSH 0.1.7 nests the byte range under `options`, while older clients send + * it directly on the request args. Keep the translation Host-version gated: + * older generated descriptors reject the new `options` field. + */ +function normalizeWorkspaceRequestPayload(endpoint: string, payload: unknown, harnessVersion?: string): unknown { + if (!isRecord(payload) || !isRecord(payload.args)) return payload + const args = payload.args + if (endpoint === 'workspaceFiles/readBytes' && requiresWorkspaceChangePath(harnessVersion)) { + if (!Object.hasOwn(args, 'range') || Object.hasOwn(args, 'options')) return payload + const { range, ...rest } = args + return { ...payload, args: { ...rest, options: { range } } } + } + // DSH 0.2 removes the first-use naming request; accept a legacy client + // payload while keeping the generated 0.2 endpoint's zero-argument shape. + if (endpoint === 'workspace/initializeDefault' && isDshV02OrNewer(harnessVersion) && Object.hasOwn(args, 'request')) { + const { request: _request, ...rest } = args + return { ...payload, args: rest } + } + return payload +} + +/** + * 0.2.2 changed `session/attachment` from one durable id to the full + * `ImageAttachmentRef` (the Host now verifies media type, byte length and + * dimensions against the stored object). Older Hosts only understand the id, + * and their strict codec rejects an unexpected `attachment` field, so reduce a + * Remote client's reference to `{ sessionId, attachmentId }` before dispatch. + * + * On a 0.2.2+ Host, a legacy client that only persisted the durable id cannot + * supply the verified reference. Recover it from the session's persisted events + * (`session/events`, `session/page`, `session/history`) and fill + * `request.attachment` so the Host can still verify and return the image. + */ +async function normalizeSessionAttachmentPayload( + endpoint: string, + payload: unknown, + harnessVersion: string | undefined, + gateway: LocalTypertGateway, + signal: AbortSignal, +): Promise { + if (endpoint !== 'session/attachment' || !isRecord(payload) || !isRecord(payload.args)) return payload + const request = isRecord(payload.args.request) ? payload.args.request : undefined + if (request === undefined) return payload + const attachment = isRecord(request.attachment) ? request.attachment : undefined + const attachmentId = attachment !== undefined && typeof attachment.attachmentId === 'string' + ? attachment.attachmentId + : typeof request.attachmentId === 'string' ? request.attachmentId : undefined + if (attachmentId === undefined) return payload + + if (!isDshV022OrNewer(harnessVersion)) { + // Pre-0.2.2 strict codec only accepts the durable id. + const sessionId = request.sessionId + return { ...payload, args: { ...payload.args, request: { sessionId, attachmentId } } } + } + // If the client already supplied a complete reference, keep it honest. + if (attachment !== undefined && isCompleteImageReference(attachment)) return payload + const reference = await findSessionAttachmentReference(gateway, request.sessionId, attachmentId, signal) + if (reference === undefined) return payload + const mergedAttachment = attachment !== undefined ? { ...reference, ...attachment } : reference + return { ...payload, args: { ...payload.args, request: { ...request, attachment: mergedAttachment } } } +} + +/** Best-effort recovery of the full `ImageAttachmentRef` a 0.2.2 Host verifies. */ +async function findSessionAttachmentReference( + gateway: LocalTypertGateway, + sessionId: unknown, + attachmentId: string, + signal: AbortSignal, +): Promise | undefined> { + if (typeof sessionId !== 'string' || sessionId.length === 0) return undefined + + // 1. Try session/events first (complete live stream if available) + try { + const result = await gateway.dispatch('session/events', { args: { request: { address: { kind: 'session', sessionId } } } }, signal) + const reference = extractAttachmentReference(result, attachmentId) + if (reference !== undefined) return reference + } catch { + // Fall back to paginated session/page + } + + // 2. Try paginating through session/page + let beforeSeq: number | undefined = undefined + for (let page = 0; page < 10; page += 1) { + try { + const pageRequest: Record = { + address: { kind: 'session', sessionId }, + maxMessages: 200, + ...(beforeSeq !== undefined ? { beforeSeq } : {}), + } + const result = await gateway.dispatch('session/page', { args: { request: pageRequest } }, signal) + const reference = extractAttachmentReference(result, attachmentId) + if (reference !== undefined) return reference + if (result.ok === true && isRecord(result.value)) { + if (result.value.hasMore === true && typeof result.value.beforeSeq === 'number') { + beforeSeq = result.value.beforeSeq + continue + } + } + break + } catch { + break + } + } + + // 3. Fallback to session/history for older 0.2.x shapes + try { + const result = await gateway.dispatch('session/history', { args: { request: { sessionId, maxMessages: 200 } } }, signal) + const reference = extractAttachmentReference(result, attachmentId) + if (reference !== undefined) return reference + } catch {} + + return undefined +} + +/** Locate a complete image reference inside an events/records response. */ +function extractAttachmentReference(result: TypertRpcResult, attachmentId: string): Record | undefined { + if (result.ok !== true) return undefined + const value = result.value + let records: unknown[] | undefined + if (Array.isArray(value)) records = value + else if (isRecord(value)) { + if (Array.isArray(value.records)) records = value.records + else if (Array.isArray(value.events)) records = value.events + } + if (records === undefined) return undefined + for (const record of records) { + const found = findImageReference(record, attachmentId, 0) + if (found !== undefined) return found + } + return undefined +} + +/** Recursively find an image block carrying a complete reference for `attachmentId`. */ +function findImageReference(value: unknown, attachmentId: string, depth: number): Record | undefined { + if (depth > 12 || value === null || typeof value !== 'object') return undefined + if (Array.isArray(value)) { + for (const item of value) { + const found = findImageReference(item, attachmentId, depth + 1) + if (found !== undefined) return found + } + return undefined + } + const block = value as Record + const candidate = isRecord(block.attachment) ? block.attachment : block + const candidateId = typeof candidate.attachmentId === 'string' ? candidate.attachmentId : undefined + if (candidateId === attachmentId && isCompleteImageReference(candidate)) { + return { + attachmentId, + mediaType: candidate.mediaType, + bytes: candidate.bytes, + width: candidate.width, + height: candidate.height, + ...(typeof candidate.name === 'string' ? { name: candidate.name } : {}), + } + } + for (const nested of Object.values(block)) { + if (nested === null || typeof nested !== 'object') continue + const found = findImageReference(nested, attachmentId, depth + 1) + if (found !== undefined) return found + } + return undefined +} + +function isCompleteImageReference(value: Record): boolean { + return typeof value.mediaType === 'string' + && typeof value.bytes === 'number' + && typeof value.width === 'number' + && typeof value.height === 'number' +} + +/** Whether this Host reads the 0.2.2 attachment-reference request shape. */ +function isDshV022OrNewer(version: string | undefined): boolean { + const match = /^(?:dsh-)?v?(\d+)\.(\d+)\.(\d+)(?:-|$)/u.exec(version?.trim() ?? '') + if (match === null) return false + const major = Number(match[1]) + const minor = Number(match[2]) + const patch = Number(match[3]) + return major > 0 || (major === 0 && (minor > 2 || (minor === 2 && patch >= 2))) +} + +function isDshV02OrNewer(version: string | undefined): boolean { + const match = /^(?:dsh-)?v?(\d+)\.(\d+)\.(\d+)(?:-|$)/u.exec(version?.trim() ?? '') + if (match === null) return false + return Number(match[1]) === 0 && Number(match[2]) >= 2 +} + +function requiresWorkspaceChangePath(version: string | undefined): boolean { + const match = /^(?:dsh-)?v?(\d+)\.(\d+)\.(\d+)(?:-|$)/u.exec(version?.trim() ?? '') + if (match === null) return false + return Number(match[1]) === 0 + && ((Number(match[2]) === 1 && Number(match[3]) >= 7) || Number(match[2]) === 2) +} + +async function dispatchCommandForHost( + gateway: LocalTypertGateway, + payload: unknown, + signal: AbortSignal, + harnessVersion?: string, +): Promise { + const parsed = commandExecutePayloadSchema.parse(payload) + const legacyPayload = { + args: { + agentId: parsed.args.agentId, + line: parsed.args.line, + images: parsed.args.images ?? [], + }, + } + const currentPayload = { + args: { + agentId: parsed.args.agentId, + line: parsed.args.line, + submittedAttachments: parsed.args.submittedAttachments ?? [], + }, + } + const args = harnessSessionGeneration(harnessVersion) === 'v3' ? currentPayload : legacyPayload + return gateway.dispatch( + 'commands/execute', + args, + signal, + ) +} + +function decodeCanonicalBase64(value: string): Uint8Array { + const bytes = Buffer.from(value, 'base64') + if (bytes.toString('base64') !== value) throw new RpcError('INVALID_MESSAGE', 'The Harness Remote transfer chunk is invalid.') + return bytes +} + +function normalizeWorkspaceBinaryResult(endpoint: string, result: TypertRpcResult): TypertRpcResult { + if (result.ok !== true || (endpoint !== 'workspaceFiles/readBytes' && endpoint !== 'officeToPdf/render')) return result + if (!isJsonRecord(result.value)) return result + const directBytes = isBinary(result.value.data) ? result.value.data : undefined + const attachmentBytes = directBytes === undefined ? attachmentAt(result, ['data']) : undefined + if (directBytes === undefined && attachmentBytes === undefined) return result + const bytes = directBytes ?? attachmentBytes! + return { + ok: true, + value: { + ...result.value, + data: Buffer.from(bytes).toString('base64'), + }, + } +} + +function attachmentAt(result: TypertRpcResult, path: readonly string[]): Uint8Array | undefined { + const attachments = (result as TypertRpcResult & { attachments?: unknown }).attachments + if (!Array.isArray(attachments)) return undefined + const attachment = attachments.find(item => { + if (!isJsonRecord(item) || !Array.isArray(item.path) || item.path.length !== path.length) return false + return item.path.every((part, index) => part === path[index]) + }) + return isJsonRecord(attachment) && isBinary(attachment.bytes) ? attachment.bytes : undefined +} + +function isBinary(value: unknown): value is Uint8Array { + return value instanceof Uint8Array +} + +function isJsonRecord(value: unknown): value is Record { + return typeof value === 'object' && value !== null && !Array.isArray(value) +} + +function concatChunks(chunks: readonly Uint8Array[], totalBytes: number): Uint8Array { + const result = new Uint8Array(totalBytes) + let offset = 0 + for (const chunk of chunks) { + result.set(chunk, offset) + offset += chunk.byteLength + } + return result +} + +function needsDirectoryFallback(result: TypertRpcResult): boolean { + if (result.ok) return false + const code = result.error.code.toLocaleLowerCase() + const message = result.error.message.toLocaleLowerCase() + return code.includes('capability') + || code === 'directory-picker/unavailable' + || code === 'directory-picker-unavailable' + || message.includes('browse capability') + || message.includes('browser capability') + || message.includes('brower capability') + || message.includes('directory-picker-unavailable') +} + +/** Frames at or above this size are logged so an A/B run is measurable. */ +const FRAME_DIAGNOSTIC_MIN_BYTES = 256 * 1024 + + +const SESSION_PROJECTION_WHITELIST = new Set([ + 'permissions', + 'remoteStatusKnown', + 'codexStatus', + 'inbox', + 'agentTeam', + 'turnOutline', + 'imageLimits', + 'turn', + 'turnState', + 'model', + 'status', + 'activeTurnId', + 'modelSelection', + 'userQuestions', + 'agentPreset', + 'sessionListMetadata', + 'title', + 'sessionTitle', + 'conversationTitle', + 'label', + 'name', + 'summary', + 'metadata', + 'session', + 'data', + 'view', + 'sessionStats', + 'tokenUsage', +]) + +const DANGEROUS_KEYS = new Set(['__proto__', 'prototype', 'constructor']) +const MAX_WHITELIST_PROJECTION_BYTES = 64 * 1024 +const MAX_UNKNOWN_PROJECTION_BYTES = 4096 + +function filterSessionProjections(session: unknown): unknown { + if (!isRecord(session) || !isRecord(session.projections) || !isRecord(session.projections.values)) { + return session + } + const originalValues = session.projections.values + const filteredValues: Record = {} + let changed = false + + for (const [key, value] of Object.entries(originalValues)) { + if (DANGEROUS_KEYS.has(key)) { + changed = true + continue + } + const isWhitelisted = SESSION_PROJECTION_WHITELIST.has(key) + const limitBytes = isWhitelisted ? MAX_WHITELIST_PROJECTION_BYTES : MAX_UNKNOWN_PROJECTION_BYTES + try { + const serialized = JSON.stringify(value) + if (typeof serialized === 'string' && Buffer.byteLength(serialized, 'utf8') <= limitBytes) { + filteredValues[key] = value + } else { + changed = true + } + } catch { + changed = true + } + } + + if (!changed) return session + + return { + ...session, + projections: { + ...session.projections, + values: filteredValues, + }, + } +} + +/** + * A session catalogue above the client row bound cannot be listed at all: every + * client validates the shared list against a fixed maximum (2 048 rows today) + * before it filters by workspace, so one large account blanks the whole Remote + * surface (measured 5 431 rows, 4 701 of them subagent Sessions). Degrade only + * when the bound is actually exceeded, and degrade by dropping the rows that no + * client lists as roots instead of failing the listing. + */ +const SESSION_LIST_ROW_BUDGET = 2_048 + +function trimSessionCatalogRows(endpoint: string | undefined, items: unknown[]): unknown[] { + if (endpoint !== 'session/list' || items.length <= SESSION_LIST_ROW_BUDGET) return items + const roots = items.filter(isListableRemoteSession) + const kept = roots.length > 0 ? roots : items + return kept.length <= SESSION_LIST_ROW_BUDGET + ? kept + : kept.slice().sort((left, right) => updatedAtOf(right) - updatedAtOf(left)).slice(0, SESSION_LIST_ROW_BUDGET) +} + +function isListableRemoteSession(session: unknown): boolean { + return isRecord(session) && session.parentSessionId === undefined && session.origin !== 'subagent' +} + +function updatedAtOf(session: unknown): number { + return isRecord(session) && typeof session.updatedAt === 'number' ? session.updatedAt : 0 +} + +/** + * Harness 0.2.2 dropped the top-level `title` from SessionSummary rows; the + * durable title stays in the projection block, so Remote lists render blank + * names unless the Host lifts it back onto the row. + */ +function withSessionRowTitle(session: unknown): unknown { + if (!isRecord(session) || (typeof session.title === 'string' && session.title !== '')) return session + const values = isRecord(session.projections) ? session.projections.values : undefined + const title = isRecord(values) ? values.title : undefined + return typeof title === 'string' && title !== '' ? { ...session, title } : session +} + +export function filterSessionListProjections(result: TypertRpcResult): TypertRpcResult +export function filterSessionListProjections(endpoint: string, result: TypertRpcResult): TypertRpcResult +export function filterSessionListProjections( + resultOrEndpoint: TypertRpcResult | string, + maybeResult?: TypertRpcResult, +): TypertRpcResult { + const endpoint = typeof resultOrEndpoint === 'string' ? resultOrEndpoint : undefined + const result = endpoint === undefined ? resultOrEndpoint as TypertRpcResult : maybeResult! + if (endpoint !== undefined && endpoint !== 'session/list' && endpoint !== 'session/search') return result + if (!result || !result.ok) return result + const filterList = (items: unknown[]): unknown[] => trimSessionCatalogRows(endpoint, items) + .map(filterSessionProjections) + .map(withSessionRowTitle) + if (isRecord(result.value)) { + let changed = false + const updated = { ...result.value } + if (Array.isArray(result.value.items)) { + updated.items = filterList(result.value.items) + changed = true + } + if (Array.isArray(result.value.sessions)) { + updated.sessions = filterList(result.value.sessions) + changed = true + } + if (changed) return { ...result, value: updated } + } + if (Array.isArray(result.value)) { + return { + ...result, + value: filterList(result.value), + } + } + return result +} + +function filterRemotePluginInventory(endpoint: string, result: TypertRpcResult): TypertRpcResult { + if (!result.ok) return result + const isRemote = (value: unknown): boolean => typeof value === 'string' + && /^(?:ds-harness-remote-fast|ds-harness-remote|dsh-remote)(?:\/|$)/.test(value) + const filterEntries = (entries: unknown[]): unknown[] => entries.filter(entry => + !isRecord(entry) || !isRemote(entry.moduleName)) + if (endpoint === 'pluginManager/listPlugins' && Array.isArray(result.value)) { + return { ...result, value: filterEntries(result.value) } + } + if (endpoint === 'pluginManager/listBundles' && Array.isArray(result.value)) { + return { ...result, value: result.value + .filter(bundle => !isRecord(bundle) || !isRemote(bundle.name)) + .map(bundle => isRecord(bundle) && Array.isArray(bundle.rows) + ? { ...bundle, rows: filterEntries(bundle.rows) } : bundle) } + } + if (endpoint === 'pluginInventory/list' && isRecord(result.value) && Array.isArray(result.value.entries)) { + return { ...result, value: { ...result.value, entries: filterEntries(result.value.entries) } } + } + return result +} + +function requestArgs(payload: unknown): Record { + const root = record(payload) + const args = isRecord(root.args) ? root.args : root + return record(args.request ?? args._request ?? args) +} + +function record(value: unknown): Record { + return isRecord(value) ? value : {} +} + +function isRecord(value: unknown): value is Record { + return typeof value === 'object' && value !== null && !Array.isArray(value) +} + +function isCompactSnapshot(value: unknown): boolean { + return value !== null && typeof value === 'object' && (value as { type?: unknown }).type === 'snapshot' +} + +/** Whether one official plugin-manager row belongs to this Remote plugin or its bundle. */ +function remoteOwnedBundleRow(row: Record, plugin: boolean): boolean { + const remoteModule = (value: unknown): boolean => typeof value === 'string' + && /^(?:ds-harness-remote-fast|ds-harness-remote|dsh-remote)(?:\/|$)/.test(value) + if (remoteModule(plugin ? row.moduleName : row.name)) return true + return !plugin && (!Array.isArray(row.rows) + || row.rows.some(value => !isRecord(value) || remoteModule(value.moduleName)) + || (Array.isArray(row.overrides) + && row.overrides.some(value => remoteModule(value)))) +}