@flowdular/sandbox 0.2.9 → 0.3.0

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) => {