@flowdular/sdk 0.1.0 → 0.2.1

package/packages/dev-console/package.json

@@ -13,7 +13,7 @@
 	},
 	"devDependencies": {
 		"vite": "8.2.2",
-		"vitest": "4.1.10"
+		"vitest": "4.1.11"
 	},
 	"license": "MIT",
 	"repository": {

package/packages/harness/package.json

@@ -22,7 +22,7 @@
 	"devDependencies": {
 		"@types/node": "24.13.3",
 		"typescript": "5.9.3",
-		"vitest": "4.1.10"
+		"vitest": "4.1.11"
 	},
 	"license": "MIT",
 	"repository": {

package/packages/kernel/package.json

@@ -19,7 +19,7 @@
 	"devDependencies": {
 		"@types/node": "24.13.3",
 		"typescript": "5.9.3",
-		"vitest": "4.1.10"
+		"vitest": "4.1.11"
 	},
 	"license": "MIT",
 	"repository": {

package/packages/server/package.json

@@ -17,7 +17,7 @@
 	},
 	"devDependencies": {
 		"typescript": "5.9.3",
-		"vitest": "4.1.10",
+		"vitest": "4.1.11",
 		"@types/node": "24.13.3"
 	},
 	"license": "MIT",

package/packages/server/src/application-routes.ts

@@ -1,21 +1,93 @@
-import { RenderRoute, ServerRoute, type Route, type RenderRouteEntry } from '@octanejs/app-core';
+import { injectHtmlHead } from './web-html.ts';
+import {
+	RenderRoute,
+	ServerRoute,
+	type Route,
+	type RenderRouteEntry,
+} from '@octanejs/app-core';
 
 export function validateApplicationPath(path: string): string {
-	if (!/^\/[a-z][a-z0-9-]*$/.test(path) || ['auth','api','sites','sign-in','sign-up','forgot-password','reset-password','accept-invitation'].includes(path.slice(1))) throw new Error('Invalid application path.');
+	if (
+		path.length > 64 ||
+		!/^\/[a-z][a-z0-9-]*$/.test(path) ||
+		[
+			'setup',
+			'health',
+			'ready',
+			'assets',
+			'auth',
+			'api',
+			'sites',
+			'sign-in',
+			'sign-up',
+			'forgot-password',
+			'reset-password',
+			'accept-invitation',
+		].includes(path.slice(1))
+	)
+		throw new Error('Invalid application path.');
 	return path;
 }
 
-export function createApplicationRoutes(options: { readonly path: string; readonly entry: RenderRouteEntry; readonly publicRoot: boolean }): readonly Route[] {
+export function createApplicationRoutes(options: {
+	readonly path: string;
+	readonly entry: RenderRouteEntry;
+	readonly publicRoot: boolean;
+}): readonly Route[] {
 	const base = validateApplicationPath(options.path);
 	const paths = [
-		'/auth', '/auth/login', '/auth/register', '/auth/forgot-password', '/auth/reset-password', '/auth/accept-invitation', '/auth/mfa',
-		'/sign-in','/sign-up','/forgot-password','/reset-password','/accept-invitation',
-		base, base+'/:workspace', base+'/:workspace/:view',
+		'/auth',
+		'/auth/login',
+		'/auth/register',
+		'/auth/forgot-password',
+		'/auth/reset-password',
+		'/auth/accept-invitation',
+		'/auth/mfa',
+		'/sign-in',
+		'/sign-up',
+		'/forgot-password',
+		'/reset-password',
+		'/accept-invitation',
+		base,
+		base + '/:workspace',
+		base + '/:workspace/:view',
 		...(!options.publicRoot ? ['/', '/:workspace', '/:workspace/:view'] : []),
 	];
-	const routes: Route[] = paths.map(path => new RenderRoute({path,entry:options.entry}));
+	const routes: Route[] = paths.map(
+		(path) =>
+			new RenderRoute({
+				path,
+				entry: options.entry,
+				before: [
+					async (context, next) => {
+						context.state.set('flowdular.application.path', base);
+						const response = await next();
+						response.headers.set('cache-control', 'no-store');
+						return injectHtmlHead(
+							response,
+							`<script id="flowdular-application-data" type="application/json">${JSON.stringify(base)}</script>`,
+						);
+					},
+				],
+			}),
+	);
 	if (base !== '/app') {
-		for (const path of ['/app','/app/*legacyPath']) routes.push(new ServerRoute({path,methods:['GET','HEAD'],handler: context => new Response(null,{status:308,headers:{location:base+context.url.pathname.slice(4)+context.url.search,'cache-control':'no-store'}})}));
+		for (const path of ['/app', '/app/*legacyPath'])
+			routes.push(
+				new ServerRoute({
+					path,
+					methods: ['GET', 'HEAD'],
+					handler: (context) =>
+						new Response(null, {
+							status: 308,
+							headers: {
+								location:
+									base + context.url.pathname.slice(4) + context.url.search,
+								'cache-control': 'no-store',
+							},
+						}),
+				}),
+			);
 	}
 	return routes;
 }

package/packages/server/src/index.ts

@@ -1,5 +1,8 @@
 export { defineEndpoint } from './endpoint.ts';
-export { createApplicationRoutes, validateApplicationPath } from './application-routes.ts';
+export {
+	createApplicationRoutes,
+	validateApplicationPath,
+} from './application-routes.ts';
 export { trackResponseBody } from './response-lifetime.ts';
 export {
 	assertRouteConflicts,

package/packages/server/src/web-html.ts

@@ -5,11 +5,6 @@ export function webHtmlResponse(
 	data: unknown,
 	nonce?: string,
 ): Response {
-	if (
-		!response.body ||
-		!response.headers.get('content-type')?.includes('text/html')
-	)
-		return response;
 	const json = JSON.stringify({ url, data })
 		.replace(/</g, '\\u003c')
 		.replace(/\u2028/g, '\\u2028')
@@ -17,6 +12,15 @@ export function webHtmlResponse(
 	const attribute =
 		nonce && /^[a-zA-Z0-9+/=_-]+$/.test(nonce) ? ` nonce="${nonce}"` : '';
 	const insert = `<script id="flowdular-web-data" type="application/json"${attribute}>${json}</script><style${attribute}>.flowdular-splash{display:none!important}html,body,#root{background:initial}</style>`;
+	return injectHtmlHead(response, insert);
+}
+
+export function injectHtmlHead(response: Response, insert: string): Response {
+	if (
+		!response.body ||
+		!response.headers.get('content-type')?.includes('text/html')
+	)
+		return response;
 	let buffer = '';
 	let inserted = false;
 	const decoder = new TextDecoder();

package/packages/server/src/web.ts

@@ -1,3 +1,4 @@
+import { validateApplicationPath } from './application-routes.ts';
 import {
 	RenderRoute,
 	ServerRoute,
@@ -29,6 +30,10 @@ export type {
 const DATA_STATE = 'flowdular.web.data';
 const DATA_ACCEPT = 'application/vnd.flowdular.page+json';
 const RESERVED = new Set([
+	'setup',
+	'health',
+	'ready',
+	'assets',
 	'app',
 	'api',
 	'auth',
@@ -67,7 +72,7 @@ export function validateWebMounts(input: unknown): readonly WebMount[] {
 				/[\u0000-\u001f]/.test(value.tenantId) ||
 				typeof value.path !== 'string' ||
 				value.path.length > 256 ||
-				!/^\/[a-z0-9-]+(?:\/[a-z0-9-]+)*$/.test(value.path) ||
+				!/^(?:\/|\/[a-z0-9-]+(?:\/[a-z0-9-]+)*)$/.test(value.path) ||
 				RESERVED.has(value.path.split('/')[1]!) ||
 				(value.enabled !== undefined && typeof value.enabled !== 'boolean')
 			)
@@ -225,11 +230,22 @@ function failure(status: number): Response {
 export function createModuleWebRoutes(options: {
 	readonly modules: readonly WebModuleComposition[];
 	readonly mounts: readonly WebMount[];
+	readonly applicationPath?: string;
 	readonly resolveIdentity: (
 		context: Context,
 	) => WebIdentity | null | Promise<WebIdentity | null>;
 }): readonly Route[] {
-	const mounts = validateWebMounts(options.mounts);
+	const mounts = [...validateWebMounts(options.mounts)].sort(
+		(a, b) => b.path.length - a.path.length,
+	);
+	const applicationPath = validateApplicationPath(
+		options.applicationPath ?? '/app',
+	);
+	const reserved = [...RESERVED]
+		.map((segment) => '/' + segment)
+		.concat(applicationPath);
+	const within = (path: string, prefix: string) =>
+		path === prefix || path.startsWith(prefix + '/');
 	const surfaces = new Map<string, ModuleWebSurface>();
 	for (const module of options.modules) {
 		for (const surface of module.web ?? []) {
@@ -243,11 +259,32 @@ export function createModuleWebRoutes(options: {
 	}
 	const routes: Route[] = [];
 	for (const site of mounts) {
+		if (reserved.some((prefix) => within(site.path, prefix)))
+			invalid('mount overlaps application routes.');
+		const base = site.path === '/' ? '' : site.path;
 		const surface = surfaces.get(`${site.moduleId}/${site.surfaceId}`);
 		// A removed or disabled module must not fall through to a workspace route.
 		if (site.enabled && surface) {
 			for (const page of surface.pages) {
+				if (
+					site.path === '/' &&
+					(reserved.some((prefix) => within(page.path, prefix)) ||
+						mounts.some(
+							(other) => other.path !== '/' && within(page.path, other.path),
+						))
+				)
+					invalid('root page overlaps a reserved address.');
 				const before: Middleware = async (context, next) => {
+					if (
+						site.path === '/' &&
+						(reserved.some((prefix) => within(context.url.pathname, prefix)) ||
+							mounts.some(
+								(other) =>
+									other.path !== '/' &&
+									within(context.url.pathname, other.path),
+							))
+					)
+						return failure(404);
 					if (!['GET', 'HEAD'].includes(context.request.method))
 						return failure(405);
 					try {
@@ -270,8 +307,20 @@ export function createModuleWebRoutes(options: {
 							signal: context.request.signal,
 						});
 						if (result instanceof Response) {
-							result.headers.set('cache-control', 'no-store');
-							return result;
+							// Redirect/fetch response headers can be immutable.
+							const headers = new Headers(result.headers);
+							headers.set('cache-control', 'no-store');
+							headers.append('vary', 'Accept');
+							if (context.request.method === 'HEAD')
+								await result.body?.cancel();
+							return new Response(
+								context.request.method === 'HEAD' ? null : result.body,
+								{
+									status: result.status,
+									statusText: result.statusText,
+									headers,
+								},
+							);
 						}
 						const json = JSON.stringify(result);
 						if (
@@ -318,7 +367,7 @@ export function createModuleWebRoutes(options: {
 				};
 				routes.push(
 					new RenderRoute({
-						path: site.path + (page.path === '/' ? '' : page.path),
+						path: base + (page.path === '/' ? '' : page.path) || '/',
 						entry: page.entry,
 						...(page.layout ? { layout: page.layout } : {}),
 						before: [before],
@@ -338,9 +387,12 @@ export function createModuleWebRoutes(options: {
 			!surface.pages.some((page) => page.path === '/')
 		)
 			routes.push(fallback(site.path));
-		routes.push(fallback(site.path + '/*unmatched'));
+		routes.push(fallback(base + '/*unmatched'));
 	}
-	if (!mounts.some((site) => site.path === '/sites')) {
+	if (
+		mounts.some((site) => site.path.startsWith('/sites/')) &&
+		!mounts.some((site) => site.path === '/sites')
+	) {
 		routes.push(
 			new ServerRoute({
 				path: '/sites',

package/packages/ui/package.json

@@ -21,7 +21,7 @@
 	"devDependencies": {
 		"@tsrx/typescript-plugin": "0.3.120",
 		"typescript": "5.9.3",
-		"vitest": "4.1.10"
+		"vitest": "4.1.11"
 	},
 	"license": "MIT",
 	"repository": {

package/packages/coding-agent/package.json

@@ -1,44 +0,0 @@
-{
-	"name": "@flowdular/coding-agent",
-	"version": "0.1.0",
-	"type": "module",
-	"exports": {
-		".": "./src/index.ts"
-	},
-	"scripts": {
-		"typecheck": "tsc --noEmit -p tsconfig.json",
-		"test": "vitest run",
-		"sync-roles": "node --experimental-transform-types --disable-warning=ExperimentalWarning scripts/sync-roles.ts"
-	},
-	"dependencies": {
-		"@flowdular/ai-provider": "workspace:*",
-		"ai": "7.0.85",
-		"yaml": "2.9.0"
-	},
-	"devDependencies": {
-		"@flowdular/database-testing": "workspace:*",
-		"@types/node": "24.13.3",
-		"typescript": "5.9.3",
-		"vitest": "4.1.10"
-	},
-	"license": "MIT",
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/Flowdular/flowdular.git",
-		"directory": "packages/coding-agent"
-	},
-	"files": [
-		"src",
-		"schemas",
-		"dist",
-		"bin",
-		"public",
-		"module.json",
-		"migrations",
-		"translations",
-		"spec",
-		"README.md",
-		"LICENSE"
-	],
-	"private": true
-}

package/packages/coding-agent/src/drivers/byok.ts

@@ -1,322 +0,0 @@
-import {
-	mkdir,
-	readFile,
-	readdir,
-	rm,
-	stat,
-	writeFile,
-} from 'node:fs/promises';
-import { dirname, join } from 'node:path';
-import {
-	classifyProviderFailure,
-	normalizeUsage,
-	probeLanguageModel,
-	resolveLanguageModel,
-	type AiProviderConfiguration,
-} from '@flowdular/sdk/ai-provider';
-import {
-	jsonSchema,
-	stepCountIs,
-	streamText,
-	tool,
-	type ModelMessage,
-	type ToolSet,
-} from 'ai';
-import {
-	type CodingAgentAvailability,
-	type CodingAgentDriver,
-	type CodingAgentEvent,
-	type CodingAgentTurnRequest,
-	type FileChangeKind,
-} from '../types.ts';
-import {
-	resolveInsideWorkspace,
-	resolveReadableInsideWorkspace,
-	resolveWritableInsideWorkspace,
-	workspaceRelative,
-} from '../workspace.ts';
-
-export interface ByokDriverOptions {
-	readonly configuration: AiProviderConfiguration;
-	readonly maxSteps?: number;
-	readonly maxOutputTokens?: number;
-	readonly maxFileBytes?: number;
-	readonly maxListedFiles?: number;
-}
-
-const DEFAULT_MAX_STEPS = 24;
-const DEFAULT_MAX_OUTPUT_TOKENS = 8_192;
-const DEFAULT_MAX_FILE_BYTES = 128 * 1024;
-const DEFAULT_MAX_LISTED_FILES = 400;
-const IGNORED_DIRECTORIES = new Set(['node_modules', '.git', 'dist']);
-
-interface PendingEvent {
-	readonly event: CodingAgentEvent;
-}
-
-async function listFiles(
-	root: string,
-	directory: string,
-	limit: number,
-	found: string[],
-): Promise<void> {
-	if (found.length >= limit) return;
-	for (const entry of await readdir(directory, { withFileTypes: true })) {
-		if (found.length >= limit) return;
-		if (entry.name.startsWith('.') && entry.name !== '.ai') continue;
-		if (IGNORED_DIRECTORIES.has(entry.name)) continue;
-		const path = join(directory, entry.name);
-		if (entry.isDirectory()) await listFiles(root, path, limit, found);
-		else found.push(workspaceRelative(root, path));
-	}
-}
-
-/* The BYOK driver is the only backend a self-hosted sandbox can offer, so its
-   tools are the whole file surface the model gets: bounded to the session
-   workspace, size capped, and with no command execution. */
-export function createByokDriver(
-	options: ByokDriverOptions,
-): CodingAgentDriver {
-	const maxFileBytes = options.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES;
-	const maxListedFiles = options.maxListedFiles ?? DEFAULT_MAX_LISTED_FILES;
-
-	function workspaceTools(
-		workspacePath: string,
-		allowedPaths: readonly string[],
-		emit: (event: CodingAgentEvent) => void,
-	): ToolSet {
-		const record = (
-			name: string,
-			detail: string,
-			run: () => Promise<string>,
-		) => {
-			emit({ type: 'tool.started', tool: name, detail });
-			return run().then(
-				(value) => {
-					emit({ type: 'tool.completed', tool: name, detail, ok: true });
-					return value;
-				},
-				(error: unknown) => {
-					emit({ type: 'tool.completed', tool: name, detail, ok: false });
-					return `Error: ${error instanceof Error ? error.message : String(error)}`;
-				},
-			);
-		};
-		const changed = async (
-			path: string,
-			absolute: string,
-		): Promise<FileChangeKind> => {
-			try {
-				await stat(absolute);
-				return 'modified';
-			} catch {
-				return 'created';
-			}
-		};
-
-		return {
-			list_files: tool({
-				description:
-					'List the files of the session workspace, relative to its root.',
-				inputSchema: jsonSchema<{ directory?: string }>({
-					type: 'object',
-					properties: {
-						directory: {
-							type: 'string',
-							description: 'Optional subdirectory, relative to the workspace.',
-						},
-					},
-					additionalProperties: false,
-				}),
-				execute: (input) =>
-					record('list_files', input.directory ?? '.', async () => {
-						const start = resolveInsideWorkspace(
-							workspacePath,
-							input.directory ?? '.',
-						);
-						const found: string[] = [];
-						await listFiles(workspacePath, start, maxListedFiles, found);
-						return found.sort().join('\n') || '(empty)';
-					}),
-			}),
-			read_file: tool({
-				description: 'Read one file of the session workspace.',
-				inputSchema: jsonSchema<{ path: string }>({
-					type: 'object',
-					properties: { path: { type: 'string' } },
-					required: ['path'],
-					additionalProperties: false,
-				}),
-				execute: (input) =>
-					record('read_file', input.path, async () => {
-						const absolute = await resolveReadableInsideWorkspace(
-							workspacePath,
-							input.path,
-						);
-						const content = await readFile(absolute, 'utf8');
-						return content.length > maxFileBytes
-							? `${content.slice(0, maxFileBytes)}\n… truncated at ${maxFileBytes} bytes.`
-							: content;
-					}),
-			}),
-			write_file: tool({
-				description:
-					'Create or replace one file of the session workspace with the complete new content.',
-				inputSchema: jsonSchema<{ path: string; content: string }>({
-					type: 'object',
-					properties: {
-						path: { type: 'string' },
-						content: { type: 'string' },
-					},
-					required: ['path', 'content'],
-					additionalProperties: false,
-				}),
-				execute: (input) =>
-					record('write_file', input.path, async () => {
-						if (input.content.length > maxFileBytes) {
-							throw new Error(
-								`File content exceeds ${maxFileBytes} bytes for this workspace.`,
-							);
-						}
-						const absolute = await resolveWritableInsideWorkspace(
-							workspacePath,
-							input.path,
-							allowedPaths,
-						);
-						const change = await changed(input.path, absolute);
-						await mkdir(dirname(absolute), { recursive: true });
-						await writeFile(absolute, input.content, 'utf8');
-						emit({
-							type: 'file.changed',
-							path: workspaceRelative(workspacePath, absolute),
-							change,
-						});
-						return `Wrote ${workspaceRelative(workspacePath, absolute)}.`;
-					}),
-			}),
-			delete_file: tool({
-				description: 'Delete one file of the session workspace.',
-				inputSchema: jsonSchema<{ path: string }>({
-					type: 'object',
-					properties: { path: { type: 'string' } },
-					required: ['path'],
-					additionalProperties: false,
-				}),
-				execute: (input) =>
-					record('delete_file', input.path, async () => {
-						const absolute = await resolveWritableInsideWorkspace(
-							workspacePath,
-							input.path,
-							allowedPaths,
-						);
-						await rm(absolute, { force: true });
-						emit({
-							type: 'file.changed',
-							path: workspaceRelative(workspacePath, absolute),
-							change: 'deleted',
-						});
-						return `Deleted ${workspaceRelative(workspacePath, absolute)}.`;
-					}),
-			}),
-		};
-	}
-
-	return {
-		id: 'byok',
-		label: 'Bring your own key',
-		kind: 'byok',
-		requiresLoopback: false,
-		description:
-			'Vercel AI SDK provider driving the sandbox file tools. The only backend a self-hosted sandbox can offer.',
-
-		async probe(): Promise<CodingAgentAvailability> {
-			if (!options.configuration.credential.trim()) {
-				return {
-					available: false,
-					detail: 'No provider credential is configured for this sandbox.',
-					version: null,
-				};
-			}
-			const readiness = await probeLanguageModel(options.configuration);
-			return {
-				available: readiness.healthy,
-				detail: readiness.healthy
-					? `${options.configuration.kind} responded in ${readiness.latencyMs} ms.`
-					: (readiness.errorCode ?? 'The provider probe failed.'),
-				version: options.configuration.model,
-			};
-		},
-
-		async *run(
-			request: CodingAgentTurnRequest,
-		): AsyncIterable<CodingAgentEvent> {
-			yield {
-				type: 'turn.started',
-				driver: 'byok',
-				role: request.role,
-				resumeId: request.resumeId ?? null,
-			};
-
-			const queue: PendingEvent[] = [];
-			const emit = (event: CodingAgentEvent) => queue.push({ event });
-			const messages: ModelMessage[] = [
-				...(request.history ?? []).map((message) => ({
-					role: message.role,
-					content: message.text,
-				})),
-				{ role: 'user' as const, content: request.prompt },
-			];
-
-			try {
-				const result = streamText({
-					model: resolveLanguageModel({
-						...options.configuration,
-						...(request.model ? { model: request.model } : {}),
-					}),
-					system: request.systemInstruction,
-					messages,
-					maxOutputTokens: options.maxOutputTokens ?? DEFAULT_MAX_OUTPUT_TOKENS,
-					maxRetries: 1,
-					...(request.signal ? { abortSignal: request.signal } : {}),
-					stopWhen: stepCountIs(options.maxSteps ?? DEFAULT_MAX_STEPS),
-					tools: workspaceTools(
-						request.workspacePath,
-						/* An omitted role boundary is no write authority. The sandbox always
-						   supplies an explicit allowlist for its selected specialist. */
-						request.allowedPaths ?? [],
-						emit,
-					),
-				});
-
-				let text = '';
-				let usage = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
-				for await (const part of result.fullStream) {
-					while (queue.length > 0) yield queue.shift()!.event;
-					if (part.type === 'text-delta') text += part.text;
-					if (part.type === 'finish') usage = normalizeUsage(part.totalUsage);
-					if (part.type === 'error') throw part.error;
-				}
-				while (queue.length > 0) yield queue.shift()!.event;
-				if (text.trim()) yield { type: 'assistant.message', text: text.trim() };
-				yield {
-					type: 'turn.completed',
-					resumeId: request.resumeId ?? null,
-					usage,
-					costUsd: null,
-					finishReason: 'stop',
-				};
-			} catch (error) {
-				while (queue.length > 0) yield queue.shift()!.event;
-				const failure = classifyProviderFailure(error);
-				yield { type: 'error', code: failure.code, message: failure.message };
-				yield {
-					type: 'turn.completed',
-					resumeId: request.resumeId ?? null,
-					usage: { inputTokens: 0, outputTokens: 0, totalTokens: 0 },
-					costUsd: null,
-					finishReason: request.signal?.aborted ? 'aborted' : 'error',
-				};
-			}
-		},
-	};
-}