@flowdular/sdk 0.1.0

package/packages/sandbox/src/index.ts

@@ -0,0 +1,10 @@
+export {
+	createSandboxRoutes,
+	createSandboxRuntime,
+	findFlowdularWorkspace,
+} from './server/index.ts';
+export type {
+	SandboxConfiguration,
+	SandboxRuntime,
+	SandboxSession,
+} from './server/index.ts';

package/packages/sandbox/src/preview/PreviewHost.tsrx

@@ -0,0 +1,373 @@
+import { useEffect, useMemo } from 'octane';
+import {
+	ApplicationShell,
+	type ModuleClientContribution,
+} from '@flowdular/sdk/client';
+import { Alert, EmptyState, Tag } from '@flowdular/sdk/ui';
+import { cell, createStore, useValue } from 'segment-state';
+import { Head } from '@octanejs/seo';
+import type { RenderRouteProps } from '@octanejs/vite-plugin';
+import type { SessionView } from '../client/api.ts';
+import { signalReady } from '../client/state.ts';
+import { importDraftModule } from './load-module.ts';
+import {
+	registerSandboxTranslations,
+	restoreSandboxLocale,
+	t,
+	useTranslation,
+} from '../client/i18n.ts';
+import '@flowdular/sdk/ui/styles';
+import '../styles.css';
+
+registerSandboxTranslations();
+
+interface PreviewIdentity {
+	readonly accountId: string;
+	readonly email: string;
+	readonly displayName: string;
+	readonly role: string;
+	readonly scopes: readonly string[];
+	readonly tenantId: string;
+	readonly tenants: readonly {
+		readonly tenantId: string;
+		readonly name: string;
+		readonly slug: string;
+		readonly role: string;
+	}[];
+}
+
+interface PreviewPrincipal {
+	readonly accountId: string;
+	readonly email: string;
+	readonly displayName: string;
+	readonly role: string;
+	readonly scopes: readonly string[];
+	readonly tenantId: string;
+	readonly tenants: readonly {
+		readonly tenantId: string;
+		readonly name: string;
+		readonly slug: string;
+		readonly role: string;
+	}[];
+}
+
+function previewState() {
+	const store = createStore({
+		contributions: cell<readonly ModuleClientContribution[]>([]),
+		principal: cell<PreviewPrincipal | null>(null),
+		status: cell<'loading' | 'ready' | 'empty' | 'failed'>('loading'),
+		message: '',
+		moduleId: '',
+		/* The view the shell opens on: the first navigation entry of the module
+   the URL asked for, or of the first module that contributed one. */
+		initialView: '',
+	});
+	return { store, state: store.state };
+}
+
+/* The preview runs against the session's own authentication runtime, so the
+   draft module sees a real principal, real scopes, and a real CSRF token
+   instead of a stub. The credential belongs to one ephemeral database. */
+interface PreviewModuleInfo {
+	readonly id: string;
+	readonly directory: string;
+	readonly hasClient: boolean;
+	readonly support?: boolean;
+}
+
+async function signInPreview(sessionId: string): Promise<{
+	readonly principal: PreviewPrincipal;
+	readonly csrfToken: string;
+	readonly scopes: readonly string[];
+	readonly modules: readonly PreviewModuleInfo[];
+	readonly error: string | null;
+}> {
+	document.cookie = `coreloom_preview=${sessionId}; path=/; samesite=strict`;
+	const info = await (await fetch(
+		'/sandbox/api/sessions/' + encodeURIComponent(sessionId) + '/preview',
+		{
+			headers: { accept: 'application/json' },
+		},
+	)).json() as {
+		credentials?: { email: string; password: string };
+		scopes?: readonly string[];
+		modules?: readonly PreviewModuleInfo[];
+		error?: string | { message?: string };
+	};
+	const credentials = info.credentials;
+	if (!credentials) {
+		throw new Error(typeof info.error === 'string'
+			? info.error
+			: info.error?.message ?? t('sandbox.preview.sessionUnavailable'));
+	}
+	const response = await fetch('/api/auth/sign-in', {
+		method: 'POST',
+		headers: { 'content-type': 'application/json' },
+		credentials: 'same-origin',
+		body: JSON.stringify(credentials),
+	});
+	const session = await response.json() as {
+		principal?: PreviewPrincipal;
+		csrfToken?: string;
+		error?: { message?: string };
+	};
+	if (!response.ok || !session.principal || !session.csrfToken) {
+		throw new Error(session.error?.message ??
+			t('sandbox.preview.identityFailed'));
+	}
+	return {
+		principal: session.principal,
+		csrfToken: session.csrfToken,
+		scopes: info.scopes ?? [],
+		modules: info.modules ?? [],
+		error: typeof info.error === 'string' ? info.error : null,
+	};
+}
+
+/* Draft sources are served through a sandbox route that names the session and
+   the module directory, never through a host file system path. */
+function clientEntry(
+	sessionId: string,
+	directory: string,
+	support = false,
+): string {
+	return `/${
+		support ? 'preview-support' : 'preview-module'
+	}/${encodeURIComponent(sessionId)}/${encodeURIComponent(
+		directory,
+	)}/src/client/index.ts`;
+}
+
+function sessionIdFromLocation(url: string): string {
+	const segments = new URL(url, 'http://sandbox.local').pathname.split(
+		'/',
+	).filter(Boolean);
+	return segments[0] === 'preview' ? segments[1] ?? '' : '';
+}
+
+function identityFor(
+	principal: PreviewPrincipal | null,
+	contributions: readonly ModuleClientContribution[],
+	moduleId: string,
+): PreviewIdentity {
+	/* The signed-in preview principal decides authority. Its scopes are widened
+   only with the surfaces the draft modules declare, so every screen they
+   contribute is reachable and nothing else appears. */
+	const scopes = new Set<string>([
+		'system.workspace.access',
+		...(principal?.scopes ?? []),
+	]);
+	for (const contribution of contributions) {
+		for (const item of contribution.navigation ?? []) scopes.add(item.scope);
+		for (const widget of contribution.widgets ?? []) scopes.add(widget.scope);
+	}
+	return {
+		accountId: principal?.accountId ?? 'preview-account',
+		email: principal?.email ?? 'preview@sandbox.local',
+		displayName: principal?.displayName ?? t('sandbox.preview.identityName'),
+		role: principal?.role ?? 'owner',
+		scopes: [...scopes],
+		tenantId: principal?.tenantId ?? 'preview-tenant',
+		tenants: principal?.tenants && principal.tenants.length > 0
+			? principal.tenants
+			: [
+					{
+						tenantId: 'preview-tenant',
+						name: moduleId || t('sandbox.preview.workspace'),
+						slug: 'preview',
+						role: 'owner',
+					},
+				],
+	};
+}
+
+/* Element selection: the parent turns it on, the preview reports what was
+   clicked, and the chat attaches it to the next message. */
+function installSelection(enabled: boolean): () => void {
+	if (!enabled || typeof document === 'undefined') return () => undefined;
+	const describe = (element: Element): string => {
+		const parts: string[] = [];
+		let current: Element | null = element;
+		for (let depth = 0; current && depth < 4; depth += 1) {
+			const classes = (current.getAttribute('class') ?? '').split(/\s+/).filter(
+				Boolean,
+			).slice(0, 2).map((value) => '.' + value).join('');
+			parts.unshift(current.tagName.toLowerCase() + classes);
+			current = current.parentElement;
+		}
+		return parts.join(' > ');
+	};
+	const onClick = (event: MouseEvent) => {
+		const target = event.target as Element | null;
+		if (!target) return;
+		event.preventDefault();
+		event.stopPropagation();
+		const view =
+			target.closest('[data-flowdular-view]')?.getAttribute(
+				'data-flowdular-view',
+			) ??
+				'';
+		window.parent.postMessage(
+			{
+				type: 'flowdular:selection',
+				label: (target.textContent ?? '').trim().slice(0, 80) ||
+					target.tagName.toLowerCase(),
+				selector: describe(target),
+				view,
+				text: (target.textContent ?? '').trim().slice(0, 400),
+			},
+			'*',
+		);
+	};
+	const onOver = (event: MouseEvent) => {
+		const target = event.target as HTMLElement | null;
+		if (target) target.style.outline = '2px solid #2563eb';
+	};
+	const onOut = (event: MouseEvent) => {
+		const target = event.target as HTMLElement | null;
+		if (target) target.style.outline = '';
+	};
+	document.addEventListener('click', onClick, true);
+	document.addEventListener('mouseover', onOver, true);
+	document.addEventListener('mouseout', onOut, true);
+	return () => {
+		document.removeEventListener('click', onClick, true);
+		document.removeEventListener('mouseover', onOver, true);
+		document.removeEventListener('mouseout', onOut, true);
+	};
+}
+
+export function PreviewHost(props?: RenderRouteProps) @{
+	const { t } = useTranslation();
+	const preview = useMemo(() => previewState(), []);
+	const [contributions] = useValue(preview.state.contributions);
+	const [principal] = useValue(preview.state.principal);
+	const [status, setStatus] = useValue(preview.state.status);
+	const [message, setMessage] = useValue(preview.state.message);
+	const [moduleId, setModuleId] = useValue(preview.state.moduleId);
+	const [initialView] = useValue(preview.state.initialView);
+
+	useEffect(() => {
+		restoreSandboxLocale();
+		const url = props?.url ?? window.location.href;
+		const sessionId = sessionIdFromLocation(url);
+		const parameters = new URL(url, 'http://sandbox.local').searchParams;
+		const selecting = parameters.has('select');
+		/* The workbench opens the preview on one module of the session; every
+   module still composes, so this only picks the first screen. */
+		const openOn = parameters.get('module') ?? '';
+		const teardown = installSelection(selecting);
+
+		void (async () => {
+			try {
+				const response = await fetch(
+					'/sandbox/api/sessions/' + encodeURIComponent(sessionId),
+					{ headers: { accept: 'application/json' } },
+				);
+				const view = await response.json() as
+					SessionView & {
+						error?: { message?: string };
+					};
+				if (!response.ok) {
+					setMessage(
+						view.error?.message ?? t('sandbox.preview.sessionUnavailable'),
+					);
+					setStatus('failed');
+					return;
+				}
+				setModuleId(view.session.moduleId);
+				const identity = await signInPreview(sessionId);
+				/* Every draft module with a client entry contributes to the same
+   shell, exactly as the platform composes them. */
+				const created: ModuleClientContribution[] = [];
+				const missing: string[] = [];
+				let opening = '';
+				for (const module of identity.modules) {
+					if (!module.hasClient) continue;
+					const loaded = await importDraftModule(
+						clientEntry(sessionId, module.directory, module.support),
+					);
+					if (!loaded.createClientContribution) {
+						missing.push(module.id);
+						continue;
+					}
+					const contribution = loaded.createClientContribution({
+						csrfToken: identity.csrfToken,
+						scopes: [...identity.principal.scopes, ...identity.scopes],
+					});
+					created.push(contribution);
+					const entry = contribution.navigation?.[0]?.viewId ?? '';
+					if (
+						entry &&
+							(!opening || !module.support && !openOn ||
+								module.directory === openOn)
+					) {
+						opening = entry;
+					}
+				}
+				if (created.length === 0) {
+					setMessage(
+						missing.length > 0
+							? missing.join(', ') + t('sandbox.preview.missingExport', {
+									modules: missing.join(', '),
+								})
+							: t('sandbox.preview.noClient'),
+					);
+					setStatus('empty');
+					return;
+				}
+				preview.store.act((transaction) => {
+					transaction.set(preview.state.contributions, created);
+					transaction.set(preview.state.principal, identity.principal);
+					transaction.set(preview.state.initialView, opening);
+				}, 'preview/loaded');
+				setStatus('ready');
+			} catch (error) {
+				setMessage(
+					error instanceof Error
+						? error.message
+						: t('sandbox.preview.loadFailed'),
+				);
+				setStatus('empty');
+			} finally {
+				signalReady();
+			}
+		})();
+
+		return teardown;
+	}, []);
+
+	/* The shell registers document metadata, so the preview provides the same
+   Head boundary the platform gives it. */
+	<Head>
+		@if (status === 'ready' && contributions.length > 0) {
+			<ApplicationShell
+				contributions={contributions}
+				identity={identityFor(principal, contributions, moduleId)}
+				initialView={initialView || contributions[0]!.navigation?.[0]?.viewId ||
+					'overview'}
+				onSignOut={() => undefined}
+				onSwitchTenant={() => undefined}
+			/>
+		} @else if (status === 'loading') {
+			<div class="ui-view" style="padding: 24px">
+				<p class="ui-help">{t('sandbox.preview.loading')}</p>
+			</div>
+		} @else {
+			<div class="ui-view" style="padding: 24px">
+				<EmptyState
+					icon="flask"
+					title={t('sandbox.preview.empty.title')}
+					code="src/client/index.ts"
+				>
+					{message || t('sandbox.preview.empty.description')}
+				</EmptyState>
+				@if (status === 'failed') {
+					<Alert>{message}</Alert>
+				} @else {
+					<Tag tone="info">{moduleId || t('sandbox.preview.draftModule')}</Tag>
+				}
+			</div>
+		}
+	</Head>
+}

