@flowdular/sdk 0.1.0 → 0.2.1

package/packages/sandbox/src/index.ts

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

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

@@ -1,373 +0,0 @@
-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

@@ -1,16 +0,0 @@
-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

@@ -1,308 +0,0 @@
-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.`;
-}