From 7edab06e0b935dc61896e42f01efa79b85fc9745 Mon Sep 17 00:00:00 2001 From: Jorge Rivera Date: Mon, 26 Oct 2026 13:34:14 +0100 Subject: [PATCH 1/8] feat(studio): switch how a plan figure is counted from the plan card Decision rows that carry a scope choice list its options: the active one marked, available ones selectable, partial ones with their years and unavailable ones disabled with their reason. A pick sends a switch with the plan revision through the interrupt stream, keeps the card until the re-offered plan arrives, and shows what moved. A stale revision or an unavailable option leaves the card with a notice. The wire mirror gains the plan revision, requirements, operations and asks it lagged on. --- .../organisms/Studio/hooks/useChat.ts | 116 +++++--- .../organisms/Studio/workspace/ChatPanel.tsx | 6 +- .../Studio/workspace/PlanCard.module.scss | 6 + .../organisms/Studio/workspace/PlanCard.tsx | 11 +- .../Studio/workspace/PlanModal.module.scss | 83 ++++++ .../organisms/Studio/workspace/PlanModal.tsx | 113 +++++++- src/lib/studio/plan.ts | 141 ++++++++++ src/lib/studio/studioClient.ts | 31 ++- src/lib/studio/test/plan.test.ts | 262 ++++++++++++++++++ src/lib/studio/test/studioClient.test.ts | 72 ++++- src/lib/studio/wire.ts | 74 ++++- 11 files changed, 861 insertions(+), 54 deletions(-) create mode 100644 src/lib/studio/plan.ts create mode 100644 src/lib/studio/test/plan.test.ts diff --git a/src/components/organisms/Studio/hooks/useChat.ts b/src/components/organisms/Studio/hooks/useChat.ts index 0b147cb8..fd193091 100644 --- a/src/components/organisms/Studio/hooks/useChat.ts +++ b/src/components/organisms/Studio/hooks/useChat.ts @@ -30,6 +30,14 @@ import { } from '@/lib/studio/clarify'; import { restoreCanvas, takeManifest, type CanvasBaseline } from '@/lib/studio/composition'; import { plainTextFromNote } from '@/lib/studio/note'; +import { + planFromFrame, + refusedSwitch, + settledPlan, + startSwitch, + switchReply, + type PlanState, +} from '@/lib/studio/plan'; import { withAnswer } from '@/lib/studio/transcript'; import { cancelTurn, @@ -41,14 +49,7 @@ import { type StreamHandlers, } from '@/lib/studio/studioClient'; import { reviseWidget, widgetFromComponent } from '@/lib/studio/widgets'; -import type { - CompositionManifest, - MutationOperation, - PlanDecision, - PlanStep, - Seed, - StudioFrame, -} from '@/lib/studio/wire'; +import type { CompositionManifest, MutationOperation, Seed, StudioFrame } from '@/lib/studio/wire'; import { uuid } from '@/lib/uuid'; import type { CardRef, Widget } from '@/lib/chat/widgets'; @@ -64,16 +65,7 @@ export type ChatMessage = // 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 @@ -221,10 +213,12 @@ 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. + // 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 @@ -552,24 +546,17 @@ export const useChat = (initial?: ChatSnapshot) => { break; } - case 'plan.proposed': + case 'plan.proposed': { + // Also the answer to a switch: the fresh plan, with + // what moved, replaces the card it kept. + const plan = planFromFrame(frame); + 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, - }, - })); + pendingInterruptRef.current = { interruptId: frame.interrupt_id, plan }; + setState((prev) => ({ ...prev, ...NO_LINE, thinking: false, plan })); break; + } case 'plan.versioned': // Transient bookkeeping — the fresh plan.proposed that // follows re-renders the card. @@ -625,6 +612,7 @@ export const useChat = (initial?: ChatSnapshot) => { activity: endTurnActivity(prev.activity, turn, 'failed'), ...NO_LINE, thinking: false, + plan: settledPlan(prev.plan), }; }); break; @@ -641,6 +629,7 @@ export const useChat = (initial?: ChatSnapshot) => { activity: endTurnActivity(prev.activity, turn), ...NO_LINE, thinking: false, + plan: settledPlan(prev.plan), })); break; } @@ -673,6 +662,7 @@ export const useChat = (initial?: ChatSnapshot) => { activity: endTurnActivity(prev.activity, turn, 'skipped'), ...NO_LINE, thinking: false, + plan: settledPlan(prev.plan), }; }); }; @@ -706,6 +696,7 @@ export const useChat = (initial?: ChatSnapshot) => { activity: endTurnActivity(prev.activity, turn, 'failed'), ...NO_LINE, thinking: false, + plan: settledPlan(prev.plan), })); } } @@ -941,6 +932,62 @@ 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 leaves the pause as it was and the card says + // why: a stale revision (another switch got there first) or an option + // the harness no longer offers. + 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 || !reply) { + return; + } + + const label = plan?.decisions + .find((decision) => decision.choice_id === choiceId) + ?.options?.find((option) => option.option_id === optionId)?.label; + const generation = generationRef.current; + + 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, + onRefusal: (refusal) => { + if (generationRef.current === generation) { + pendingInterruptRef.current = pending; + setState((prev) => ({ + ...prev, + ...NO_LINE, + thinking: false, + plan: prev.plan && refusedSwitch(prev.plan, refusal), + })); + } + + return true; + }, + }, + signal, + ), + ); + }, + [stream], + ); + // 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. @@ -1050,6 +1097,7 @@ export const useChat = (initial?: ChatSnapshot) => { answerClarify, skipClarify, respondPlan, + switchChoice, stop, reset, hydrate, diff --git a/src/components/organisms/Studio/workspace/ChatPanel.tsx b/src/components/organisms/Studio/workspace/ChatPanel.tsx index 4642b75b..c02dc184 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; the text waits in the input. + if (!follow.trim() || chat.plan?.switching) { return; } @@ -210,6 +211,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..e83619ae 100644 --- a/src/components/organisms/Studio/workspace/PlanCard.module.scss +++ b/src/components/organisms/Studio/workspace/PlanCard.module.scss @@ -119,6 +119,12 @@ letter-spacing: -0.031em; } +// What the switch behind this plan changed, under the steps. +.moved { + margin: 0; + padding: 0 rem(16) rem(14); +} + // --- "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..fe8e3957 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 } 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,15 @@ const PlanCard = ({ plan, onApprove, onCancel }: PlanCardProps) => { ))} +

Start building?

- -
@@ -73,6 +75,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..2c89bb89 100644 --- a/src/components/organisms/Studio/workspace/PlanModal.module.scss +++ b/src/components/organisms/Studio/workspace/PlanModal.module.scss @@ -139,6 +139,89 @@ } } +// 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) { + background-color: var(--color-net-mid); + } + + &:disabled { + cursor: default; + } + + // Unavailable, or waiting on a switch in flight. + &:disabled: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; +} + // --- "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..e4463057 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,92 @@ 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. */ +export const PlanMovedNote = ({ plan, className }: { plan: PlanState; className?: string }) => + plan.moved.length > 0 ? ( +
    + {plan.moved.map((moved) => ( +
  • {movedSentence(moved)}
  • + ))} +
