@flowdular/sandbox 0.2.6 → 0.2.8

package/src/client/locales/en.json

@@ -257,6 +257,7 @@
 	"chat.role": "Role",
 	"chat.targetModule": "Target module",
 	"chat.auto": "Auto",
+	"chat.settings": "Settings",
 	"chat.autoHandoff": "Continue handoffs automatically",
 	"chat.stop": "Stop",
 	"chat.send": "Send",
@@ -480,8 +481,27 @@
 	"models.save": "Save",
 	"models.saved": "Model settings saved.",
 	"models.error": "Could not save model settings.",
+	"chat.activity.updated": "Last update {seconds}s ago",
+	"chat.activity.quiet": "No update for {seconds}s. The agent may still be working.",
 	"chat.activity.thinking": "Agent is thinking…",
 	"chat.activity.responding": "Agent is preparing a response…",
 	"chat.fresh": "Fresh agent context",
-	"chat.freshHelp": "The next message starts a fresh context with the brief and recent messages. Draft files, specification and sandbox history are preserved."
+	"chat.freshHelp": "The next message starts a fresh context with the brief and recent messages. Draft files, specification and sandbox history are preserved.",
+	"chat.tool.name": "Tool",
+	"chat.tool.detail": "Target or command",
+	"chat.tool.result": "Completion detail",
+	"chat.tool.noDetail": "No detail provided",
+	"chat.tool.duration": "{seconds}s",
+	"chat.tool.action.read": "Read file",
+	"chat.tool.action.edit": "Edit file",
+	"chat.tool.action.write": "Write file",
+	"chat.tool.action.delete": "Delete file",
+	"chat.tool.action.list": "Find files",
+	"chat.tool.action.search": "Search",
+	"chat.tool.action.command": "Run command",
+	"chat.tool.action.tool": "Tool call",
+	"chat.tool.status.done": "Done",
+	"chat.tool.status.failed": "Failed",
+	"chat.tool.status.running": "Running",
+	"chat.tool.status.unknown": "No result"
 }

package/src/client/locales/pl.json

@@ -257,6 +257,7 @@
 	"chat.role": "Rola",
 	"chat.targetModule": "Moduł docelowy",
 	"chat.auto": "Automatycznie",
+	"chat.settings": "Ustawienia",
 	"chat.autoHandoff": "Automatycznie kontynuuj przekazania",
 	"chat.stop": "Zatrzymaj",
 	"chat.send": "Wyślij",
@@ -480,8 +481,27 @@
 	"models.save": "Zapisz",
 	"models.saved": "Zapisano ustawienia modeli.",
 	"models.error": "Nie udało się zapisać ustawień modeli.",
+	"chat.activity.updated": "Ostatnia aktualizacja {seconds}s temu",
+	"chat.activity.quiet": "Brak aktualizacji od {seconds}s. Agent może nadal pracować.",
 	"chat.activity.thinking": "Agent analizuje zadanie…",
 	"chat.activity.responding": "Agent przygotowuje odpowiedź…",
 	"chat.fresh": "Świeży kontekst agenta",
-	"chat.freshHelp": "Następna wiadomość rozpocznie nowy kontekst z briefem i ostatnimi wiadomościami. Pliki, specyfikacja i historia sandboxa pozostaną zachowane."
+	"chat.freshHelp": "Następna wiadomość rozpocznie nowy kontekst z briefem i ostatnimi wiadomościami. Pliki, specyfikacja i historia sandboxa pozostaną zachowane.",
+	"chat.tool.name": "Narzędzie",
+	"chat.tool.detail": "Plik lub polecenie",
+	"chat.tool.result": "Szczegóły zakończenia",
+	"chat.tool.noDetail": "Brak szczegółów",
+	"chat.tool.duration": "{seconds}s",
+	"chat.tool.action.read": "Odczyt pliku",
+	"chat.tool.action.edit": "Edycja pliku",
+	"chat.tool.action.write": "Zapis pliku",
+	"chat.tool.action.delete": "Usunięcie pliku",
+	"chat.tool.action.list": "Wyszukiwanie plików",
+	"chat.tool.action.search": "Wyszukiwanie",
+	"chat.tool.action.command": "Polecenie",
+	"chat.tool.action.tool": "Narzędzie",
+	"chat.tool.status.done": "Gotowe",
+	"chat.tool.status.failed": "Błąd",
+	"chat.tool.status.running": "W toku",
+	"chat.tool.status.unknown": "Brak wyniku"
 }

