1540 lines
67 KiB
TypeScript
1540 lines
67 KiB
TypeScript
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<void>
|
|
|
|
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<string | undefined>
|
|
|
|
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<unknown>
|
|
}
|
|
|
|
/** 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<z.infer<typeof scheduleCreateArgsSchema>, '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<string, string> = {
|
|
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<string>(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<string, ActiveRemoteStream>()
|
|
private readonly incomingTransfers = new Map<string, IncomingTransfer>()
|
|
private readonly outgoingTransfers = new Map<string, OutgoingTransfer>()
|
|
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<TypertRpcResult> {
|
|
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<TypertRpcResult> {
|
|
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<TypertRpcResult> {
|
|
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<HarnessApiTransferCommitResult> {
|
|
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<unknown>
|
|
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<unknown>, signal: AbortSignal): AsyncGenerator<unknown> {
|
|
const iterator = source[Symbol.asyncIterator]()
|
|
let first: IteratorResult<unknown>
|
|
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<void>(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<boolean> {
|
|
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<void> {
|
|
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<void> {
|
|
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<void> {
|
|
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<unknown>, signal: AbortSignal, historyFollow = false, transferFrames = false): Promise<void> {
|
|
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<void> {
|
|
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<void>((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<unknown> {
|
|
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<string, unknown> = 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<string> {
|
|
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<string, unknown>): Record<string, unknown> {
|
|
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<unknown> {
|
|
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<Record<string, unknown> | 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<string, unknown> = {
|
|
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<string, unknown> | 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<string, unknown> | 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<string, unknown>
|
|
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<string, unknown>): 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<TypertRpcResult> {
|
|
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<string, unknown> {
|
|
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<string, unknown> = {}
|
|
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<string, unknown> {
|
|
const root = record(payload)
|
|
const args = isRecord(root.args) ? root.args : root
|
|
return record(args.request ?? args._request ?? args)
|
|
}
|
|
|
|
function record(value: unknown): Record<string, unknown> {
|
|
return isRecord(value) ? value : {}
|
|
}
|
|
|
|
function isRecord(value: unknown): value is Record<string, unknown> {
|
|
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<string, unknown>, 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))))
|
|
}
|