+ ) : null; + +/** + * 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. Every option waits while a switch is in + * flight. + */ +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 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 +186,29 @@ const PlanModal = ({ plan, open, onOpenChange, onApprove, onCancel }: PlanModalP {plan.decisions.length > 0 && (
      {plan.decisions.map((decision) => ( -
    • - {decision.question} — {decision.chosen} - {decision.reason ? ` (${decision.reason})` : ''} -
    • + ))}
    )} + + {plan.notice && ( +

    + {plan.notice} +

    + )}

    Start building?

    - -
    diff --git a/src/lib/studio/plan.ts b/src/lib/studio/plan.ts new file mode 100644 index 00000000..7d8a9f3a --- /dev/null +++ b/src/lib/studio/plan.ts @@ -0,0 +1,141 @@ +/** + * 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 sent against an older plan. */ +export const PLAN_REVISION_STALE = 'plan_revision_stale'; + +export const STALE_NOTICE = + 'The plan changed before your switch reached it. Check the plan and switch again.'; + +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, +}); + +/** The plan after the harness refused its switch: the card keeps the + * newest plan this page holds and says why. */ +export const refusedSwitch = (plan: PlanState, refusal: StreamRefusal): PlanState => ({ + ...plan, + switching: null, + notice: + refusal.error?.constraint_id === PLAN_REVISION_STALE + ? STALE_NOTICE + : (refusal.error?.detail ?? `The switch was refused (HTTP ${refusal.status}).`), +}); + +/** 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/studioClient.ts b/src/lib/studio/studioClient.ts index e39604ad..daf4f6a7 100644 --- a/src/lib/studio/studioClient.ts +++ b/src/lib/studio/studioClient.ts @@ -37,16 +37,31 @@ const transportError = (detail: string): StudioFrame => ({ } as ToolError, }); -/** What a stream reports to its caller. */ +/** An HTTP refusal of a stream request: its status and, when the body is + * one, the harness's ToolError. */ +export type StreamRefusal = { status: number; error: ToolError | 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): ToolError | 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; @@ -70,10 +85,13 @@ const streamStudio = async ( if (!res.ok || !res.body) { let detail = `HTTP ${res.status}`; + let error: ToolError | null = null; try { const parsed = (await res.json()) as { detail?: unknown }; + error = asToolError(parsed); + if (typeof parsed.detail === 'string') { detail = parsed.detail; } @@ -81,6 +99,10 @@ const streamStudio = async ( // Non-JSON body — the status line stands. } + if (!res.ok && onRefusal?.({ status: res.status, error })) { + return; + } + onFrame(transportError(detail)); return; @@ -162,7 +184,10 @@ export const runTurn = ( 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/plan.test.ts b/src/lib/studio/test/plan.test.ts new file mode 100644 index 00000000..dcf85f3e --- /dev/null +++ b/src/lib/studio/test/plan.test.ts @@ -0,0 +1,262 @@ +/** + * 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, + STALE_NOTICE, + isActiveOption, + isSelectable, + movedSentence, + planFromFrame, + refusedSwitch, + settledPlan, + startSwitch, + switchReply, + yearsText, +} from '../plan.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); +}); + +test('a stale revision keeps the card and asks the user to check the plan', () => { + const plan = startSwitch(planFromFrame(frame()), { + choiceId: 'spec_1:measure_basis', + optionId: 'measure_basis:net', + }); + const refused = refusedSwitch(plan, { + status: 409, + error: { + error: 'edit_conflict', + retry: 'refresh_then_retry', + detail: 'plan revision rev-a is not the pending plan', + constraint_id: PLAN_REVISION_STALE, + }, + }); + + assert.equal(refused.switching, null); + assert.equal(refused.notice, STALE_NOTICE); + assert.equal(refused.revision, 'rev-a'); + assert.notEqual(switchReply(refused, 'spec_1:measure_basis', 'measure_basis:net'), null); +}); + +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, + error: { + error: 'binding_invalid', + retry: 'correct_and_retry', + detail: 'Net disbursements are not published for 2020.', + constraint_id: 'switch_option_unavailable', + }, + }); + + assert.equal(refused.switching, null); + assert.equal(refused.notice, 'Net disbursements are not published for 2020.'); +}); + +test('a refusal without a ToolError body names the status', () => { + const refused = refusedSwitch(planFromFrame(frame()), { status: 502, error: null }); + + assert.equal(refused.notice, 'The switch was refused (HTTP 502).'); +}); + +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/studioClient.test.ts b/src/lib/studio/test/studioClient.test.ts index 6c87c4c7..ad3e2322 100644 --- a/src/lib/studio/test/studioClient.test.ts +++ b/src/lib/studio/test/studioClient.test.ts @@ -5,7 +5,8 @@ import assert from 'node:assert/strict'; import test from 'node:test'; -import { cancelTurn, fetchComponentRevision, runTurn } from '../studioClient.ts'; +import { cancelTurn, fetchComponentRevision, runInterrupt, runTurn } from '../studioClient.ts'; +import type { 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 +78,72 @@ 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, 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, error: null }]); + assert.equal(frames.length, 1); + assert.equal(frames[0]?.event === 'error' && frames[0].error.detail, 'proxy failed'); +}); diff --git a/src/lib/studio/wire.ts b/src/lib/studio/wire.ts index 5ffd7a84..bd83604e 100644 --- a/src/lib/studio/wire.ts +++ b/src/lib/studio/wire.ts @@ -219,7 +219,7 @@ export type TurnRequest = { auto_add?: boolean; }; -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 +234,14 @@ 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. Sent + // together with `switch` and never otherwise. The harness refuses a + // stale revision with 409 `plan_revision_stale` 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 +277,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 +295,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 +346,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 }; From 8f8ebb42d1d411488bfd2b4d2d05b9e8c7cb5747 Mon Sep 17 00:00:00 2001 From: Jorge Rivera Date: Mon, 26 Oct 2026 14:15:59 +0100 Subject: [PATCH 2/8] fix(studio): keep the switch control usable after a refusal A stale-revision refusal stops further switches on that card and says why; options in flight keep focus; the moved note and notice stay mounted so screen readers announce them; a plain detail body reaches the notice. --- .../Studio/workspace/PlanCard.module.scss | 4 ++ .../Studio/workspace/PlanModal.module.scss | 14 +++++-- .../organisms/Studio/workspace/PlanModal.tsx | 37 ++++++++++--------- src/lib/studio/plan.ts | 23 ++++++------ src/lib/studio/studioClient.ts | 12 +++--- src/lib/studio/test/plan.test.ts | 24 +++++++++--- src/lib/studio/test/studioClient.test.ts | 4 +- 7 files changed, 72 insertions(+), 46 deletions(-) diff --git a/src/components/organisms/Studio/workspace/PlanCard.module.scss b/src/components/organisms/Studio/workspace/PlanCard.module.scss index e83619ae..ea0abf9f 100644 --- a/src/components/organisms/Studio/workspace/PlanCard.module.scss +++ b/src/components/organisms/Studio/workspace/PlanCard.module.scss @@ -123,6 +123,10 @@ .moved { margin: 0; padding: 0 rem(16) rem(14); + + &:empty { + padding: 0; + } } // --- "Start building?" ------------------------------------------------------ diff --git a/src/components/organisms/Studio/workspace/PlanModal.module.scss b/src/components/organisms/Studio/workspace/PlanModal.module.scss index 2c89bb89..86e9bc7e 100644 --- a/src/components/organisms/Studio/workspace/PlanModal.module.scss +++ b/src/components/organisms/Studio/workspace/PlanModal.module.scss @@ -170,16 +170,17 @@ background-color 0.25s ease, opacity 0.25s ease; - &:hover:not(:disabled) { + &:hover:not(:disabled, [aria-disabled="true"]) { background-color: var(--color-net-mid); } - &:disabled { + &:disabled, + &[aria-disabled="true"] { cursor: default; } // Unavailable, or waiting on a switch in flight. - &:disabled:not(.optionActive, .optionPending) { + &:is(:disabled, [aria-disabled="true"]):not(.optionActive, .optionPending) { opacity: 0.55; } } @@ -222,6 +223,13 @@ list-style: none; } +// Both stay mounted as live regions; empty, they take no room. +.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 e4463057..c07dc4b2 100644 --- a/src/components/organisms/Studio/workspace/PlanModal.tsx +++ b/src/components/organisms/Studio/workspace/PlanModal.tsx @@ -32,22 +32,23 @@ type PlanModalProps = { }; /** What the switch that produced this plan changed, said once on the plan - * it re-offered. */ -export const PlanMovedNote = ({ plan, className }: { plan: PlanState; className?: string }) => - plan.moved.length > 0 ? ( -
      - {plan.moved.map((moved) => ( -
    • {movedSentence(moved)}
    • - ))} -
    - ) : null; + * 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)}
    • + ))} +
    +); /** * 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. Every option waits while a switch is in - * flight. + * 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, @@ -72,6 +73,7 @@ const DecisionRow = ({ 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 @@ -90,8 +92,9 @@ const DecisionRow = ({ )} aria-pressed={active} aria-busy={pending || undefined} - disabled={!isSelectable(decision, option) || !!plan.switching} - onClick={() => onSwitch?.(choiceId, option.option_id)} + aria-disabled={inert || undefined} + disabled={option.status === 'unavailable'} + onClick={() => !inert && onSwitch?.(choiceId, option.option_id)} > {option.label} {note && {note}} @@ -196,11 +199,9 @@ const PlanModal = ({ plan, open, onOpenChange, onApprove, onCancel, onSwitch }: )} - {plan.notice && ( -

    - {plan.notice} -

    - )} +

    + {plan.notice} +

    Start building?

    diff --git a/src/lib/studio/plan.ts b/src/lib/studio/plan.ts index 7d8a9f3a..50db1ef3 100644 --- a/src/lib/studio/plan.ts +++ b/src/lib/studio/plan.ts @@ -44,7 +44,7 @@ export type SwitchReply = Required< export const PLAN_REVISION_STALE = 'plan_revision_stale'; export const STALE_NOTICE = - 'The plan changed before your switch reached it. Check the plan and switch again.'; + '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, @@ -124,16 +124,17 @@ export const startSwitch = (plan: PlanState, pick: PlanSwitch): PlanState => ({ notice: null, }); -/** The plan after the harness refused its switch: the card keeps the - * newest plan this page holds and says why. */ -export const refusedSwitch = (plan: PlanState, refusal: StreamRefusal): PlanState => ({ - ...plan, - switching: null, - notice: - refusal.error?.constraint_id === PLAN_REVISION_STALE - ? STALE_NOTICE - : (refusal.error?.detail ?? `The switch was refused (HTTP ${refusal.status}).`), -}); +/** The plan after the harness refused its switch, saying why. A stale + * revision cannot be recovered from here (the refusal carries no newer + * plan), so that card drops its revision and offers no further switch. */ +export const refusedSwitch = (plan: PlanState, refusal: StreamRefusal): PlanState => + refusal.error?.constraint_id === PLAN_REVISION_STALE + ? { ...plan, revision: null, switching: null, notice: STALE_NOTICE } + : { + ...plan, + switching: null, + notice: refusal.detail ?? `The switch was refused (HTTP ${refusal.status}).`, + }; /** A plan whose switch ended without a fresh plan (an error, a stop, a turn * that finished) leaves the card; any other plan stays. */ diff --git a/src/lib/studio/studioClient.ts b/src/lib/studio/studioClient.ts index daf4f6a7..86eb3782 100644 --- a/src/lib/studio/studioClient.ts +++ b/src/lib/studio/studioClient.ts @@ -37,9 +37,9 @@ const transportError = (detail: string): StudioFrame => ({ } as ToolError, }); -/** An HTTP refusal of a stream request: its status and, when the body is - * one, the harness's ToolError. */ -export type StreamRefusal = { status: number; error: ToolError | null }; +/** 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. */ +export type StreamRefusal = { status: number; detail: string | null; error: ToolError | 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 @@ -84,7 +84,7 @@ const streamStudio = async ( } if (!res.ok || !res.body) { - let detail = `HTTP ${res.status}`; + let detail: string | null = null; let error: ToolError | null = null; try { @@ -99,11 +99,11 @@ const streamStudio = async ( // Non-JSON body — the status line stands. } - if (!res.ok && onRefusal?.({ status: res.status, error })) { + if (!res.ok && onRefusal?.({ status: res.status, detail, error })) { return; } - onFrame(transportError(detail)); + onFrame(transportError(detail ?? `HTTP ${res.status}`)); return; } diff --git a/src/lib/studio/test/plan.test.ts b/src/lib/studio/test/plan.test.ts index dcf85f3e..d5d69b61 100644 --- a/src/lib/studio/test/plan.test.ts +++ b/src/lib/studio/test/plan.test.ts @@ -7,6 +7,7 @@ import test from 'node:test'; import { PLAN_REVISION_STALE, + canSwitch, STALE_NOTICE, isActiveOption, isSelectable, @@ -167,13 +168,14 @@ test('without active_option_id the chosen label marks the active option', () => assert.equal(isActiveOption(decision, net!), false); }); -test('a stale revision keeps the card and asks the user to check the plan', () => { +test('a stale revision ends switching on the card and asks for a reload', () => { const plan = startSwitch(planFromFrame(frame()), { choiceId: 'spec_1:measure_basis', optionId: 'measure_basis:net', }); const refused = refusedSwitch(plan, { status: 409, + detail: 'plan revision rev-a is not the pending plan', error: { error: 'edit_conflict', retry: 'refresh_then_retry', @@ -184,8 +186,9 @@ test('a stale revision keeps the card and asks the user to check the plan', () = assert.equal(refused.switching, null); assert.equal(refused.notice, STALE_NOTICE); - assert.equal(refused.revision, 'rev-a'); - assert.notEqual(switchReply(refused, 'spec_1:measure_basis', 'measure_basis:net'), null); + assert.equal(refused.revision, null); + assert.equal(canSwitch(refused), false); + assert.equal(switchReply(refused, 'spec_1:measure_basis', 'measure_basis:net'), null); }); test('an unavailable option keeps the card and shows the harness reason', () => { @@ -195,6 +198,7 @@ test('an unavailable option keeps the card and shows the harness reason', () => }); const refused = refusedSwitch(plan, { status: 422, + detail: 'Net disbursements are not published for 2020.', error: { error: 'binding_invalid', retry: 'correct_and_retry', @@ -205,12 +209,20 @@ test('an unavailable option keeps the card and shows the harness reason', () => assert.equal(refused.switching, null); assert.equal(refused.notice, 'Net disbursements are not published for 2020.'); + assert.equal(refused.revision, 'rev-a'); }); -test('a refusal without a ToolError body names the status', () => { - const refused = refusedSwitch(planFromFrame(frame()), { status: 502, error: null }); +test('a plain detail body is the notice; without one the status is named', () => { + const plan = planFromFrame(frame()); - assert.equal(refused.notice, 'The switch was refused (HTTP 502).'); + assert.equal( + refusedSwitch(plan, { status: 401, detail: 'Sign in again.', error: null }).notice, + 'Sign in again.', + ); + assert.equal( + refusedSwitch(plan, { status: 502, detail: null, error: null }).notice, + 'The switch was refused (HTTP 502).', + ); }); test('a fresh plan after a switch replaces the waiting card with what moved', () => { diff --git a/src/lib/studio/test/studioClient.test.ts b/src/lib/studio/test/studioClient.test.ts index ad3e2322..2a07a1d6 100644 --- a/src/lib/studio/test/studioClient.test.ts +++ b/src/lib/studio/test/studioClient.test.ts @@ -123,7 +123,7 @@ test('runInterrupt: a refusal reaches onRefusal with its status and ToolError, a }, }); - assert.deepEqual(refusals, [{ status: 409, error: staleBody }]); + assert.deepEqual(refusals, [{ status: 409, detail: staleBody.detail, error: staleBody }]); assert.deepEqual(frames, []); }); @@ -143,7 +143,7 @@ test('runInterrupt: a refusal onRefusal leaves is an error frame with its detail }, }); - assert.deepEqual(refusals, [{ status: 502, error: null }]); + 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'); }); From c9bfe17b153493deecd36222d050af242483ef9c Mon Sep 17 00:00:00 2001 From: Jorge Rivera Date: Mon, 26 Oct 2026 14:48:16 +0100 Subject: [PATCH 3/8] fix(studio): replace a stale plan card with the one the harness holds A switch or approve refused as plan_revision_stale now takes the current_plan the harness returns and shows it with the refusal's detail, so switching and approving continue on the plan actually pending. Approve sends the plan revision the user saw. --- .../organisms/Studio/hooks/useChat.ts | 80 +++++++++++++------ src/lib/studio/plan.ts | 53 +++++++++--- src/lib/studio/studioClient.ts | 14 +++- src/lib/studio/test/plan.test.ts | 64 ++++++++++++++- src/lib/studio/test/studioClient.test.ts | 35 ++++++++ src/lib/studio/wire.ts | 15 +++- 6 files changed, 215 insertions(+), 46 deletions(-) diff --git a/src/components/organisms/Studio/hooks/useChat.ts b/src/components/organisms/Studio/hooks/useChat.ts index fd193091..de09c2f9 100644 --- a/src/components/organisms/Studio/hooks/useChat.ts +++ b/src/components/organisms/Studio/hooks/useChat.ts @@ -31,8 +31,10 @@ import { import { restoreCanvas, takeManifest, type CanvasBaseline } from '@/lib/studio/composition'; import { plainTextFromNote } from '@/lib/studio/note'; import { + approveReply, planFromFrame, refusedSwitch, + stalePlan, settledPlan, startSwitch, switchReply, @@ -47,9 +49,16 @@ import { runTurn, STOP_GRACE_MS, type StreamHandlers, + type StreamRefusal, } from '@/lib/studio/studioClient'; import { reviseWidget, widgetFromComponent } from '@/lib/studio/widgets'; -import type { CompositionManifest, MutationOperation, Seed, StudioFrame } from '@/lib/studio/wire'; +import type { + CompositionManifest, + InterruptResponse, + MutationOperation, + Seed, + StudioFrame, +} from '@/lib/studio/wire'; import { uuid } from '@/lib/uuid'; import type { CardRef, Widget } from '@/lib/chat/widgets'; @@ -317,6 +326,12 @@ export const useChat = (initial?: ChatSnapshot) => { }, [syncCanvas], ); + // Put a plan card up as the pending pause: 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) => ({ @@ -546,17 +561,13 @@ export const useChat = (initial?: ChatSnapshot) => { break; } - case 'plan.proposed': { + case 'plan.proposed': // Also the answer to a switch: the fresh plan, with // what moved, replaces the card it kept. - const plan = planFromFrame(frame); - stall.stop(); grace.cancel(); - pendingInterruptRef.current = { interruptId: frame.interrupt_id, plan }; - setState((prev) => ({ ...prev, ...NO_LINE, thinking: false, plan })); + offerPlan(planFromFrame(frame)); break; - } case 'plan.versioned': // Transient bookkeeping — the fresh plan.proposed that // follows re-renders the card. @@ -728,7 +739,7 @@ export const useChat = (initial?: ChatSnapshot) => { } }); }, - [applyManifest, patchWidget], + [applyManifest, offerPlan, patchWidget], ); const send = useCallback( @@ -846,10 +857,17 @@ 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; + const generation = generationRef.current; pendingInterruptRef.current = null; @@ -868,11 +886,27 @@ export const useChat = (initial?: ChatSnapshot) => { return; } + const onRefusal = (refusal: StreamRefusal) => { + const current = stalePlan(refusal); + + if (current && generationRef.current === generation) { + offerPlan(current); + } + + return current !== null; + }; + stream(turnCount.current, (handlers, signal) => - runInterrupt(conversation, pending.interruptId, reply, handlers, signal), + runInterrupt( + conversation, + pending.interruptId, + reply, + { ...handlers, onRefusal }, + signal, + ), ); }, - [stream], + [offerPlan, stream], ); // Answer every question of the pending clarify at once, keyed by @@ -924,7 +958,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, ); @@ -934,9 +970,9 @@ export const useChat = (initial?: ChatSnapshot) => { // 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 leaves the pause as it was and the card says - // why: a stale revision (another switch got there first) or an option - // the harness no longer offers. + // 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 instead. const switchChoice = useCallback( (choiceId: string, optionId: string) => { const conversation = sessionRef.current; @@ -944,11 +980,11 @@ export const useChat = (initial?: ChatSnapshot) => { const plan = pending?.plan; const reply = plan ? switchReply(plan, choiceId, optionId) : null; - if (!conversation || !pending || !reply) { + if (!conversation || !pending || !plan || !reply) { return; } - const label = plan?.decisions + const label = plan.decisions .find((decision) => decision.choice_id === choiceId) ?.options?.find((option) => option.option_id === optionId)?.label; const generation = generationRef.current; @@ -969,13 +1005,7 @@ export const useChat = (initial?: ChatSnapshot) => { ...handlers, onRefusal: (refusal) => { if (generationRef.current === generation) { - pendingInterruptRef.current = pending; - setState((prev) => ({ - ...prev, - ...NO_LINE, - thinking: false, - plan: prev.plan && refusedSwitch(prev.plan, refusal), - })); + offerPlan(refusedSwitch(plan, refusal)); } return true; @@ -985,7 +1015,7 @@ export const useChat = (initial?: ChatSnapshot) => { ), ); }, - [stream], + [offerPlan, stream], ); // The Stop control: ask the harness to cancel and end the running turn diff --git a/src/lib/studio/plan.ts b/src/lib/studio/plan.ts index 50db1ef3..247ae7a0 100644 --- a/src/lib/studio/plan.ts +++ b/src/lib/studio/plan.ts @@ -40,9 +40,12 @@ export type SwitchReply = Required< Pick >; -/** The ToolError `constraint_id` of a switch sent against an older plan. */ +/** 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.'; @@ -124,17 +127,43 @@ export const startSwitch = (plan: PlanState, pick: PlanSwitch): PlanState => ({ notice: null, }); -/** The plan after the harness refused its switch, saying why. A stale - * revision cannot be recovered from here (the refusal carries no newer - * plan), so that card drops its revision and offers no further switch. */ -export const refusedSwitch = (plan: PlanState, refusal: StreamRefusal): PlanState => - refusal.error?.constraint_id === PLAN_REVISION_STALE - ? { ...plan, revision: null, switching: null, notice: STALE_NOTICE } - : { - ...plan, - switching: null, - notice: refusal.detail ?? `The switch was refused (HTTP ${refusal.status}).`, - }; +const isStale = (refusal: StreamRefusal): boolean => + refusal.error?.constraint_id === PLAN_REVISION_STALE; + +/** 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. A stale + * revision brings the current plan, and switching works again on it; + * without one the card drops its revision and offers no further switch. */ +export const refusedSwitch = (plan: PlanState, refusal: StreamRefusal): PlanState => { + if (isStale(refusal)) { + return ( + stalePlan(refusal) ?? { ...plan, revision: null, switching: null, notice: STALE_NOTICE } + ); + } + + return { + ...plan, + switching: null, + notice: refusal.detail ?? `The switch was refused (HTTP ${refusal.status}).`, + }; +}; + +/** 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. */ diff --git a/src/lib/studio/studioClient.ts b/src/lib/studio/studioClient.ts index 86eb3782..bd1d019b 100644 --- a/src/lib/studio/studioClient.ts +++ b/src/lib/studio/studioClient.ts @@ -15,6 +15,7 @@ import type { CompositionMutation, InterruptResponse, MutationOperation, + PlanRevisionStaleError, StudioFrame, ToolError, TurnRequest, @@ -38,8 +39,13 @@ const transportError = (detail: string): StudioFrame => ({ }); /** 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. */ -export type StreamRefusal = { status: number; detail: string | null; error: ToolError | null }; + * 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 @@ -50,7 +56,7 @@ export type StreamHandlers = { onRefusal?: (refusal: StreamRefusal) => boolean; }; -const asToolError = (body: unknown): ToolError | null => +const asToolError = (body: unknown): PlanRevisionStaleError | null => body !== null && typeof body === 'object' && typeof (body as ToolError).error === 'string' && @@ -85,7 +91,7 @@ const streamStudio = async ( if (!res.ok || !res.body) { let detail: string | null = null; - let error: ToolError | null = null; + let error: PlanRevisionStaleError | null = null; try { const parsed = (await res.json()) as { detail?: unknown }; diff --git a/src/lib/studio/test/plan.test.ts b/src/lib/studio/test/plan.test.ts index d5d69b61..983e15a6 100644 --- a/src/lib/studio/test/plan.test.ts +++ b/src/lib/studio/test/plan.test.ts @@ -7,6 +7,7 @@ import test from 'node:test'; import { PLAN_REVISION_STALE, + approveReply, canSwitch, STALE_NOTICE, isActiveOption, @@ -15,10 +16,12 @@ import { 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 = { @@ -168,7 +171,66 @@ test('without active_option_id the chosen label marks the active option', () => assert.equal(isActiveOption(decision, net!), false); }); -test('a stale revision ends switching on the card and asks for a reload', () => { +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 ends switching and asks for a reload', () => { const plan = startSwitch(planFromFrame(frame()), { choiceId: 'spec_1:measure_basis', optionId: 'measure_basis:net', diff --git a/src/lib/studio/test/studioClient.test.ts b/src/lib/studio/test/studioClient.test.ts index 2a07a1d6..ec6a839b 100644 --- a/src/lib/studio/test/studioClient.test.ts +++ b/src/lib/studio/test/studioClient.test.ts @@ -147,3 +147,38 @@ test('runInterrupt: a refusal onRefusal leaves is an error frame with its detail 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); +}); diff --git a/src/lib/studio/wire.ts b/src/lib/studio/wire.ts index bd83604e..633d02e4 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' @@ -235,10 +241,11 @@ export type InterruptResponse = { // 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. Sent - // together with `switch` and never otherwise. The harness refuses a - // stale revision with 409 `plan_revision_stale` and an option it did not - // offer, or offered as unavailable, with 422 `switch_option_unavailable`. + // `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; From d31e0eb82456974a7af2853d2d6fc76040ee2147 Mon Sep 17 00:00:00 2001 From: Jorge Rivera Date: Mon, 26 Oct 2026 16:50:59 +0100 Subject: [PATCH 4/8] feat(studio): render reading chips after an answer and switch on a click Studio shows the harness's apply_choice chips beside the follow-up prompts on the latest answer. A click sends a turn carrying the chosen option and no message, shows the chip label as the user's side, and streams the answer like any turn; a refused chip shows the reason and is removed. --- .../organisms/Studio/hooks/useChat.ts | 89 ++++++++++++++++++- .../Studio/workspace/ChatMessage.tsx | 25 +++++- .../Studio/workspace/ChatPanel.module.scss | 6 ++ .../organisms/Studio/workspace/ChatPanel.tsx | 1 + src/lib/studio/chips.ts | 74 +++++++++++++++ src/lib/studio/studioClient.ts | 21 +++++ src/lib/studio/test/chips.test.ts | 88 ++++++++++++++++++ .../event-15-suggestions-apply-choice.json | 18 ++++ .../request-13-turn-apply-choice.json | 9 ++ src/lib/studio/test/studioClient.test.ts | 68 +++++++++++++- src/lib/studio/wire.ts | 30 ++++++- 11 files changed, 417 insertions(+), 12 deletions(-) create mode 100644 src/lib/studio/chips.ts create mode 100644 src/lib/studio/test/chips.test.ts create mode 100644 src/lib/studio/test/fixtures/event-15-suggestions-apply-choice.json create mode 100644 src/lib/studio/test/fixtures/request-13-turn-apply-choice.json diff --git a/src/components/organisms/Studio/hooks/useChat.ts b/src/components/organisms/Studio/hooks/useChat.ts index de09c2f9..67bfedb0 100644 --- a/src/components/organisms/Studio/hooks/useChat.ts +++ b/src/components/organisms/Studio/hooks/useChat.ts @@ -19,6 +19,7 @@ import { WORKING, } from '@/lib/studio/chatLine'; import { createCanvasEdits } from '@/lib/studio/canvasEdits'; +import { chipRefusalDetail, splitSuggestions, withRefusedChip } from '@/lib/studio/chips'; import { clarifyAnswer, clarifyFromFrame, @@ -45,6 +46,7 @@ import { cancelTurn, fetchComponentRevision, mutateComposition, + runApplyChoice, runInterrupt, runTurn, STOP_GRACE_MS, @@ -53,6 +55,7 @@ import { } from '@/lib/studio/studioClient'; import { reviseWidget, widgetFromComponent } from '@/lib/studio/widgets'; import type { + ApplyChoiceSuggestion, CompositionManifest, InterruptResponse, MutationOperation, @@ -66,9 +69,11 @@ 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; +// 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. @@ -589,15 +594,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. @@ -1018,6 +1027,77 @@ export const useChat = (initial?: ChatSnapshot) => { [offerPlan, stream], ); + // A clicked `apply_choice` chip: a turn with the chip's choice and no + // message, which the transcript shows as the chip's label. Chips show + // only on the latest answer, so nothing is in flight or paused. 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 (inFlightRef.current > 0) { + return; + } + + if (!sessionRef.current) { + sessionRef.current = uuid(); + } + + turnCount.current += 1; + const turn = turnCount.current; + const conversation = sessionRef.current; + const generation = generationRef.current; + + pendingInterruptRef.current = null; + editingRef.current = null; + setState((prev) => ({ + ...withLine(prev, `Switching to ${chip.label}`), + messages: [ + ...prev.messages, + { role: 'user', text: chip.label }, + { role: 'bot', text: '' }, + ], + activity: [ + ...prev.activity, + { turn, prompt: chip.label, startedAt: Date.now(), tools: [] }, + ], + thinking: true, + clarify: null, + plan: null, + })); + + stream(turn, (handlers, signal) => + runApplyChoice( + conversation, + chip, + { + ...handlers, + onRefusal: (refusal) => { + const detail = chipRefusalDetail(refusal); + + if (detail === null) { + return false; + } + + if (generationRef.current === generation) { + setState((prev) => ({ + ...prev, + messages: withRefusedChip(prev.messages, chip, detail), + activity: endTurnActivity(prev.activity, turn, 'failed'), + ...NO_LINE, + thinking: false, + })); + } + + return true; + }, + }, + signal, + ), + ); + }, + [stream], + ); + // 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. @@ -1128,6 +1208,7 @@ export const useChat = (initial?: ChatSnapshot) => { 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..2aa53851 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,7 @@ import MessageFeedback from './MessageFeedback'; import WidgetChips from './WidgetChips'; import type { ChatMessage as ChatMessageData, TurnWidget } from '../hooks/useChat'; import type { CardView } from '../canvas/layout'; +import type { ApplyChoiceSuggestion } from '@/lib/studio/wire'; type ChatMessageProps = { message: ChatMessageData; @@ -24,6 +26,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 +34,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 +48,7 @@ const ChatMessage = ({ onAdd, onRemove, onFollowup, + onApplyChoice, readOnly, }: ChatMessageProps) => { if (message.role === 'user') { @@ -61,7 +65,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 +96,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..13b97d91 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: 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 c02dc184..006871d6 100644 --- a/src/components/organisms/Studio/workspace/ChatPanel.tsx +++ b/src/components/organisms/Studio/workspace/ChatPanel.tsx @@ -150,6 +150,7 @@ const ChatPanel = ({ onAdd={onAdd} onRemove={onRemove} onFollowup={chat.send} + onApplyChoice={chat.applyChoice} readOnly={readOnly} /> {sharedAfter(index) && ( diff --git a/src/lib/studio/chips.ts b/src/lib/studio/chips.ts new file mode 100644 index 00000000..006ffb84 --- /dev/null +++ b/src/lib/studio/chips.ts @@ -0,0 +1,74 @@ +/** + * 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. */ +export const splitSuggestions = ( + items: SuggestionItems, +): { followups: string[]; chips: ApplyChoiceSuggestion[] } => { + const followups: string[] = []; + const chips: ApplyChoiceSuggestion[] = []; + + for (const item of items) { + if ('kind' in item) { + chips.push(item); + } else { + followups.push(item.prompt); + } + } + + return { followups, chips }; +}; + +const sameChip = (a: ApplyChoiceSuggestion, b: ApplyChoiceSuggestion): boolean => + a.choice_id === b.choice_id && a.option_id === b.option_id; + +/** 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/studioClient.ts b/src/lib/studio/studioClient.ts index bd1d019b..db6c79b6 100644 --- a/src/lib/studio/studioClient.ts +++ b/src/lib/studio/studioClient.ts @@ -10,6 +10,7 @@ */ import type { + ApplyChoice, CancelRequest, CompositionManifest, CompositionMutation, @@ -186,6 +187,26 @@ export const runTurn = ( signal, ); +/** Run a turn from a clicked `apply_choice` chip: the chip's choice and + * option, and no message. */ +export const runApplyChoice = ( + conversationId: string, + { choice_id, option_id }: ApplyChoice, + handlers: StreamHandlers, + signal?: AbortSignal, +): Promise => + streamStudio( + 'turn', + { + kind: 'turn.request', + schema_version: 1, + conversation_id: conversationId, + apply_choice: { choice_id, option_id }, + }, + handlers, + signal, + ); + /** Answer a pause; the response is a NEW stream continuing the same turn. */ export const runInterrupt = ( conversationId: string, diff --git a/src/lib/studio/test/chips.test.ts b/src/lib/studio/test/chips.test.ts new file mode 100644 index 00000000..113a7527 --- /dev/null +++ b/src/lib/studio/test/chips.test.ts @@ -0,0 +1,88 @@ +/** + * 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 { chipRefusalDetail, splitSuggestions, 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: 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, + }); +}); + +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._', + }); +}); 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..9c4b5a74 --- /dev/null +++ b/src/lib/studio/test/fixtures/event-15-suggestions-apply-choice.json @@ -0,0 +1,18 @@ +{ + "event": "suggestions", + "seq": 9, + "items": [ + { + "kind": "apply_choice", + "label": "health, CRS 120 alone", + "choice_id": "spec_6176d83382fca6c596e00cb242a06803:sector", + "option_id": "sector:120" + }, + { + "kind": "apply_choice", + "label": "Africa's countries only", + "choice_id": "spec_6176d83382fca6c596e00cb242a06803:region", + "option_id": "region:members_only" + } + ] +} 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..c725e52b --- /dev/null +++ b/src/lib/studio/test/fixtures/request-13-turn-apply-choice.json @@ -0,0 +1,9 @@ +{ + "kind": "turn.request", + "schema_version": 1, + "session_id": "sess_01j9zc0000", + "apply_choice": { + "choice_id": "spec_6176d83382fca6c596e00cb242a06803:sector", + "option_id": "sector:120" + } +} diff --git a/src/lib/studio/test/studioClient.test.ts b/src/lib/studio/test/studioClient.test.ts index ec6a839b..91febf22 100644 --- a/src/lib/studio/test/studioClient.test.ts +++ b/src/lib/studio/test/studioClient.test.ts @@ -3,10 +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, runInterrupt, runTurn } from '../studioClient.ts'; -import type { StudioFrame } from '../wire.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 })); @@ -182,3 +189,60 @@ test('runInterrupt: a stale refusal hands onRefusal the current plan as sent', a 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'); + assert.deepEqual(JSON.parse(init.body as string), { + ...request, + conversation_id: conversation, + }); +}); + +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' }, + { + 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 633d02e4..33f8a8a5 100644 --- a/src/lib/studio/wire.ts +++ b/src/lib/studio/wire.ts @@ -211,11 +211,17 @@ export type Seed = { operations: SeedOperation[]; }; +/** A clicked `ApplyChoiceSuggestion`: the scope choice of a stored reading + * and the option it moves to. */ +export type ApplyChoice = { choice_id: string; option_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 @@ -223,6 +229,13 @@ 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` or `switch_option_unavailable`) and a `detail` + * to show. */ + apply_choice?: ApplyChoice | null; }; export type InterruptDecision = 'approve' | 'amend' | 'reject' | 'switch' | 'answer' | 'skip'; @@ -462,6 +475,19 @@ 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. */ +export type ApplyChoiceSuggestion = { + kind: 'apply_choice'; + label: string; + choice_id: string; + option_id: string; +}; + export type StudioFrame = | { event: 'message.delta'; seq: number; text: string } | { event: 'message.complete'; seq: number; text: string } @@ -480,6 +506,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 }; From 855a66c6c0f56af34467326c4f61ca0b8c3db886 Mon Sep 17 00:00:00 2001 From: Jorge Rivera Date: Mon, 26 Oct 2026 18:51:07 +0100 Subject: [PATCH 5/8] docs(studio): tidy the plan switch and chip comments --- .../organisms/Studio/hooks/useChat.ts | 20 +++++++++---------- .../Studio/workspace/ChatPanel.module.scss | 2 +- .../organisms/Studio/workspace/ChatPanel.tsx | 2 +- .../Studio/workspace/PlanModal.module.scss | 2 +- .../organisms/Studio/workspace/PlanModal.tsx | 2 +- src/lib/studio/plan.ts | 12 +++++------ src/lib/studio/wire.ts | 4 ++-- 7 files changed, 22 insertions(+), 22 deletions(-) diff --git a/src/components/organisms/Studio/hooks/useChat.ts b/src/components/organisms/Studio/hooks/useChat.ts index 67bfedb0..dd13584f 100644 --- a/src/components/organisms/Studio/hooks/useChat.ts +++ b/src/components/organisms/Studio/hooks/useChat.ts @@ -69,8 +69,8 @@ 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; -// its `chips` switch a scope choice of the answer's readings. +// 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[]; chips?: ApplyChoiceSuggestion[] }; @@ -227,8 +227,8 @@ 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. + // 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; @@ -331,8 +331,8 @@ export const useChat = (initial?: ChatSnapshot) => { }, [syncCanvas], ); - // Put a plan card up as the pending pause: from the stream, or from a - // refusal that answered a stale card with the current one. + // 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 })); @@ -567,7 +567,7 @@ export const useChat = (initial?: ChatSnapshot) => { break; } case 'plan.proposed': - // Also the answer to a switch: the fresh plan, with + // Also the answer to a switch, whose fresh plan, with // what moved, replaces the card it kept. stall.stop(); grace.cancel(); @@ -979,9 +979,9 @@ export const useChat = (initial?: ChatSnapshot) => { // 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 + // 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 instead. + // card. const switchChoice = useCallback( (choiceId: string, optionId: string) => { const conversation = sessionRef.current; @@ -1027,7 +1027,7 @@ export const useChat = (initial?: ChatSnapshot) => { [offerPlan, stream], ); - // A clicked `apply_choice` chip: a turn with the chip's choice and no + // 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. Chips show // only on the latest answer, so nothing is in flight or paused. A chip // the harness refuses (the answer moved on, or Search cannot serve the diff --git a/src/components/organisms/Studio/workspace/ChatPanel.module.scss b/src/components/organisms/Studio/workspace/ChatPanel.module.scss index 13b97d91..1e3c2645 100644 --- a/src/components/organisms/Studio/workspace/ChatPanel.module.scss +++ b/src/components/organisms/Studio/workspace/ChatPanel.module.scss @@ -247,7 +247,7 @@ } } -// A chip that switches the answer's reading: the follow-up chip, dashed, so +// 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; diff --git a/src/components/organisms/Studio/workspace/ChatPanel.tsx b/src/components/organisms/Studio/workspace/ChatPanel.tsx index 006871d6..e90bffa9 100644 --- a/src/components/organisms/Studio/workspace/ChatPanel.tsx +++ b/src/components/organisms/Studio/workspace/ChatPanel.tsx @@ -87,7 +87,7 @@ const ChatPanel = ({ }, [chat.messages, chat.queued, chat.status, chat.statusDetail, follow]); const sendFollow = () => { - // A plan switch in flight has the pause; the text waits in the input. + // A plan switch in flight has the pause, so the text waits in the input. if (!follow.trim() || chat.plan?.switching) { return; } diff --git a/src/components/organisms/Studio/workspace/PlanModal.module.scss b/src/components/organisms/Studio/workspace/PlanModal.module.scss index 86e9bc7e..0b162666 100644 --- a/src/components/organisms/Studio/workspace/PlanModal.module.scss +++ b/src/components/organisms/Studio/workspace/PlanModal.module.scss @@ -223,7 +223,7 @@ list-style: none; } -// Both stay mounted as live regions; empty, they take no room. +// Both stay mounted as live regions and take no room when empty. .moved:empty, .notice:empty { margin: 0; diff --git a/src/components/organisms/Studio/workspace/PlanModal.tsx b/src/components/organisms/Studio/workspace/PlanModal.tsx index c07dc4b2..b6593de3 100644 --- a/src/components/organisms/Studio/workspace/PlanModal.tsx +++ b/src/components/organisms/Studio/workspace/PlanModal.tsx @@ -47,7 +47,7 @@ export const PlanMovedNote = ({ plan, className }: { plan: PlanState; className? * 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 + * ignores clicks but keeps focus (`aria-disabled`). Only unavailable ones * are natively disabled. */ const DecisionRow = ({ diff --git a/src/lib/studio/plan.ts b/src/lib/studio/plan.ts index 247ae7a0..23d36d14 100644 --- a/src/lib/studio/plan.ts +++ b/src/lib/studio/plan.ts @@ -27,9 +27,9 @@ export type PlanState = { version: number; actions: PlanAction[]; interruptId: string; - // The approval key a switch echoes; null from a harness that predates it. + // 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. + // 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. @@ -130,7 +130,7 @@ export const startSwitch = (plan: PlanState, pick: PlanSwitch): PlanState => ({ const isStale = (refusal: StreamRefusal): boolean => refusal.error?.constraint_id === PLAN_REVISION_STALE; -/** The card a stale switch or approve is answered with: the harness's +/** 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 => { @@ -140,8 +140,8 @@ export const stalePlan = (refusal: StreamRefusal): PlanState | null => { }; /** The card after the harness refused its switch, saying why. A stale - * revision brings the current plan, and switching works again on it; - * without one the card drops its revision and offers no further switch. */ + * revision brings the current plan, and switching works again on it. + * Without one the card drops its revision and offers no further switch. */ export const refusedSwitch = (plan: PlanState, refusal: StreamRefusal): PlanState => { if (isStale(refusal)) { return ( @@ -166,6 +166,6 @@ export const approveReply = ( : { 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. */ + * 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/wire.ts b/src/lib/studio/wire.ts index 33f8a8a5..a2b3bcbe 100644 --- a/src/lib/studio/wire.ts +++ b/src/lib/studio/wire.ts @@ -219,7 +219,7 @@ export type TurnRequest = { kind: 'turn.request'; schema_version: 1; conversation_id: string; - /** Absent only beside `apply_choice`; the harness reads an absent + /** Absent only beside `apply_choice`. The harness reads an absent * message as "". */ message?: string; surface?: 'studio' | 'download' | 'embed'; @@ -479,7 +479,7 @@ export type LegacyElicitationRequest = { 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` + * option. A click sends a turn with `apply_choice` and no message. `label` * is the option's label. */ export type ApplyChoiceSuggestion = { kind: 'apply_choice'; From ce1b9e5ba7790bb0c6256b5aadc1ef272b0f3ee7 Mon Sep 17 00:00:00 2001 From: Jorge Rivera Date: Tue, 27 Oct 2026 08:48:52 +0100 Subject: [PATCH 6/8] feat(studio): send the turn and reading a chip was offered for A chip carries the turn whose answer offered it and the spec_id of the reading it switches, and the click sends both in apply_choice, so the harness can refuse a chip whose answer or reading is no longer current. --- src/lib/studio/studioClient.ts | 8 +++---- src/lib/studio/test/chips.test.ts | 13 +++++++++++ .../event-15-suggestions-apply-choice.json | 8 +++++-- .../request-13-turn-apply-choice.json | 4 +++- src/lib/studio/test/studioClient.test.ts | 11 +++++----- src/lib/studio/wire.ts | 22 ++++++++++++++----- 6 files changed, 48 insertions(+), 18 deletions(-) diff --git a/src/lib/studio/studioClient.ts b/src/lib/studio/studioClient.ts index db6c79b6..549d43de 100644 --- a/src/lib/studio/studioClient.ts +++ b/src/lib/studio/studioClient.ts @@ -187,11 +187,11 @@ export const runTurn = ( signal, ); -/** Run a turn from a clicked `apply_choice` chip: the chip's choice and - * option, and no message. */ +/** 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 }: ApplyChoice, + { choice_id, option_id, turn, spec_id }: ApplyChoice, handlers: StreamHandlers, signal?: AbortSignal, ): Promise => @@ -201,7 +201,7 @@ export const runApplyChoice = ( kind: 'turn.request', schema_version: 1, conversation_id: conversationId, - apply_choice: { choice_id, option_id }, + apply_choice: { choice_id, option_id, turn, spec_id }, }, handlers, signal, diff --git a/src/lib/studio/test/chips.test.ts b/src/lib/studio/test/chips.test.ts index 113a7527..bde2c5a9 100644 --- a/src/lib/studio/test/chips.test.ts +++ b/src/lib/studio/test/chips.test.ts @@ -28,6 +28,19 @@ test('splitSuggestions: the fixture frame is two chips in frame order, no follow 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' }; 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 index 9c4b5a74..11dacc19 100644 --- a/src/lib/studio/test/fixtures/event-15-suggestions-apply-choice.json +++ b/src/lib/studio/test/fixtures/event-15-suggestions-apply-choice.json @@ -6,13 +6,17 @@ "kind": "apply_choice", "label": "health, CRS 120 alone", "choice_id": "spec_6176d83382fca6c596e00cb242a06803:sector", - "option_id": "sector:120" + "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" + "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 index c725e52b..90244280 100644 --- a/src/lib/studio/test/fixtures/request-13-turn-apply-choice.json +++ b/src/lib/studio/test/fixtures/request-13-turn-apply-choice.json @@ -4,6 +4,8 @@ "session_id": "sess_01j9zc0000", "apply_choice": { "choice_id": "spec_6176d83382fca6c596e00cb242a06803:sector", - "option_id": "sector:120" + "option_id": "sector:120", + "turn": 2, + "spec_id": "spec_0b7d6c7e1f2a4b5c8d9e0f1a2b3c4d5e" } } diff --git a/src/lib/studio/test/studioClient.test.ts b/src/lib/studio/test/studioClient.test.ts index 91febf22..3ac6d67e 100644 --- a/src/lib/studio/test/studioClient.test.ts +++ b/src/lib/studio/test/studioClient.test.ts @@ -211,10 +211,11 @@ test('runApplyChoice: a chip posts the harness fixture request, with no message' const init = fetch.mock.calls[0]?.arguments[1] as RequestInit; assert.equal(fetch.mock.calls[0]?.arguments[0], '/api/studio/turn'); - assert.deepEqual(JSON.parse(init.body as string), { - ...request, - conversation_id: conversation, - }); + 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) => { @@ -232,7 +233,7 @@ test('runApplyChoice: a 422 chip refusal reaches onRefusal, and no error frame', await runApplyChoice( 'conv', - { choice_id: 'spec_1:sector', option_id: 'sector:120' }, + { choice_id: 'spec_1:sector', option_id: 'sector:120', turn: 1, spec_id: 'spec_1' }, { onFrame: (frame) => frames.push(frame), onRefusal: (refusal) => { diff --git a/src/lib/studio/wire.ts b/src/lib/studio/wire.ts index a2b3bcbe..8c90c197 100644 --- a/src/lib/studio/wire.ts +++ b/src/lib/studio/wire.ts @@ -211,9 +211,15 @@ export type Seed = { operations: SeedOperation[]; }; -/** A clicked `ApplyChoiceSuggestion`: the scope choice of a stored reading - * and the option it moves to. */ -export type ApplyChoice = { choice_id: string; option_id: string }; +/** 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'; @@ -233,8 +239,9 @@ export type TurnRequest = { * 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` or `switch_option_unavailable`) and a `detail` - * to show. */ + * (`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; }; @@ -480,12 +487,15 @@ 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. */ + * 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 = From 8647014402ed7cf0798784e5ec196bbdd5f496aa Mon Sep 17 00:00:00 2001 From: Jorge Rivera Date: Tue, 27 Oct 2026 10:06:46 +0100 Subject: [PATCH 7/8] fix(studio): keep a stale plan unapprovable and own turn starts and ends in one place A switch refused as stale keeps the card's revision, so an approve is refused, and only the harness's switch refusals count as refused switches; any other failure ends the turn. stream() guards every refusal against a stopped or superseded turn, send and applyChoice open a turn through one startTurn, a chip clicked mid-request queues, a forked conversation shows no chips, and the card shows its notice. --- .../organisms/Studio/hooks/useChat.ts | 370 +++++++++--------- .../Studio/workspace/ChatMessage.tsx | 3 +- .../Studio/workspace/PlanCard.module.scss | 6 +- .../organisms/Studio/workspace/PlanCard.tsx | 3 +- .../organisms/Studio/workspace/PlanModal.tsx | 12 +- src/lib/studio/chips.ts | 27 +- src/lib/studio/plan.ts | 41 +- src/lib/studio/test/chips.test.ts | 51 ++- src/lib/studio/test/plan.test.ts | 76 ++-- 9 files changed, 346 insertions(+), 243 deletions(-) diff --git a/src/components/organisms/Studio/hooks/useChat.ts b/src/components/organisms/Studio/hooks/useChat.ts index dd13584f..c800b6f0 100644 --- a/src/components/organisms/Studio/hooks/useChat.ts +++ b/src/components/organisms/Studio/hooks/useChat.ts @@ -19,7 +19,12 @@ import { WORKING, } from '@/lib/studio/chatLine'; import { createCanvasEdits } from '@/lib/studio/canvasEdits'; -import { chipRefusalDetail, splitSuggestions, withRefusedChip } from '@/lib/studio/chips'; +import { + chipRefusalDetail, + splitSuggestions, + withoutChips, + withRefusedChip, +} from '@/lib/studio/chips'; import { clarifyAnswer, clarifyFromFrame, @@ -93,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 = { @@ -154,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 @@ -182,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 @@ -194,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), @@ -345,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 @@ -626,14 +656,7 @@ export const useChat = (initial?: ChatSnapshot) => { }; } - return { - ...prev, - messages, - activity: endTurnActivity(prev.activity, turn, 'failed'), - ...NO_LINE, - thinking: false, - plan: settledPlan(prev.plan), - }; + return endTurn({ ...prev, messages }, turn, 'failed'); }); break; case 'done': @@ -644,13 +667,7 @@ export const useChat = (initial?: ChatSnapshot) => { applyManifest(frame.composition); } - setState((prev) => ({ - ...prev, - activity: endTurnActivity(prev.activity, turn), - ...NO_LINE, - thinking: false, - plan: settledPlan(prev.plan), - })); + setState((prev) => endTurn(prev, turn)); break; } }; @@ -676,17 +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, - plan: settledPlan(prev.plan), - }; + 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. @@ -704,20 +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, - plan: settledPlan(prev.plan), - })); + setState((prev) => endTurn(prev, turn, 'failed')); } } }); @@ -751,58 +760,66 @@ export const useChat = (initial?: ChatSnapshot) => { [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; @@ -833,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) })); @@ -876,7 +871,6 @@ export const useChat = (initial?: ChatSnapshot) => { ) => { const conversation = sessionRef.current; const pending = pendingInterruptRef.current; - const generation = generationRef.current; pendingInterruptRef.current = null; @@ -895,24 +889,19 @@ export const useChat = (initial?: ChatSnapshot) => { return; } - const onRefusal = (refusal: StreamRefusal) => { - const current = stalePlan(refusal); - - if (current && generationRef.current === generation) { - offerPlan(current); - } + stream( + turnCount.current, + (handlers, signal) => + runInterrupt(conversation, pending.interruptId, reply, handlers, signal), + (refusal) => { + const current = stalePlan(refusal); - return current !== null; - }; + if (current) { + offerPlan(current); + } - stream(turnCount.current, (handlers, signal) => - runInterrupt( - conversation, - pending.interruptId, - reply, - { ...handlers, onRefusal }, - signal, - ), + return current !== null; + }, ); }, [offerPlan, stream], @@ -981,7 +970,8 @@ export const useChat = (initial?: ChatSnapshot) => { // 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. + // 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; @@ -996,7 +986,6 @@ export const useChat = (initial?: ChatSnapshot) => { const label = plan.decisions .find((decision) => decision.choice_id === choiceId) ?.options?.find((option) => option.option_id === optionId)?.label; - const generation = generationRef.current; pendingInterruptRef.current = null; setState((prev) => ({ @@ -1005,99 +994,92 @@ export const useChat = (initial?: ChatSnapshot) => { plan: prev.plan && startSwitch(prev.plan, { choiceId, optionId }), })); - stream(turnCount.current, (handlers, signal) => - runInterrupt( - conversation, - pending.interruptId, - reply, - { - ...handlers, - onRefusal: (refusal) => { - if (generationRef.current === generation) { - offerPlan(refusedSwitch(plan, refusal)); - } + stream( + turnCount.current, + (handlers, signal) => + runInterrupt(conversation, pending.interruptId, reply, handlers, signal), + (refusal) => { + const refused = refusedSwitch(plan, refusal); + + if (refused) { + offerPlan(refused); + } - return true; - }, - }, - signal, - ), + 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. Chips show - // only on the latest answer, so nothing is in flight or paused. 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. + // 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 (inFlightRef.current > 0) { + if (holdTurn({ text: chip.label, chip })) { return; } - if (!sessionRef.current) { - sessionRef.current = uuid(); - } - - turnCount.current += 1; - const turn = turnCount.current; - const conversation = sessionRef.current; - const generation = generationRef.current; + const { turn, conversation } = startTurn( + { role: 'user', text: chip.label }, + `Switching to ${chip.label}`, + ); - pendingInterruptRef.current = null; - editingRef.current = null; - setState((prev) => ({ - ...withLine(prev, `Switching to ${chip.label}`), - messages: [ - ...prev.messages, - { role: 'user', text: chip.label }, - { role: 'bot', text: '' }, - ], - activity: [ - ...prev.activity, - { turn, prompt: chip.label, startedAt: Date.now(), tools: [] }, - ], - thinking: true, - clarify: null, - plan: null, - })); + stream( + turn, + (handlers, signal) => runApplyChoice(conversation, chip, handlers, signal), + (refusal) => { + const detail = chipRefusalDetail(refusal); - stream(turn, (handlers, signal) => - runApplyChoice( - conversation, - chip, - { - ...handlers, - onRefusal: (refusal) => { - const detail = chipRefusalDetail(refusal); - - if (detail === null) { - return false; - } + if (detail === null) { + return false; + } - if (generationRef.current === generation) { - setState((prev) => ({ - ...prev, - messages: withRefusedChip(prev.messages, chip, detail), - activity: endTurnActivity(prev.activity, turn, 'failed'), - ...NO_LINE, - thinking: false, - })); - } + setState((prev) => + endTurn( + { ...prev, messages: withRefusedChip(prev.messages, chip, detail) }, + turn, + 'failed', + ), + ); - return true; - }, - }, - signal, - ), + return true; + }, ); }, - [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), + })); + + 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. @@ -1171,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), diff --git a/src/components/organisms/Studio/workspace/ChatMessage.tsx b/src/components/organisms/Studio/workspace/ChatMessage.tsx index 2aa53851..761a1879 100644 --- a/src/components/organisms/Studio/workspace/ChatMessage.tsx +++ b/src/components/organisms/Studio/workspace/ChatMessage.tsx @@ -9,6 +9,7 @@ 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 = { @@ -110,7 +111,7 @@ const ChatMessage = ({ ))} {chips.map((chip) => (