package/src/client/transcript.ts

@@ -0,0 +1,110 @@
+import type { ChatEntry } from '../server/sessions.ts';
+
+export interface TranscriptRow {
+	readonly key: number;
+	entry: ChatEntry;
+	started?: ChatEntry;
+	pending: boolean;
+}
+
+/* Pair calls by provider identity, including parallel calls to the same file.
+   Old transcripts without ids are paired only with one unambiguous pending call.
+   This is presentation only: persisted events and their full details stay intact. */
+export function transcriptRows(entries: readonly ChatEntry[]): TranscriptRow[] {
+	const rows: TranscriptRow[] = [];
+	const calls = new Map<string, TranscriptRow>();
+	const pending = new Set<TranscriptRow>();
+	const closeTurn = () => {
+		for (const row of pending) row.pending = false;
+		pending.clear();
+		calls.clear();
+	};
+	for (const entry of entries) {
+		const event = entry.event;
+		if (
+			entry.kind === 'user' ||
+			entry.handoff ||
+			event?.type === 'turn.started' ||
+			event?.type === 'turn.completed'
+		)
+			closeTurn();
+		if (event?.type === 'reasoning' && !event.text.trim()) continue;
+		if (event?.type === 'tool.completed') {
+			let start = event.callId ? calls.get(event.callId) : undefined;
+			if (!event.callId && pending.size === 1) {
+				const candidate = pending.values().next().value!;
+				const original = candidate.entry.event;
+				if (
+					original?.type === 'tool.started' &&
+					!original.callId &&
+					(event.tool === original.tool || event.tool === 'tool') &&
+					(!event.detail || event.detail === original.detail)
+				)
+					start = candidate;
+			}
+			if (
+				start &&
+				start.entry.role === entry.role &&
+				start.entry.module === entry.module
+			) {
+				start.started = start.entry;
+				start.entry = entry;
+				start.pending = false;
+				pending.delete(start);
+				if (event.callId) calls.delete(event.callId);
+				continue;
+			}
+		}
+		const row: TranscriptRow = {
+			key: entry.sequence,
+			entry,
+			pending: event?.type === 'tool.started',
+		};
+		rows.push(row);
+		if (event?.type === 'tool.started') {
+			pending.add(row);
+			if (event.callId) calls.set(event.callId, row);
+		}
+	}
+	return rows;
+}
+
+export function shortToolDetail(detail: string): string {
+	if (!/^(?:\/|[A-Za-z]:[\\/]|modules[\\/])/.test(detail)) return detail;
+	return detail
+		.replaceAll('\\', '/')
+		.replace(
+			/^.*?\/(?:\.flowdular|\.coreloom)\/sandbox\/sessions\/[^/]+\/workspace\//,
+			'',
+		)
+		.replace(/^modules\//, '');
+}
+
+export function toolAction(name: string): string {
+	switch (name.toLowerCase()) {
+		case 'read':
+		case 'read_file':
+			return 'read';
+		case 'edit':
+		case 'multiedit':
+		case 'update':
+			return 'edit';
+		case 'write':
+		case 'write_file':
+		case 'create':
+			return 'write';
+		case 'delete_file':
+		case 'delete':
+			return 'delete';
+		case 'glob':
+		case 'list_files':
+			return 'list';
+		case 'grep':
+			return 'search';
+		case 'bash':
+		case 'command':
+			return 'command';
+		default:
+			return 'tool';
+	}
+}

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/auto-review.ts

@@ -9,6 +9,7 @@ import {
 	writeFile,
 } from 'node:fs/promises';
 import { basename, join } from 'node:path';
+import { referenceSource } from './reference.ts';
 import {
 	basePathOf,
 	modulePathOf,
@@ -107,7 +108,7 @@ export async function prepareAutoReview(
 	const skill = join(paths.workspace, 'reference', 'skills', 'auto-review');
 	await mkdir(skill, { recursive: true });
 	await cp(
-		join(workspaceRoot, '.ai', 'skills', 'auto-review', 'SKILL.md'),
+		await referenceSource(workspaceRoot, '.ai/skills/auto-review/SKILL.md'),
 		join(skill, 'SKILL.md'),
 	);
 }

package/src/server/gate-repair.ts

@@ -0,0 +1,88 @@
+import { matchesGlob } from 'node:path';
+import type { AgentRoleDefinition } from '#coding-agent';
+import type { GateResult } from './gates.ts';
+
+interface DiagnosticPath {
+	path: string;
+	module: string;
+}
+
+/* Read diagnostic locations, never instructions embedded in output. Manifest
+   reports name the module; their issues name the file that actually failed. */
+function locations(gate: GateResult, activeModule: string): DiagnosticPath[] {
+	const module = gate.module ?? activeModule;
+	const output = gate.output.slice(0, 16_000);
+	try {
+		const result = JSON.parse(
+			output.slice(output.indexOf('{'), output.lastIndexOf('}') + 1),
+		);
+		const reports = result?.error?.details?.reports;
+		if (Array.isArray(reports)) {
+			return reports.flatMap((report) => {
+				const target =
+					typeof report.file === 'string'
+						? (/(?:^|\/)modules\/([a-z0-9-]+)\/module\.json$/.exec(
+								report.file,
+							)?.[1] ?? module)
+						: module;
+				return Array.isArray(report.issues)
+					? report.issues
+							.filter(
+								(issue: { severity?: string; path?: unknown }) =>
+									issue.severity === 'error' && typeof issue.path === 'string',
+							)
+							.map((issue: { path: string }) => ({
+								path: issue.path,
+								module: target,
+							}))
+					: [];
+			});
+		}
+	} catch {
+		/* Compiler and formatter output is plain text. */
+	}
+	return output.split('\n').flatMap((line) => {
+		const match =
+			/^\s*(?:FAIL\s+)?((?:modules\/[a-z0-9-]+\/)?(?:src|tests|translations|migrations)\/[^\s:(]+)(?:\(\d+,\d+\)|:\d+|\s|$)/.exec(
+				line,
+			);
+		if (!match) return [];
+		const qualified = /^modules\/([a-z0-9-]+)\/(.+)$/.exec(match[1]!);
+		return [
+			{ path: qualified?.[2] ?? match[1]!, module: qualified?.[1] ?? module },
+		];
+	});
+}
+
+export function gateRepairOwner(
+	gate: GateResult,
+	activeModule: string,
+	roles: readonly AgentRoleDefinition[],
+	modules: readonly string[],
+): { role: string; module: string } | null {
+	for (const location of locations(gate, activeModule)) {
+		if (
+			!modules.includes(location.module) ||
+			location.path.split('/').includes('..')
+		)
+			continue;
+		const preferred =
+			location.path.startsWith('src/client/') ||
+			location.path.startsWith('translations/')
+				? 'frontend-engineer'
+				: location.path.startsWith('spec/')
+					? 'business-manager'
+					: location.path.startsWith('src/agent/') ||
+						  location.path.startsWith('src/tools/')
+						? 'agentic-engineer'
+						: 'backend-engineer';
+		const candidates = roles.filter((role) =>
+			role.allowedPaths.some((pattern) => matchesGlob(location.path, pattern)),
+		);
+		const owner =
+			candidates.find((role) => role.id === preferred) ??
+			(candidates.length === 1 ? candidates[0] : undefined);
+		if (owner) return { role: owner.id, module: location.module };
+	}
+	return null;
+}

package/src/server/planning.ts

@@ -8,6 +8,7 @@ import type {
 	HandoffDeclaration,
 } from '#coding-agent';
 import type { GateResult } from './gates.ts';
+import { gateRepairOwner } from './gate-repair.ts';
 import { SandboxSetupError } from './workspace-root.ts';
 import {
 	moduleSuffixOf,
@@ -573,20 +574,29 @@ export function planHandoff(context: HandoffContext): HandoffPlan {
 	   there even when the finished turn worked somewhere else. */
 	const failedGate = context.gates.find((gate) => gate.status !== 'passed');
 	if (failedGate) {
-		const repairRole = context.reviewing
-			? (validateDeclared(context).role ?? context.role)
-			: context.role;
+		const owner = gateRepairOwner(
+			failedGate,
+			context.module,
+			roles,
+			context.routing.session.modules.map((module) => module.directory),
+		);
+		const repairRole =
+			owner?.role ??
+			(context.reviewing
+				? (validateDeclared(context).role ?? context.role)
+				: context.role);
 		return plan(
 			'continue',
 			repairRole,
 			`The ${gateLabel(failedGate)} gate failed, so the responsible specialist fixes it before delivery.`,
 			[
-				`The ${gateLabel(failedGate)} gate failed after your change. Fix exactly what it reports, change nothing else, and end with your handoff line.`,
+				`Continue as ${roleName(roles, repairRole)}. The ${gateLabel(failedGate)} gate failed. Fix the reported files within your role, preserve other work, and end with your handoff line.`,
+				`Recorded gate results:\n${context.gates.map((gate) => `${gateLabel(gate)}: ${gate.status}`).join('\n')}`,
 				`Gate command: ${failedGate.command}`,
 				`Gate output (first ${GATE_PROMPT_OUTPUT} characters; the transcript holds the rest):`,
 				failedGate.output.slice(0, GATE_PROMPT_OUTPUT),
 			].join('\n\n'),
-			failedGate.module ?? context.module,
+			owner?.module ?? failedGate.module ?? context.module,
 		);
 	}
 

package/src/server/preview-hot-updates.ts

@@ -0,0 +1,40 @@
+import { relative } from 'node:path';
+import type { Plugin } from 'vite';
+
+/* Octane broadcasts full-reload for every TSRX change, including modules used
+   only by preview iframes. Draft saves must invalidate cached transforms without
+   navigating the operator's page. The preview refreshes at turn completion or
+   on request, when its isolated worker also selects the current revision. */
+export function isolatePreviewHotUpdates(
+	plugins: Plugin[],
+	workspaceRoot: string,
+): Plugin[] {
+	return plugins.map((plugin) => {
+		const hook = plugin.hotUpdate;
+		if (!hook) return plugin;
+		const original = typeof hook === 'function' ? hook : hook.handler;
+		return {
+			...plugin,
+			hotUpdate: {
+				...(typeof hook === 'function' ? {} : hook),
+				async handler(options) {
+					const path = relative(workspaceRoot, options.file).replaceAll(
+						'\\',
+						'/',
+					);
+					if (/^(?:\.flowdular|\.coreloom)\/sandbox\/sessions\//.test(path)) {
+						for (const environment of Object.values(
+							options.server.environments,
+						)) {
+							const graph = environment.moduleGraph;
+							for (const module of graph.getModulesByFile(options.file) ?? [])
+								graph.invalidateModule(module);
+						}
+						return [];
+					}
+					return original.call(this, options);
+				},
+			},
+		};
+	});
+}

package/src/server/reference.ts

@@ -1,3 +1,4 @@
+import { materializeSdkReference } from './sdk-reference.ts';
 import { createRequire } from 'node:module';
 import {
 	access,
@@ -9,7 +10,7 @@ import {
 } from 'node:fs/promises';
 import { dirname, join, relative } from 'node:path';
 
-async function referenceSource(
+export async function referenceSource(
 	workspaceRoot: string,
 	path: string,
 ): Promise<string> {
@@ -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;
+}