package/packages/sandbox/src/preview/load-module.ts

@@ -0,0 +1,16 @@
+import type { ModuleClientContribution } from '@flowdular/sdk/client';
+
+export interface DraftModuleEntry {
+	readonly createClientContribution?: (context: {
+		readonly csrfToken: string;
+		readonly scopes: readonly string[];
+	}) => ModuleClientContribution;
+}
+
+/* The draft module lives in a session workspace outside this app, so its entry
+   is resolved at runtime. The ignore comment stays in this plain module: the
+   TSRX compiler drops comments from call arguments, which would make Vite warn
+   about an unanalyzable import on every preview load. */
+export function importDraftModule(entry: string): Promise<DraftModuleEntry> {
+	return import(/* @vite-ignore */ entry) as Promise<DraftModuleEntry>;
+}

package/packages/sandbox/src/server/attachments.ts

@@ -0,0 +1,308 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { isAbsolute, join, relative, resolve } from 'node:path';
+import {
+	readSession,
+	sessionPaths,
+	updateSession,
+	type SandboxSession,
+	type SessionAttachment,
+} from './sessions.ts';
+import { SandboxSetupError } from './workspace-root.ts';
+
+export const MAX_ATTACHMENTS = 10;
+export const MAX_ATTACHMENT_BYTES = 5 * 1024 * 1024;
+export const MAX_ATTACHMENT_NAME = 128;
+
+interface AttachmentType {
+	readonly kind: SessionAttachment['kind'];
+	readonly contentType: string;
+}
+
+/* The only extensions accepted. Images are verified by magic bytes; the
+   concept/text formats are accepted by extension, with a NUL-byte guard that
+   rejects a binary wearing a text extension. */
+const ATTACHMENT_TYPES: Readonly<Record<string, AttachmentType>> = {
+	png: { kind: 'image', contentType: 'image/png' },
+	jpg: { kind: 'image', contentType: 'image/jpeg' },
+	jpeg: { kind: 'image', contentType: 'image/jpeg' },
+	gif: { kind: 'image', contentType: 'image/gif' },
+	webp: { kind: 'image', contentType: 'image/webp' },
+	md: { kind: 'file', contentType: 'text/markdown; charset=utf-8' },
+	txt: { kind: 'file', contentType: 'text/plain; charset=utf-8' },
+	json: { kind: 'file', contentType: 'application/json; charset=utf-8' },
+	csv: { kind: 'file', contentType: 'text/csv; charset=utf-8' },
+	pdf: { kind: 'file', contentType: 'application/pdf' },
+	svg: { kind: 'file', contentType: 'image/svg+xml' },
+};
+
+const ATTACHMENT_ID =
+	/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+/* Attachment ids are the only client-chosen segment that reaches a file path,
+   so anything that is not an id the sandbox minted is refused before a path is
+   built from it. */
+export function assertAttachmentId(value: string): string {
+	if (!ATTACHMENT_ID.test(value)) {
+		throw new SandboxSetupError(
+			'INVALID_ATTACHMENT_ID',
+			'The attachment id is not a sandbox attachment identifier.',
+		);
+	}
+	return value;
+}
+
+function extensionOf(name: string): string {
+	const dot = name.lastIndexOf('.');
+	return dot > 0 ? name.slice(dot + 1).toLowerCase() : '';
+}
+
+/* The original filename reduced to a safe basename: no path segments, only
+   [A-Za-z0-9._-], no `..` traversal, no leading dot, and bounded length with
+   the extension preserved. */
+function safeAttachmentName(raw: string): string {
+	const base = raw.split(/[/\\]/).pop() ?? '';
+	let safe = base.replace(/[^A-Za-z0-9._-]/g, '_').replace(/\.{2,}/g, '.');
+	safe = safe.replace(/^\.+/, '');
+	if (safe.length > MAX_ATTACHMENT_NAME) {
+		const dot = safe.lastIndexOf('.');
+		const ext = dot > 0 ? safe.slice(dot) : '';
+		safe = safe.slice(0, Math.max(1, MAX_ATTACHMENT_NAME - ext.length)) + ext;
+	}
+	if (!safe || safe === '.' || safe.includes('..')) {
+		throw new SandboxSetupError(
+			'ATTACHMENT_NAME_INVALID',
+			'The attachment filename is not a valid name.',
+		);
+	}
+	return safe;
+}
+
+/* Images must prove their format; the pdf and svg formats carry a recognisable
+   header too. Text formats are accepted by extension. */
+function contentMatches(ext: string, bytes: Buffer): boolean {
+	switch (ext) {
+		case 'png':
+			return (
+				bytes.length >= 8 &&
+				bytes[0] === 0x89 &&
+				bytes[1] === 0x50 &&
+				bytes[2] === 0x4e &&
+				bytes[3] === 0x47
+			);
+		case 'jpg':
+		case 'jpeg':
+			return (
+				bytes.length >= 3 &&
+				bytes[0] === 0xff &&
+				bytes[1] === 0xd8 &&
+				bytes[2] === 0xff
+			);
+		case 'gif': {
+			const head = bytes.subarray(0, 6).toString('latin1');
+			return head === 'GIF87a' || head === 'GIF89a';
+		}
+		case 'webp':
+			return (
+				bytes.length >= 12 &&
+				bytes.subarray(0, 4).toString('latin1') === 'RIFF' &&
+				bytes.subarray(8, 12).toString('latin1') === 'WEBP'
+			);
+		case 'pdf':
+			return bytes.subarray(0, 5).toString('latin1') === '%PDF-';
+		case 'svg': {
+			const head = bytes.subarray(0, 4096).toString('utf8').trimStart();
+			return head.startsWith('<') && /<svg[\s>]/i.test(head);
+		}
+		default:
+			/* Text formats: reject a binary payload carrying a text extension. */
+			return !bytes.subarray(0, 8192).includes(0);
+	}
+}
+
+function resolveType(name: string, bytes: Buffer): AttachmentType {
+	const ext = extensionOf(name);
+	const type = ATTACHMENT_TYPES[ext];
+	if (!type) {
+		throw new SandboxSetupError(
+			'ATTACHMENT_TYPE_REJECTED',
+			`Attachments of type .${ext || '(none)'} are not allowed. Allowed: ${Object.keys(
+				ATTACHMENT_TYPES,
+			).join(', ')}.`,
+		);
+	}
+	if (!contentMatches(ext, bytes)) {
+		throw new SandboxSetupError(
+			'ATTACHMENT_TYPE_REJECTED',
+			`The file contents do not match a .${ext} file.`,
+		);
+	}
+	return type;
+}
+
+export function attachmentContentType(name: string): string {
+	return (
+		ATTACHMENT_TYPES[extensionOf(name)]?.contentType ??
+		'application/octet-stream'
+	);
+}
+
+/* Two attachments must never share a workspace filename, or one would overwrite
+   the other in reference/attachments/. */
+function uniqueName(
+	name: string,
+	existing: readonly SessionAttachment[],
+): string {
+	const taken = new Set(existing.map((item) => item.name));
+	if (!taken.has(name)) return name;
+	const dot = name.lastIndexOf('.');
+	const stem = dot > 0 ? name.slice(0, dot) : name;
+	const ext = dot > 0 ? name.slice(dot) : '';
+	for (let index = 2; index < 1000; index += 1) {
+		const candidate = `${stem}-${index}${ext}`;
+		if (!taken.has(candidate)) return candidate;
+	}
+	return `${randomUUID().slice(0, 8)}-${name}`;
+}
+
+function assertInside(root: string, path: string): string {
+	const inside = relative(resolve(root), resolve(path));
+	if (!inside || inside.startsWith('..') || isAbsolute(inside)) {
+		throw new SandboxSetupError(
+			'ATTACHMENT_NAME_INVALID',
+			'The attachment path escapes the session directory.',
+		);
+	}
+	return path;
+}
+
+function storedPath(
+	paths: ReturnType<typeof sessionPaths>,
+	meta: SessionAttachment,
+): string {
+	return assertInside(
+		paths.attachments,
+		join(paths.attachments, `${meta.id}-${meta.name}`),
+	);
+}
+
+function workspacePath(
+	paths: ReturnType<typeof sessionPaths>,
+	meta: SessionAttachment,
+): string {
+	return assertInside(
+		paths.workspaceAttachments,
+		join(paths.workspaceAttachments, meta.name),
+	);
+}
+
+export async function addAttachment(
+	workspaceRoot: string,
+	session: SandboxSession,
+	input: { readonly name: string; readonly bytes: Buffer },
+): Promise<SessionAttachment> {
+	if (input.bytes.byteLength === 0) {
+		throw new SandboxSetupError('ATTACHMENT_EMPTY', 'The attachment is empty.');
+	}
+	if (input.bytes.byteLength > MAX_ATTACHMENT_BYTES) {
+		throw new SandboxSetupError(
+			'ATTACHMENT_TOO_LARGE',
+			`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],
+	});
+	return meta;
+}
+
+export async function listAttachments(
+	workspaceRoot: string,
+	session: SandboxSession,
+): Promise<readonly SessionAttachment[]> {
+	return (await readSession(workspaceRoot, session.id)).attachments;
+}
+
+function findAttachment(
+	attachments: readonly SessionAttachment[],
+	attachmentId: string,
+): SessionAttachment {
+	const meta = attachments.find((item) => item.id === attachmentId);
+	if (!meta) {
+		throw new SandboxSetupError(
+			'ATTACHMENT_NOT_FOUND',
+			'No such attachment exists in this session.',
+		);
+	}
+	return meta;
+}
+
+export async function removeAttachment(
+	workspaceRoot: string,
+	session: SandboxSession,
+	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),
+	});
+}
+
+export async function readAttachment(
+	workspaceRoot: string,
+	session: SandboxSession,
+	attachmentId: string,
+): Promise<{
+	readonly bytes: Buffer;
+	readonly contentType: string;
+	readonly name: string;
+}> {
+	assertAttachmentId(attachmentId);
+	const current = await readSession(workspaceRoot, session.id);
+	const meta = findAttachment(current.attachments, attachmentId);
+	const paths = sessionPaths(workspaceRoot, current.id, current.moduleSuffix);
+	const bytes = await readFile(storedPath(paths, meta));
+	return {
+		bytes,
+		contentType: attachmentContentType(meta.name),
+		name: meta.name,
+	};
+}
+
+/* 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. */
+export function attachmentInstruction(
+	attachments: readonly SessionAttachment[],
+): string | null {
+	if (attachments.length === 0) return null;
+	const list = attachments
+		.map((item) => `${item.name} (${item.kind})`)
+		.join(', ');
+	return `Attachments the operator provided (in reference/attachments/): ${list}. Screenshots show the desired change; read the files before implementing.`;
+}