@flowdular/sandbox 0.2.8 → 0.3.0

package/src/client/PendingQuestionsCard.tsrx

@@ -0,0 +1,193 @@
+import { useState } from 'octane';
+import { Alert, Button, Icon, Tag } from '@flowdular/sdk/ui';
+import {
+	MAX_ANSWER_LENGTH,
+	type PendingQuestion,
+	type PendingQuestions,
+} from '../server/questions.ts';
+import type { SubmittedAnswer } from './api.ts';
+import { useTranslation } from './i18n.ts';
+
+export interface PendingQuestionsCardProps {
+	readonly pending: PendingQuestions | null;
+	/* A turn is still in flight, so nothing here is answerable yet. */
+	readonly loading: boolean;
+	/* The session no longer accepts work: archived, or already delivered. */
+	readonly denied: boolean;
+	readonly busy: boolean;
+	/* Why the last submission was refused. It renders above the state branch,
+   because a refusal that already cleared the record leaves no questions to
+   render it beside. */
+	readonly error: string;
+	readonly onSubmit: (answers: readonly SubmittedAnswer[], message: string) => void;
+}
+
+/* One operator's unsent decisions, stamped with the turn that asked. A newer
+   question set makes the draft stale without an effect or a reset pass. */
+interface AnswerDraft {
+	readonly sequence: number;
+	readonly mode: Readonly<Record<string, 'option' | 'free'>>;
+	readonly choice: Readonly<Record<string, string>>;
+	readonly typed: Readonly<Record<string, string>>;
+	readonly note: string;
+}
+
+const EMPTY: AnswerDraft = {
+	sequence: -1,
+	mode: {},
+	choice: {},
+	typed: {},
+	note: '',
+};
+
+/* The decisions a specialist is waiting for: one radio group per question, the
+   recommendation preselected, and a free-text answer where the specialist
+   allowed one. Submitting starts the next turn in the role that asked. */
+export function PendingQuestionsCard(props: PendingQuestionsCardProps) @{
+	const { t } = useTranslation();
+	const questions = props.pending?.questions ?? [];
+	const sequence = props.pending?.sequence ?? -1;
+	const [stored, setStored] = useState<AnswerDraft>(EMPTY);
+	const draft =
+		stored.sequence === sequence ? stored : EMPTY;
+	const patch = (change: Partial<AnswerDraft>) => setStored({
+		...draft,
+		...change,
+		sequence,
+	});
+
+	const modeOf = (question: PendingQuestion): 'option' | 'free' | '' =>
+		draft.mode[question.id] ??
+			(question.recommended
+				? 'option'
+				: question.options.length === 0
+					? 'free'
+					: '');
+	const choiceOf = (question: PendingQuestion) =>
+		draft.choice[question.id] ?? question.recommended ?? '';
+	const answerOf = (question: PendingQuestion) => {
+		const mode = modeOf(question);
+		if (mode === 'free') return (draft.typed[question.id] ?? '').trim();
+		return mode === 'option' ? choiceOf(question) : '';
+	};
+	const pick = (question: PendingQuestion, option: string) => patch({
+		mode: { ...draft.mode, [question.id]: 'option' },
+		choice: { ...draft.choice, [question.id]: option },
+	});
+	const complete = questions.every((question) => answerOf(question).length > 0);
+
+	<section class="ui-form">
+		@if (props.error) {
+			<Alert tone="danger">{props.error}</Alert>
+		}
+		@if (props.loading) {
+			<p class="ui-note">
+				<Icon name="refresh" size={14} />
+				{t('sandbox.questions.loading')}
+			</p>
+		} @else if (props.denied) {
+			<Alert tone="warning">{t('sandbox.questions.denied')}</Alert>
+		} @else if (questions.length === 0) {
+			<p class="ui-note">
+				<Icon name="help" size={14} />
+				{t('sandbox.questions.empty')}
+			</p>
+		} @else {
+			<>
+				<div class="ui-form__section">
+					<div class="ui-form__section-head">
+						<b>{t('sandbox.questions.title')}</b>
+						<small>{t('sandbox.questions.help')}</small>
+					</div>
+					@for (const question of questions; key question.id) {
+						<div class="ui-field">
+							<span class="ui-label">
+								<span class="ui-mono">{question.id}</span>
+								{' ' + question.question}
+							</span>
+							@for (const option of question.options; key option) {
+								<label class="ui-checkbox">
+									<input
+										type="radio"
+										name={'answer-' + sequence + '-' + question.id}
+										value={option}
+										checked={modeOf(question) === 'option' &&
+											choiceOf(question) === option}
+										disabled={props.busy}
+										onChange={() => pick(question, option)}
+									/>
+									<span>{option}</span>
+									@if (option === question.recommended) {
+										<Tag tone="info">{t('sandbox.questions.recommended')}</Tag>
+									}
+								</label>
+							}
+							@if (question.allowFreeText) {
+								<>
+									<label class="ui-checkbox">
+										<input
+											type="radio"
+											name={'answer-' + sequence + '-' + question.id}
+											value=""
+											checked={modeOf(question) === 'free'}
+											disabled={props.busy}
+											onChange={() => patch({
+												mode: { ...draft.mode, [question.id]: 'free' },
+											})}
+										/>
+										<span>{t('sandbox.questions.freeText')}</span>
+									</label>
+									<input
+										class="ui-input"
+										type="text"
+										maxlength={MAX_ANSWER_LENGTH}
+										aria-label={t('sandbox.questions.freeText')}
+										placeholder={t('sandbox.questions.freeTextPlaceholder')}
+										value={draft.typed[question.id] ?? ''}
+										disabled={props.busy || modeOf(question) !== 'free'}
+										onInput={(event) => patch({
+											typed: {
+												...draft.typed,
+												[question.id]: event.currentTarget.value,
+											},
+										})}
+									/>
+								</>
+							}
+						</div>
+					}
+				</div>
+				<div class="ui-field">
+					<span class="ui-label">{t('sandbox.questions.note')}</span>
+					<textarea
+						class="ui-textarea"
+						rows={2}
+						placeholder={t('sandbox.questions.notePlaceholder')}
+						value={draft.note}
+						disabled={props.busy}
+						onInput={(event) => patch({ note: event.currentTarget.value })}
+					></textarea>
+				</div>
+				<div class="ui-form__actions">
+					<Button
+						size="sm"
+						variant="primary"
+						disabled={props.busy || !complete}
+						onClick={() => props.onSubmit(
+							questions.map(
+								(question) => ({
+									id: question.id,
+									answer: answerOf(question),
+								}),
+							),
+							draft.note.trim(),
+						)}
+					>
+						<Icon name="check" size={14} />
+						{t('sandbox.questions.submit')}
+					</Button>
+				</div>
+			</>
+		}
+	</section>
+}

