Files
deepseek-harness/packages/interaction/user-questions/src/projection.ts
T

338 lines
14 KiB
TypeScript

/** Fold of `ask_user_question` tool events into the answerable question set, and its Session projection. */
import { z } from 'zod'
import { SessionLogOffset, TOOL_OUTCOME_UNKNOWN } from '@deepseek-ai/dsh-session'
import type { SessionEvent, SessionLogOffset as SessionLogOffsetType } from '@deepseek-ai/dsh-session'
import type { ProjectionDefinition } from '@deepseek-ai/dsh-session-projection'
import type {} from '@deepseek-ai/dsh-agent/types'
import type {} from '@deepseek-ai/dsh-tools/types'
import { ToolCallId } from '@deepseek-ai/dsh-llm'
import type { ContentBlock, ToolSchema } from '@deepseek-ai/dsh-llm'
import type { AskUserQuestionAnswerItem, AskUserQuestionItem, AskUserQuestionOption, PendingUserQuestion, SettledUserQuestion, UserQuestionProjectionView } from './types.ts'
/**
* The pure fold state: whether the request header in effect declares the
* timed `ask_user_question` schema, and the question view that schema's
* calls build. Calls made under the blocking legacy schema never enter it.
*/
export interface UserQuestionFold {
readonly timed: boolean
readonly questions: UserQuestionProjectionView
}
/** Host projection state; `questions` is the wire value, reused whenever an event changes nothing. */
export interface UserQuestionProjectionState extends UserQuestionFold {
readonly inheritedEventCount: SessionLogOffsetType
}
/** Tool whose calls this projection tracks. */
export const ASK_USER_QUESTION_TOOL = 'ask_user_question'
/**
* Model-facing parameter only the timed `ask_user_question` schema declares.
* Its presence in the logged request header is what tells the fold that the
* `ask_user_question` calls that follow can be continued past a timeout; the
* blocking legacy schema never declares it.
*/
export const TIMED_WAIT_PARAMETER = 'timeout'
const toolOptionSchema = z.object({
label: z.string(),
description: z.string().optional(),
}).loose()
const toolQuestionSchema = z.object({
id: z.string(),
question: z.string(),
header: z.string().optional(),
options: z.array(toolOptionSchema).optional(),
multi_select: z.boolean().optional(),
}).loose()
const toolArgumentsSchema = z.object({
questions: z.array(toolQuestionSchema).min(1),
}).loose()
const optionSchema = z.object({
label: z.string(),
description: z.string().optional(),
}).strict().transform((option): AskUserQuestionOption => ({
label: option.label,
...(option.description === undefined ? {} : { description: option.description }),
}))
const questionSchema = z.object({
id: z.string(),
question: z.string(),
detail: z.string().optional(),
header: z.string().optional(),
options: z.array(optionSchema).optional(),
multiSelect: z.boolean().optional(),
}).strict().transform((question): AskUserQuestionItem => ({
id: question.id,
question: question.question,
...(question.detail === undefined ? {} : { detail: question.detail }),
...(question.header === undefined ? {} : { header: question.header }),
...(question.options === undefined ? {} : { options: question.options }),
...(question.multiSelect === undefined ? {} : { multiSelect: question.multiSelect }),
}))
const pendingQuestionsSchema: z.ZodType<readonly PendingUserQuestion[]> = z.array(z.object({
callId: z.string().min(1).transform(ToolCallId),
questions: z.array(questionSchema).min(1),
state: z.enum(['open', 'continued']),
}).strict()).superRefine((active, context) => {
if (new Set(active.map(question => question.callId)).size !== active.length) {
context.addIssue({ code: 'custom', message: 'callIds must be unique' })
}
})
const answerSchema = z.object({
id: z.string(),
selected: z.array(z.string()),
custom: z.string().optional(),
}).strict().transform((answer): AskUserQuestionAnswerItem => ({
id: answer.id,
selected: answer.selected,
...(answer.custom === undefined ? {} : { custom: answer.custom }),
}))
const settledQuestionsSchema: z.ZodType<readonly SettledUserQuestion[]> = z.array(z.object({
callId: z.string().min(1).transform(ToolCallId),
answers: z.array(answerSchema),
}).strict())
const projectionViewSchema: z.ZodType<UserQuestionProjectionView> = z.object({
active: pendingQuestionsSchema,
settled: settledQuestionsSchema,
}).strict()
/** The `answers` batch as both the in-time tool result and the steered late reply spell it. */
const answerBatchSchema = z.object({ answers: z.array(answerSchema) }).loose()
/** A Session with no timed `ask_user_question` call yet, shared so the wire value stays referentially stable. */
const emptyView: UserQuestionProjectionView = { active: [], settled: [] }
const initialFold: UserQuestionFold = { timed: false, questions: emptyView }
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === 'object' && value !== null && !Array.isArray(value)
}
/**
* Whether one logged tool schema is the timed `ask_user_question` tool's.
* @param tool - One entry of a request header's assembled tool schemas.
* @returns True only for an `ask_user_question` schema whose parameters declare {@link TIMED_WAIT_PARAMETER}.
*/
export function isTimedAskUserQuestionSchema(tool: Pick<ToolSchema, 'name' | 'parameters'>): boolean {
if (tool.name !== ASK_USER_QUESTION_TOOL) return false
const properties: unknown = tool.parameters['properties']
return isRecord(properties) && TIMED_WAIT_PARAMETER in properties
}
/**
* Read the question batch out of logged `ask_user_question` arguments.
* @param argumentsText - Raw JSON arguments recorded on the `tool/call` event.
* @returns The questions in service vocabulary, or null when the arguments are unreadable.
*/
export function questionsOf(argumentsText: string): readonly AskUserQuestionItem[] | null {
let parsed: unknown
try {
parsed = JSON.parse(argumentsText)
} catch (error) {
// Malformed model arguments never reached the tool; there is no card to show.
void error
return null
}
const result = toolArgumentsSchema.safeParse(parsed)
if (!result.success) return null
return result.data.questions.map(question => ({
id: question.id,
question: question.question,
...(question.header === undefined ? {} : { header: question.header }),
...(question.options === undefined
? {}
: {
options: question.options.map(option => ({
label: option.label,
...(option.description === undefined ? {} : { description: option.description }),
})),
}),
...(question.multi_select === undefined ? {} : { multiSelect: question.multi_select }),
}))
}
function isPendingResult(content: readonly ContentBlock[]): boolean {
const text = content.find(block => block.type === 'text')
if (text === undefined) return false
try {
const parsed: unknown = JSON.parse(text.text)
return typeof parsed === 'object' && parsed !== null && (parsed as { pending?: unknown }).pending === true
} catch (error) {
// A non-JSON result text is a failure message, never the pending payload.
void error
return false
}
}
/**
* Read the answer batch out of one recorded text: a tool result or a late reply.
* @param content - Content blocks of the recorded message.
* @returns The batch, or null when the text carries none this reader can use.
*/
function answerBatchOf(content: readonly ContentBlock[]): readonly AskUserQuestionAnswerItem[] | null {
const text = content.find(block => block.type === 'text')
if (text === undefined) return null
let parsed: unknown
try {
parsed = JSON.parse(text.text)
} catch (error) {
// A failure result, a dismissal, and any other text that is not an answer JSON carries no batch.
void error
return null
}
const result = answerBatchSchema.safeParse(parsed)
return result.success ? result.data.answers : null
}
/**
* Close one answerable question and keep the answers it settled with.
* A reply whose call is no longer answerable changes nothing.
* @param view - Current question state.
* @param callId - Call the result or reply named.
* @param answers - The batch it carried; empty when a late reply carried none.
* @returns The same view when that call was not answerable, otherwise the updated one.
*/
function settleQuestion(
view: UserQuestionProjectionView,
callId: string,
answers: readonly AskUserQuestionAnswerItem[],
): UserQuestionProjectionView {
const question = view.active.find(item => item.callId === callId)
if (question === undefined) return view
return {
active: view.active.filter(item => item.callId !== callId),
settled: [...view.settled, { callId: question.callId, answers }],
}
}
/**
* Apply one Session event to this Session's question fold.
* A `request/header` decides, from the assembled tool schemas it records,
* whether the `ask_user_question` calls that follow are timed; a call made
* under the blocking legacy schema is never tracked, so a Session that only
* ever used that tool folds to the empty view. A tracked question stays
* answerable as `continued` in exactly two cases: the tool returned the
* pending payload, or Session resume repair appended the synthetic
* `TOOL_OUTCOME_UNKNOWN` result for a call the process never finished. An
* answer batch settles it with that batch; any failure drops it. A PTC
* sub-call enters the fold when its recorded result is pending. A late reply
* settles only when the agent admits its user message; queued inbox messages
* can still be discarded before that point.
* @param fold - Current fold state.
* @param event - Next Session event in append order.
* @returns The same fold when the event is unrelated, otherwise the updated one.
*/
export function applyUserQuestionEvent(fold: UserQuestionFold, event: SessionEvent): UserQuestionFold {
const view = fold.questions
switch (event.type) {
case 'request/header': {
// The log records the exact schema list the model saw; a seeded or
// tool-less header carries none, which reads as the legacy tool.
const tools: unknown = event.data.header.tools
const timed = Array.isArray(tools) && tools.some((tool: unknown) =>
isRecord(tool) && typeof tool.name === 'string' && isRecord(tool.parameters)
&& isTimedAskUserQuestionSchema({ name: tool.name, parameters: tool.parameters }))
return timed === fold.timed ? fold : { ...fold, timed }
}
case 'tool/call': {
if (!fold.timed || event.data.name !== ASK_USER_QUESTION_TOOL) return fold
const questions = questionsOf(event.data.arguments)
if (questions === null) return fold
const callId = event.data.callId
return {
...fold,
questions: {
...view,
active: [...view.active.filter(question => question.callId !== callId), { callId, questions, state: 'open' }],
},
}
}
case 'tool/result': {
const callId = event.data.message.toolCallId
if (!view.active.some(question => question.callId === callId)) return fold
if (isPendingResult(event.data.message.content) || event.data.error?.code === TOOL_OUTCOME_UNKNOWN) {
return {
...fold,
questions: {
...view,
active: view.active.map(question => question.callId === callId ? { ...question, state: 'continued' } : question),
},
}
}
const answers = event.data.error === undefined && event.data.message.isError !== true
? answerBatchOf(event.data.message.content)
: null
return {
...fold,
questions: answers === null
? { ...view, active: view.active.filter(question => question.callId !== callId) }
: settleQuestion(view, callId, answers),
}
}
case 'tool/ptc-dispatch': {
if (event.data.name !== ASK_USER_QUESTION_TOOL || event.data.isError || !isPendingResult(event.data.content)) return fold
const questions = questionsOf(JSON.stringify(event.data.arguments))
if (questions === null) return fold
const callId = event.data.subCallId
return {
...fold,
questions: {
...view,
active: [...view.active.filter(question => question.callId !== callId), { callId, questions, state: 'continued' }],
},
}
}
case 'user/message': {
const source = event.data.source
if (source.kind !== 'user-question-reply') return fold
const questions = settleQuestion(view, source.callId, answerBatchOf(event.data.content) ?? [])
return questions === view ? fold : { ...fold, questions }
}
default:
return fold
}
}
/**
* Fold a whole Session log into its question state.
* @param events - Session events in append order.
* @returns Open and continued timed calls in ask order, and settled ones in settlement order.
*/
export function foldUserQuestions(events: readonly SessionEvent[]): UserQuestionProjectionView {
return events.reduce(applyUserQuestionEvent, initialFold).questions
}
/** Session projection exposing open, continued, and settled timed questions to every Client. */
export const userQuestionProjectionDefinition = {
key: 'userQuestions',
stateSchema: z.object({
inheritedEventCount: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER).transform(SessionLogOffset),
timed: z.boolean(),
questions: projectionViewSchema,
}).strict(),
init: (_header, inheritedEventCount) => ({ inheritedEventCount, ...initialFold }),
apply: (state, event) => {
if (event.seq < state.inheritedEventCount) return state
const fold = applyUserQuestionEvent(state, event)
return fold === state ? state : { ...state, ...fold }
},
wire: { viewSchema: projectionViewSchema, view: state => state.questions },
stateVersion: 2,
} satisfies ProjectionDefinition<'userQuestions', UserQuestionProjectionState>
declare module '@deepseek-ai/dsh-session-projection/types' {
interface SessionProjectionStateMap {
userQuestions: UserQuestionProjectionState
}
}