@flowdular/sandbox 0.2.8 → 0.3.0

package/README.md

@@ -459,6 +459,31 @@ anyone else works, so a broken change never travels down the chain. The fix
 prompt carries the gate command and the first 4000 characters of its output;
 the transcript keeps the whole output (head and tail of a long one).
 
+### Active questions
+
+A specialist that needs a business decision closes its reply with one fenced
+block tagged `questions` holding
+`{"questions":[{"id":"Q-1","question":"...","options":["..."],"recommended":"...","allowFreeText":true}]}`.
+The sandbox parses and bounds it (at most 12 questions with unique `Q-n` ids, a
+question of 1 to 400 characters, at most 8 options of 1 to 120 characters, a
+recommendation that is one of them) and stores it on the session as
+`pendingQuestions`; a block it cannot read is a turn warning, not a failed turn.
+The transcript lists the questions instead of showing JSON, and the session view
+offers a form with the recommendation preselected.
+
+```
+POST /sandbox/api/sessions/:id/answers
+{ "answers": [{ "id": "Q-1", "answer": "Only the owner" }], "message": "optional" }
+```
+
+Behind the same boundary as every other mutation. It clears the questions and
+starts the next turn in the role that asked, in the module it asked about, with
+`Decisions:` and one `- Q-1: <question> -> <answer>` line per decision leading
+the operator's optional message. Refusals: `409 NO_PENDING_QUESTIONS`, `409
+SESSION_ARCHIVED`, `409 SESSION_DELIVERED`, and `400 INVALID_INPUT` for an
+unanswered question, an unknown id, an over-long answer, or an answer that is
+not one of the offered options when no free text was allowed.
+
 ## Turn lifetime
 
 A turn runs to completion on the server whatever happens to the browser: the

package/bin/flowdular-sandbox.mjs

@@ -66,6 +66,40 @@ import { createServer } from "vite";
 
 // ../dev-console/src/index.mjs
 import { createLogger } from "vite";
+
+// ../dev-console/src/brand.mjs
+var MARK = [
+  "    XXX     XXX",
+  "    XXX     XXX",
+  " XXXXXXXXXXXXXXXXX",
+  "XXXXXXXXXXXXXXXXXXX",
+  "    XXX     XXX",
+  "XXXXXXXXXXXXXXXXXXX",
+  " XXXXXXXXXXXXXXXXX",
+  "    XXX     XXX",
+  "    XXX     XXX"
+];
+function renderBrandHeader({
+  title = "FLOWDULAR",
+  subtitle = "",
+  color = false,
+  columns = process.stdout.columns ?? 80,
+  terminal = Boolean(process.stdout.isTTY)
+} = {}) {
+  const brand = (text) => color ? `\x1B[1;38;5;42m${text}\x1B[0m` : text;
+  const muted = (text) => color ? `\x1B[90m${text}\x1B[0m` : text;
+  if (!terminal) {
+    return `  ${brand(title)}${subtitle ? `  ${muted(subtitle)}` : ""}`;
+  }
+  const heading = [
+    `  ${brand(title)}`,
+    ...subtitle ? [`  ${muted(subtitle)}`] : []
+  ];
+  if (columns < 21) return heading.join("\n");
+  return [...MARK.map((row) => `  ${brand(row)}`), "", ...heading].join("\n");
+}
+
+// ../dev-console/src/index.mjs
 var ansiPattern = /\u001B\[[0-?]*[ -/]*[@-~]/g;
 var ansi = {
   reset: "\x1B[0m",
@@ -116,7 +150,7 @@ function statusLine(theme, label, value, tone = "text") {
 }
 function printReady({ title, subtitle, lines, theme }) {
   console.log("");
-  console.log(`  ${theme.brand(title)}  ${theme.muted(subtitle)}`);
+  console.log(renderBrandHeader({ title, subtitle, color: theme.enabled }));
   for (const [label, value, tone = "text"] of lines) {
     if (value === null || value === void 0) continue;
     console.log(statusLine(theme, label, value, tone));

package/internal/coding-agent/src/index.ts

@@ -28,7 +28,12 @@ export {
 	type InstructionContext,
 } from './roles/contract.ts';
 export { parseHandoff, type HandoffDeclaration } from './roles/handoff.ts';
-export { selectTaskSkill, type TaskSkillContext } from './roles/skills.ts';
+export {
+	ALWAYS_ELIGIBLE_SKILLS,
+	ROLE_SKILLS,
+	selectTaskSkill,
+	type TaskSkillContext,
+} from './roles/skills.ts';
 export { DEFAULT_AGENT_ROLES } from './roles/defaults.ts';
 export type { AgentRoleDefinition } from './roles/defaults.ts';
 export {

package/internal/coding-agent/src/roles/defaults.ts

@@ -85,7 +85,11 @@ Leave client files to the frontend engineer and tools/business-agent definitions
 		allowedPaths: ['spec/**', 'translations/**'],
 		gates: ['spec-schema'],
 		handoff: ['backend-engineer', 'ux-designer'],
-		instruction: `You own specification decisions and locale terminology, never implementation. Use only the Task skill selected under Session. Consult reference/packages/contracts/schemas/module-spec.schema.json and reference/example-module/spec/module.yaml when writing the spec.
+		instruction: `You own specification decisions and locale terminology, never implementation. Use only the Task skill selected under Session. Consult reference/platform-capabilities.md, reference/packages/contracts/schemas/module-spec.schema.json and reference/example-module/spec/module.yaml when writing the spec.
+
+Write schemaVersion 2: entities with typed fields and states, screens, actions, widgets, settings, agentTools, plus outOfScope and decisions. Fill decisions for every choice, including the platform defaults you proposed. The capability card is closed: anything it lists as missing goes to outOfScope with the business decision, never into a scenario. v1 specs stay valid.
+
+When a decision is missing, end the reply with exactly one fenced block tagged questions holding {"questions":[{"id":"Q-1","question":"...","options":["..."],"recommended":"...","allowFreeText":true}]} and nothing after it. The operator answers in a form and the replies arrive next turn as a Decisions section.
 
 For an edit, compare against base/modules/<dir>/spec/module.yaml and make the smallest delta covering the brief. Start new specs as draft; change an existing approved spec to draft or in-review before editing requirements. Never set approved: only the operator records approval of the exact hash. Later edits invalidate it.
 

package/internal/coding-agent/src/roles/skills.ts

@@ -3,13 +3,28 @@ export interface TaskSkillContext {
 	readonly sessionKind: 'new-module' | 'edit-module';
 	readonly blueprint: string;
 	readonly task: string;
+	/* The text an explicit $skill may come from. Defaults to the request text.
+	   A turn whose request also carries words a specialist wrote narrows it to
+	   the operator's own, so a question can never choose the skill that answers
+	   it; empty means this turn has no operator text to scan. The keyword
+	   defaults keep reading `task`, which is the whole request either way. */
+	readonly explicitSkillSource?: string;
 	readonly available: readonly string[];
+	/* Whether the operator has approved the exact current specification of the
+	   module this turn works on. Absent counts as not approved, so a new module
+	   starts with the interview instead of the implementation skill. */
+	readonly specApproved?: boolean;
 }
 
 /* A single deterministic selection. Discovery is not injected into the prompt.
    Only skills this specialist can use are eligible for an explicit $skill. */
-const ROLE_SKILLS: Readonly<Record<string, readonly string[]>> = {
-	'business-manager': ['module-new', 'module-update'],
+export const ROLE_SKILLS: Readonly<Record<string, readonly string[]>> = {
+	'business-manager': [
+		'spec-interview',
+		'module-new',
+		'module-update',
+		'translations-i18n',
+	],
 	'backend-engineer': [
 		'module-new',
 		'module-update',
@@ -18,17 +33,19 @@ const ROLE_SKILLS: Readonly<Record<string, readonly string[]>> = {
 		'bug-hunt',
 		'test-hardening',
 		'auth-security-review',
+		'cli-extension',
 		'perf-audit',
 	],
 	'frontend-engineer': [
 		'ux-design',
 		'module-update',
+		'translations-i18n',
 		'variables',
 		'workflow-development',
 		'bug-hunt',
 		'test-hardening',
 	],
-	'ux-designer': ['ux-design'],
+	'ux-designer': ['ux-design', 'translations-i18n'],
 	'agentic-engineer': [
 		'agent-tool-design',
 		'business-agent-design',
@@ -38,13 +55,23 @@ const ROLE_SKILLS: Readonly<Record<string, readonly string[]>> = {
 	],
 };
 
+/* Review is read-only and is available to custom registered specialists too, so
+   it is eligible for every role without appearing in any role's list. */
+export const ALWAYS_ELIGIBLE_SKILLS: readonly string[] = ['auto-review'];
+
 export function selectTaskSkill(context: TaskSkillContext): string | null {
-	// Review is read-only and is available to custom registered specialists too.
-	const eligible = [...(ROLE_SKILLS[context.role] ?? []), 'auto-review'];
+	const eligible = [
+		...(ROLE_SKILLS[context.role] ?? []),
+		...ALWAYS_ELIGIBLE_SKILLS,
+	];
 	const available = new Set(context.available);
 	const installed = (skill: string) =>
 		eligible.includes(skill) && available.has(skill);
-	const explicit = [...context.task.matchAll(/\$([a-z][a-z0-9-]*)\b/g)]
+	const explicit = [
+		...(context.explicitSkillSource ?? context.task).matchAll(
+			/\$([a-z][a-z0-9-]*)\b/g,
+		),
+	]
 		.map((match) => match[1]!)
 		.find(installed);
 	if (explicit) return explicit;
@@ -56,6 +83,15 @@ export function selectTaskSkill(context: TaskSkillContext): string | null {
 				? 'bug-hunt'
 				: null;
 	if (focused && installed(focused)) return focused;
+	/* A new module starts as an interview, not as an implementation: until the
+	   operator approves the exact spec there is nothing to implement from. */
+	if (
+		context.role === 'business-manager' &&
+		context.sessionKind === 'new-module' &&
+		context.specApproved !== true &&
+		installed('spec-interview')
+	)
+		return 'spec-interview';
 	const moduleSkill =
 		context.sessionKind === 'new-module' ? 'module-new' : 'module-update';
 	const defaultSkill =

package/internal/coding-agent/src/workspace.ts

@@ -229,6 +229,10 @@ export function spawnLineStream(options: SpawnJsonOptions): ProcessLineStream {
 		});
 	});
 
+	/* A spawn failure rejects before the caller has drained the lines and
+	   awaited this promise; without a handler of its own that rejection is
+	   unhandled and takes the process down. */
+	finished.catch(() => undefined);
 	return {
 		lines: createInterface({ input: child.stdout, crlfDelay: Infinity }),
 		finished,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@flowdular/sandbox",
-	"version": "0.2.8",
+	"version": "0.3.0",
 	"description": "The Flowdular sandbox: chat a change, build it behind the gates, preview it in the real application, deliver it as code.",
 	"license": "MIT",
 	"homepage": "https://github.com/flowdular/flowdular/tree/main/packages/sandbox#readme",
@@ -55,9 +55,9 @@
 		"@octanejs/seo": "0.0.38",
 		"@octanejs/vite-plugin": "0.1.51",
 		"octane": "0.1.51",
-		"segment-state": "0.2.0",
+		"segment-state": "0.2.1",
 		"vite": "8.2.2",
-		"@flowdular/sdk": "0.2.3"
+		"@flowdular/sdk": "0.3.0"
 	},
 	"imports": {
 		"#coding-agent": "./internal/coding-agent/src/index.ts"

package/src/App.tsrx

@@ -31,9 +31,11 @@ import {
 	stopTurn,
 	streamEject,
 	streamTurn,
+	submitAnswers,
 	uploadAttachment,
 	type EjectPlanView,
 	type EjectTargetId,
+	type SubmittedAnswer,
 	type TurnHandlers,
 } from './client/api.ts';
 import { ChatPane } from './client/ChatPane.tsrx';
@@ -54,11 +56,13 @@ import {
 	type GitHubSettingsInput,
 } from './client/GitHubSettingsModal.tsrx';
 import {
+	answersErrorFor,
 	createSandboxClientState,
 	mergeEntries,
 	mergeSteps,
 	signalReady,
 	sessionIdFromUrl,
+	type AnswersRefusal,
 	type PreviewSelection,
 } from './client/state.ts';
 import {
@@ -121,6 +125,11 @@ export function App(props?: RenderRouteProps) @{
 	const [ejecting, setEjecting] = useValue(sandbox.state.ejecting);
 	const [ejectBuild, setEjectBuild] = useValue(sandbox.state.ejectBuild);
 	const [modelSettingsOpen, setModelSettingsOpen] = useState(false);
+	/* A refused answer belongs beside the form that was refused, not in the
+   session-wide banner and not beside another session's form. */
+	const [answersRefusal, setAnswersRefusal] = useState<AnswersRefusal | null>(
+		null,
+	);
 	const [menuOpen, setMenuOpen] = useValue(sandbox.state.menuOpen);
 	const [githubSettingsOpen, setGitHubSettingsOpen] = useValue(
 		sandbox.state.githubSettingsOpen,
@@ -380,6 +389,35 @@ export function App(props?: RenderRouteProps) @{
 		);
 	};
 
+	/* Answering the open questions is a turn the server composes: it prepends the
+   decisions to the optional note and resumes the specialist that asked. */
+	const answerQuestions = (
+		answers: readonly SubmittedAnswer[],
+		note: string,
+	) => {
+		const session = currentSession();
+		if (!session || sandbox.store.get(sandbox.state.running)) return;
+		const sequence = session.pendingQuestions?.sequence ?? -1;
+		setAnswersRefusal(null);
+		detach();
+		setRunning(true);
+		setError('');
+		const handlers = handlersFor(session.id);
+		turn.controller = submitAnswers(session.id, answers, note, {
+			...handlers,
+			onFailed: (failure) => {
+				if (sandbox.store.get(sandbox.state.activeSessionId) !== session.id) {
+					return;
+				}
+				setAnswersRefusal({
+					session: session.id,
+					sequence,
+					message: failure,
+				});
+			},
+		});
+	};
+
 	const continueWith = (handoff: HandoffPlan) => {
 		const session = currentSession();
 		if (!session || running) return;
@@ -863,6 +901,7 @@ export function App(props?: RenderRouteProps) @{
 								<ChatPane
 									entries={entries}
 									delivered={Boolean(view.session.ejectedAt)}
+									archived={Boolean(view.session.archivedAt)}
 									roles={state.roles}
 									drivers={state.drivers}
 									modules={view.session.modules}
@@ -875,6 +914,12 @@ export function App(props?: RenderRouteProps) @{
 									busy={busy}
 									selection={selection}
 									autoContinue={view.session.autoContinue}
+									pendingQuestions={view.session.pendingQuestions ?? null}
+									answersError={answersErrorFor(
+										answersRefusal,
+										view.session.id,
+										view.session.pendingQuestions ?? null,
+									)}
 									pendingBrief={startingPoint(view.session, entries)}
 									onStart={() => send(startingPoint(view.session, entries))}
 									onContinue={continueWith}
@@ -893,6 +938,7 @@ export function App(props?: RenderRouteProps) @{
 									onDriver={setDriver}
 									onMessage={setDraft}
 									onSend={(fresh) => send(undefined, fresh)}
+									onAnswers={answerQuestions}
 									onStop={stop}
 									onClearSelection={() => setSelection(null)}
 								/>

package/src/client/ChatPane.tsrx

@@ -16,7 +16,14 @@ import {
 	type DriverSummary,
 	type ModuleSpecReview,
 	type RoleSummary,
+	type SubmittedAnswer,
 } from './api.ts';
+import {
+	readQuestions,
+	type PendingQuestion,
+	type PendingQuestions,
+} from '../server/questions.ts';
+import { PendingQuestionsCard } from './PendingQuestionsCard.tsrx';
 import { ToolEvent } from './ToolEvent.tsrx';
 import { transcriptRows, type TranscriptRow } from './transcript.ts';
 import { TurnActivity } from './TurnActivity.tsrx';
@@ -34,6 +41,9 @@ import { roleLabel, handoffLabel } from './session-labels.ts';
 export interface ChatPaneProps {
 	readonly entries: readonly ChatEntry[];
 	readonly delivered: boolean;
+	/* Archived and delivered both close the session to work, so a pending
+   decision form is read-only under either. */
+	readonly archived: boolean;
 	readonly roles: readonly RoleSummary[];
 	readonly drivers: readonly DriverSummary[];
 	readonly modules: readonly SessionModule[];
@@ -48,6 +58,9 @@ export interface ChatPaneProps {
 	readonly busy?: boolean;
 	readonly selection: PreviewSelection | null;
 	readonly autoContinue: boolean;
+	/* The decisions the specialist that asked is still waiting for. */
+	readonly pendingQuestions: PendingQuestions | null;
+	readonly answersError: string;
 	/* Set when the session has never run a turn, so the brief can still start it. */
 	readonly pendingBrief: string;
 	readonly onStart: () => void;
@@ -61,6 +74,7 @@ export interface ChatPaneProps {
 	readonly onDriver: (driver: string) => void;
 	readonly onMessage: (message: string) => void;
 	readonly onSend: (freshContext?: boolean) => void;
+	readonly onAnswers: (answers: readonly SubmittedAnswer[], message: string) => void;
 	readonly onStop: () => void;
 	readonly onClearSelection: () => void;
 }
@@ -103,10 +117,11 @@ function isError(entry: ChatEntry): boolean {
 
 const HANDOFF_LINE = /^handoff\s*:/i;
 
-/* The handoff line is protocol, not conversation: the card below the message
-   already says who continues, so the transcript shows the words only. */
-function spoken(entry: ChatEntry): string {
-	const lines = (entry.text ?? '').split('\n');
+/* The handoff line and the questions block are protocol, not conversation: the
+   cards below the message already say who continues and what is being asked,
+   so the transcript shows the words only. */
+function spoken(entry: ChatEntry, text: string): string {
+	const lines = text.split('\n');
 	while (lines.length > 0 &&
 		lines[lines.length - 1]!.trim() === '') lines.pop();
 	const last = lines[lines.length - 1]?.replace(/[`*_]/g, '').trim() ?? '';
@@ -120,6 +135,11 @@ interface StreamBlock {
 	readonly key: number;
 	readonly entry: ChatEntry | null;
 	readonly events: readonly TranscriptRow[] | null;
+	/* The message as words, with the protocol lines taken out. */
+	readonly speech: string;
+	/* The decisions this message asked for, read once so the transcript can
+   list them instead of showing the operator raw JSON. */
+	readonly questions: readonly PendingQuestion[];
 }
 
 /* One stream in the order it happened: a message, then the tool activity that
@@ -150,13 +170,26 @@ function streamBlocks(entries: readonly ChatEntry[]): readonly StreamBlock[] {
 		}
 		blocks.push({ key: entry.sequence, entry, events: null });
 	}
-	return blocks.map(
-		(block) => ({
+	return blocks.map((block) => {
+		const reading =
+			block.entry?.kind === 'agent'
+				? readQuestions(block.entry.text ?? '')
+				: null;
+		return {
 			key: block.key,
 			entry: block.entry,
 			events: block.events,
-		}),
-	);
+			speech: block.entry
+				? spoken(
+						block.entry,
+						reading?.kind === 'valid'
+							? reading.remainder
+							: block.entry.text ?? '',
+					)
+				: '',
+			questions: reading?.kind === 'valid' ? reading.questions : [],
+		};
+	});
 }
 
 function blockKey(block: StreamBlock): number {
@@ -484,8 +517,19 @@ export function ChatPane(props: ChatPaneProps) @{
 									<p class="chat__text">{block.entry!.text}</p>
 								</details>
 							}
-							@if (block.entry!.sequence === open && !props.running) {
-								@if (block.entry!.handoff!.kind === 'approval') {
+							@if (block.entry!.sequence === open) {
+								@if (block.entry!.handoff!.kind === 'question') {
+									<PendingQuestionsCard
+										pending={props.pendingQuestions}
+										loading={props.running}
+										denied={props.delivered || props.archived}
+										busy={props.busy === true}
+										error={props.answersError}
+										onSubmit={props.onAnswers}
+									/>
+								} @else if (
+									block.entry!.handoff!.kind === 'approval' && !props.running
+								) {
 									<ApprovalHandoff
 										handoff={block.entry!.handoff!}
 										reviews={props.specs}
@@ -494,7 +538,9 @@ export function ChatPane(props: ChatPaneProps) @{
 										onRequestChanges={props.onRequestChanges}
 										onEdit={props.onEditSpec}
 									/>
-								} @else if (block.entry!.handoff!.kind === 'continue') {
+								} @else if (
+									block.entry!.handoff!.kind === 'continue' && !props.running
+								) {
 									<div class="ui-form__actions">
 										<Button
 											size="sm"
@@ -530,7 +576,22 @@ export function ChatPane(props: ChatPaneProps) @{
 								</span>
 								{moduleLabel(block.entry!)}
 							</header>
-							<p class="chat__text">{spoken(block.entry!)}</p>
+							<p class="chat__text">{block.speech}</p>
+							@if (block.questions.length > 0) {
+								<ul>
+									@for (const question of block.questions; key question.id) {
+										<li>
+											<span class="ui-mono">{question.id}</span>
+											{' ' + question.question}
+											@if (question.options.length > 0) {
+												<span class="ui-help">{question.options.join(
+													' · ',
+												)}</span>
+											}
+										</li>
+									}
+								</ul>
+							}
 							{restoreRow(block.key)}
 						</article>
 					}