package/src/client/api.ts

@@ -701,34 +701,25 @@ async function consumeTurnStream(
 	});
 }
 
-/* The turn runs on the server whatever this stream does. Aborting the
-   controller only closes this browser's view of it; stopTurn stops the agent. */
-export function streamTurn(
-	sessionId: string,
-	input: {
-		readonly message: string;
-		readonly freshContext?: boolean;
-		readonly role: string;
-		/* The draft module directory the turn works in; absent lets the sandbox
-		   decide from the last handoff. */
-		readonly module?: string;
-		readonly driver: string;
-	},
+/* Every route that starts a turn answers with the same stream, so they share
+   one transport. The turn runs on the server whatever this stream does:
+   aborting the controller only closes this browser's view of it, and stopTurn
+   stops the agent. */
+function postTurnStream(
+	path: string,
+	input: unknown,
 	handlers: TurnHandlers,
 ): AbortController {
 	const controller = new AbortController();
 	void (async () => {
 		try {
-			const response = await fetch(
-				`/sandbox/api/sessions/${encodeURIComponent(sessionId)}/turn`,
-				{
-					method: 'POST',
-					headers: MUTATION_HEADERS,
-					credentials: 'same-origin',
-					body: JSON.stringify(input),
-					signal: controller.signal,
-				},
-			);
+			const response = await fetch(path, {
+				method: 'POST',
+				headers: MUTATION_HEADERS,
+				credentials: 'same-origin',
+				body: JSON.stringify(input),
+				signal: controller.signal,
+			});
 			if (!response.ok || !response.body) {
 				const value = (await response
 					.json()
@@ -751,6 +742,47 @@ export function streamTurn(
 	return controller;
 }
 
+export function streamTurn(
+	sessionId: string,
+	input: {
+		readonly message: string;
+		readonly freshContext?: boolean;
+		readonly role: string;
+		/* The draft module directory the turn works in; absent lets the sandbox
+		   decide from the last handoff. */
+		readonly module?: string;
+		readonly driver: string;
+	},
+	handlers: TurnHandlers,
+): AbortController {
+	return postTurnStream(
+		`/sandbox/api/sessions/${encodeURIComponent(sessionId)}/turn`,
+		input,
+		handlers,
+	);
+}
+
+export interface SubmittedAnswer {
+	readonly id: string;
+	readonly answer: string;
+}
+
+/* The decisions the operator made on the questions the last turn asked. The
+   server prepends them to the optional message and starts the next turn in the
+   role that asked, so this is a turn stream like any other. */
+export function submitAnswers(
+	sessionId: string,
+	answers: readonly SubmittedAnswer[],
+	message: string,
+	handlers: TurnHandlers,
+): AbortController {
+	return postTurnStream(
+		`/sandbox/api/sessions/${encodeURIComponent(sessionId)}/answers`,
+		{ answers, ...(message ? { message } : {}) },
+		handlers,
+	);
+}
+
 /* Attach to a turn that is already running, after a reload or from another
    tab. Resolves with false when nothing is running. */
 export function followTurn(

package/src/client/locales/en.json

@@ -33,6 +33,17 @@
 	"handoff.description.review": "Review the results and decide what to do next.",
 	"handoff.description.blocked": "Work needs your attention. See the reason below.",
 	"handoff.details": "Specialist's message",
+	"questions.title": "Decisions the specialist needs",
+	"questions.help": "Pick one answer per question. The specialist continues with them.",
+	"questions.recommended": "Recommended",
+	"questions.freeText": "Something else",
+	"questions.freeTextPlaceholder": "Write your own answer",
+	"questions.note": "Anything else to add (optional)",
+	"questions.notePlaceholder": "Context the specialist should know",
+	"questions.submit": "Send decisions",
+	"questions.loading": "The specialist is working. The questions can be answered when the turn ends.",
+	"questions.empty": "No structured decisions are open. Answer in the message box below.",
+	"questions.denied": "This session no longer accepts decisions. Start a new session to change the module again.",
 	"api.error.request": "The sandbox request failed.",
 	"api.error.unreachable": "The sandbox server is not reachable. Start it again with npx @flowdular/sandbox.",
 	"api.error.deliveryStart": "Delivery could not start.",

package/src/client/locales/pl.json

@@ -33,6 +33,17 @@
 	"handoff.description.review": "Sprawdź rezultat i zdecyduj, co dalej.",
 	"handoff.description.blocked": "Praca wymaga Twojej uwagi. Poniżej znajdziesz przyczynę.",
 	"handoff.details": "Wiadomość specjalisty",
+	"questions.title": "Decyzje potrzebne specjaliście",
+	"questions.help": "Wybierz jedną odpowiedź na pytanie. Specjalista pracuje dalej z nimi.",
+	"questions.recommended": "Rekomendacja",
+	"questions.freeText": "Coś innego",
+	"questions.freeTextPlaceholder": "Wpisz własną odpowiedź",
+	"questions.note": "Coś jeszcze (opcjonalnie)",
+	"questions.notePlaceholder": "Kontekst, który specjalista powinien znać",
+	"questions.submit": "Wyślij decyzje",
+	"questions.loading": "Specjalista pracuje. Na pytania będzie można odpowiedzieć po zakończeniu tury.",
+	"questions.empty": "Nie ma otwartych decyzji do wyboru. Odpowiedz w polu wiadomości poniżej.",
+	"questions.denied": "Ta sesja nie przyjmuje już decyzji. Zacznij nową sesję, aby ponownie zmienić moduł.",
 	"api.error.request": "Nie udało się wykonać tej operacji.",
 	"api.error.unreachable": "Brak połączenia z pracownią. Uruchom ją ponownie poleceniem npx @flowdular/sandbox.",
 	"api.error.deliveryStart": "Nie udało się rozpocząć publikacji.",

package/src/client/state.ts

@@ -26,6 +26,27 @@ export interface PendingAttachment {
 	readonly error?: string;
 }
 
+/* A refused answer submission, stamped with the session and the question set it
+   answered, so it can never be shown beside another form. */
+export interface AnswersRefusal {
+	readonly session: string;
+	readonly sequence: number;
+	readonly message: string;
+}
+
+/* A refusal outlives the record it answered, because a submission that already
+   consumed the questions still has to say why it failed. It does not outlive
+   the session it was refused in, nor a newer question set. */
+export function answersErrorFor(
+	refusal: AnswersRefusal | null,
+	sessionId: string,
+	pending: { readonly sequence: number } | null,
+): string {
+	if (!refusal || refusal.session !== sessionId) return '';
+	if (pending && pending.sequence > refusal.sequence) return '';
+	return refusal.message;
+}
+
 export function createSandboxClientState() {
 	const store = createStore({
 		state: cell<SandboxState | null>(null),

package/src/server/preview-runtime.ts

@@ -5,7 +5,9 @@ import { pathToFileURL } from 'node:url';
 import type { ServerRoute } from '@octanejs/app-core';
 import { createRouter, type Router } from '@octanejs/app-core';
 import {
+	createDataClassRegistry,
 	createModuleSettingsRuntime,
+	PLATFORM_SETTINGS_TENANT,
 	createPlatformAgentRegistry,
 	createPlatformCapabilityRegistry,
 	createPlatformToolRegistry,
@@ -28,6 +30,17 @@ import {
 	type SessionModule,
 } from './sessions.ts';
 import type { DatabaseProvider } from '@flowdular/sdk/database';
+import {
+	createStorageKeyring,
+	createStoragePort,
+	storageConfigFromEnvironment,
+} from '@flowdular/sdk/storage';
+import {
+	createMailPort,
+	createModuleMetrics,
+	mailConfigFromEnvironment,
+	serverTracer,
+} from '@flowdular/sdk/server';
 import { createIsolatedPreviewRuntime } from './preview-worker-manager.ts';
 import {
 	resolvePreviewModules,
@@ -60,6 +73,9 @@ export interface PreviewComposition {
 	readonly moduleId: string;
 	readonly modules: readonly PreviewModuleComposition[];
 	readonly auth: AuthRuntime;
+	/* The drafts' settings runtime; a request primes the principal's workspace
+	   on it once the authentication middleware resolved the principal. */
+	readonly settings: ModuleSettingsRuntime;
 	readonly credentials: PreviewCredentials;
 	readonly router: Router;
 	readonly routes: readonly ServerRoute[];
@@ -89,7 +105,7 @@ function memorySettings(): ModuleSettingsRuntime {
 	const keyOf = (tenantId: string, moduleId: string, key: string) =>
 		`${tenantId}\0${moduleId}\0${key}`;
 	return createModuleSettingsRuntime({
-		load: (tenantId, moduleId) => {
+		load: async (tenantId, moduleId) => {
 			const values: Record<string, ModuleSettingValue> = {};
 			for (const record of records.values()) {
 				if (record.tenantId === tenantId && record.moduleId === moduleId) {
@@ -98,10 +114,10 @@ function memorySettings(): ModuleSettingsRuntime {
 			}
 			return values;
 		},
-		save: (record) => {
+		save: async (record) => {
 			records.set(keyOf(record.tenantId, record.moduleId, record.key), record);
 		},
-		clear: (tenantId, moduleId, key) => {
+		clear: async (tenantId, moduleId, key) => {
 			records.delete(keyOf(tenantId, moduleId, key));
 		},
 	});
@@ -152,7 +168,9 @@ async function createPreviewAuth(
 	} catch {
 		credentials = {
 			email: PREVIEW_EMAIL,
-			password: `preview-${randomBytes(12).toString('base64url')}`,
+			/* Entropy only: the platform password policy refuses a password that
+			   carries the local part of the account's own email address. */
+			password: randomBytes(24).toString('base64url'),
 		};
 		await mkdir(paths.data, { recursive: true, mode: 0o700 });
 		await writeFile(credentialPath, JSON.stringify(credentials), {
@@ -204,6 +222,8 @@ async function loadDraftComposition(
 		const composition = draft.createServerComposition({
 			...context,
 			agentDefinitions: context.agentDefinitions.forModule(module.id),
+			dataClasses: context.dataClasses.forModule(module.id),
+			metrics: createModuleMetrics(module.id),
 			workspaceRoot: paths.root,
 		});
 		if (composition.settings) context.settings.declare(composition.settings);
@@ -336,6 +356,17 @@ export function createInProcessPreviewRuntime(
 			const modules: PreviewModuleComposition[] = [];
 			const errors: string[] = [];
 			const agentDefinitions = createPlatformAgentRegistry();
+			const dataClasses = createDataClassRegistry();
+			/* A preview writes objects under its own session directory, never to a
+			   configured object store: a draft module must not reach a deployment's
+			   bucket, and the session directory is removed with the session. */
+			const storage = createStoragePort(
+				storageConfigFromEnvironment(
+					{ ...process.env, NODE_ENV: 'test', FD_STORAGE_ADAPTER: 'local' },
+					paths.root,
+				),
+				{ keyring: createStorageKeyring(process.env, paths.root) },
+			);
 			const context: Omit<PlatformServerContext, 'workspaceRoot'> = {
 				environment: process.env,
 				auth,
@@ -343,7 +374,22 @@ export function createInProcessPreviewRuntime(
 				agentTools: createPlatformToolRegistry() as PlatformToolRegistry,
 				agentDefinitions,
 				capabilities: createPlatformCapabilityRegistry(),
+				dataClasses,
 				databases,
+				storage,
+				/* In memory for the same reason the object store is session-local: a
+				   draft module must not reach anyone from a preview. */
+				mail: createMailPort(
+					mailConfigFromEnvironment({
+						...process.env,
+						NODE_ENV: 'test',
+						FD_MAIL_TRANSPORT: 'development',
+					}),
+				),
+				/* Rebound to each draft module as it composes, as the generated
+				   composition does; this binding is the preview's own. */
+				metrics: createModuleMetrics('sandbox.preview'),
+				tracer: serverTracer(),
 			};
 			for (const module of sources) {
 				const draft = await loadDraftComposition(
@@ -369,6 +415,8 @@ export function createInProcessPreviewRuntime(
 				});
 			}
 			agentDefinitions.seal();
+			dataClasses.seal();
+			await context.settings.prime(PLATFORM_SETTINGS_TENANT);
 
 			const account = await (
 				await auth.service()
@@ -401,6 +449,7 @@ export function createInProcessPreviewRuntime(
 				moduleId: session.moduleId,
 				modules,
 				auth,
+				settings: context.settings,
 				credentials,
 				routes: all,
 				router: createRouter([...all]),
@@ -417,8 +466,11 @@ export function createInProcessPreviewRuntime(
 						{ status: 500, headers: { 'content-type': 'application/json' } },
 					),
 				/* The session engine outlives a generation, so retiring one releases
-				   the drafts and nothing else. */
-				dispose: () => disposeAll(drafts),
+				   the drafts and the preview object store, and nothing else. */
+				dispose: async () => {
+					await disposeAll(drafts);
+					await storage.dispose();
+				},
 			};
 			compositions.set(session.id, composition);
 			return composition;

package/src/server/preview-worker-manager.ts

@@ -408,6 +408,7 @@ export function createIsolatedPreviewRuntime(
 		const composition: PreviewComposition = {
 			...meta,
 			auth: null as never,
+			settings: null as never,
 			router: null as never,
 			routes: Array.from({ length: meta.routes }, () => null as never),
 			request: async (request) => {

package/src/server/preview-worker.ts

@@ -1,5 +1,6 @@
 import { createServer } from 'node:http';
 import { createRouter, type ServerRoute } from '@octanejs/app-core';
+import { principalFromContext } from '@flowdular/sdk/modules/auth/server';
 import { createRemoteDatabaseProvider } from './preview-database-proxy.ts';
 import { createInProcessPreviewRuntime } from './preview-runtime.ts';
 import type { SandboxSession } from './sessions.ts';
@@ -89,9 +90,11 @@ async function previewRequest(request: Request): Promise<Response> {
 		url,
 		state: new Map(),
 	};
-	return composition.auth.middleware(context, async () =>
-		(match.route as ServerRoute).handler(context),
-	);
+	return composition.auth.middleware(context, async () => {
+		const principal = principalFromContext(context);
+		if (principal) await composition.settings.prime(principal.tenantId);
+		return (match.route as ServerRoute).handler(context);
+	});
 }
 
 const server = createServer(async (incoming, outgoing) => {