diff --git a/packages/client-core/src/harness-questions.ts b/packages/client-core/src/harness-questions.ts new file mode 100644 index 0000000..a481ffa --- /dev/null +++ b/packages/client-core/src/harness-questions.ts @@ -0,0 +1,198 @@ +import type { HarnessClientFrame, HarnessQuestionAnswer } from './harness-alpha-client.js' +import { RemoteGatewayError, type RemoteGatewayStream, type RemoteTypertGateway } from './remote-gateway.js' + +interface Question { + sessionId: string + callId: string + questions: unknown[] + state: 'open' | 'continued' + eventId?: string + controller?: AbortController + stream?: RemoteGatewayStream + timer?: ReturnType + deadline?: number + answering?: boolean + answered?: boolean + projected?: boolean +} + +/** Official timed-question claims and durable projection recovery; no requests are replayed. */ +export class HarnessQuestions { + private readonly questions = new Map() + private closed = false + private readonly projectionSeqs = new Map() + + constructor( + private readonly gateway: RemoteTypertGateway, + private readonly respondEvent: (id: string, outcome: { kind: 'result'; value?: unknown } | { kind: 'rejected'; error: unknown }) => Promise, + private readonly emit: (frame: HarnessClientFrame) => void, + ) {} + + request(sessionId: string, eventId: string, request: Record): boolean { + const wait = record(request.wait) + if (wait?.timed !== true || typeof wait.callId !== 'string') return false + if (this.closed) return true + const id = questionId(sessionId, wait.callId) + const previous = this.questions.get(id) + if (previous !== undefined) this.release(previous) + const question: Question = { + sessionId, + callId: wait.callId, + questions: Array.isArray(request.questions) ? request.questions : [], + state: 'open', + eventId, + ...(previous?.projected ? { projected: true } : {}), + } + this.questions.set(id, question) + void this.claim(id, question).catch(async () => { + if (!this.current(id, question) || question.controller?.signal.aborted) return + // Failed claim: reject the foreground request and let the Host settle its lifetime. + await this.respondEvent(eventId, { kind: 'rejected', error: { name: 'UserQuestionError', code: 'ASK_ABORTED', message: 'The question claim could not be opened.' } }).catch(() => undefined) + this.release(question) + }) + return true + } + + cancel(eventId: string): boolean { + for (const [id, question] of this.questions) { + if (question.eventId !== eventId) continue + this.release(question) + question.eventId = undefined + // The authoritative projection determines whether this is continued or cancelled. + return true + } + return false + } + + projection(sessionId: string, value: unknown, seq?: number): void { + if (this.closed) return + const previous = this.projectionSeqs.get(sessionId) + if (seq !== undefined && previous !== undefined && seq < previous) return + const view = record(value) + if (!Array.isArray(view?.active) || !Array.isArray(view?.settled)) return + if (seq !== undefined) this.projectionSeqs.set(sessionId, seq) + const active = new Set() + for (const row of view.active) { + const item = record(row) + if (typeof item?.callId !== 'string' || !Array.isArray(item.questions) + || (item.state !== 'open' && item.state !== 'continued')) continue + const id = questionId(sessionId, item.callId) + active.add(id) + let question = this.questions.get(id) + if (question === undefined) { + question = { sessionId, callId: item.callId, questions: item.questions, state: item.state } + this.questions.set(id, question) + } + question.projected = true + question.questions = item.questions + question.state = item.state + if (item.state === 'continued') { + this.release(question) + question.eventId = undefined + this.publish(id, question) + } else if (question.controller === undefined || question.deadline !== undefined) { + this.publish(id, question) + } + } + const settled = new Set(view.settled.flatMap(row => { + const item = record(row) + return typeof item?.callId === 'string' ? [questionId(sessionId, item.callId)] : [] + })) + for (const [id, question] of this.questions) { + if (question.sessionId !== sessionId || active.has(id)) continue + // Event and control streams can interleave before the first active projection arrives. + if (!question.projected && question.eventId !== undefined && !settled.has(id)) continue + this.release(question) + this.questions.delete(id) + this.emit({ rpcId: '', payload: { type: 'question/resolved', sessionId, questionRpcId: id, outcome: settled.has(id) ? 'answered' : 'cancelled' } }) + } + } + + async answer(id: string, sessionId: string, answer: HarnessQuestionAnswer): Promise { + const question = this.questions.get(id) + if (question === undefined) return false + if (question.sessionId !== sessionId || question.answering || question.answered) throw new RemoteGatewayError('PERMISSION_NOT_PENDING', 'That question is not available for this reply.') + question.answering = true + try { + if (question.state === 'open') { + if (question.eventId === undefined || question.deadline === undefined || Date.now() >= question.deadline) { + throw new RemoteGatewayError('PERMISSION_NOT_PENDING', 'The foreground question has ended. Wait for the Host question state to refresh.') + } + await this.respondEvent(question.eventId, { kind: 'result', value: answer }) + } else { + const response = await this.gateway.call('userQuestions/answer', { args: { agentId: sessionId, callId: question.callId, answer } }) + const result = record(response) + if (response === false || (result?.ok === true && result.value === false)) throw new RemoteGatewayError('PERMISSION_NOT_PENDING', 'That question was already answered or expired.') + if (result?.ok === false) throw new RemoteGatewayError('QUESTION_REPLY_REJECTED', 'The Host rejected the question reply.') + if (response !== true && !(result?.ok === true && result.value === true)) throw new RemoteGatewayError('INVALID_MESSAGE', 'The Host returned an invalid question reply result.') + } + question.answered = true + this.release(question) + this.emit({ rpcId: '', payload: { type: 'question/resolved', sessionId, questionRpcId: id, outcome: question.state === 'continued' ? 'queued' : 'answered' } }) + return true + } finally { + question.answering = false + } + } + + republish(sessionId: string): void { + if (this.closed) return + for (const [id, question] of this.questions) { + if (question.sessionId !== sessionId || question.answered) continue + if (question.state === 'continued' || question.controller === undefined || question.deadline !== undefined) { + this.publish(id, question) + } + } + } + + close(notifyRemote: boolean): void { + this.closed = true + for (const question of this.questions.values()) this.release(question, notifyRemote) + this.questions.clear() + this.projectionSeqs.clear() + } + + private async claim(id: string, question: Question): Promise { + const controller = new AbortController() + question.controller = controller + const stream = await this.gateway.open('userQuestions/attachWait', { args: { agentId: question.sessionId, callId: question.callId } }, controller.signal) + if (!this.current(id, question) || controller.signal.aborted) { await stream.close(false); return } + question.stream = stream + const iterator = stream[Symbol.asyncIterator]() + const opening = await iterator.next() + const remaining = record(opening.value)?.remainingMs + if (opening.done || typeof remaining !== 'number' || !Number.isFinite(remaining) || remaining < 0 || remaining > 2_147_483_647) { + this.release(question) + return + } + if (!this.current(id, question) || controller.signal.aborted) return + question.deadline = Date.now() + remaining + this.publish(id, question) + const expire = (): void => { + if (!this.current(id, question) || question.eventId === undefined || question.answered) return + // An in-flight reply owns settlement. A failed reply must still release the wait. + if (question.answering) { question.timer = setTimeout(expire, 50); return } + void this.respondEvent(question.eventId, { kind: 'rejected', error: { name: 'UserQuestionError', code: 'ASK_TIMED_OUT', message: 'The question answer window ended.' } }).finally(() => this.release(question)).catch(() => undefined) + } + question.timer = setTimeout(expire, remaining) + await iterator.next() + if (this.current(id, question)) this.release(question) + } + + private current(id: string, question: Question): boolean { return !this.closed && this.questions.get(id) === question } + private publish(id: string, question: Question): void { + this.emit({ rpcId: id, payload: { type: 'question/requested', sessionId: question.sessionId, callId: question.callId, questions: question.questions, questionState: question.state, ...(question.deadline === undefined ? {} : { deadline: question.deadline }) } }) + } + private release(question: Question, notifyRemote = true): void { + clearTimeout(question.timer) + question.timer = undefined + question.deadline = undefined + question.controller?.abort() + question.controller = undefined + void question.stream?.close(notifyRemote).catch(() => undefined) + question.stream = undefined + } +} + +function record(value: unknown): Record | undefined { return typeof value === 'object' && value !== null && !Array.isArray(value) ? value as Record : undefined } +function questionId(sessionId: string, callId: string): string { return `timed-question:${JSON.stringify([sessionId, callId])}` }