@flowdular/sandbox 0.2.7 → 0.2.9

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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@flowdular/sandbox",
-	"version": "0.2.7",
+	"version": "0.2.9",
 	"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.2.4"
 	},
 	"imports": {
 		"#coding-agent": "./internal/coding-agent/src/index.ts"

package/src/server/attachments.ts

@@ -1,5 +1,6 @@
+import { withSessionLock } from './session-lock.ts';
 import { randomUUID } from 'node:crypto';
-import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { lstat, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { isAbsolute, join, relative, resolve } from 'node:path';
 import {
 	readSession,
@@ -210,28 +211,26 @@ export async function addAttachment(
 			`Attachments are limited to ${MAX_ATTACHMENT_BYTES / (1024 * 1024)} MB.`,
 		);
 	}
-	const current = await readSession(workspaceRoot, session.id);
-	if (current.attachments.length >= MAX_ATTACHMENTS) {
-		throw new SandboxSetupError(
-			'ATTACHMENT_LIMIT_REACHED',
-			`A session may hold at most ${MAX_ATTACHMENTS} attachments.`,
-		);
-	}
-	const type = resolveType(input.name, input.bytes);
-	const meta: SessionAttachment = {
-		id: randomUUID(),
-		name: uniqueName(safeAttachmentName(input.name), current.attachments),
-		kind: type.kind,
-		size: input.bytes.byteLength,
-		addedAt: Date.now(),
-	};
-	const paths = sessionPaths(workspaceRoot, current.id, current.moduleSuffix);
-	await mkdir(paths.attachments, { recursive: true });
-	await mkdir(paths.workspaceAttachments, { recursive: true });
-	await writeFile(storedPath(paths, meta), input.bytes);
-	await writeFile(workspacePath(paths, meta), input.bytes);
-	await updateSession(workspaceRoot, current.id, {
-		attachments: [...current.attachments, meta],
+	let meta!: SessionAttachment;
+	await updateSession(workspaceRoot, session.id, async (current) => {
+		if (current.attachments.length >= MAX_ATTACHMENTS) {
+			throw new SandboxSetupError(
+				'ATTACHMENT_LIMIT_REACHED',
+				`A session may hold at most ${MAX_ATTACHMENTS} attachments.`,
+			);
+		}
+		const type = resolveType(input.name, input.bytes);
+		meta = {
+			id: randomUUID(),
+			name: uniqueName(safeAttachmentName(input.name), current.attachments),
+			kind: type.kind,
+			size: input.bytes.byteLength,
+			addedAt: Date.now(),
+		};
+		const paths = sessionPaths(workspaceRoot, current.id, current.moduleSuffix);
+		await mkdir(paths.attachments, { recursive: true });
+		await writeFile(storedPath(paths, meta), input.bytes);
+		return { attachments: [...current.attachments, meta] };
 	});
 	return meta;
 }
@@ -263,13 +262,15 @@ export async function removeAttachment(
 	attachmentId: string,
 ): Promise<void> {
 	assertAttachmentId(attachmentId);
-	const current = await readSession(workspaceRoot, session.id);
-	const meta = findAttachment(current.attachments, attachmentId);
-	const paths = sessionPaths(workspaceRoot, current.id, current.moduleSuffix);
-	await rm(storedPath(paths, meta), { force: true });
-	await rm(workspacePath(paths, meta), { force: true });
-	await updateSession(workspaceRoot, current.id, {
-		attachments: current.attachments.filter((item) => item.id !== attachmentId),
+	await updateSession(workspaceRoot, session.id, async (current) => {
+		const meta = findAttachment(current.attachments, attachmentId);
+		const paths = sessionPaths(workspaceRoot, current.id, current.moduleSuffix);
+		await rm(storedPath(paths, meta), { force: true });
+		return {
+			attachments: current.attachments.filter(
+				(item) => item.id !== attachmentId,
+			),
+		};
 	});
 }
 
@@ -294,6 +295,42 @@ export async function readAttachment(
 	};
 }
 
+/* The host prepares a stable turn snapshot before path enforcement begins.
+   Uploads/removals only change the private store, never an active workspace. */
+export async function materializeAttachments(
+	workspaceRoot: string,
+	session: SandboxSession,
+): Promise<readonly SessionAttachment[]> {
+	return withSessionLock(workspaceRoot, session.id, async () => {
+		const current = await readSession(workspaceRoot, session.id);
+		const paths = sessionPaths(workspaceRoot, current.id, current.moduleSuffix);
+		const reference = join(paths.workspace, 'reference');
+		const info = await lstat(reference).catch(
+			(error: NodeJS.ErrnoException) => {
+				if (error.code === 'ENOENT') return null;
+				throw error;
+			},
+		);
+		if (info && !info.isDirectory())
+			throw new SandboxSetupError(
+				'ATTACHMENT_REFERENCE_INVALID',
+				'The session reference directory is not a regular directory.',
+			);
+		await mkdir(reference, { recursive: true });
+		// rm unlinks a planted attachment symlink instead of following it.
+		await rm(paths.workspaceAttachments, { recursive: true, force: true });
+		await mkdir(paths.workspaceAttachments, { recursive: true });
+		for (const meta of current.attachments) {
+			await writeFile(
+				workspacePath(paths, meta),
+				await readFile(storedPath(paths, meta)),
+				{ flag: 'wx' },
+			);
+		}
+		return current.attachments;
+	});
+}
+
 /* The note prepended to a turn's instruction when the session has attachments.
    The files are already in reference/attachments/, so the agent opens them with
    its normal file tools; the path plus this note is the whole contract. */

package/src/server/reference.ts

@@ -1,3 +1,4 @@
+import { materializeSdkReference } from './sdk-reference.ts';
 import { createRequire } from 'node:module';
 import {
 	access,
@@ -104,6 +105,7 @@ Read-only copies of the platform contracts this session must implement against.
 Never edit anything in this directory: it is not part of the module and it is
 not ejected.
 
+- sdk: complete installed SDK package and module sources, with package.json exports. Read these real files instead of following node_modules symlinks outside the workspace. Present when the host application has an installed SDK.
 - packages/server: defineEndpoint, HTTP helpers, and the endpoint identity contract.
 - packages/client: the client contribution contract (createClientContribution, ModuleClientContext), shell slots, and shell state.
 - packages/contracts: module manifest, spec, and blueprint schemas.
@@ -166,6 +168,7 @@ export async function materializeReference(
 					.some((segment) => EXCLUDED.has(segment)),
 		}).catch(() => undefined);
 	}
+	await materializeSdkReference(workspaceRoot, sessionWorkspace);
 	const skills = await listSkills(workspaceRoot);
 	await writeFile(
 		join(sessionWorkspace, 'reference/README.md'),
@@ -183,6 +186,7 @@ export async function writeAgentPointer(
 	fileName: 'CLAUDE.md' | 'AGENTS.md',
 	roleName: string,
 	skill?: string | null,
+	hasSdk = false,
 ): Promise<void> {
 	await writeFile(
 		join(sessionWorkspace, fileName),
@@ -194,6 +198,11 @@ export async function writeAgentPointer(
 			skill
 				? `- Read only reference/skills/${skill}/SKILL.md for this task. Do not load other skills or the whole reference catalog.`
 				: '- No matching task skill is installed. Do not load unrelated skills.',
+			...(hasSdk
+				? [
+						'- Read installed SDK sources at reference/sdk; use its package.json exports to locate an API. Do not follow external node_modules symlinks or scan the whole SDK.',
+					]
+				: []),
 			'- Write only inside your module directory under modules/, in the paths the instruction allows. Everything under reference/ is read-only.',
 			'- End your final message with the HANDOFF line the instruction describes.',
 			'',

package/src/server/routes.ts

@@ -1266,9 +1266,8 @@ export function createSandboxRoutes(
 		},
 	});
 
-	/* Attachments are copied into the session workspace at upload time, so the
-	   coding agent, which may only read inside the workspace, opens them by name
-	   from reference/attachments/. The bytes never leave this origin. */
+	/* Uploads stay outside the active workspace. Each turn copies its attachment
+	   snapshot into reference/attachments/ before the path guard starts. */
 	const addSandboxAttachment = new ServerRoute({
 		path: '/sandbox/api/sessions/:id/attachments',
 		methods: ['POST'],

package/src/server/sdk-reference.ts

@@ -0,0 +1,99 @@
+import { createRequire } from 'node:module';
+import {
+	cp,
+	lstat,
+	mkdir,
+	mkdtemp,
+	readFile,
+	realpath,
+	rename,
+	rm,
+	writeFile,
+} from 'node:fs/promises';
+import { dirname, join, relative } from 'node:path';
+import { SandboxSetupError } from './workspace-root.ts';
+
+const EXCLUDED = new Set([
+	'node_modules',
+	'dist',
+	'.git',
+	'.flowdular',
+	'.turbo',
+]);
+
+/* Published SDK contents are immutable. Cache a real copy per session and SDK
+   installation, outside the module graph. Never widen agent filesystem access. */
+export async function materializeSdkReference(
+	workspaceRoot: string,
+	sessionWorkspace: string,
+): Promise<boolean> {
+	let source: string;
+	try {
+		const require = createRequire(join(workspaceRoot, 'platform/package.json'));
+		source = await realpath(
+			dirname(require.resolve('@flowdular/sdk/package.json')),
+		);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === 'MODULE_NOT_FOUND')
+			return false;
+		throw error;
+	}
+	const manifest = await readFile(join(source, 'package.json'), 'utf8');
+	const reference = join(sessionWorkspace, 'reference');
+	const info = await lstat(reference).catch((error: NodeJS.ErrnoException) => {
+		if (error.code === 'ENOENT') return null;
+		throw error;
+	});
+	if (info && !info.isDirectory())
+		throw new SandboxSetupError(
+			'SDK_REFERENCE_INVALID',
+			'The session reference directory is not a regular directory.',
+		);
+	await mkdir(reference, { recursive: true });
+	const target = join(reference, 'sdk');
+	// Metadata belongs to the host, outside the agent workspace and its guard.
+	const marker = join(dirname(sessionWorkspace), 'sdk-reference.json');
+	const identity = JSON.stringify({ source, manifest });
+	try {
+		if (
+			(await lstat(target)).isDirectory() &&
+			(await lstat(join(target, 'package.json'))).isFile() &&
+			(await readFile(marker, 'utf8')) === identity &&
+			(await readFile(join(target, 'package.json'), 'utf8')) === manifest
+		)
+			return true;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+	}
+	const staging = await mkdtemp(
+		join(dirname(sessionWorkspace), 'sdk-reference-'),
+	);
+	try {
+		await writeFile(join(staging, 'package.json'), manifest);
+		for (const member of ['packages', 'modules', 'modules.json']) {
+			const from = join(source, member);
+			try {
+				await lstat(from);
+			} catch (error) {
+				if ((error as NodeJS.ErrnoException).code === 'ENOENT') continue;
+				throw error;
+			}
+			await cp(from, join(staging, member), {
+				recursive: true,
+				filter: async (path) => {
+					const parts = relative(source, path).split('/');
+					if (parts.some((part) => EXCLUDED.has(part) || part.startsWith('.')))
+						return false;
+					// A dependency symlink must never survive inside the snapshot.
+					return !(await lstat(path)).isSymbolicLink();
+				},
+			});
+		}
+		await rm(target, { recursive: true, force: true });
+		await rename(staging, target);
+		await writeFile(marker, identity);
+	} finally {
+		await rm(staging, { recursive: true, force: true });
+	}
+	return true;
+}

package/src/server/session-lock.ts

@@ -0,0 +1,26 @@
+import { resolve } from 'node:path';
+
+/* Session metadata and operator-owned attachment snapshots share one queue.
+   Failed work releases the next caller and idle sessions retain no lock. */
+const pending = new Map<string, Promise<void>>();
+
+export async function withSessionLock<T>(
+	workspaceRoot: string,
+	sessionId: string,
+	work: () => Promise<T>,
+): Promise<T> {
+	const key = `${resolve(workspaceRoot)}\0${sessionId}`;
+	const previous = pending.get(key);
+	let release!: () => void;
+	const current = new Promise<void>((done) => {
+		release = done;
+	});
+	pending.set(key, current);
+	await previous;
+	try {
+		return await work();
+	} finally {
+		release();
+		if (pending.get(key) === current) pending.delete(key);
+	}
+}

package/src/server/sessions.ts

@@ -1,3 +1,4 @@
+import { withSessionLock } from './session-lock.ts';
 import { randomUUID } from 'node:crypto';
 import {
 	access,
@@ -588,16 +589,23 @@ export async function listSessions(
 	return sessions.sort((left, right) => right.updatedAt - left.updatedAt);
 }
 
+type SessionPatch = Partial<Omit<SandboxSession, 'id' | 'createdAt'>>;
+
 export async function updateSession(
 	workspaceRoot: string,
 	sessionId: string,
-	patch: Partial<Omit<SandboxSession, 'id' | 'createdAt'>>,
+	patch:
+		| SessionPatch
+		| ((current: SandboxSession) => SessionPatch | Promise<SessionPatch>),
 ): Promise<SandboxSession> {
-	const current = await readSession(workspaceRoot, sessionId);
-	return writeSession(workspaceRoot, {
-		...current,
-		...patch,
-		updatedAt: Date.now(),
+	return withSessionLock(workspaceRoot, sessionId, async () => {
+		const current = await readSession(workspaceRoot, sessionId);
+		const updates = typeof patch === 'function' ? await patch(current) : patch;
+		return writeSession(workspaceRoot, {
+			...current,
+			...updates,
+			updatedAt: Date.now(),
+		});
 	});
 }
 

package/src/server/turns.ts

@@ -1,3 +1,4 @@
+import { materializeSdkReference } from './sdk-reference.ts';
 import { spawn } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import {
@@ -28,7 +29,10 @@ import {
 	moduleReviewRevision,
 	recordAutoReview,
 } from './auto-review.ts';
-import { attachmentInstruction } from './attachments.ts';
+import {
+	attachmentInstruction,
+	materializeAttachments,
+} from './attachments.ts';
 import { captureCheckpoint } from './checkpoints.ts';
 import { guardAgentPaths } from './path-guard.ts';
 import type { SandboxConfiguration } from './config.ts';
@@ -535,7 +539,7 @@ export async function* runTurn(
 	context: TurnContext,
 	input: TurnInput,
 ): AsyncGenerator<ChatEntry, TurnOutcome> {
-	const session = await readSession(context.workspaceRoot, input.sessionId);
+	let session = await readSession(context.workspaceRoot, input.sessionId);
 	const paths = sessionPaths(
 		context.workspaceRoot,
 		session.id,
@@ -576,6 +580,14 @@ export async function* runTurn(
 	const driverId = input.driver ?? session.driver;
 	const driver = await context.registry.resolve(driverId);
 
+	session = {
+		...session,
+		attachments: await materializeAttachments(context.workspaceRoot, session),
+	};
+	const hasSdk = await materializeSdkReference(
+		context.workspaceRoot,
+		paths.workspace,
+	);
 	const attachmentNote = attachmentInstruction(session.attachments);
 
 	yield await appendChatEntry(context.workspaceRoot, session, {
@@ -671,6 +683,11 @@ export async function* runTurn(
 							)}. This turn is yours in modules/${active.directory} only; another specialist takes the turn for the others. Each module is a project of this pnpm workspace, so a draft that imports another draft resolves the session copy.`,
 					]
 				: []),
+			...(hasSdk
+				? [
+						'Read the actual installed SDK under reference/sdk/packages and reference/sdk/modules. Its package.json maps public exports. These are readable copies inside the workspace; do not follow external SDK symlinks. Search only the API needed for the current task.',
+					]
+				: []),
 			'reference/ is read-only. Consult only the code and references needed for this task; do not preload its catalog.',
 			'Other module.json files under modules/ describe the dependency graph. Only the draft module directories have sources you may change.',
 			...(active.kind === 'edit'
@@ -685,6 +702,7 @@ export async function* runTurn(
 		driverId === 'claude-code' ? 'CLAUDE.md' : 'AGENTS.md',
 		role.name,
 		skill,
+		hasSdk,
 	);
 
 	const history = historyFrom(await readChat(context.workspaceRoot, session));

package/src/server/workspace-install.ts

@@ -4,6 +4,7 @@ import { access, cp, readFile, readdir, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { createRequire } from 'node:module';
 import type { SessionModule } from './sessions.ts';
+import { parseDocument } from 'yaml';
 
 export interface InstallResult {
 	readonly ran: boolean;
@@ -36,10 +37,6 @@ async function packageName(directory: string): Promise<string | null> {
 	}
 }
 
-function yamlString(value: string): string {
-	return `'${value.replace(/'/g, "''")}'`;
-}
-
 /* A session workspace is a pnpm workspace of its own: the draft modules are its
    projects, every other workspace package is linked to the live checkout, and
    the host lockfile seeds the resolution so the session installs exactly the
@@ -57,7 +54,7 @@ export async function materializeSessionWorkspace(options: {
 		);
 		if (name) draft.add(name);
 	}
-	const overrides: string[] = [];
+	const overrides: Record<string, string> = {};
 	for (const group of ['packages', 'modules']) {
 		let entries: readonly string[] = [];
 		try {
@@ -69,9 +66,7 @@ export async function materializeSessionWorkspace(options: {
 			const directory = join(options.workspaceRoot, group, entry);
 			const name = await packageName(directory);
 			if (!name || draft.has(name)) continue;
-			overrides.push(
-				`  ${yamlString(name)}: ${yamlString(`link:${directory}`)}`,
-			);
+			overrides[name] = `link:${directory}`;
 		}
 	}
 
@@ -89,7 +84,7 @@ export async function materializeSessionWorkspace(options: {
 		if (typeof sdk.version !== 'string')
 			throw new Error('Invalid installed SDK version.');
 		sdkVersion = sdk.version;
-		overrides.push(`  '@flowdular/sdk': ${yamlString(`link:${sdkRoot}`)}`);
+		overrides['@flowdular/sdk'] = `link:${sdkRoot}`;
 	} catch (error) {
 		if (
 			!['MODULE_NOT_FOUND', 'ERR_PACKAGE_PATH_NOT_EXPORTED'].includes(
@@ -132,29 +127,23 @@ export async function materializeSessionWorkspace(options: {
 		join(options.workspaceRoot, 'pnpm-workspace.yaml'),
 		'utf8',
 	).catch(() => '');
-	const carried = hostWorkspace
-		.split('\n')
-		.filter(
-			(line) =>
-				!/^(packages|overrides):/.test(line) &&
-				!/^\s+-\s+(platform|modules\/\*|packages\/\*)\s*$/.test(line),
-		)
-		.join('\n')
-		.trim();
+	// Edit YAML structurally so lists, custom package globs and host overrides
+	// cannot spill into an unrelated setting when a top-level key is replaced.
+	const workspaceDocument = parseDocument(hostWorkspace);
+	if (workspaceDocument.errors.length > 0) throw workspaceDocument.errors[0];
+	workspaceDocument.set('packages', ['modules/*']);
+	workspaceDocument.set('allowUnusedPatches', true);
+	for (const name of draft) {
+		if (workspaceDocument.hasIn(['overrides', name])) {
+			workspaceDocument.deleteIn(['overrides', name]);
+		}
+	}
+	for (const [name, target] of Object.entries(overrides)) {
+		workspaceDocument.setIn(['overrides', name], target);
+	}
 	await writeFile(
 		join(options.sessionWorkspace, 'pnpm-workspace.yaml'),
-		`${[
-			'packages:',
-			'  - modules/*',
-			/* Host patches travel along even when no draft depends on the patched
-			   package; pnpm must not treat that as an error. */
-			'allowUnusedPatches: true',
-			carried,
-			'overrides:',
-			...overrides,
-		]
-			.filter(Boolean)
-			.join('\n')}\n`,
+		workspaceDocument.toString(),
 		'utf8',
 	);
 	for (const shared of ['pnpm-lock.yaml', 'patches']) {