diff --git a/packages/plugin/src/remote-session-tools.ts b/packages/plugin/src/remote-session-tools.ts new file mode 100644 index 0000000..3adcf64 --- /dev/null +++ b/packages/plugin/src/remote-session-tools.ts @@ -0,0 +1,391 @@ +import { uploadRemoteFile } from './remote-file-upload.js' +import { basename, isAbsolute } from 'node:path' +import { downloadRemoteFile } from './remote-file-download.js' +import { createHash } from 'node:crypto' +import { z } from 'zod' +import type { ConnectedRemote } from './client-runtime-contract.js' +import { RemoteTypertGateway } from './remote-typert-gateway.js' +import { uuidV7 } from './ids.js' + +const id = z.string().min(1).max(256) +const MAX_REMOTE_WORKSPACES = 512 +const MAX_REMOTE_SESSIONS = 2048 +const MAX_SESSIONS_PER_WORKSPACE = 2048 +const sequence = z.number().int().min(0).max(Number.MAX_SAFE_INTEGER) +const workspace = z.object({ hostId: id, backend: z.literal('harness'), workspaceId: id }).strict() +const session = workspace.extend({ sessionId: id }) +const operationId = z.string().regex(/^[A-Za-z0-9_-]{16,128}$/) +const cursor = z.object({ throughSeq: sequence, beforeSeq: sequence }).strict().refine(value => value.beforeSeq <= value.throughSeq) +export const sessionToolInputs = { + remote_upload_file: session.extend({ operationId, localPath: z.string().min(1).max(4096).refine(value => isAbsolute(value) && !value.includes('\0')), + name: z.string().min(1).refine(value => Buffer.byteLength(value, 'utf8') <= 220 && value !== '.' && value !== '..' && !/[\\/:\x00-\x1f\x7f]/u.test(value)).optional() }), + remote_download_file: session.extend({ path: z.string().min(1).max(4096).refine(value => !value.includes("\0") && !value.startsWith("/") && !value.includes("\\") && !value.includes(":") && value.split("/").every(part => part !== ".." && part !== "")) }), + remote_list_sessions: workspace.extend({ offset: sequence.max(100_000).default(0), limit: z.number().int().min(1).max(100).default(30) }), + remote_read_session: session.extend({ cursor: cursor.optional(), maxMessages: z.number().int().min(1).max(50).default(20) }), + remote_create_session: workspace.extend({ operationId }), + remote_send_message: session.extend({ operationId, message: z.string().min(1).max(64 * 1024).refine(value => value.trim().length > 0) }), + remote_interrupt_session: session.extend({ operationId }), + remote_wait_sessions: z.object({ targets: z.array(session).min(1).max(8), timeoutMs: z.number().int().min(0).max(60_000).default(30_000) }).strict(), + remote_get_operation: z.object({ operationId }).strict(), +} +export type SessionToolOperation = keyof typeof sessionToolInputs +export type SessionTarget = z.infer +type WorkspaceTarget = z.infer +type Mutation = 'remote_create_session' | 'remote_send_message' | 'remote_interrupt_session' +type Status = 'running' | 'idle' | 'needs_user_input' | 'failed' | 'unavailable' | 'unknown' +type Receipt = WorkspaceTarget & { + operationId: string + status: 'pending' | 'accepted' | 'rejected' | 'unknown' + sessionId?: string + requestId?: string +} +type LedgerEntry = { fingerprint: string; receipt: Receipt; pending: Promise } +export type RemoteToolConnection = (hostId: string, signal: AbortSignal, + query: (remote: ConnectedRemote, signal: AbortSignal) => Promise) => Promise + +const rowSchema = z.object({ + sessionId: id, title: z.string().optional(), running: z.boolean(), blank: z.boolean(), updatedAt: z.number(), + parentSessionId: z.string().optional(), origin: z.string().optional(), projections: z.unknown().optional(), +}) +type SessionRow = z.infer +const workspaceRow = z.object({ workspaceId: id, path: z.string(), title: z.string(), sessionIds: z.array(id).max(MAX_SESSIONS_PER_WORKSPACE) }) +const record = (value: unknown): Record => value !== null && typeof value === 'object' && !Array.isArray(value) ? value as Record : {} +export class RemoteSessionToolError extends Error {} +const fail = (code: string): never => { throw new RemoteSessionToolError(code) } + +/** Fixed native operations over the existing carrier. No alternate Harness wire API. */ +export class RemoteSessionTools { + // Only hashes, target identifiers and receipts live here; never message bodies. + // No eviction: dropping an old key would allow an uncertain mutation to replay. + private readonly ledger = new Map() + private generation = 0 + constructor(private readonly connect: RemoteToolConnection) {} + invalidate(): void { this.generation++; this.ledger.clear() } + + async run(operation: SessionToolOperation, input: unknown, signal: AbortSignal): Promise { + signal.throwIfAborted() + const generation = this.generation + const result = await this.execute(operation, input, signal) + if (generation !== this.generation) fail('REMOTE_AUTHORITY_CHANGED: Inspect the remote state; do not replay mutations.') + return result + } + + private async execute(operation: SessionToolOperation, input: unknown, signal: AbortSignal): Promise { + switch (operation) { + case 'remote_upload_file': { + const args = sessionToolInputs[operation].parse(input) + const fingerprint = createHash('sha256').update(JSON.stringify([operation, args])).digest('hex') + const old = this.ledger.get(args.operationId) + if (old) { + if (old.fingerprint !== fingerprint) fail('OPERATION_ID_CONFLICT') + return old.pending + } + if (this.ledger.size >= 1024) fail('OPERATION_LIMIT') + const generation = this.generation + const receipt: Receipt = { ...target(args), sessionId: args.sessionId, operationId: args.operationId, status: 'pending' } + let uploaderEntered = false + const pending = Promise.resolve().then(() => this.connect(args.hostId, signal, async (remote, active) => { + const gateway = new RemoteTypertGateway(remote.client) + if (!remote.features.remoteGateway) fail('HARNESS_SESSIONS_UNAVAILABLE') + await this.requireSession(gateway, args, active) + const name = args.name ?? basename(args.localPath) + sessionToolInputs.remote_upload_file.parse({ ...args, name }) + uploaderEntered = true + return uploadRemoteFile(remote.client, args.sessionId, args.localPath, name, active, () => { + if (generation !== this.generation) fail('REMOTE_AUTHORITY_CHANGED') + }) + })).then(result => Object.assign(receipt, result), () => { + // Before the uploader is entered, no upload RPC can have been sent. + // Once entered, cleanup/transport failures may hide a publication. + receipt.status = uploaderEntered ? 'unknown' : 'rejected' + return receipt + }) + this.ledger.set(args.operationId, { fingerprint, receipt, pending }) + return pending + } + case 'remote_download_file': { + const args = sessionToolInputs[operation].parse(input) + const generation = this.generation + return this.onHost(args, signal, async (gateway, active) => { + await this.requireSession(gateway, args, active) + return downloadRemoteFile(gateway, args.sessionId, args.path, active, () => { + if (generation !== this.generation) fail('REMOTE_AUTHORITY_CHANGED') + }) + }) + } + case 'remote_get_operation': { + const args = sessionToolInputs[operation].parse(input) + return this.ledger.get(args.operationId)?.receipt ?? { operationId: args.operationId, status: 'not_found', + warning: 'No receipt in this runtime. This does not prove the operation was not executed. Inspect the remote session before sending again.' } + } + case 'remote_list_sessions': { + const args = sessionToolInputs[operation].parse(input) + return this.onHost(args, signal, async (gateway, active) => { + const rows = await this.catalog(gateway, args, active) + const sorted = rows.sort((a, b) => b.updatedAt - a.updatedAt || a.sessionId.localeCompare(b.sessionId)) + const items = sorted.slice(args.offset, args.offset + args.limit).map(summary) + return { ...target(args), sessions: items, + nextOffset: args.offset + items.length < sorted.length ? args.offset + items.length : null } + }) + } + case 'remote_read_session': { + const args = sessionToolInputs[operation].parse(input) + return this.onHost(args, signal, async (gateway, active) => { + const row = await this.requireSession(gateway, args, active) + const page = args.cursor === undefined + ? await first(gateway, 'session/follow', { request: { address: address(args.sessionId), maxMessages: args.maxMessages } }, active) + : record(await gateway.invoke({ namespace: 'session', method: 'page', args: { request: { + address: address(args.sessionId), ...args.cursor, maxMessages: args.maxMessages, + } }, signal: active })) + const throughSeq = args.cursor?.throughSeq ?? page.cursor + if (args.cursor === undefined && page.type !== 'snapshot') fail('INVALID_SESSION_SNAPSHOT') + const records = historyRecords(page) + if (args.cursor && records.some(row => Number(record(row.event).seq) >= args.cursor!.beforeSeq)) fail('INVALID_HISTORY_PAGE') + const state = new ObservedState(row) + if (args.cursor === undefined) state.snapshot(page) + return { ...target(args), sessionId: args.sessionId, status: state.status, + ...boundedHistory(records, page.hasMore === true, throughSeq) } + }) + } + case 'remote_wait_sessions': return this.wait(sessionToolInputs[operation].parse(input), signal) + case 'remote_create_session': return this.mutate(operation, sessionToolInputs[operation].parse(input), signal) + case 'remote_send_message': return this.mutate(operation, sessionToolInputs[operation].parse(input), signal) + case 'remote_interrupt_session': return this.mutate(operation, sessionToolInputs[operation].parse(input), signal) + } + } + + private onHost(args: WorkspaceTarget, signal: AbortSignal, + query: (gateway: RemoteTypertGateway, signal: AbortSignal) => Promise): Promise { + return this.connect(args.hostId, signal, (remote, active) => { + if (!remote.features.remoteGateway) fail('HARNESS_SESSIONS_UNAVAILABLE') + return query(new RemoteTypertGateway(remote.client), active) + }) + } + + private async requireWorkspace(gateway: RemoteTypertGateway, args: WorkspaceTarget, signal: AbortSignal) { + const baseline = await first(gateway, 'workspace/follow', {}, signal) + if (baseline.type !== 'baseline') fail('INVALID_WORKSPACE_BASELINE') + const rows = z.array(workspaceRow).max(MAX_REMOTE_WORKSPACES).parse(record(baseline.value).items) + const found = rows.find(row => row.workspaceId === args.workspaceId) + if (!found) fail('WORKSPACE_NOT_FOUND') + return found! + } + + private async catalog(gateway: RemoteTypertGateway, args: WorkspaceTarget, signal: AbortSignal): Promise { + const found = await this.requireWorkspace(gateway, args, signal) + const response = record(await gateway.invoke({ namespace: 'session', method: 'list', args: { _request: {} }, signal })) + // The Host catalogue covers the whole account while one workspace owns a + // small slice of it, so the row bound must apply after workspace ownership + // and the subagent filter: bound-then-filter rejects a large account + // outright (measured 5 431 rows against a 2 048 bound) instead of listing + // the handful of sessions this workspace actually owns. + const rows = z.array(rowSchema).parse(response.items) + const allowed = new Set(found.sessionIds) + // Workspace ownership comes from the official catalog, never a guessed cwd. + const owned = rows.filter(row => allowed.has(row.sessionId) && row.parentSessionId === undefined && row.origin !== 'subagent') + return owned.length > MAX_REMOTE_SESSIONS ? owned.slice(0, MAX_REMOTE_SESSIONS) : owned + } + + private async requireSession(gateway: RemoteTypertGateway, args: SessionTarget, signal: AbortSignal) { + const row = (await this.catalog(gateway, args, signal)).find(row => row.sessionId === args.sessionId) + if (!row) fail('SESSION_NOT_IN_WORKSPACE') + return row! + } + + private async mutate(operation: Mutation, + args: WorkspaceTarget & { operationId: string; sessionId?: string; message?: string }, signal: AbortSignal): Promise { + const fingerprint = createHash('sha256').update(JSON.stringify([operation, args.hostId, args.backend, + args.workspaceId, args.sessionId ?? null, args.message ?? null])).digest('hex') + const old = this.ledger.get(args.operationId) + if (old) { + if (old.fingerprint !== fingerprint) fail('OPERATION_ID_CONFLICT') + return old.pending + } + if (this.ledger.size >= 512) fail('OPERATION_RECEIPT_LIMIT') + const receipt: Receipt = { ...target(args), operationId: args.operationId, status: 'pending', + ...(args.sessionId === undefined ? {} : { sessionId: args.sessionId }), + ...(operation === 'remote_send_message' ? { requestId: uuidV7() } : {}) } + let dispatched = false + // Defer preflight so the entry exists before any concurrent caller can enter. + const entry: LedgerEntry = { fingerprint, receipt, pending: undefined! } + entry.pending = Promise.resolve().then(async () => { + try { + await this.onHost(args, signal, async (gateway, active) => { + if (operation === 'remote_create_session') await this.requireWorkspace(gateway, args, active) + else await this.requireSession(gateway, args as SessionTarget, active) + active.throwIfAborted() + const endpoint = operation === 'remote_create_session' ? 'session/create' + : operation === 'remote_send_message' ? 'session/prompt' : 'session/cancel' + const request = operation === 'remote_create_session' ? { workspaceId: args.workspaceId } + : operation === 'remote_send_message' ? { sessionId: args.sessionId, requestId: receipt.requestId, + mode: 'queue', content: [{ type: 'text', text: args.message }] } + : { sessionId: args.sessionId } + dispatched = true + const result = await gateway.dispatch(endpoint, { args: { request } }, active) + if (!result.ok) { entry.receipt = { ...receipt, status: 'rejected' }; return } + const value = record(result.value) + if (operation === 'remote_create_session') { + const sessionId = id.parse(value.sessionId) + entry.receipt = { ...receipt, sessionId, status: 'accepted' } + } else if (operation === 'remote_interrupt_session' && value.accepted !== true) { + entry.receipt = { ...receipt, status: 'unknown' } + } else entry.receipt = { ...receipt, status: 'accepted' } + }) + } catch { + if (!dispatched) { + // Safe to retry only when no mutation reached the carrier. + if (this.ledger.get(args.operationId) === entry) this.ledger.delete(args.operationId) + fail('REMOTE_PREFLIGHT_FAILED: No mutation was dispatched. Check login and target identifiers.') + } + // Preserve a confirmed reply even if carrier cleanup fails afterwards. + if (entry.receipt.status === 'pending') entry.receipt = { ...receipt, status: 'unknown' } + } + return entry.receipt + }) + this.ledger.set(args.operationId, entry) + return entry.pending + } + + private async wait(args: z.infer, signal: AbortSignal) { + const keys = args.targets.map(item => JSON.stringify(item)) + if (new Set(keys).size !== keys.length) fail('DUPLICATE_WAIT_TARGET') + const stop = new AbortController() + const active = AbortSignal.any([signal, stop.signal]) + const states = args.targets.map(item => ({ ...item, status: 'unknown' as Status })) + let timedOut = false + // A zero timeout is an immediate snapshot, not a zero-budget connection attempt. + let timer: ReturnType | undefined + if (args.timeoutMs > 0) timer = setTimeout(() => { timedOut = true; stop.abort() }, args.timeoutMs) + const workers = args.targets.map(async (item, index) => { + try { + await this.onHost(item, active, async (gateway, current) => { + const row = await this.requireSession(gateway, item, current) + const source = await gateway.open('session/follow', { args: { request: { address: address(item.sessionId), maxMessages: 20 } } }, current) + const iterator = source[Symbol.asyncIterator]() + try { + const observed = new ObservedState(row) + const snapshot = await iterator.next() + if (snapshot.done || record(snapshot.value).type !== 'snapshot') fail('INVALID_SESSION_SNAPSHOT') + observed.snapshot(record(snapshot.value)) + states[index]!.status = observed.status + if (args.timeoutMs === 0 || observed.status !== 'running') return + while (!current.aborted) { + const next = await iterator.next() + if (next.done) { current.throwIfAborted(); fail('SESSION_STREAM_CLOSED') } + observed.frame(record(next.value)) + states[index]!.status = observed.status + if (observed.status !== 'running') return + } + current.throwIfAborted() + } finally { await iterator.return?.() } + }) + } catch { + if (!active.aborted) states[index]!.status = 'unavailable' + } + }) + try { + if (args.timeoutMs === 0) await Promise.all(workers) + else await Promise.race(workers) + } finally { + if (timer !== undefined) clearTimeout(timer) + stop.abort() + await Promise.allSettled(workers) + } + signal.throwIfAborted() + return { sessions: states, timedOut } + } +} + +function target(args: WorkspaceTarget): WorkspaceTarget { + return { hostId: args.hostId, backend: 'harness', workspaceId: args.workspaceId } +} +function address(sessionId: string) { return { kind: 'session', sessionId } } +function summary(row: SessionRow) { + return { sessionId: row.sessionId, title: (row.title ?? '').slice(0, 500), running: row.running, blank: row.blank, updatedAt: row.updatedAt } +} + +async function first(gateway: RemoteTypertGateway, endpoint: string, args: Record, signal: AbortSignal) { + const stop = new AbortController() + const source = await gateway.open(endpoint, { args }, AbortSignal.any([signal, stop.signal])) + const iterator = source[Symbol.asyncIterator]() + try { + const next = await iterator.next() + signal.throwIfAborted() + if (next.done) fail('REMOTE_STREAM_CLOSED') + return record(next.value) + } finally { + stop.abort() + await iterator.return?.() + } +} +function historyRecords(page: Record): Record[] { + if (!Array.isArray(page.records) || typeof page.hasMore !== 'boolean') fail('INVALID_HISTORY_PAGE') + return (page.records as unknown[]).map(value => { + const row = record(value), event = record(row.event) + if (!['event', 'chunks'].includes(String(row.type)) || !Number.isSafeInteger(event.seq) + || Number(event.seq) < 0 || typeof event.type !== 'string') fail('INVALID_HISTORY_RECORD') + return row + }) +} +function boundedHistory(records: Record[], hasMore: boolean, throughSeq: unknown) { + if (!Number.isSafeInteger(throughSeq) || Number(throughSeq) < -1) fail('INVALID_HISTORY_CURSOR') + if (records.some(row => Number(record(row.event).seq) > Number(throughSeq))) fail('INVALID_HISTORY_CURSOR') + const selected: Array<{ seq: number; type: string; json: string; truncated: boolean }> = [] + let budget = 48_000 + for (const row of [...records].reverse()) { + const event = record(row.event), json = JSON.stringify(row) + if (selected.length > 0 && json.length > budget) break + const text = json.slice(0, Math.min(budget, 16_000)) + selected.unshift({ seq: Number(event.seq), type: String(event.type), json: text, truncated: text.length < json.length }) + budget -= text.length + if (budget <= 0) break + } + const more = hasMore || selected.length < records.length + if (more && selected.length === 0) fail('INVALID_HISTORY_PAGE') + const beforeSeq = selected.length === 0 ? undefined : Math.min(...selected.map(row => row.seq)) + if (more && beforeSeq === 0) fail('INVALID_HISTORY_PAGE') + return { records: selected, hasMore: more, + nextCursor: more && beforeSeq !== undefined && beforeSeq > 0 ? { throughSeq, beforeSeq } : null } +} + +/** Status is execution state, never a claim that the user's objective is complete. */ +class ObservedState { + status: Status + private running: boolean + private queued = false + private failed = false + private readonly approvals = new Set() + private readonly questions = new Set() + constructor(row: SessionRow) { this.running = row.running; this.status = row.running ? 'running' : 'idle'; this.projection('inbox', record(record(row.projections).values).inbox) } + snapshot(value: Record) { + // The snapshot is newer than preflight catalog lookup. Its latest native + // lifecycle event resolves a turn starting/ending between those requests. + for (const row of historyRecords(value)) this.event(record(row.event), true) + const values = record(record(value.projections).values) + if ('inbox' in values) this.projection('inbox', values.inbox) + this.update() + } + frame(value: Record) { + if (value.type === 'event' || value.type === 'chunks') this.event(record(value.event), true) + else if (value.type === 'projection' && typeof value.key === 'string') this.projection(value.key, value.value) + this.update() + } + private event(event: Record, live: boolean) { + const data = record(event.data), id = typeof data.id === 'string' ? data.id : undefined + if (event.type === 'turn/start') { this.failed = false; this.approvals.clear(); this.questions.clear(); if (live) { this.running = true; this.queued = false } } + if (event.type === 'turn/end') { this.failed = [data.reason, record(data.reason).kind].some(reason => reason === 'error' || reason === 'failed'); this.approvals.clear(); this.questions.clear(); if (live) this.running = false } + if (event.type === 'approval/asked' && id) this.approvals.add(id) + if (event.type === 'approval/decided' && id) this.approvals.delete(id) + const callId = record(record(data.message).source).callId ?? data.callId ?? data.id + if (event.type === 'tool/call' && (data.name ?? data.toolName) === 'ask_user_question' && typeof callId === 'string') this.questions.add(callId) + if (event.type === 'tool/result' && typeof callId === 'string') this.questions.delete(callId) + } + private projection(key: string, value: unknown) { + if (key === 'inbox') this.queued = Array.isArray(record(value)['next-turn']) && (record(value)['next-turn'] as unknown[]).length > 0 + this.update() + } + private update() { + this.status = this.running && (this.approvals.size > 0 || this.questions.size > 0) ? 'needs_user_input' + : this.running || this.queued ? 'running' : this.failed ? 'failed' : 'idle' + } +}