import { z } from 'zod' import type { LocalTypertGateway, RemoteTypertGatewayTarget, TypertRpcResult } from './typert-gateway-contract.js' import { RpcError } from './safe-error.js' import { uuidV7 } from './ids.js' const identity = z.string().regex(/^[A-Za-z0-9_:-]{1,256}$/) const attachmentArgs = z.object({ agentId: identity, id: identity, attachmentId: identity }).strict() const dimensions = { cols: z.number().int().min(1).max(1000), rows: z.number().int().min(1).max(1000) } const input = z.discriminatedUnion('type', [ z.object({ type: z.literal('write'), sequence: z.number().int().positive().safe(), data: z.string().max(64 * 1024) }).strict(), z.object({ type: z.literal('resize'), sequence: z.number().int().positive().safe(), ...dimensions }).strict(), ]) type Input = z.infer /** Fixed terminal API changed in 0.2.1-alpha.3; other streams remain read-only. */ export function usesDuplexTerminal(version: string | undefined): boolean { const match = /^(?:dsh-)?v?0\.(\d+)\.(\d+)(?:-([^+]+))?(?:\+.*)?$/.exec(version ?? '') if (!match) return false const minor = Number(match[1]), patch = Number(match[2]) if (minor > 2 || (minor === 2 && patch > 1)) return true if (minor !== 2 || patch !== 1) return false return match[3] === undefined || !match[3].startsWith('alpha.') || Number(match[3].slice(6)) >= 3 } /** Bounded single-consumer queue. Closing discards inputs, never replays them. */ class Queue implements AsyncIterable { private values: { value: unknown; bytes: number }[] = [] private bytes = 0 private wake?: () => void private closed = false private error?: unknown constructor(private readonly maxBytes = 256 * 1024, private readonly maxItems = 64) {} push(value: unknown): void { if (this.closed) throw new RpcError('TRANSPORT_CLOSED', 'The terminal attachment closed.') const bytes = new TextEncoder().encode(JSON.stringify(value)).byteLength if (this.values.length >= this.maxItems || this.bytes + bytes > this.maxBytes) throw new RpcError('RATE_LIMITED', 'The terminal attachment buffer is full.') this.values.push({ value, bytes }); this.bytes += bytes; this.wake?.() } close(error?: unknown, discard = false): void { if (this.closed) return this.closed = true; this.error = error if (discard) { this.values = []; this.bytes = 0 } this.wake?.() } async *[Symbol.asyncIterator](): AsyncGenerator { while (true) { const entry = this.values.shift() if (entry) { this.bytes -= entry.bytes; yield entry.value } else if (this.closed) break else await new Promise(resolve => { this.wake = resolve }) } if (this.error) throw this.error } } interface Attachment { args: z.infer control: AbortController queue: Queue sequence: number writable: boolean pending: Map } /** Existing Remote follow/write/resize calls terminate at the official attach stream. */ export class TerminalCarrierCompat { private readonly attachments = new Map() constructor(private readonly gateway: LocalTypertGateway) {} async open(payload: unknown, signal: AbortSignal): Promise> { signal.throwIfAborted() const args = attachmentArgs.parse(z.object({ args: z.unknown() }).strict().parse(payload).args) const key = `${args.agentId}/${args.id}` this.attachments.get(key)?.control.abort() const control = new AbortController() const queue = new Queue() const entry: Attachment = { args, control, queue, sequence: 0, writable: false, pending: new Map() } const lifetime = AbortSignal.any([signal, control.signal]) const close = () => { queue.close(undefined, true) for (const pending of entry.pending.values()) pending.reject(new RpcError('TRANSPORT_CLOSED', 'The terminal attachment closed. Input will not be replayed.')) entry.pending.clear() if (this.attachments.get(key) === entry) this.attachments.delete(key) } lifetime.addEventListener('abort', close, { once: true }) lifetime.throwIfAborted() this.attachments.set(key, entry) let source: AsyncIterable try { source = await this.gateway.open('terminal/attach', { args: { agentId: args.agentId, id: args.id } }, lifetime, queue) } catch (error) { control.abort(); throw error } return (async function* () { try { for await (const value of source) { if (lifetime.aborted) break if (isRecord(value) && value.type === 'ack') { const pending = entry.pending.get(Number(value.sequence)) if (!pending) throw new RpcError('INVALID_MESSAGE', 'Unexpected terminal input acknowledgement.') entry.pending.delete(Number(value.sequence)) if (value.refusal) pending.reject(new RpcError('PERMISSION_DENIED', 'Terminal input was refused.')) else pending.resolve() } else if (isRecord(value) && (value.type === 'snapshot' || value.type === 'state') && isRecord(value.info)) { entry.writable = value.writable === true yield { ...value, info: { ...value.info, ...(entry.writable ? { controllerId: args.attachmentId } : {}) } } } else yield value } } finally { control.abort(); lifetime.removeEventListener('abort', close) } })() } async call(endpoint: string, payload: unknown, signal: AbortSignal): Promise { const fields = endpoint === 'terminal/write' ? { data: z.string().max(64 * 1024) } : dimensions const args: z.infer & Record = attachmentArgs.extend(fields).parse(z.object({ args: z.unknown() }).strict().parse(payload).args) const entry = this.attachments.get(`${args.agentId}/${args.id}`) if (!entry || entry.args.attachmentId !== args.attachmentId || !entry.writable) throw new RpcError('PERMISSION_DENIED', 'This terminal input attachment is not writable.') if (entry.pending.size >= 32) throw new RpcError('RATE_LIMITED', 'Too many unacknowledged terminal inputs.') signal.throwIfAborted() const sequence = ++entry.sequence const value = input.parse({ type: endpoint === 'terminal/write' ? 'write' : 'resize', sequence, ...('data' in args ? { data: args.data } : { cols: args.cols, rows: args.rows }) }) const abort = () => entry.control.abort() signal.addEventListener('abort', abort, { once: true }) try { await new Promise((resolve, reject) => { entry.pending.set(sequence, { resolve, reject }) try { entry.queue.push(value) } catch (error) { entry.pending.delete(sequence); entry.control.abort(); reject(error) } }) return { ok: true } } finally { signal.removeEventListener('abort', abort) } } } /** Native RC.1 Client attach stream over the existing encrypted terminal subset. */ export async function openRemoteTerminal( target: RemoteTypertGatewayTarget, payload: unknown, signal: AbortSignal, uplink: AsyncIterable, ): Promise> { const args = z.object({ agentId: identity, id: identity }).strict().parse(z.object({ args: z.unknown() }).strict().parse(payload).args) const attachmentId = uuidV7() const control = new AbortController() const lifetime = AbortSignal.any([signal, control.signal]) const output = new Queue(4 * 1024 * 1024, 256) let writable = false const iterator = uplink[Symbol.asyncIterator]() const abort = () => { output.close(); void iterator.return?.().catch(() => undefined) } lifetime.addEventListener('abort', abort, { once: true }) lifetime.throwIfAborted() let source: AsyncIterable try { source = await target.open('terminal/follow', { args: { ...args, attachmentId } }, lifetime) } catch (error) { control.abort(); throw error } let startInput!: () => void const ready = new Promise(resolve => { startInput = resolve }) lifetime.addEventListener('abort', startInput, { once: true }) if (lifetime.aborted) startInput() void (async () => { try { for await (const value of source) { if (lifetime.aborted) break if (isRecord(value) && (value.type === 'snapshot' || value.type === 'state') && isRecord(value.info)) { writable = value.info.controllerId === attachmentId output.push({ ...value, writable }) if (value.type === 'snapshot') startInput() } else output.push(value) } } catch (error) { output.close(error) } finally { control.abort() } })() void (async () => { let sequence = 0 try { await ready while (!lifetime.aborted) { const next = await iterator.next() if (next.done || lifetime.aborted) break const value: Input = input.parse(next.value) if (value.sequence !== ++sequence) throw new RpcError('INVALID_MESSAGE', 'Terminal input sequence is invalid.') if (!writable) { output.push({ type: 'ack', sequence, refusal: 'read-only' }); continue } const result = await target.dispatch(`terminal/${value.type}`, { args: { ...args, attachmentId, ...(value.type === 'write' ? { data: value.data } : { cols: value.cols, rows: value.rows }) } }, lifetime) if (!result.ok) throw Object.assign(new Error(result.error.message), result.error) if (!lifetime.aborted) output.push({ type: 'ack', sequence }) } } catch (error) { output.close(error); control.abort() } })() return (async function* () { try { yield* output } finally { control.abort(); lifetime.removeEventListener('abort', abort); lifetime.removeEventListener('abort', startInput) } })() } function isRecord(value: unknown): value is Record { return typeof value === 'object' && value !== null && !Array.isArray(value) }