diff --git a/src/components/organisms/Studio/Studio.tsx b/src/components/organisms/Studio/Studio.tsx index b0173265..b8abae6a 100644 --- a/src/components/organisms/Studio/Studio.tsx +++ b/src/components/organisms/Studio/Studio.tsx @@ -39,7 +39,7 @@ import type { ShareKind } from '@/lib/chat/shareStore'; import { track } from '@/lib/events/client'; import { stashGuestSession, takeGuestSession } from '@/lib/studio/guestStash'; import { logRefusedDescriptions } from '@/lib/studio/infoPanel'; -import { GUEST_PROMPTS } from '@/lib/studio/promptAllowance'; +import { GUEST_PROMPTS, promptEvent, type PromptIntent } from '@/lib/studio/promptAllowance'; import { takeSeeds } from '@/lib/studio/seedStore'; import { deriveTheme, themeVars } from '@/lib/studio/theme'; import { isPrompt } from '@/lib/studio/transcript'; @@ -182,25 +182,39 @@ const Studio = ({ // Queued prompts hold their place in the limit until sent or removed. const walled = guest && guestUsed + conversation.queued.length >= GUEST_PROMPTS; - // Every prompt (landing, follow-up, card menu) goes through here: past - // the limit a guest's is dropped, the rest are counted as usage (turn, - // intent and length — never the text). - const send: typeof conversation.send = (text, options, seeds) => { + // Every prompt (landing, follow-up, card menu, a clicked chip) goes + // through here: past the limit a guest's is dropped, the rest are counted + // as usage (turn, intent and a typed prompt's length, never the text). A + // prompt the chat queues is counted here once; the queue's drain sends it + // inside the chat, past this gate. + const prompt = ( + intent: PromptIntent | undefined, + length: number | undefined, + run: () => void, + ) => { // Read the count afresh: the `?q=` handover fires from the first // render's closure, before the stored count has synced in. - if (guest && readGuestUsed() + conversation.queued.length >= GUEST_PROMPTS) { + const event = promptEvent({ + guest, + used: readGuestUsed(), + queued: conversation.queued.length, + sent: sentCount, + intent, + length, + }); + + if (!event) { return; } - track('studio.prompt', { - turn: sentCount + conversation.queued.length + 1, - intent: options?.intent ?? (sentCount === 0 ? 'new' : 'follow_up'), - length: text.trim().length, - guest, - }); - conversation.send(text, options, seeds); + track('studio.prompt', event); + run(); }; - const chat = { ...conversation, send }; + const send: typeof conversation.send = (text, options, seeds) => + prompt(options?.intent, text.trim().length, () => conversation.send(text, options, seeds)); + const applyChoice: typeof conversation.applyChoice = (chip) => + prompt('apply_choice', undefined, () => conversation.applyChoice(chip)); + const chat = { ...conversation, send, applyChoice }; // Usage: each card the harness puts on the canvas, once (a reopened or // shared conversation's cards were counted when they were made). diff --git a/src/components/organisms/Studio/hooks/useChat.ts b/src/components/organisms/Studio/hooks/useChat.ts index 0b147cb8..c800b6f0 100644 --- a/src/components/organisms/Studio/hooks/useChat.ts +++ b/src/components/organisms/Studio/hooks/useChat.ts @@ -19,6 +19,12 @@ import { WORKING, } from '@/lib/studio/chatLine'; import { createCanvasEdits } from '@/lib/studio/canvasEdits'; +import { + chipRefusalDetail, + splitSuggestions, + withoutChips, + withRefusedChip, +} from '@/lib/studio/chips'; import { clarifyAnswer, clarifyFromFrame, @@ -30,22 +36,34 @@ import { } from '@/lib/studio/clarify'; import { restoreCanvas, takeManifest, type CanvasBaseline } from '@/lib/studio/composition'; import { plainTextFromNote } from '@/lib/studio/note'; +import { + approveReply, + planFromFrame, + refusedSwitch, + stalePlan, + settledPlan, + startSwitch, + switchReply, + type PlanState, +} from '@/lib/studio/plan'; import { withAnswer } from '@/lib/studio/transcript'; import { cancelTurn, fetchComponentRevision, mutateComposition, + runApplyChoice, runInterrupt, runTurn, STOP_GRACE_MS, type StreamHandlers, + type StreamRefusal, } from '@/lib/studio/studioClient'; import { reviseWidget, widgetFromComponent } from '@/lib/studio/widgets'; import type { + ApplyChoiceSuggestion, CompositionManifest, + InterruptResponse, MutationOperation, - PlanDecision, - PlanStep, Seed, StudioFrame, } from '@/lib/studio/wire'; @@ -56,24 +74,17 @@ import type { CardRef, Widget } from '@/lib/chat/widgets'; // so the transcript shows what the question was about. `answer` marks the // user's answer to a paused turn (a clarify choice or text, a plan // amendment): shown like any user message, but part of the turn it answers. +// A bot turn's `followups` are prompts a click sends as the next message, +// and its `chips` switch a scope choice of the answer's readings. export type ChatMessage = | { role: 'user'; text: string; card?: { title: string }; answer?: true } - | { role: 'bot'; text: string; followups?: string[] }; + | { role: 'bot'; text: string; followups?: string[]; chips?: ApplyChoiceSuggestion[] }; // A widget stamped with the send() turn it arrived in — the canvas keeps // only the latest turn's widgets plus whatever the user pinned. export type TurnWidget = Widget & { turn: number }; -// A plan awaiting the user's approve/amend/reject (the harness's -// `plan.proposed` pause). -export type PlanState = { - title: string; - steps: PlanStep[]; - decisions: PlanDecision[]; - version: number; - actions: ('approve' | 'amend' | 'reject')[]; - interruptId: string; -}; +export type { PlanState }; /** * A card-scoped turn's target: which card the question is about, and whether @@ -87,12 +98,14 @@ export type CardTarget = { }; // A message sent while a request was in flight: it waits for the -// conversation to be free and enters the transcript when it is sent. +// conversation to be free and enters the transcript when it is sent. A +// clicked `apply_choice` chip waits the same way, under its label. export type QueuedMessage = { id: string; text: string; card?: CardTarget; seeds?: Seed[]; + chip?: ApplyChoiceSuggestion; }; export type ChatState = { @@ -148,6 +161,16 @@ const withLine = (prev: ChatState, status: string, statusDetail: string | null = statusSince: status === prev.status ? prev.statusSince : Date.now(), }); +// A turn's end on screen, however it ended: its Activity entry closes, the +// chat line clears, and a plan card whose switch got no fresh plan leaves. +const endTurn = (prev: ChatState, turn: number, open?: 'skipped' | 'failed'): ChatState => ({ + ...prev, + activity: endTurnActivity(prev.activity, turn, open), + ...NO_LINE, + thinking: false, + plan: settledPlan(prev.plan), +}); + // A conversation restored WITHOUT its server-side session (a fork of a // share, or a save whose session is gone) primes the next turn with a compact // recap of the transcript, so the agent picks up the thread instead of @@ -176,6 +199,12 @@ const buildRecap = (messages: ChatMessage[]): string | null => { )}\n\nNew message:\n`; }; +// A saved transcript as the chat shows it. Without its harness session the +// conversation starts afresh on the harness, which holds none of the answers +// that offered its chips, so they go. +const restoredMessages = (saved: ChatSnapshot): ChatMessage[] => + saved.sessionId ? saved.messages : withoutChips(saved.messages); + /** * Drives one Studio conversation against the harness's `/api/studio/*` * frames. Pauses (`plan.proposed`, `elicitation.request`) END the stream and @@ -188,7 +217,7 @@ const buildRecap = (messages: ChatMessage[]): string | null => { */ export const useChat = (initial?: ChatSnapshot) => { const [state, setState] = useState(() => ({ - messages: initial?.messages ?? [], + messages: initial ? restoredMessages(initial) : [], widgets: initial?.widgets ?? [], queued: [], activity: restoreActivity(initial?.activity), @@ -222,9 +251,11 @@ export const useChat = (initial?: ChatSnapshot) => { // The pending pause's addressing (interrupt_id) with, for elicitations, // the normalized clarify that answerClarify() builds its reply and // status note from, and that skipClarify() reads `skippable` from. + // For plans, the plan that switchChoice() checks a pick against. const pendingInterruptRef = useRef<{ interruptId: string; clarify?: Clarify; + plan?: PlanState; } | null>(null); // The card an in-flight `edit` turn is changing. The harness answers an // edit with a REPLACEMENT component under a new id (and drops the old one @@ -323,6 +354,12 @@ export const useChat = (initial?: ChatSnapshot) => { }, [syncCanvas], ); + // Put a plan card up as the pending pause, whether from the stream or + // from a refusal that answered a stale card with the current one. + const offerPlan = useCallback((plan: PlanState) => { + pendingInterruptRef.current = { interruptId: plan.interruptId, plan }; + setState((prev) => ({ ...prev, ...NO_LINE, thinking: false, plan })); + }, []); // Swap one widget in place, wherever it sits in the list. const patchWidget = useCallback((id: string, fn: (widget: TurnWidget) => TurnWidget) => { setState((prev) => ({ @@ -331,8 +368,15 @@ export const useChat = (initial?: ChatSnapshot) => { })); }, []); + // `onRefusal` answers an HTTP refusal of the request (see StreamHandlers) + // and returns true when it has dealt with it; any other refusal ends the + // turn as an error. const stream = useCallback( - (turn: number, start: (handlers: StreamHandlers, signal: AbortSignal) => Promise) => { + ( + turn: number, + start: (handlers: StreamHandlers, signal: AbortSignal) => Promise, + onRefusal?: (refusal: StreamRefusal) => boolean, + ) => { const controller = new AbortController(); const generation = generationRef.current; // Set by Stop. The stream is read to its end and its frames are @@ -553,22 +597,11 @@ export const useChat = (initial?: ChatSnapshot) => { break; } case 'plan.proposed': + // Also the answer to a switch, whose fresh plan, with + // what moved, replaces the card it kept. stall.stop(); grace.cancel(); - pendingInterruptRef.current = { interruptId: frame.interrupt_id }; - setState((prev) => ({ - ...prev, - ...NO_LINE, - thinking: false, - plan: { - title: frame.title, - steps: frame.steps, - decisions: frame.decisions ?? [], - version: frame.version, - actions: frame.actions, - interruptId: frame.interrupt_id, - }, - })); + offerPlan(planFromFrame(frame)); break; case 'plan.versioned': // Transient bookkeeping — the fresh plan.proposed that @@ -591,15 +624,19 @@ export const useChat = (initial?: ChatSnapshot) => { })); break; } - case 'suggestions': - if (frame.items.length > 0) { + case 'suggestions': { + const { followups, chips } = splitSuggestions(frame.items); + + if (followups.length > 0 || chips.length > 0) { patchBot((last) => ({ ...last, - followups: frame.items.map((item) => item.prompt), + ...(followups.length > 0 && { followups }), + ...(chips.length > 0 && { chips }), })); } break; + } case 'composition.updated': // The whiteboard keeps its own layout; a manifest only // says which cards the harness took off the canvas. @@ -619,13 +656,7 @@ export const useChat = (initial?: ChatSnapshot) => { }; } - return { - ...prev, - messages, - activity: endTurnActivity(prev.activity, turn, 'failed'), - ...NO_LINE, - thinking: false, - }; + return endTurn({ ...prev, messages }, turn, 'failed'); }); break; case 'done': @@ -636,12 +667,7 @@ export const useChat = (initial?: ChatSnapshot) => { applyManifest(frame.composition); } - setState((prev) => ({ - ...prev, - activity: endTurnActivity(prev.activity, turn), - ...NO_LINE, - thinking: false, - })); + setState((prev) => endTurn(prev, turn)); break; } }; @@ -667,16 +693,15 @@ export const useChat = (initial?: ChatSnapshot) => { messages[messages.length - 1] = { ...last, text: stoppedReply(preamble) }; } - return { - ...prev, - messages, - activity: endTurnActivity(prev.activity, turn, 'skipped'), - ...NO_LINE, - thinking: false, - }; + return endTurn({ ...prev, messages }, turn, 'skipped'); }); }; + // A refusal of a stream that reset/hydrate walked away from, or + // that the user stopped, is dropped, as handle() drops frames. + const refuse = (refusal: StreamRefusal): boolean => + generationRef.current !== generation || stopped || (onRefusal?.(refusal) ?? false); + // Queue behind whatever is in flight. The controller is published // when the request actually starts, so reset aborts the fetch // that is running, not one still waiting here. @@ -694,19 +719,14 @@ export const useChat = (initial?: ChatSnapshot) => { stall.beat(); return start( - { onFrame: handle, onKeepAlive: stall.beat }, + { onFrame: handle, onKeepAlive: stall.beat, onRefusal: refuse }, controller.signal, ).catch((error: Error) => { if (error.name !== 'AbortError' && generationRef.current === generation) { failed = true; if (!stopped) { - setState((prev) => ({ - ...prev, - activity: endTurnActivity(prev.activity, turn, 'failed'), - ...NO_LINE, - thinking: false, - })); + setState((prev) => endTurn(prev, turn, 'failed')); } } }); @@ -737,61 +757,69 @@ export const useChat = (initial?: ChatSnapshot) => { } }); }, - [applyManifest, patchWidget], + [applyManifest, offerPlan, patchWidget], ); - const send = useCallback( - (message: string, card?: CardTarget, seeds?: Seed[]) => { - const text = message.trim(); + // While a request is in flight a new turn waits its turn; the settle + // handler sends it (then the next) once the conversation is free. During + // a pause it also waits behind turns already held, so it cannot overtake + // them. Returns whether the turn was held. + const holdTurn = useCallback((item: Omit): boolean => { + if ( + inFlightRef.current === 0 && + (queueRef.current.length === 0 || pendingInterruptRef.current === null) + ) { + return false; + } - if (!text) { - return; - } + const queued: QueuedMessage = { id: uuid(), ...item }; - // While a request is in flight the message waits its turn; the - // settle handler sends it (then the next) once the conversation - // is free. During a pause it also waits behind messages already - // held, so it cannot overtake them. - if ( - inFlightRef.current > 0 || - (queueRef.current.length > 0 && pendingInterruptRef.current !== null) - ) { - const item: QueuedMessage = { id: uuid(), text, card, seeds }; + queueRef.current.push(queued); + setState((prev) => ({ ...prev, queued: [...prev.queued, queued] })); - queueRef.current.push(item); - setState((prev) => ({ ...prev, queued: [...prev.queued, item] })); + return true; + }, []); - return; - } + // Open a turn on screen: the user's message and an empty reply join the + // transcript, the turn gets its Activity entry, and the chat line shows + // `line`. A new turn on a paused conversation abandons the pause (the + // contract's rule), so any plan or clarify card goes with it. + const startTurn = useCallback((user: ChatMessage & { role: 'user' }, line: string) => { + const conversation = sessionRef.current ?? uuid(); - if (!sessionRef.current) { - sessionRef.current = uuid(); - } + sessionRef.current = conversation; + turnCount.current += 1; + const turn = turnCount.current; - turnCount.current += 1; - const turn = turnCount.current; + pendingInterruptRef.current = null; + editingRef.current = null; + setState((prev) => ({ + ...withLine(prev, line), + messages: [...prev.messages, user, { role: 'bot', text: '' }], + activity: [ + ...prev.activity, + { turn, prompt: user.text, startedAt: Date.now(), tools: [] }, + ], + thinking: true, + clarify: null, + plan: null, + })); - // A new turn on a paused conversation abandons the pause (the - // contract's rule) — drop any pending plan/clarify card with it. - pendingInterruptRef.current = null; + return { turn, conversation }; + }, []); - setState((prev) => ({ - ...withLine(prev, 'Resolving the question'), - messages: [ - ...prev.messages, - { role: 'user', text, ...(card?.title && { card: { title: card.title } }) }, - { role: 'bot', text: '' }, - ], - activity: [ - ...prev.activity, - { turn, prompt: text, startedAt: Date.now(), tools: [] }, - ], - thinking: true, - clarify: null, - plan: null, - })); + const send = useCallback( + (message: string, card?: CardTarget, seeds?: Seed[]) => { + const text = message.trim(); - const conversation = sessionRef.current; + if (!text || holdTurn({ text, card, seeds })) { + return; + } + + const { turn, conversation } = startTurn( + { role: 'user', text, ...(card?.title && { card: { title: card.title } }) }, + 'Resolving the question', + ); const recap = recapRef.current; recapRef.current = null; @@ -822,31 +850,9 @@ export const useChat = (initial?: ChatSnapshot) => { }), ); }, - [stream], + [holdTurn, startTurn, stream], ); - // The queue head goes next, unless a pause (plan or clarify) is waiting - // on the user: a new turn would abandon it, so the answer goes first. - useEffect(() => { - drainRef.current = () => { - if (inFlightRef.current > 0 || pendingInterruptRef.current) { - return; - } - - const next = queueRef.current.shift(); - - if (!next) { - return; - } - - setState((prev) => ({ - ...prev, - queued: prev.queued.filter((item) => item.id !== next.id), - })); - send(next.text, next.card, next.seeds); - }; - }, [send]); - const unqueue = useCallback((id: string) => { queueRef.current = queueRef.current.filter((item) => item.id !== id); setState((prev) => ({ ...prev, queued: prev.queued.filter((item) => item.id !== id) })); @@ -855,8 +861,14 @@ export const useChat = (initial?: ChatSnapshot) => { // Continue a paused turn on /interrupt — shared by clarify answers, the // skip button and the plan actions. `answer` is what the user chose or // wrote, which enters the transcript. + // A stale plan answer (an approve sent from an out-of-date card) is + // refused with the current card, which replaces it to be answered again. const resume = useCallback( - (reply: ClarifyReply, note: string | null, answer?: string) => { + ( + reply: ClarifyReply | Pick, + note: string | null, + answer?: string, + ) => { const conversation = sessionRef.current; const pending = pendingInterruptRef.current; @@ -877,11 +889,22 @@ export const useChat = (initial?: ChatSnapshot) => { return; } - stream(turnCount.current, (handlers, signal) => - runInterrupt(conversation, pending.interruptId, reply, handlers, signal), + stream( + turnCount.current, + (handlers, signal) => + runInterrupt(conversation, pending.interruptId, reply, handlers, signal), + (refusal) => { + const current = stalePlan(refusal); + + if (current) { + offerPlan(current); + } + + return current !== null; + }, ); }, - [stream], + [offerPlan, stream], ); // Answer every question of the pending clarify at once, keyed by @@ -933,7 +956,9 @@ export const useChat = (initial?: ChatSnapshot) => { : `_Change requested: ${payload ?? ''}_`; resume( - { decision, ...(decision === 'amend' ? { payload } : {}) }, + decision === 'approve' + ? approveReply(pendingInterruptRef.current?.plan) + : { decision, ...(decision === 'amend' ? { payload } : {}) }, note, decision === 'amend' ? payload : undefined, ); @@ -941,6 +966,120 @@ export const useChat = (initial?: ChatSnapshot) => { [resume], ); + // A scope decision's option, picked on the plan card. The card stays, + // its controls waiting, until the harness re-offers the plan with what + // moved. A refused switch keeps the pause and the card says why. A + // stale one (the plan moved on elsewhere) is answered with the current + // card. Any other refusal fails the turn, and the card leaves with the + // pause it answered. + const switchChoice = useCallback( + (choiceId: string, optionId: string) => { + const conversation = sessionRef.current; + const pending = pendingInterruptRef.current; + const plan = pending?.plan; + const reply = plan ? switchReply(plan, choiceId, optionId) : null; + + if (!conversation || !pending || !plan || !reply) { + return; + } + + const label = plan.decisions + .find((decision) => decision.choice_id === choiceId) + ?.options?.find((option) => option.option_id === optionId)?.label; + + pendingInterruptRef.current = null; + setState((prev) => ({ + ...withLine(prev, label ? `Switching to ${label}` : 'Switching'), + thinking: true, + plan: prev.plan && startSwitch(prev.plan, { choiceId, optionId }), + })); + + stream( + turnCount.current, + (handlers, signal) => + runInterrupt(conversation, pending.interruptId, reply, handlers, signal), + (refusal) => { + const refused = refusedSwitch(plan, refusal); + + if (refused) { + offerPlan(refused); + } + + return refused !== null; + }, + ); + }, + [offerPlan, stream], + ); + + // A clicked `apply_choice` chip runs a turn with the chip's choice and no + // message, which the transcript shows as the chip's label. A click while + // a request is in flight waits in the queue, as a typed message does. A + // chip the harness refuses (the answer moved on, or Search cannot serve + // the option) leaves the reply saying why, with the answer's other chips. + const applyChoice = useCallback( + (chip: ApplyChoiceSuggestion) => { + if (holdTurn({ text: chip.label, chip })) { + return; + } + + const { turn, conversation } = startTurn( + { role: 'user', text: chip.label }, + `Switching to ${chip.label}`, + ); + + stream( + turn, + (handlers, signal) => runApplyChoice(conversation, chip, handlers, signal), + (refusal) => { + const detail = chipRefusalDetail(refusal); + + if (detail === null) { + return false; + } + + setState((prev) => + endTurn( + { ...prev, messages: withRefusedChip(prev.messages, chip, detail) }, + turn, + 'failed', + ), + ); + + return true; + }, + ); + }, + [holdTurn, startTurn, stream], + ); + + // The queue head goes next, unless a pause (plan or clarify) is waiting + // on the user: a new turn would abandon it, so the answer goes first. + useEffect(() => { + drainRef.current = () => { + if (inFlightRef.current > 0 || pendingInterruptRef.current) { + return; + } + + const next = queueRef.current.shift(); + + if (!next) { + return; + } + + setState((prev) => ({ + ...prev, + queued: prev.queued.filter((item) => item.id !== next.id), + })); + + if (next.chip) { + applyChoice(next.chip); + } else { + send(next.text, next.card, next.seeds); + } + }; + }, [applyChoice, send]); + // The Stop control: ask the harness to cancel and end the running turn // (see `halt` in stream()). Requests queued behind it also wait for the // cancel request to answer. @@ -1014,7 +1153,7 @@ export const useChat = (initial?: ChatSnapshot) => { recapRef.current = saved.sessionId ? null : buildRecap(saved.messages); turnCount.current = saved.turnCount; setState({ - messages: saved.messages, + messages: restoredMessages(saved), widgets: saved.widgets, queued: [], activity: restoreActivity(saved.activity), @@ -1050,6 +1189,8 @@ export const useChat = (initial?: ChatSnapshot) => { answerClarify, skipClarify, respondPlan, + switchChoice, + applyChoice, stop, reset, hydrate, diff --git a/src/components/organisms/Studio/workspace/ChatMessage.tsx b/src/components/organisms/Studio/workspace/ChatMessage.tsx index c7b4f31d..761a1879 100644 --- a/src/components/organisms/Studio/workspace/ChatMessage.tsx +++ b/src/components/organisms/Studio/workspace/ChatMessage.tsx @@ -1,5 +1,6 @@ 'use client'; +import classNames from 'classnames'; import ReactMarkdown from 'react-markdown'; import remarkGfm from 'remark-gfm'; @@ -8,6 +9,8 @@ import MessageFeedback from './MessageFeedback'; import WidgetChips from './WidgetChips'; import type { ChatMessage as ChatMessageData, TurnWidget } from '../hooks/useChat'; import type { CardView } from '../canvas/layout'; +import { chipKey } from '@/lib/studio/chips'; +import type { ApplyChoiceSuggestion } from '@/lib/studio/wire'; type ChatMessageProps = { message: ChatMessageData; @@ -24,6 +27,7 @@ type ChatMessageProps = { onAdd: (id: string) => void; onRemove: (id: string) => void; onFollowup: (text: string) => void; + onApplyChoice: (chip: ApplyChoiceSuggestion) => void; // A shared (read-only) transcript: chips without actions, no follow-ups. readOnly: boolean; }; @@ -31,7 +35,7 @@ type ChatMessageProps = { /** * One transcript entry: a user bubble, or a bot turn — markdown, the cards * it put on the whiteboard as chips, and (on the latest turn) the suggested - * follow-ups. + * follow-ups and the chips that switch a scope choice of the answer. */ const ChatMessage = ({ message, @@ -45,6 +49,7 @@ const ChatMessage = ({ onAdd, onRemove, onFollowup, + onApplyChoice, readOnly, }: ChatMessageProps) => { if (message.role === 'user') { @@ -61,7 +66,10 @@ const ChatMessage = ({ // An empty bot turn shows nothing. The live line renders below the // transcript, and a turn that ended on a clarify leaves an empty bot // message behind. - if (!message.text && (!message.followups || !message.followups.length)) { + const followups = message.followups ?? []; + const chips = message.chips ?? []; + + if (!message.text && followups.length === 0 && chips.length === 0) { return null; } @@ -89,9 +97,9 @@ const ChatMessage = ({ /> {/* Follow-ups belong to the CURRENT turn only — once a newer turn exists they're stale, so drop them. */} - {isLast && !readOnly && message.followups && message.followups.length > 0 && ( + {isLast && !readOnly && (followups.length > 0 || chips.length > 0) && (
- {message.followups.map((followup) => ( + {followups.map((followup) => ( + ))}
)} diff --git a/src/components/organisms/Studio/workspace/ChatPanel.module.scss b/src/components/organisms/Studio/workspace/ChatPanel.module.scss index 701db02b..1e3c2645 100644 --- a/src/components/organisms/Studio/workspace/ChatPanel.module.scss +++ b/src/components/organisms/Studio/workspace/ChatPanel.module.scss @@ -247,6 +247,12 @@ } } +// A chip that switches the answer's reading is the follow-up chip, dashed, so +// it reads as a change to this answer. +.choiceChip { + border-style: dashed; +} + // Clarify picker: a card that stands in for the input while the agent waits // on a choice. rem(10) padding all round, options as bordered rows. .picker { diff --git a/src/components/organisms/Studio/workspace/ChatPanel.tsx b/src/components/organisms/Studio/workspace/ChatPanel.tsx index 4642b75b..e90bffa9 100644 --- a/src/components/organisms/Studio/workspace/ChatPanel.tsx +++ b/src/components/organisms/Studio/workspace/ChatPanel.tsx @@ -87,7 +87,8 @@ const ChatPanel = ({ }, [chat.messages, chat.queued, chat.status, chat.statusDetail, follow]); const sendFollow = () => { - if (!follow.trim()) { + // A plan switch in flight has the pause, so the text waits in the input. + if (!follow.trim() || chat.plan?.switching) { return; } @@ -149,6 +150,7 @@ const ChatPanel = ({ onAdd={onAdd} onRemove={onRemove} onFollowup={chat.send} + onApplyChoice={chat.applyChoice} readOnly={readOnly} /> {sharedAfter(index) && ( @@ -210,6 +212,9 @@ const ChatPanel = ({ plan={chat.plan} onApprove={() => chat.respondPlan('approve')} onCancel={() => chat.respondPlan('reject')} + // Switching goes with amending, which the + // wall takes away with the input. + onSwitch={wall ? undefined : chat.switchChoice} /> )} {wall ? ( diff --git a/src/components/organisms/Studio/workspace/PlanCard.module.scss b/src/components/organisms/Studio/workspace/PlanCard.module.scss index 035e4036..94e644c7 100644 --- a/src/components/organisms/Studio/workspace/PlanCard.module.scss +++ b/src/components/organisms/Studio/workspace/PlanCard.module.scss @@ -119,6 +119,18 @@ letter-spacing: -0.031em; } +// What the switch behind this plan changed, and why the harness refused the +// last answer to it, under the steps. +.moved, +.notice { + margin: 0; + padding: 0 rem(16) rem(14); + + &:empty { + padding: 0; + } +} + // --- "Start building?" ------------------------------------------------------ // Grows OUT of the input below: rounded on top only, its bottom edge diff --git a/src/components/organisms/Studio/workspace/PlanCard.tsx b/src/components/organisms/Studio/workspace/PlanCard.tsx index 976ef4b8..8d1fab97 100644 --- a/src/components/organisms/Studio/workspace/PlanCard.tsx +++ b/src/components/organisms/Studio/workspace/PlanCard.tsx @@ -4,7 +4,7 @@ import classNames from 'classnames'; import { useState } from 'react'; import styles from './PlanCard.module.scss'; -import PlanModal from './PlanModal'; +import PlanModal, { PlanMovedNote, PlanNotice } from './PlanModal'; import type { ChatState } from '../hooks/useChat'; import Button from '@/components/atoms/Button/Button'; @@ -16,6 +16,7 @@ type PlanCardProps = { plan: NonNullable; onApprove: () => void; onCancel: () => void; + onSwitch?: (choiceId: string, optionId: string) => void; }; /** @@ -27,7 +28,7 @@ type PlanCardProps = { * changes or ask a follow up…" while the plan is pending, wired to the * amend decision). */ -const PlanCard = ({ plan, onApprove, onCancel }: PlanCardProps) => { +const PlanCard = ({ plan, onApprove, onCancel, onSwitch }: PlanCardProps) => { const [open, setOpen] = useState(false); const preview = plan.steps.slice(0, PREVIEW_STEPS); const more = plan.steps.length > PREVIEW_STEPS; @@ -57,14 +58,16 @@ const PlanCard = ({ plan, onApprove, onCancel }: PlanCardProps) => { ))} + +

Start building?

- -
@@ -73,6 +76,7 @@ const PlanCard = ({ plan, onApprove, onCancel }: PlanCardProps) => { plan={plan} open={open} onOpenChange={setOpen} + onSwitch={onSwitch} onApprove={() => { setOpen(false); onApprove(); diff --git a/src/components/organisms/Studio/workspace/PlanModal.module.scss b/src/components/organisms/Studio/workspace/PlanModal.module.scss index d862f541..0b162666 100644 --- a/src/components/organisms/Studio/workspace/PlanModal.module.scss +++ b/src/components/organisms/Studio/workspace/PlanModal.module.scss @@ -139,6 +139,97 @@ } } +// A scope decision's options, the clarify picker's option buttons at the +// size of the decision text. +.options { + @include flex(row, flex-start, stretch); + + flex-wrap: wrap; + gap: rem(4); + margin-top: rem(6); +} + +.option { + @include flex(column, flex-start, flex-start); + @include font-size(11px, 1.34); + + gap: rem(2); + max-width: 100%; + padding: rem(6) rem(8); + font-family: var(--font-outfit); + font-weight: 400; + color: var(--color-charcoal); + text-align: left; + letter-spacing: -0.031em; + cursor: pointer; + background: none; + border: 1px solid var(--color-sage-light); + border-radius: rem(8); + transition: + border-color 0.25s ease, + background-color 0.25s ease, + opacity 0.25s ease; + + &:hover:not(:disabled, [aria-disabled="true"]) { + background-color: var(--color-net-mid); + } + + &:disabled, + &[aria-disabled="true"] { + cursor: default; + } + + // Unavailable, or waiting on a switch in flight. + &:is(:disabled, [aria-disabled="true"]):not(.optionActive, .optionPending) { + opacity: 0.55; + } +} + +.optionActive { + background-color: var(--color-net-light); + border-color: var(--color-charcoal); +} + +.optionPending { + border-style: dashed; + border-color: var(--color-charcoal); +} + +.optionLabel { + font-weight: 500; +} + +.optionNote { + color: var(--color-stone); +} + +// What a switch changed, and why a switch was refused. +.moved, +.notice { + @include font-size(11px, 1.4); + + margin: rem(10) rem(6) 0; + font-family: var(--font-outfit); + font-weight: 400; + color: var(--color-charcoal); + letter-spacing: -0.031em; +} + +.moved { + @include flex(column, flex-start, stretch); + + gap: rem(4); + padding: 0; + list-style: none; +} + +// Both stay mounted as live regions and take no room when empty. +.moved:empty, +.notice:empty { + margin: 0; + padding: 0; +} + // --- "Start building?" ------------------------------------------------------ // Pinned to the dialog's bottom edge, under the scrolling steps; the diff --git a/src/components/organisms/Studio/workspace/PlanModal.tsx b/src/components/organisms/Studio/workspace/PlanModal.tsx index c673b808..dfb80c97 100644 --- a/src/components/organisms/Studio/workspace/PlanModal.tsx +++ b/src/components/organisms/Studio/workspace/PlanModal.tsx @@ -9,6 +9,16 @@ import type { ChatState } from '../hooks/useChat'; import Button from '@/components/atoms/Button/Button'; import Icon from '@/components/atoms/Icon/Icon'; import Modal from '@/components/molecules/Modal/Modal'; +import { + canSwitch, + isActiveOption, + isSelectable, + movedSentence, + switchOptions, + yearsText, + type PlanState, +} from '@/lib/studio/plan'; +import type { PlanDecision } from '@/lib/studio/wire'; type PlanModalProps = { plan: NonNullable; @@ -16,15 +26,103 @@ type PlanModalProps = { onOpenChange: (open: boolean) => void; onApprove: () => void; onCancel: () => void; + // Switches a scope decision to another option. Left out where the + // viewer cannot change the plan (a guest, a read-only view). + onSwitch?: (choiceId: string, optionId: string) => void; +}; + +/** What the switch that produced this plan changed, said once on the plan + * it re-offered. The live region stays mounted, empty between switches, + * so a screen reader announces the sentences when they arrive. */ +export const PlanMovedNote = ({ plan, className }: { plan: PlanState; className?: string }) => ( +
    + {plan.moved.map((moved) => ( +
  • {movedSentence(moved)}
  • + ))} +
+); + +/** Why the harness refused the last answer to this plan, for the user to + * answer it again. A live region, mounted while empty, as above. */ +export const PlanNotice = ({ plan, className }: { plan: PlanState; className?: string }) => ( +

+ {plan.notice} +

+); + +/** + * One decision: the question, the chosen answer and why. A scope decision + * the plan lets the user switch also lists its options, the active one + * marked; a partial option names the years it covers, an unavailable one + * says why and cannot be picked. While a switch is in flight every option + * ignores clicks but keeps focus (`aria-disabled`). Only unavailable ones + * are natively disabled. + */ +const DecisionRow = ({ + decision, + plan, + onSwitch, +}: { + decision: PlanDecision; + plan: PlanState; + onSwitch?: (choiceId: string, optionId: string) => void; +}) => { + const options = onSwitch && canSwitch(plan) ? switchOptions(decision) : null; + const choiceId = decision.choice_id; + + return ( +
  • + {decision.question} — {decision.chosen} + {decision.reason ? ` (${decision.reason})` : ''} + {options && choiceId && ( +
    + {options.map((option) => { + const active = isActiveOption(decision, option); + const pending = + plan.switching?.choiceId === choiceId && + plan.switching.optionId === option.option_id; + const inert = !isSelectable(decision, option) || !!plan.switching; + const note = + option.status === 'unavailable' + ? option.reason + : option.status === 'partial' && option.years + ? `Covers ${yearsText(option.years)}` + : null; + + return ( + + ); + })} +
    + )} +
  • + ); }; /** * The full plan (design: "Proposed Research Plan – N Steps" modal): every * step on the dot rail with its description unfolded (a chevron folds it), - * the agent's decisions under them, and the same "Start building?" bar - * with Cancel and Approve pinned to the bottom. + * the agent's decisions under them (a scope decision with its options to + * switch between), and the same "Start building?" bar with Cancel and + * Approve pinned to the bottom. */ -const PlanModal = ({ plan, open, onOpenChange, onApprove, onCancel }: PlanModalProps) => { +const PlanModal = ({ plan, open, onOpenChange, onApprove, onCancel, onSwitch }: PlanModalProps) => { // Steps start unfolded — the modal exists to read them. const [folded, setFolded] = useState>(new Set()); @@ -99,21 +197,25 @@ const PlanModal = ({ plan, open, onOpenChange, onApprove, onCancel }: PlanModalP {plan.decisions.length > 0 && (
      {plan.decisions.map((decision) => ( -
    • - {decision.question} — {decision.chosen} - {decision.reason ? ` (${decision.reason})` : ''} -
    • + ))}
    )} + +

    Start building?

    - -
    diff --git a/src/lib/studio/chips.ts b/src/lib/studio/chips.ts new file mode 100644 index 00000000..89def2b9 --- /dev/null +++ b/src/lib/studio/chips.ts @@ -0,0 +1,95 @@ +/** + * The chips a `suggestions` frame offers after an answer: prompt follow-ups, + * sent as the user's next message, and `apply_choice` chips, which switch a + * scope choice of the answer's readings in one turn. Also what the + * transcript shows when the harness refuses a chip that no longer applies. + */ + +import type { ChatMessage } from '@/components/organisms/Studio/hooks/useChat'; + +import type { StreamRefusal } from './studioClient'; +import type { ApplyChoiceSuggestion, StudioFrame } from './wire'; + +type SuggestionItems = Extract['items']; + +/** The frame's items split by kind: prompt follow-ups (their prompts, as + * sent) and `apply_choice` chips, each in frame order. An item of another + * kind is left out. */ +export const splitSuggestions = ( + items: SuggestionItems, +): { followups: string[]; chips: ApplyChoiceSuggestion[] } => { + const followups: string[] = []; + const chips: ApplyChoiceSuggestion[] = []; + + for (const item of items) { + if ('kind' in item) { + if (item.kind === 'apply_choice') { + chips.push(item); + } + } else { + followups.push(item.prompt); + } + } + + return { followups, chips }; +}; + +/** What tells chips apart: the reading, the choice and the option. */ +export const chipKey = (chip: ApplyChoiceSuggestion): string => + `${chip.spec_id} ${chip.choice_id} ${chip.option_id}`; + +const sameChip = (a: ApplyChoiceSuggestion, b: ApplyChoiceSuggestion): boolean => + chipKey(a) === chipKey(b); + +/** The transcript of a conversation restored without its harness session, + * such as a fork of a share: its chips go, since the harness holds none of + * the answers that offered them. */ +export const withoutChips = (messages: ChatMessage[]): ChatMessage[] => + messages.map((message) => + message.role === 'bot' && message.chips + ? { + role: 'bot', + text: message.text, + ...(message.followups && { followups: message.followups }), + } + : message, + ); + +/** The `detail` of the harness's refusal of a chip (422 with pointer + * `/apply_choice`), or null for any other refusal. */ +export const chipRefusalDetail = (refusal: StreamRefusal): string | null => + refusal.status === 422 && refusal.error?.pointer === '/apply_choice' + ? refusal.error.detail + : null; + +/** + * The transcript after the harness refused `chip`: the reply the click + * opened says why, and carries the answer's other chips and follow-ups, so + * the user can still pick one. `messages` ends with the user's chip label + * and its empty reply; the answer that offered the chip comes before them. + */ +export const withRefusedChip = ( + messages: ChatMessage[], + chip: ApplyChoiceSuggestion, + detail: string, +): ChatMessage[] => { + const reply = messages.at(-1); + const answer = messages.at(-3); + + if (reply?.role !== 'bot') { + return messages; + } + + const offered = answer?.role === 'bot' ? answer : null; + const chips = (offered?.chips ?? []).filter((other) => !sameChip(other, chip)); + + return [ + ...messages.slice(0, -1), + { + ...reply, + text: `_${detail}_`, + ...(offered?.followups?.length && { followups: offered.followups }), + ...(chips.length > 0 && { chips }), + }, + ]; +}; diff --git a/src/lib/studio/plan.ts b/src/lib/studio/plan.ts new file mode 100644 index 00000000..71c9c4b9 --- /dev/null +++ b/src/lib/studio/plan.ts @@ -0,0 +1,190 @@ +/** + * The plan card's state and its `switch`: how a scope decision's options + * read, which of them the user can pick, the interrupt reply a pick sends, + * and what the card says when the harness refuses one. + */ + +import type { StreamRefusal } from './studioClient'; +import type { + InterruptResponse, + PlanAction, + PlanDecision, + PlanDecisionOption, + PlanMoved, + PlanProposed, + PlanStep, +} from './wire'; + +/** A switch the user asked for and the harness has not answered yet. */ +export type PlanSwitch = { choiceId: string; optionId: string }; + +/** A plan awaiting the user's approve, amend, reject or switch (the + * harness's `plan.proposed` pause). */ +export type PlanState = { + title: string; + steps: PlanStep[]; + decisions: PlanDecision[]; + version: number; + actions: PlanAction[]; + interruptId: string; + // The approval key a switch echoes, null from a harness that predates it. + revision: string | null; + // What the switch that produced this plan changed, empty otherwise. + moved: PlanMoved[]; + switching: PlanSwitch | null; + // Why the harness refused the last switch, for the card to say. + notice: string | null; +}; + +export type SwitchReply = Required< + Pick +>; + +/** The ToolError `constraint_id` of a switch or approve sent against an + * older plan. */ +export const PLAN_REVISION_STALE = 'plan_revision_stale'; + +/** Shown when a stale refusal carries no current plan (a pause the harness + * stored before it kept cards). */ +export const STALE_NOTICE = + 'This plan changed after this page received it, so it can no longer be switched here. Reload the conversation to see the current plan.'; + +export const planFromFrame = (frame: PlanProposed): PlanState => ({ + title: frame.title, + steps: frame.steps, + decisions: frame.decisions ?? [], + version: frame.version, + actions: frame.actions, + interruptId: frame.interrupt_id, + revision: frame.revision ?? null, + moved: frame.moved ?? [], + switching: null, + notice: null, +}); + +/** The plan offers switching: it lists the action and carries the revision + * a switch must echo. */ +export const canSwitch = (plan: PlanState): boolean => + plan.actions.includes('switch') && plan.revision !== null; + +/** A decision's switchable options, or null for an ordinary decision. */ +export const switchOptions = (decision: PlanDecision): PlanDecisionOption[] | null => + decision.choice_id && decision.options && decision.options.length > 0 ? decision.options : null; + +/** The option the plan counts by now: `active_option_id`, else the option + * whose label is the decision's `chosen`. */ +export const isActiveOption = (decision: PlanDecision, option: PlanDecisionOption): boolean => + decision.active_option_id + ? option.option_id === decision.active_option_id + : option.label === decision.chosen; + +/** The option can be switched to: offered as available or partial, and not + * already active. */ +export const isSelectable = (decision: PlanDecision, option: PlanDecisionOption): boolean => + option.status !== 'unavailable' && !isActiveOption(decision, option); + +/** Year ranges as the card prints them: "2015–2019, 2022". */ +export const yearsText = (years: readonly (readonly [number, number])[]): string => + years.map(([first, last]) => (first === last ? `${first}` : `${first}–${last}`)).join(', '); + +export const movedSentence = (moved: PlanMoved): string => + `${moved.from_label} changed to ${moved.to_label}. ${moved.reason}`.trim(); + +/** + * The interrupt reply that switches `choiceId` to `optionId`, or null when + * the plan offers no such switch: switching is off, another switch is in + * flight, or the option is unknown, unavailable or already active. + */ +export const switchReply = ( + plan: PlanState, + choiceId: string, + optionId: string, +): SwitchReply | null => { + if (!canSwitch(plan) || plan.switching || plan.revision === null) { + return null; + } + + const decision = plan.decisions.find((candidate) => candidate.choice_id === choiceId); + const option = decision?.options?.find((candidate) => candidate.option_id === optionId); + + if (!decision || !option || !isSelectable(decision, option)) { + return null; + } + + return { + decision: 'switch', + choice_id: choiceId, + option_id: optionId, + plan_revision: plan.revision, + }; +}; + +/** The plan while its switch is in flight: the card stays, its controls + * wait, and an earlier refusal's notice goes. */ +export const startSwitch = (plan: PlanState, pick: PlanSwitch): PlanState => ({ + ...plan, + switching: pick, + notice: null, +}); + +const isStale = (refusal: StreamRefusal): boolean => + refusal.error?.constraint_id === PLAN_REVISION_STALE; + +/** The constraint_id of a switch the harness refused because the plan does + * not offer the option. */ +export const SWITCH_OPTION_UNAVAILABLE = 'switch_option_unavailable'; + +/** The card a stale switch or approve is answered with, the harness's + * current plan, saying why it replaced the one the user answered. Null for + * any other refusal, or a stale one without a current plan. */ +export const stalePlan = (refusal: StreamRefusal): PlanState | null => { + const current = isStale(refusal) ? refusal.error?.current_plan : null; + + return current ? { ...planFromFrame(current), notice: refusal.detail } : null; +}; + +/** + * The card after the harness refused its switch, saying why, or null when + * the refusal is not one the harness gives a switch. Those are a 409 + * `plan_revision_stale` and a 422 `switch_option_unavailable`; any other + * status (a 404 for an interrupt that is gone, 401, 429, 5xx) is a failed + * request, and the pause it answered is over. + * + * A stale revision brings the current plan, and switching works again on + * it. Without one the card keeps its revision, so an approve from it is + * refused as stale, and drops the switch action. + */ +export const refusedSwitch = (plan: PlanState, refusal: StreamRefusal): PlanState | null => { + const constraint = refusal.error?.constraint_id; + + if (refusal.status === 409 && constraint === PLAN_REVISION_STALE) { + return ( + stalePlan(refusal) ?? { + ...plan, + actions: plan.actions.filter((action) => action !== 'switch'), + switching: null, + notice: STALE_NOTICE, + } + ); + } + + if (refusal.status === 422 && constraint === SWITCH_OPTION_UNAVAILABLE) { + return { ...plan, switching: null, notice: refusal.detail }; + } + + return null; +}; + +/** An `approve` of `plan`, carrying its revision so the harness can tell an + * approval from an out-of-date card. */ +export const approveReply = ( + plan: PlanState | undefined, +): Pick => + plan?.revision + ? { decision: 'approve', plan_revision: plan.revision } + : { decision: 'approve' }; + +/** A plan whose switch ended without a fresh plan (an error, a stop, a turn + * that finished) leaves the card. Any other plan stays. */ +export const settledPlan = (plan: PlanState | null): PlanState | null => + plan?.switching ? null : plan; diff --git a/src/lib/studio/promptAllowance.ts b/src/lib/studio/promptAllowance.ts index 811eb263..545905c5 100644 --- a/src/lib/studio/promptAllowance.ts +++ b/src/lib/studio/promptAllowance.ts @@ -10,3 +10,45 @@ export const GUEST_PROMPTS = 5; // Prompts a day for a signed-in user, shared by every account on one inbox. export const USER_DAILY_PROMPTS = 75; + +/** What a Studio prompt asks: the first question, a follow-up, an edit of a + * card, or a clicked `apply_choice` chip. */ +export type PromptIntent = 'new' | 'follow_up' | 'edit' | 'apply_choice'; + +export type PromptEvent = { + turn: number; + intent: PromptIntent; + length?: number; + guest: boolean; +}; + +/** + * The `studio.prompt` event for a prompt about to be sent, or null when a + * guest has no free prompt left for it. `used` is the guest's prompts spent + * so far, `queued` the prompts waiting behind the running turn (they hold + * their place in the limit), and `sent` the prompts in the transcript. + * `length` is the typed text's length; a chip has none. + */ +export const promptEvent = ({ + guest, + used, + queued, + sent, + intent, + length, +}: { + guest: boolean; + used: number; + queued: number; + sent: number; + intent?: PromptIntent; + length?: number; +}): PromptEvent | null => + guest && used + queued >= GUEST_PROMPTS + ? null + : { + turn: sent + queued + 1, + intent: intent ?? (sent === 0 ? 'new' : 'follow_up'), + ...(length !== undefined && { length }), + guest, + }; diff --git a/src/lib/studio/studioClient.ts b/src/lib/studio/studioClient.ts index e39604ad..549d43de 100644 --- a/src/lib/studio/studioClient.ts +++ b/src/lib/studio/studioClient.ts @@ -10,11 +10,13 @@ */ import type { + ApplyChoice, CancelRequest, CompositionManifest, CompositionMutation, InterruptResponse, MutationOperation, + PlanRevisionStaleError, StudioFrame, ToolError, TurnRequest, @@ -37,16 +39,36 @@ const transportError = (detail: string): StudioFrame => ({ } as ToolError, }); -/** What a stream reports to its caller. */ +/** An HTTP refusal of a stream request: its status, the body's `detail` + * when it has one, and the harness's ToolError when the body is one + * (with `current_plan` on a stale plan answer). */ +export type StreamRefusal = { + status: number; + detail: string | null; + error: PlanRevisionStaleError | null; +}; + +/** What a stream reports to its caller. `onRefusal` sees an HTTP refusal + * before the stream would report it as an `error` frame, and returns true + * when it has dealt with it. */ export type StreamHandlers = { onFrame: (frame: StudioFrame) => void; onKeepAlive?: () => void; + onRefusal?: (refusal: StreamRefusal) => boolean; }; +const asToolError = (body: unknown): PlanRevisionStaleError | null => + body !== null && + typeof body === 'object' && + typeof (body as ToolError).error === 'string' && + typeof (body as ToolError).detail === 'string' + ? (body as ToolError) + : null; + const streamStudio = async ( endpoint: 'turn' | 'interrupt', body: TurnRequest | InterruptResponse, - { onFrame, onKeepAlive }: StreamHandlers, + { onFrame, onKeepAlive, onRefusal }: StreamHandlers, signal?: AbortSignal, ): Promise => { let res: Response; @@ -69,11 +91,14 @@ const streamStudio = async ( } if (!res.ok || !res.body) { - let detail = `HTTP ${res.status}`; + let detail: string | null = null; + let error: PlanRevisionStaleError | null = null; try { const parsed = (await res.json()) as { detail?: unknown }; + error = asToolError(parsed); + if (typeof parsed.detail === 'string') { detail = parsed.detail; } @@ -81,7 +106,11 @@ const streamStudio = async ( // Non-JSON body — the status line stands. } - onFrame(transportError(detail)); + if (!res.ok && onRefusal?.({ status: res.status, detail, error })) { + return; + } + + onFrame(transportError(detail ?? `HTTP ${res.status}`)); return; } @@ -158,11 +187,34 @@ export const runTurn = ( signal, ); +/** Run a turn from a clicked `apply_choice` chip: the chip's choice, option, + * turn and reading, copied as offered, and no message. */ +export const runApplyChoice = ( + conversationId: string, + { choice_id, option_id, turn, spec_id }: ApplyChoice, + handlers: StreamHandlers, + signal?: AbortSignal, +): Promise => + streamStudio( + 'turn', + { + kind: 'turn.request', + schema_version: 1, + conversation_id: conversationId, + apply_choice: { choice_id, option_id, turn, spec_id }, + }, + handlers, + signal, + ); + /** Answer a pause; the response is a NEW stream continuing the same turn. */ export const runInterrupt = ( conversationId: string, interruptId: string, - reply: Pick, + reply: Pick< + InterruptResponse, + 'decision' | 'payload' | 'answers' | 'choice_id' | 'option_id' | 'plan_revision' + >, handlers: StreamHandlers, signal?: AbortSignal, ): Promise => diff --git a/src/lib/studio/test/chips.test.ts b/src/lib/studio/test/chips.test.ts new file mode 100644 index 00000000..c8a4c920 --- /dev/null +++ b/src/lib/studio/test/chips.test.ts @@ -0,0 +1,150 @@ +/** + * The chips after an answer: a `suggestions` frame split into prompt + * follow-ups and `apply_choice` chips, and the transcript after the harness + * refuses a chip. + */ +import assert from 'node:assert/strict'; +import { readFileSync } from 'node:fs'; +import test from 'node:test'; + +import { + chipKey, + chipRefusalDetail, + splitSuggestions, + withoutChips, + withRefusedChip, +} from '../chips.ts'; +import type { ChatMessage } from '../../../components/organisms/Studio/hooks/useChat.ts'; +import type { StudioFrame } from '../wire.ts'; + +type Suggestions = Extract; + +/** The harness's wire fixture (`services/harness/tests/wire_fixtures/studio` + * in dfo-ai), copied. */ +const frame = JSON.parse( + readFileSync( + new URL('./fixtures/event-15-suggestions-apply-choice.json', import.meta.url), + 'utf8', + ), +) as Suggestions; + +const [sector, region] = splitSuggestions(frame.items).chips; + +test('splitSuggestions: the fixture frame is two chips in frame order, no follow-ups', () => { + assert.deepEqual(splitSuggestions(frame.items), { followups: [], chips: frame.items }); +}); + +test('splitSuggestions: each chip keeps the turn and spec_id it was offered with', () => { + const { chips } = splitSuggestions(frame.items); + + assert.deepEqual( + chips.map(({ turn, spec_id }) => ({ turn, spec_id })), + frame.items.map((item) => ({ + turn: 'turn' in item ? item.turn : undefined, + spec_id: 'spec_id' in item ? item.spec_id : undefined, + })), + ); + assert.ok(chips.every((chip) => chip.turn >= 1 && chip.spec_id.startsWith('spec_'))); +}); + +test('splitSuggestions: prompt follow-ups keep their prompts beside the chips', () => { + const prompt = { label: 'By donor', prompt: 'Break this down by donor' }; + + assert.deepEqual(splitSuggestions([prompt, ...frame.items]), { + followups: ['Break this down by donor'], + chips: frame.items, + }); +}); + +test('splitSuggestions: an item of another kind is neither a chip nor a follow-up', () => { + const other = { kind: 'open_card', label: 'Open the card', prompt: 'Open it' }; + + assert.deepEqual(splitSuggestions([other as unknown as Suggestions['items'][number]]), { + followups: [], + chips: [], + }); +}); + +const toolError = (pointer: string | null) => ({ + error: 'constraint_violation' as const, + retry: 'do_not_retry' as const, + detail: 'This answer has changed since that suggestion was offered, so nothing changed.', + constraint_id: 'scope_choice_stale', + pointer, +}); + +test('chipRefusalDetail: a 422 pointing at /apply_choice gives its detail; others give null', () => { + const chip = toolError('/apply_choice'); + + assert.equal(chipRefusalDetail({ status: 422, detail: chip.detail, error: chip }), chip.detail); + assert.equal( + chipRefusalDetail({ status: 422, detail: 'x', error: toolError('/message') }), + null, + ); + assert.equal(chipRefusalDetail({ status: 502, detail: 'proxy failed', error: null }), null); +}); + +test('withRefusedChip: the reply says why and keeps the answer’s other chips and follow-ups', () => { + assert.ok(sector && region); + + const messages: ChatMessage[] = [ + { role: 'user', text: 'Aid to Africa for health' }, + { role: 'bot', text: 'USD 4.1bn', followups: ['By donor'], chips: [sector, region] }, + { role: 'user', text: sector.label }, + { role: 'bot', text: '' }, + ]; + + assert.deepEqual(withRefusedChip(messages, sector, 'Nothing changed.'), [ + ...messages.slice(0, 3), + { role: 'bot', text: '_Nothing changed._', followups: ['By donor'], chips: [region] }, + ]); +}); + +test('withRefusedChip: the last chip refused leaves a reply with no chips', () => { + assert.ok(sector); + + const messages: ChatMessage[] = [ + { role: 'bot', text: 'USD 4.1bn', chips: [sector] }, + { role: 'user', text: sector.label }, + { role: 'bot', text: '' }, + ]; + + assert.deepEqual(withRefusedChip(messages, sector, 'Nothing changed.').at(-1), { + role: 'bot', + text: '_Nothing changed._', + }); +}); + +test('withRefusedChip: a chip for another reading of the same choice and option stays', () => { + assert.ok(sector); + + const other = { ...sector, spec_id: `${sector.spec_id}_other` }; + const messages: ChatMessage[] = [ + { role: 'bot', text: 'USD 4.1bn', chips: [sector, other] }, + { role: 'user', text: sector.label }, + { role: 'bot', text: '' }, + ]; + + assert.notEqual(chipKey(sector), chipKey(other)); + assert.deepEqual(withRefusedChip(messages, sector, 'Nothing changed.').at(-1), { + role: 'bot', + text: '_Nothing changed._', + chips: [other], + }); +}); + +test('withoutChips: a restored transcript keeps its follow-ups and loses its chips', () => { + assert.ok(sector); + + const messages: ChatMessage[] = [ + { role: 'user', text: 'Aid to Africa for health' }, + { role: 'bot', text: 'USD 4.1bn', followups: ['By donor'], chips: [sector] }, + { role: 'bot', text: 'Done', chips: [sector] }, + ]; + + assert.deepEqual(withoutChips(messages), [ + { role: 'user', text: 'Aid to Africa for health' }, + { role: 'bot', text: 'USD 4.1bn', followups: ['By donor'] }, + { role: 'bot', text: 'Done' }, + ]); +}); diff --git a/src/lib/studio/test/fixtures/event-15-suggestions-apply-choice.json b/src/lib/studio/test/fixtures/event-15-suggestions-apply-choice.json new file mode 100644 index 00000000..11dacc19 --- /dev/null +++ b/src/lib/studio/test/fixtures/event-15-suggestions-apply-choice.json @@ -0,0 +1,22 @@ +{ + "event": "suggestions", + "seq": 9, + "items": [ + { + "kind": "apply_choice", + "label": "health, CRS 120 alone", + "choice_id": "spec_6176d83382fca6c596e00cb242a06803:sector", + "option_id": "sector:120", + "turn": 2, + "spec_id": "spec_0b7d6c7e1f2a4b5c8d9e0f1a2b3c4d5e" + }, + { + "kind": "apply_choice", + "label": "Africa's countries only", + "choice_id": "spec_6176d83382fca6c596e00cb242a06803:region", + "option_id": "region:members_only", + "turn": 2, + "spec_id": "spec_0b7d6c7e1f2a4b5c8d9e0f1a2b3c4d5e" + } + ] +} diff --git a/src/lib/studio/test/fixtures/request-13-turn-apply-choice.json b/src/lib/studio/test/fixtures/request-13-turn-apply-choice.json new file mode 100644 index 00000000..90244280 --- /dev/null +++ b/src/lib/studio/test/fixtures/request-13-turn-apply-choice.json @@ -0,0 +1,11 @@ +{ + "kind": "turn.request", + "schema_version": 1, + "session_id": "sess_01j9zc0000", + "apply_choice": { + "choice_id": "spec_6176d83382fca6c596e00cb242a06803:sector", + "option_id": "sector:120", + "turn": 2, + "spec_id": "spec_0b7d6c7e1f2a4b5c8d9e0f1a2b3c4d5e" + } +} diff --git a/src/lib/studio/test/plan.test.ts b/src/lib/studio/test/plan.test.ts new file mode 100644 index 00000000..49e4e146 --- /dev/null +++ b/src/lib/studio/test/plan.test.ts @@ -0,0 +1,358 @@ +/** + * The plan card's switch: the reply a pick sends, the picks the card + * refuses before sending, and the card after a refusal or a fresh plan. + */ +import assert from 'node:assert/strict'; +import test from 'node:test'; + +import { + PLAN_REVISION_STALE, + approveReply, + canSwitch, + STALE_NOTICE, + SWITCH_OPTION_UNAVAILABLE, + isActiveOption, + isSelectable, + movedSentence, + planFromFrame, + refusedSwitch, + settledPlan, + stalePlan, + startSwitch, + switchReply, + yearsText, +} from '../plan.ts'; +import type { StreamRefusal } from '../studioClient.ts'; +import type { PlanDecision, PlanProposed } from '../wire.ts'; + +const countDecision: PlanDecision = { + id: 'd1', + question: 'How is aid counted?', + chosen: 'Gross disbursements', + reason: 'the source publishes this basis', + resolved_by: 'default', + choice_id: 'spec_1:measure_basis', + active_option_id: 'measure_basis:gross', + options: [ + { + option_id: 'measure_basis:gross', + label: 'Gross disbursements', + status: 'available', + reason: null, + years: null, + }, + { + option_id: 'measure_basis:net', + label: 'Net disbursements', + status: 'partial', + reason: null, + years: [ + [2015, 2019], + [2022, 2022], + ], + }, + { + option_id: 'measure_basis:grant_equivalent', + label: 'Grant equivalent', + status: 'unavailable', + reason: 'The source does not publish this basis for these donors.', + years: null, + }, + ], +}; + +const frame = (overrides: Partial = {}): PlanProposed => ({ + event: 'plan.proposed', + seq: 4, + interrupt_id: 'int-1', + plan_version_id: 'pv-1', + version: 1, + title: 'Health aid to Ghana', + steps: [{ id: 's1', label: 'Retrieve health aid' }], + actions: ['approve', 'amend', 'reject', 'switch'], + decisions: [countDecision, { ...countDecision, id: 'd2', choice_id: null, options: null }], + revision: 'rev-a', + ...overrides, +}); + +test('planFromFrame keeps the revision and what moved', () => { + const moved = [ + { + choice_id: 'spec_1:measure_basis', + from_label: 'Gross disbursements', + to_label: 'Net disbursements', + reason: 'Repayments are now subtracted.', + }, + ]; + const plan = planFromFrame(frame({ revision: 'rev-b', moved })); + + assert.equal(plan.revision, 'rev-b'); + assert.deepEqual(plan.moved, moved); + assert.equal(plan.switching, null); + assert.equal(plan.notice, null); +}); + +test('planFromFrame reads a harness without revision or moved as none', () => { + const plan = planFromFrame(frame({ revision: undefined, moved: undefined })); + + assert.equal(plan.revision, null); + assert.deepEqual(plan.moved, []); +}); + +test('switchReply sends the choice, the option and the revision the user saw', () => { + const reply = switchReply(planFromFrame(frame()), 'spec_1:measure_basis', 'measure_basis:net'); + + assert.deepEqual(reply, { + decision: 'switch', + choice_id: 'spec_1:measure_basis', + option_id: 'measure_basis:net', + plan_revision: 'rev-a', + }); +}); + +test('switchReply refuses a pick the plan does not offer', async (t) => { + const plan = planFromFrame(frame()); + const cases = [ + ['an unavailable option', plan, 'measure_basis:grant_equivalent'], + ['the active option', plan, 'measure_basis:gross'], + ['an unknown option', plan, 'measure_basis:commitments'], + [ + 'a plan that does not list switch', + planFromFrame(frame({ actions: ['approve', 'amend', 'reject'] })), + 'measure_basis:net', + ], + [ + 'a plan without a revision', + planFromFrame(frame({ revision: null })), + 'measure_basis:net', + ], + [ + 'a switch already in flight', + startSwitch(plan, { choiceId: 'spec_1:measure_basis', optionId: 'measure_basis:net' }), + 'measure_basis:net', + ], + ] as const; + + for (const [name, candidate, optionId] of cases) { + await t.test(name, () => { + assert.equal(switchReply(candidate, 'spec_1:measure_basis', optionId), null); + }); + } +}); + +test('the active option is the chosen one, and only other offered options are selectable', () => { + const [gross, net, grant] = countDecision.options!; + + assert.deepEqual( + [gross!, net!, grant!].map((option) => [ + isActiveOption(countDecision, option), + isSelectable(countDecision, option), + ]), + [ + [true, false], + [false, true], + [false, false], + ], + ); +}); + +test('active_option_id marks the active option over a label that matches another', () => { + const [gross, net] = countDecision.options!; + const decision = { ...countDecision, active_option_id: 'measure_basis:net' }; + + assert.equal(isActiveOption(decision, net!), true); + assert.equal(isActiveOption(decision, gross!), false); +}); + +test('without active_option_id the chosen label marks the active option', () => { + const [gross, net] = countDecision.options!; + const decision = { ...countDecision, active_option_id: undefined }; + + assert.equal(isActiveOption(decision, gross!), true); + assert.equal(isActiveOption(decision, net!), false); +}); + +const STALE_DETAIL = 'This plan changed in another window. Here is the current plan.'; + +/** A 409 `plan_revision_stale`, with the harness's current card when given. */ +const staleRefusal = (currentPlan?: PlanProposed): StreamRefusal => ({ + status: 409, + detail: STALE_DETAIL, + error: { + error: 'edit_conflict', + retry: 'refresh_then_retry', + detail: STALE_DETAIL, + constraint_id: PLAN_REVISION_STALE, + ...(currentPlan && { current_plan: currentPlan }), + }, +}); + +const currentFrame = frame({ seq: 9, interrupt_id: 'int-2', version: 2, revision: 'rev-b' }); + +test('a stale switch is answered with the current card, which switches again', () => { + const waiting = startSwitch(planFromFrame(frame()), { + choiceId: 'spec_1:measure_basis', + optionId: 'measure_basis:net', + }); + const replaced = refusedSwitch(waiting, staleRefusal(currentFrame)); + + assert.deepEqual(replaced, { ...planFromFrame(currentFrame), notice: STALE_DETAIL }); + assert.deepEqual(switchReply(replaced, 'spec_1:measure_basis', 'measure_basis:net'), { + decision: 'switch', + choice_id: 'spec_1:measure_basis', + option_id: 'measure_basis:net', + plan_revision: 'rev-b', + }); +}); + +test('a stale approve is answered with the current card; other refusals are not', () => { + assert.deepEqual(stalePlan(staleRefusal(currentFrame)), { + ...planFromFrame(currentFrame), + notice: STALE_DETAIL, + }); + assert.equal(stalePlan(staleRefusal()), null); + assert.equal( + stalePlan({ + status: 422, + detail: 'decision approve does not take a payload', + error: null, + }), + null, + ); +}); + +test('an approve carries the revision of the card the user approved', () => { + assert.deepEqual(approveReply(planFromFrame(frame())), { + decision: 'approve', + plan_revision: 'rev-a', + }); + assert.deepEqual(approveReply(planFromFrame(frame({ revision: null }))), { + decision: 'approve', + }); +}); + +test('a stale switch without a current card keeps its revision, so an approve is refused', () => { + const plan = startSwitch(planFromFrame(frame()), { + choiceId: 'spec_1:measure_basis', + optionId: 'measure_basis:net', + }); + const refused = refusedSwitch(plan, staleRefusal()); + + assert.ok(refused); + assert.equal(refused.switching, null); + assert.equal(refused.notice, STALE_NOTICE); + assert.equal(canSwitch(refused), false); + assert.equal(switchReply(refused, 'spec_1:measure_basis', 'measure_basis:net'), null); + assert.deepEqual(approveReply(refused), { decision: 'approve', plan_revision: 'rev-a' }); +}); + +test('an unavailable option keeps the card and shows the harness reason', () => { + const plan = startSwitch(planFromFrame(frame()), { + choiceId: 'spec_1:measure_basis', + optionId: 'measure_basis:net', + }); + const refused = refusedSwitch(plan, { + status: 422, + detail: 'Net disbursements cannot be counted for this plan.', + error: { + error: 'constraint_violation', + retry: 'correct_and_retry', + detail: 'Net disbursements cannot be counted for this plan.', + constraint_id: SWITCH_OPTION_UNAVAILABLE, + }, + }); + + assert.ok(refused); + assert.equal(refused.switching, null); + assert.equal(refused.notice, 'Net disbursements cannot be counted for this plan.'); + assert.equal(refused.revision, 'rev-a'); + assert.equal(canSwitch(refused), true); +}); + +test('a refusal the harness does not give a switch is a failed request, with no card', async (t) => { + const plan = startSwitch(planFromFrame(frame()), { + choiceId: 'spec_1:measure_basis', + optionId: 'measure_basis:net', + }); + const toolError = (error: string, constraint_id?: string) => ({ + error: error as 'not_found', + retry: 'do_not_retry' as const, + detail: error, + ...(constraint_id && { constraint_id }), + }); + const cases: [string, StreamRefusal][] = [ + [ + 'a 404 for an interrupt that is gone', + { status: 404, detail: 'gone', error: toolError('not_found') }, + ], + ['a 401', { status: 401, detail: 'Sign in again.', error: null }], + ['a 429', { status: 429, detail: null, error: null }], + ['a 502', { status: 502, detail: null, error: null }], + [ + 'a 409 transient_unavailable', + { status: 409, detail: 'busy', error: toolError('transient_unavailable') }, + ], + [ + 'a 422 binding_invalid', + { status: 422, detail: 'bad', error: toolError('binding_invalid') }, + ], + [ + 'a stale constraint on a 422', + { status: 422, detail: 'x', error: toolError('edit_conflict', PLAN_REVISION_STALE) }, + ], + ]; + + for (const [name, refusal] of cases) { + await t.test(name, () => { + assert.equal(refusedSwitch(plan, refusal), null); + }); + } +}); + +test('a fresh plan after a switch replaces the waiting card with what moved', () => { + const waiting = startSwitch(planFromFrame(frame()), { + choiceId: 'spec_1:measure_basis', + optionId: 'measure_basis:net', + }); + const fresh = planFromFrame( + frame({ + interrupt_id: 'int-2', + version: 2, + revision: 'rev-b', + moved: [ + { + choice_id: 'spec_1:measure_basis', + from_label: 'Gross disbursements', + to_label: 'Net disbursements', + reason: 'Repayments are now subtracted.', + }, + ], + }), + ); + + assert.equal(waiting.switching?.optionId, 'measure_basis:net'); + assert.equal(fresh.switching, null); + assert.deepEqual(fresh.moved.map(movedSentence), [ + 'Gross disbursements changed to Net disbursements. Repayments are now subtracted.', + ]); + assert.equal( + switchReply(fresh, 'spec_1:measure_basis', 'measure_basis:net')?.plan_revision, + 'rev-b', + ); +}); + +test('a switch that ends without a fresh plan drops the card; other plans stay', () => { + const plan = planFromFrame(frame()); + const waiting = startSwitch(plan, { + choiceId: 'spec_1:measure_basis', + optionId: 'measure_basis:net', + }); + + assert.equal(settledPlan(waiting), null); + assert.equal(settledPlan(plan), plan); + assert.equal(settledPlan(null), null); +}); + +test('yearsText joins ranges and prints a one-year range once', () => { + assert.equal(yearsText(countDecision.options![1]!.years!), '2015–2019, 2022'); +}); diff --git a/src/lib/studio/test/promptAllowance.test.ts b/src/lib/studio/test/promptAllowance.test.ts new file mode 100644 index 00000000..92464746 --- /dev/null +++ b/src/lib/studio/test/promptAllowance.test.ts @@ -0,0 +1,47 @@ +/** + * The `studio.prompt` event and the guest limit every Studio prompt passes: + * typed text and clicked chips alike. + */ +import assert from 'node:assert/strict'; +import test from 'node:test'; + +import { GUEST_PROMPTS, promptEvent } from '../promptAllowance.ts'; + +test('promptEvent: a guest with no free prompt left sends nothing, queued prompts included', () => { + assert.equal(promptEvent({ guest: true, used: GUEST_PROMPTS, queued: 0, sent: 3 }), null); + assert.equal( + promptEvent({ + guest: true, + used: GUEST_PROMPTS - 1, + queued: 1, + sent: 3, + intent: 'apply_choice', + }), + null, + ); +}); + +test('promptEvent: a signed-in user is never walled', () => { + assert.deepEqual(promptEvent({ guest: false, used: 99, queued: 2, sent: 7, length: 12 }), { + turn: 10, + intent: 'follow_up', + length: 12, + guest: false, + }); +}); + +test('promptEvent: the first prompt is new, a later one a follow-up, unless an intent is given', () => { + assert.equal(promptEvent({ guest: true, used: 0, queued: 0, sent: 0 })?.intent, 'new'); + assert.equal(promptEvent({ guest: true, used: 1, queued: 0, sent: 1 })?.intent, 'follow_up'); + assert.equal( + promptEvent({ guest: true, used: 1, queued: 0, sent: 1, intent: 'edit' })?.intent, + 'edit', + ); +}); + +test('promptEvent: a chip counts as a turn, with its intent and no length', () => { + assert.deepEqual( + promptEvent({ guest: true, used: 1, queued: 1, sent: 1, intent: 'apply_choice' }), + { turn: 3, intent: 'apply_choice', guest: true }, + ); +}); diff --git a/src/lib/studio/test/studioClient.test.ts b/src/lib/studio/test/studioClient.test.ts index 6c87c4c7..3ac6d67e 100644 --- a/src/lib/studio/test/studioClient.test.ts +++ b/src/lib/studio/test/studioClient.test.ts @@ -3,9 +3,17 @@ * reason when the read fails. */ import assert from 'node:assert/strict'; +import { readFileSync } from 'node:fs'; import test from 'node:test'; -import { cancelTurn, fetchComponentRevision, runTurn } from '../studioClient.ts'; +import { + cancelTurn, + fetchComponentRevision, + runApplyChoice, + runInterrupt, + runTurn, +} from '../studioClient.ts'; +import type { ApplyChoiceSuggestion, StudioFrame } from '../wire.ts'; test('fetchComponentRevision: a refused read is null and logs the ids and status', async (t) => { t.mock.method(globalThis, 'fetch', async () => new Response('', { status: 502 })); @@ -77,3 +85,165 @@ test('cancelTurn: a cancel request that never answers settles once the bound pas assert.equal(outcome, 'settled'); }); + +const switchReply = { + decision: 'switch', + choice_id: 'spec_1:measure_basis', + option_id: 'measure_basis:net', + plan_revision: 'rev-a', +} as const; + +const staleBody = { + error: 'edit_conflict', + retry: 'refresh_then_retry', + detail: 'plan revision rev-a is not the pending plan', + constraint_id: 'plan_revision_stale', +}; + +test('runInterrupt: a switch posts exactly the interrupt members and the switch fields', async (t) => { + const fetch = t.mock.method(globalThis, 'fetch', async () => new Response('')); + + await runInterrupt('conv', 'int-1', switchReply, { onFrame: () => {} }); + + const init = fetch.mock.calls[0]?.arguments[1] as RequestInit; + + assert.deepEqual(JSON.parse(init.body as string), { + kind: 'interrupt.response', + schema_version: 1, + conversation_id: 'conv', + interrupt_id: 'int-1', + ...switchReply, + }); +}); + +test('runInterrupt: a refusal reaches onRefusal with its status and ToolError, and no error frame', async (t) => { + t.mock.method(globalThis, 'fetch', async () => Response.json(staleBody, { status: 409 })); + const frames: StudioFrame[] = []; + const refusals: unknown[] = []; + + await runInterrupt('conv', 'int-1', switchReply, { + onFrame: (frame) => frames.push(frame), + onRefusal: (refusal) => { + refusals.push(refusal); + + return true; + }, + }); + + assert.deepEqual(refusals, [{ status: 409, detail: staleBody.detail, error: staleBody }]); + assert.deepEqual(frames, []); +}); + +test('runInterrupt: a refusal onRefusal leaves is an error frame with its detail', async (t) => { + t.mock.method(globalThis, 'fetch', async () => + Response.json({ detail: 'proxy failed' }, { status: 502 }), + ); + const frames: StudioFrame[] = []; + const refusals: unknown[] = []; + + await runInterrupt('conv', 'int-1', switchReply, { + onFrame: (frame) => frames.push(frame), + onRefusal: (refusal) => { + refusals.push(refusal); + + return false; + }, + }); + + assert.deepEqual(refusals, [{ status: 502, detail: 'proxy failed', error: null }]); + assert.equal(frames.length, 1); + assert.equal(frames[0]?.event === 'error' && frames[0].error.detail, 'proxy failed'); +}); + +test('runInterrupt: a stale refusal hands onRefusal the current plan as sent', async (t) => { + const currentPlan = { + event: 'plan.proposed', + seq: 9, + interrupt_id: 'int-2', + plan_version_id: 'pv-2', + version: 2, + title: 'Health aid to Ghana', + steps: [], + actions: ['approve', 'amend', 'reject'], + revision: 'rev-b', + }; + + t.mock.method(globalThis, 'fetch', async () => + Response.json({ ...staleBody, current_plan: currentPlan }, { status: 409 }), + ); + let seen: unknown = null; + + await runInterrupt( + 'conv', + 'int-1', + { decision: 'approve', plan_revision: 'rev-a' }, + { + onFrame: () => {}, + onRefusal: (refusal) => { + seen = refusal.error?.current_plan; + + return true; + }, + }, + ); + + assert.deepEqual(seen, currentPlan); +}); + +test('runApplyChoice: a chip posts the harness fixture request, with no message', async (t) => { + const fetch = t.mock.method(globalThis, 'fetch', async () => new Response('')); + // The harness's wire fixtures (`services/harness/tests/wire_fixtures/studio` + // in dfo-ai), copied. The request names the conversation by the + // `session_id` alias the harness also accepts. + const read = (name: string): unknown => + JSON.parse(readFileSync(new URL(`./fixtures/${name}`, import.meta.url), 'utf8')); + const { session_id: conversation, ...request } = read( + 'request-13-turn-apply-choice.json', + ) as Record & { session_id: string }; + const { items } = read('event-15-suggestions-apply-choice.json') as { + items: ApplyChoiceSuggestion[]; + }; + const chip = items[0]; + + assert.ok(chip); + await runApplyChoice(conversation, chip, { onFrame: () => {} }); + + const init = fetch.mock.calls[0]?.arguments[1] as RequestInit; + + assert.equal(fetch.mock.calls[0]?.arguments[0], '/api/studio/turn'); + const body = JSON.parse(init.body as string) as { apply_choice: Record }; + + assert.deepEqual(body, { ...request, conversation_id: conversation }); + assert.equal(body.apply_choice.turn, chip.turn); + assert.equal(body.apply_choice.spec_id, chip.spec_id); +}); + +test('runApplyChoice: a 422 chip refusal reaches onRefusal, and no error frame', async (t) => { + const body = { + error: 'constraint_violation', + retry: 'do_not_retry', + detail: 'That option is not offered here.', + constraint_id: 'switch_option_unavailable', + pointer: '/apply_choice', + }; + + t.mock.method(globalThis, 'fetch', async () => Response.json(body, { status: 422 })); + const frames: StudioFrame[] = []; + const refusals: unknown[] = []; + + await runApplyChoice( + 'conv', + { choice_id: 'spec_1:sector', option_id: 'sector:120', turn: 1, spec_id: 'spec_1' }, + { + onFrame: (frame) => frames.push(frame), + onRefusal: (refusal) => { + refusals.push(refusal); + + return true; + }, + }, + ); + + assert.deepEqual(refusals, [{ status: 422, detail: body.detail, error: body }]); + assert.deepEqual(frames, []); +}); diff --git a/src/lib/studio/wire.ts b/src/lib/studio/wire.ts index 5ffd7a84..8c90c197 100644 --- a/src/lib/studio/wire.ts +++ b/src/lib/studio/wire.ts @@ -89,6 +89,12 @@ export type ToolError = { retry_after_seconds?: number | null; }; +/** The 409 `plan_revision_stale` body of POST /api/studio/interrupt: a + * ToolError plus `current_plan`, the `plan.proposed` frame of the plan now + * awaiting an answer, exactly as the stream sent it (`seq` included). Absent + * only for a pause stored before the harness kept cards. */ +export type PlanRevisionStaleError = ToolError & { current_plan?: PlanProposed | null }; + export type ComponentType = | 'stat_card' | 'line_chart' @@ -205,11 +211,23 @@ export type Seed = { operations: SeedOperation[]; }; +/** A clicked `ApplyChoiceSuggestion`, echoed whole: the scope choice of a + * stored reading, the option it moves to, the conversation turn whose answer + * offered the chip (`turn`, from 1) and the reading it switches (`spec_id`). */ +export type ApplyChoice = { + choice_id: string; + option_id: string; + turn: number; + spec_id: string; +}; + export type TurnRequest = { kind: 'turn.request'; schema_version: 1; conversation_id: string; - message: string; + /** Absent only beside `apply_choice`. The harness reads an absent + * message as "". */ + message?: string; surface?: 'studio' | 'download' | 'embed'; component_ref?: ComponentRef | null; /** The Search results a "… in Studio" action hands over, one per @@ -217,9 +235,17 @@ export type TurnRequest = { * planning and plans from those datasets and their operations. */ seed_spec?: Seed[] | null; auto_add?: boolean; + /** A clicked chip. The turn applies the option to the reading the + * answer used, with no search. It comes without `message`, `seed_spec` + * or `component_ref`. A chip that no longer applies is refused 422 + * `constraint_violation` with `pointer: "/apply_choice"` + * (`scope_choice_stale`, when a later turn has answered or a later + * reading holds the choice, or `switch_option_unavailable`) and a + * `detail` to show. */ + apply_choice?: ApplyChoice | null; }; -export type InterruptDecision = 'approve' | 'amend' | 'reject' | 'answer' | 'skip'; +export type InterruptDecision = 'approve' | 'amend' | 'reject' | 'switch' | 'answer' | 'skip'; export type InterruptResponse = { kind: 'interrupt.response'; @@ -234,6 +260,15 @@ export type InterruptResponse = { // One answer per question of an `elicitation.request`, keyed by the // frame's question ids exactly. Sent with `answer` only. answers?: Record; + // A plan's `switch`: the decision's `choice_id`, one of its options' + // `option_id`, and the `revision` of the plan the user saw. `approve` + // sends `plan_revision` alone. The harness refuses a stale revision with + // 409 `plan_revision_stale` (a `PlanRevisionStaleError`) and an option it + // did not offer, or offered as unavailable, with 422 + // `switch_option_unavailable`. + choice_id?: string; + option_id?: string; + plan_revision?: string; }; export type ElicitationAnswer = @@ -269,6 +304,17 @@ export type CancelRequest = { export type PlanStep = { id: string; label: string; description?: string | null }; +/** One way a scope decision can be counted. `partial` options cover only + * `years` (inclusive `[first, last]` ranges); `unavailable` ones say why in + * `reason`, reader copy written by the harness. */ +export type PlanDecisionOption = { + option_id: string; + label: string; + status: 'available' | 'partial' | 'unavailable'; + reason: string | null; + years: [number, number][] | null; +}; + export type PlanDecision = { id: string; question: string; @@ -276,6 +322,47 @@ export type PlanDecision = { reason: string; resolved_by: 'default' | 'user'; alternatives?: string[] | null; + // A scope decision the user can switch: the harness's ScopeChoice id, + // every option it offers, and the one the plan counts by now. A + // decision without `choice_id` is an ordinary planner decision. + choice_id?: string | null; + options?: PlanDecisionOption[] | null; + active_option_id?: string | null; +}; + +export type PlanAction = 'approve' | 'amend' | 'reject' | 'switch'; + +/** What a switch changed, one entry per scope decision it moved. */ +export type PlanMoved = { + choice_id: string; + from_label: string; + to_label: string; + reason: string; +}; + +/** One piece of evidence the plan needs, in words the harness composed. */ +export type PlanRequirement = { + id: string; + kind: string; + sentence: string; + decision_ids?: string[]; +}; + +/** One computed step of the plan, in words. */ +export type PlanOperation = { + id: string; + kind: string; + sentence: string; + requirement_id?: string | null; +}; + +/** One output the user asked for: the step ids that answer it, or why the + * plan does not compute it, or both when it answers in part. */ +export type PlanAsk = { + ask: string; + answered_by?: string[]; + declined?: string | null; + not_computed?: string | null; }; export type PlanProposed = { @@ -286,9 +373,19 @@ export type PlanProposed = { version: number; title: string; steps: PlanStep[]; - actions: ('approve' | 'amend' | 'reject')[]; + // `switch` is listed only when some decision has a `choice_id` with + // another available option. + actions: PlanAction[]; depth?: 'shallow' | 'standard' | 'deep' | null; decisions?: PlanDecision[] | null; + // The plan's approval key, a string distinct from the integer + // `version`. A `switch` echoes it as `plan_revision`. + revision?: string | null; + requirements?: PlanRequirement[] | null; + operations?: PlanOperation[] | null; + asks?: PlanAsk[] | null; + // Set on the plan a switch re-offers. + moved?: PlanMoved[] | null; }; export type StepProgress = { completed: number; total: number }; @@ -385,6 +482,22 @@ export type LegacyElicitationRequest = { rationale?: string | null; }; +/** A chip that sends `prompt` as the user's next message. */ +export type SuggestionItem = { label: string; prompt: string }; + +/** A chip that moves one scope choice of the answer's readings to another + * option. A click sends a turn with `apply_choice` and no message. `label` + * is the option's label, `turn` the conversation turn whose answer offers + * the chip, counted from 1, and `spec_id` the reading the chip switches. */ +export type ApplyChoiceSuggestion = { + kind: 'apply_choice'; + label: string; + choice_id: string; + option_id: string; + turn: number; + spec_id: string; +}; + export type StudioFrame = | { event: 'message.delta'; seq: number; text: string } | { event: 'message.complete'; seq: number; text: string } @@ -403,6 +516,6 @@ export type StudioFrame = | { event: 'composition.updated'; seq: number; manifest: CompositionManifest } | ElicitationRequest | LegacyElicitationRequest - | { event: 'suggestions'; seq: number; items: { label: string; prompt: string }[] } + | { event: 'suggestions'; seq: number; items: (SuggestionItem | ApplyChoiceSuggestion)[] } | { event: 'error'; seq: number; error: ToolError } | { event: 'done'; seq: number; trace_id: string; composition?: CompositionManifest | null };