@flowdular/sandbox 0.2.7 → 0.2.8

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@flowdular/sandbox",
-	"version": "0.2.7",
+	"version": "0.2.8",
 	"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",

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));