@playcraft/cli 0.1.54 → 0.1.56-beta

package/dist/workspace-runtime/workspaces/archive.js

@@ -0,0 +1,207 @@
+import { constants } from 'node:fs';
+import { lstat, open, opendir, realpath } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
+import { Readable, Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { createDeflateRaw } from 'node:zlib';
+import { isCredentialFile } from './git.js';
+const EXCLUDED_NAMES = new Set(['.git', 'node_modules', '.playcraft.json', '.playcraft-workspace.json']);
+const MAX_SOURCE_BYTES = 2 * 1024 * 1024 * 1024;
+const MAX_ENTRIES = 50_000;
+const UTF8_DESCRIPTOR_FLAGS = 0x0808;
+const CRC_TABLE = Uint32Array.from({ length: 256 }, (_, value) => {
+    let crc = value;
+    for (let bit = 0; bit < 8; bit += 1)
+        crc = (crc >>> 1) ^ (crc & 1 ? 0xedb88320 : 0);
+    return crc >>> 0;
+});
+/** Exports working files, including ignored deliverables, without following symbolic links. */
+export async function createWorkspaceArchive(root, options = {}) {
+    const rootReal = await realpath(root);
+    const excludedRoots = await Promise.all((options.excludedRoots ?? []).map(path => realpath(path).catch(() => path)));
+    const entries = [];
+    let bytes = 0;
+    const walk = async (directory) => {
+        options.signal?.throwIfAborted();
+        const info = await lstat(directory);
+        if (!info.isDirectory() || info.isSymbolicLink() || !inside(rootReal, await realpath(directory)))
+            throw new Error('workspace_archive_changed');
+        for await (const entry of await opendir(directory)) {
+            options.signal?.throwIfAborted();
+            if (EXCLUDED_NAMES.has(entry.name) || entry.name.startsWith('.playcraft-credential-'))
+                continue;
+            const target = join(directory, entry.name);
+            const path = relative(rootReal, target).split(sep).join('/');
+            if (isCredentialFile(path) || /(?:^|\/)\.playcraft\/(?:workspace-context(?:\.[^/]*)?|video-replication)(?:\/|$)/.test(path))
+                continue;
+            if (excludedRoots.some(excluded => inside(excluded, target)))
+                continue;
+            const info = await lstat(target);
+            if (info.isSymbolicLink())
+                continue;
+            if (!inside(rootReal, await realpath(target)))
+                throw new Error('workspace_archive_changed');
+            if (info.isDirectory()) {
+                await walk(target);
+                continue;
+            }
+            if (!info.isFile())
+                continue;
+            if (Buffer.byteLength(path) > 65_535 || /[\0\\]/.test(path))
+                throw new Error('workspace_archive_invalid_path');
+            bytes += info.size;
+            if (bytes > (options.maxSourceBytes ?? MAX_SOURCE_BYTES) || entries.length >= (options.maxEntries ?? MAX_ENTRIES))
+                throw new Error('workspace_archive_too_large');
+            entries.push({ path, target, info });
+        }
+    };
+    await walk(rootReal);
+    entries.sort((left, right) => left.path.localeCompare(right.path));
+    return Readable.from(zipFiles(rootReal, entries, options.signal));
+}
+/** Standard ZIP (ZIP archive format, 压缩归档格式) records are streamed with bounded buffers. */
+async function* zipFiles(root, entries, signal) {
+    const central = [];
+    let offset = 0;
+    for (const entry of entries) {
+        signal?.throwIfAborted();
+        if (!inside(root, await realpath(entry.target)))
+            throw new Error('workspace_archive_changed');
+        const handle = await open(entry.target, constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+            const info = await handle.stat();
+            if (!info.isFile() || info.dev !== entry.info.dev || info.ino !== entry.info.ino || info.size !== entry.info.size
+                || info.mtimeMs !== entry.info.mtimeMs || info.ctimeMs !== entry.info.ctimeMs)
+                throw new Error('workspace_archive_changed');
+            const name = Buffer.from(entry.path);
+            const stamp = zipTimestamp(info.mtime);
+            const header = Buffer.alloc(30);
+            header.writeUInt32LE(0x04034b50, 0);
+            header.writeUInt16LE(20, 4);
+            header.writeUInt16LE(UTF8_DESCRIPTOR_FLAGS, 6);
+            header.writeUInt16LE(8, 8);
+            header.writeUInt32LE(stamp, 10);
+            header.writeUInt16LE(name.length, 26);
+            const start = offset;
+            yield header;
+            yield name;
+            offset += header.length + name.length;
+            let crc = 0xffffffff;
+            let size = 0;
+            let compressedSize = 0;
+            const checksum = new Transform({ transform(chunk, _encoding, done) {
+                    size += chunk.length;
+                    if (size > info.size) {
+                        done(new Error('workspace_archive_changed'));
+                        return;
+                    }
+                    for (const byte of chunk)
+                        crc = CRC_TABLE[(crc ^ byte) & 0xff] ^ (crc >>> 8);
+                    done(null, chunk);
+                } });
+            const compressed = createDeflateRaw();
+            const completion = pipeline(handle.createReadStream({ autoClose: false }), checksum, compressed, { signal });
+            void completion.catch(() => undefined);
+            try {
+                for await (const chunk of compressed) {
+                    signal?.throwIfAborted();
+                    compressedSize += chunk.length;
+                    offset += chunk.length;
+                    yield chunk;
+                }
+                await completion;
+            }
+            finally {
+                compressed.destroy();
+                checksum.destroy();
+                await completion.catch(() => undefined);
+            }
+            if (size !== info.size)
+                throw new Error('workspace_archive_changed');
+            const after = await handle.stat();
+            if (after.size !== info.size || after.mtimeMs !== info.mtimeMs || after.ctimeMs !== info.ctimeMs)
+                throw new Error('workspace_archive_changed');
+            crc = (crc ^ 0xffffffff) >>> 0;
+            const descriptor = Buffer.alloc(16);
+            descriptor.writeUInt32LE(0x08074b50, 0);
+            descriptor.writeUInt32LE(crc, 4);
+            descriptor.writeUInt32LE(compressedSize, 8);
+            descriptor.writeUInt32LE(size, 12);
+            yield descriptor;
+            offset += descriptor.length;
+            const record = Buffer.alloc(46);
+            record.writeUInt32LE(0x02014b50, 0);
+            record.writeUInt16LE(0x0314, 4);
+            record.writeUInt16LE(20, 6);
+            record.writeUInt16LE(UTF8_DESCRIPTOR_FLAGS, 8);
+            record.writeUInt16LE(8, 10);
+            record.writeUInt32LE(stamp, 12);
+            record.writeUInt32LE(crc, 16);
+            record.writeUInt32LE(compressedSize, 20);
+            record.writeUInt32LE(size, 24);
+            record.writeUInt16LE(name.length, 28);
+            record.writeUInt32LE(((info.mode & 0xffff) << 16) >>> 0, 38);
+            record.writeUInt32LE(start, 42);
+            central.push(record, name);
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    const centralStart = offset;
+    for (const record of central) {
+        signal?.throwIfAborted();
+        yield record;
+        offset += record.length;
+    }
+    const end = Buffer.alloc(22);
+    end.writeUInt32LE(0x06054b50, 0);
+    end.writeUInt16LE(entries.length, 8);
+    end.writeUInt16LE(entries.length, 10);
+    end.writeUInt32LE(offset - centralStart, 12);
+    end.writeUInt32LE(centralStart, 16);
+    yield end;
+}
+export async function serveWorkspaceArchive(root, request, response, options = {}) {
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    const close = () => { if (!response.writableEnded)
+        abort(); };
+    request.once('aborted', abort);
+    response.once('close', close);
+    try {
+        const archive = await createWorkspaceArchive(root, { ...options, signal: controller.signal });
+        response.writeHead(200, {
+            'content-type': 'application/zip', 'content-disposition': 'attachment; filename="workspace.zip"',
+            'cache-control': 'private, no-store', 'x-content-type-options': 'nosniff',
+        });
+        if (request.method === 'HEAD') {
+            archive.destroy();
+            response.end();
+            return;
+        }
+        await pipeline(archive, response, { signal: controller.signal });
+    }
+    catch (error) {
+        if (response.headersSent)
+            response.destroy(error instanceof Error ? error : undefined);
+        else if (!controller.signal.aborted) {
+            const reason = error instanceof Error ? error.message : 'workspace_archive_failed';
+            response.writeHead(reason === 'workspace_archive_too_large' ? 413 : 409, { 'content-type': 'application/json', 'cache-control': 'private, no-store' });
+            response.end(JSON.stringify({ error: reason.startsWith('workspace_archive_') ? reason : 'workspace_archive_failed' }));
+        }
+    }
+    finally {
+        request.off('aborted', abort);
+        response.off('close', close);
+    }
+}
+function inside(root, target) {
+    const path = relative(root, target);
+    return path === '' || (path !== '..' && !path.startsWith(`..${sep}`) && !path.startsWith(sep));
+}
+function zipTimestamp(date) {
+    const year = Math.min(2107, Math.max(1980, date.getUTCFullYear()));
+    return (((year - 1980) << 25) | ((date.getUTCMonth() + 1) << 21) | (date.getUTCDate() << 16)
+        | (date.getUTCHours() << 11) | (date.getUTCMinutes() << 5) | (date.getUTCSeconds() >>> 1)) >>> 0;
+}

package/dist/workspace-runtime/workspaces/artifact-events.js

@@ -0,0 +1,168 @@
+import { PLATFORM_ROUTES, platformEndpoint } from '@playcraft/common/cloud-workspace/runtime';
+import { workspaceRoot } from './registry.js';
+import { WorkspaceArtifactStore } from './artifacts.js';
+import { finalizeWorkspacePlayable, readWorkspacePlayable, validateWorkspacePlayable, workspacePlayableSignature } from '../previews/finalize.js';
+import { watch } from 'chokidar';
+import { join, relative, sep } from 'node:path';
+import { readdir } from 'node:fs/promises';
+import { generatedWorkspace } from './artifact-receipts.js';
+export async function refreshWorkspaceArtifacts(state, workspaceId, origin, directoryName = 'basic') {
+    if (state.journal.destroyed())
+        throw new Error('runtime_destroyed');
+    const root = await workspaceRoot(state, workspaceId, directoryName);
+    const active = state.journal.listSessions().some(session => session.workspaceId === workspaceId
+        && (session.directoryName ?? 'basic') === directoryName && ['starting', 'running', 'waiting_for_user'].includes(session.turnStatus ?? ''));
+    const result = await new WorkspaceArtifactStore(state.config.stateDir, workspaceId, directoryName)
+        .discover(root, origin?.source, origin?.paths, origin?.playable ?? (active ? { mode: 'hold' } : {}));
+    if (result.changed && !state.journal.destroyed()) {
+        const event = await state.journal.allocateSourceEvent({
+            runtimeId: state.config.runtimeId, generation: state.config.generation, runtimeEpoch: state.runtimeEpoch,
+            workspaceId, type: 'artifact.updated', occurredAt: result.list.scannedAt,
+            payload: { workspaceId, directoryName, artifacts: result.list.artifacts.map(artifact => ({ id: artifact.id, currentVersionId: artifact.currentVersionId })) },
+        });
+        // The durable source stream remains authoritative when the callback is temporarily unavailable.
+        void fetch(platformEndpoint(state.config.publicBaseUrl, PLATFORM_ROUTES.events), {
+            method: 'POST', signal: AbortSignal.timeout(5000),
+            headers: { authorization: `Bearer ${state.config.controlToken}`, 'x-playcraft-control-token': state.config.controlToken, 'content-type': 'application/json' },
+            body: JSON.stringify({ runtimeId: state.config.runtimeId, generation: state.config.generation, runtimeEpoch: state.runtimeEpoch, events: [event] }),
+        }).then(response => response.body?.cancel()).catch(() => undefined);
+    }
+    return result.list;
+}
+/** Completed commands and turns reconcile outputs, including work done before a failed turn. */
+export function observeWorkspaceArtifacts(state) {
+    const running = new Map();
+    const starts = new Map();
+    const deferred = new Map();
+    const stop = state.journal.onSourceEvent((event) => {
+        if (!['file.written', 'files.changed', 'filesystem.changed', 'item/started', 'item/completed', 'turn/started', 'turn.started', 'turn.completed', 'turn/completed', 'turn.failed', 'turn.interrupted'].includes(event.type))
+            return;
+        const payload = event.payload && typeof event.payload === 'object' ? event.payload : {};
+        const sessionId = typeof payload.sessionId === 'string' ? payload.sessionId : undefined;
+        const session = sessionId ? state.journal.getSession(sessionId) : undefined;
+        const workspaceId = typeof payload.workspaceId === 'string' ? payload.workspaceId : session?.workspaceId;
+        if (!workspaceId)
+            return;
+        const directoryName = typeof payload.directoryName === 'string' ? payload.directoryName : session?.directoryName ?? 'basic';
+        if (directoryName === 'root')
+            return;
+        const scope = `${workspaceId}:${directoryName}`;
+        const item = payload.item && typeof payload.item === 'object' ? payload.item : undefined;
+        const turn = payload.turn && typeof payload.turn === 'object' ? payload.turn : undefined;
+        const turnId = String(payload.turnId ?? turn?.id ?? session?.activeTurnId ?? 'turn');
+        const turnKey = `${encodeURIComponent(String(payload.threadId ?? session?.threadId ?? sessionId))}/${encodeURIComponent(turnId)}`;
+        const command = item?.type === 'commandExecution';
+        if (event.type.startsWith('item/') && !command)
+            return;
+        const executionId = command ? `${turnKey}/${encodeURIComponent(String(item?.id))}` : turnKey;
+        const started = event.type.endsWith('started');
+        const terminal = command || event.type.startsWith('turn');
+        const success = command ? item?.status === 'completed' && item.exitCode === 0
+            : !['turn.failed', 'turn.interrupted'].includes(event.type) && (turn?.status ?? payload.status ?? 'completed') === 'completed';
+        const task = (running.get(scope) ?? Promise.resolve()).catch(() => undefined).then(async () => {
+            const root = await workspaceRoot(state, workspaceId, directoryName);
+            const store = new WorkspaceArtifactStore(state.config.stateDir, workspaceId, directoryName);
+            const source = { kind: 'generated', ...(sessionId ? { sessionId } : {}),
+                ...(typeof payload.operationId === 'string' ? { operationId: payload.operationId } : {}), tool: command ? 'agent command' : 'agent turn' };
+            if (started) {
+                await refreshWorkspaceArtifacts(state, workspaceId, { source, paths: [], playable: { mode: 'hold', executionId } }, directoryName);
+                starts.set(executionId, await workspacePlayableSignature(root).catch(() => undefined));
+                return;
+            }
+            let force = false;
+            let promote = terminal && success;
+            const candidate = terminal ? await readWorkspacePlayable(root).catch(() => undefined) : undefined;
+            if (terminal && success) {
+                force = command && starts.has(executionId) && starts.get(executionId) !== candidate?.signature;
+                const occupied = await store.hasPendingPlayableExecution(executionId);
+                promote = (!command || force) && !occupied;
+                if (command && force && occupied && candidate) {
+                    try {
+                        validateWorkspacePlayable(candidate.bytes);
+                        deferred.set(scope, { bytes: candidate.bytes, source });
+                    }
+                    catch { /* An incomplete output never becomes a deferred successful candidate. */ }
+                }
+                if (promote && candidate && (force || !await store.rejectedPlayable(candidate.bytes))) {
+                    await finalizeWorkspacePlayable(root, candidate.bytes, source.tool, { expectedSignature: candidate.signature, source }).catch(() => undefined);
+                }
+            }
+            const unrelatedFailure = terminal && !success && candidate && (starts.has(executionId) && starts.get(executionId) === candidate.signature
+                || await store.isCurrentPlayable(candidate.bytes));
+            starts.delete(executionId);
+            await refreshWorkspaceArtifacts(state, workspaceId, { source, paths: [], playable: {
+                    mode: terminal ? success ? promote ? 'success' : 'skip' : unrelatedFailure ? 'skip' : 'failure' : 'hold', ...(terminal ? { executionId } : {}), force,
+                } }, directoryName);
+            const waiting = deferred.get(scope);
+            if (waiting && !await store.hasPendingPlayableExecution(executionId)) {
+                deferred.delete(scope);
+                const current = await readWorkspacePlayable(root).catch(() => undefined);
+                if (current?.bytes.equals(waiting.bytes) && !await store.rejectedPlayable(current.bytes)) {
+                    await finalizeWorkspacePlayable(root, waiting.bytes, waiting.source.tool, { expectedSignature: current.signature, source: waiting.source });
+                    await refreshWorkspaceArtifacts(state, workspaceId, { source: waiting.source, paths: [], playable: { mode: 'success', force: true } }, directoryName);
+                }
+            }
+        }).catch(() => undefined);
+        running.set(scope, task);
+    });
+    const receiptScope = (path) => {
+        const parts = relative(state.config.workspaceRoot, path).split(sep).filter(Boolean);
+        const offset = state.config.workspaceMode === 'multi' ? 2 : 0;
+        const directoryName = offset ? parts[1] : 'basic';
+        if (offset && (parts[0]?.startsWith('.') || parts.length > 1 && !/^(basic|remix-[a-z0-9][a-z0-9-]{3,63})$/.test(directoryName)))
+            return undefined;
+        const tail = parts.slice(offset);
+        if (tail.some((part, index) => index === 0 ? part !== '.playcraft' : index === 1 ? part !== 'artifact-receipts' : index === 2 ? !/^[a-f0-9-]{36}\.json$/.test(part) : true))
+            return undefined;
+        return { parts, offset, directoryName: directoryName ?? 'basic' };
+    };
+    // Only completed generation receipts are observed; project files and build output are excluded.
+    const queueReceipt = (path) => {
+        const found = receiptScope(path);
+        if (!found || found.parts.length !== found.offset + 3)
+            return;
+        const scope = `${found.offset ? found.parts[0] : 'single'}:${found.directoryName}`;
+        const task = (running.get(scope) ?? Promise.resolve()).catch(() => undefined)
+            .then(async () => {
+            const workspaceId = found.offset ? found.parts[0] : (await generatedWorkspace(state.config.workspaceRoot))?.workspaceId;
+            if (workspaceId)
+                await refreshWorkspaceArtifacts(state, workspaceId, undefined, found.directoryName);
+        }).catch(() => undefined);
+        running.set(scope, task);
+    };
+    const receipts = watch(state.config.workspaceRoot, {
+        persistent: false, followSymlinks: false, depth: state.config.workspaceMode === 'multi' ? 5 : 3,
+        ignored: path => !receiptScope(path),
+    }).on('add', queueReceipt).on('ready', () => {
+        // Reconcile receipts created while the initial directory watches were being attached.
+        const task = (async () => {
+            let roots = [state.config.workspaceRoot];
+            if (state.config.workspaceMode === 'multi') {
+                roots = [];
+                for (const entry of await readdir(state.config.workspaceRoot, { withFileTypes: true })) {
+                    if (!entry.isDirectory() || entry.name.startsWith('.'))
+                        continue;
+                    const container = join(state.config.workspaceRoot, entry.name);
+                    for (const directory of await readdir(container, { withFileTypes: true })) {
+                        if (directory.isDirectory() && /^(basic|remix-[a-z0-9][a-z0-9-]{3,63})$/.test(directory.name))
+                            roots.push(join(container, directory.name));
+                    }
+                }
+            }
+            for (const root of roots) {
+                const directory = join(root, '.playcraft/artifact-receipts');
+                const names = await readdir(directory).catch(() => []);
+                for (const name of names)
+                    if (/^[a-f0-9-]{36}\.json$/.test(name))
+                        queueReceipt(join(directory, name));
+            }
+        })().catch(() => undefined);
+        running.set('receipt-startup', task);
+    }).on('error', () => undefined);
+    return async () => {
+        stop();
+        await receipts.close();
+        await running.get('receipt-startup');
+        await Promise.all([...running.values()]);
+    };
+}

package/dist/workspace-runtime/workspaces/artifact-files.js

@@ -0,0 +1,201 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, readFile, realpath, link, unlink } from 'node:fs/promises';
+import { extname, join, posix, resolve, sep } from 'node:path';
+import { WORKSPACE_ARTIFACT_MAX_BYTES, isWorkspaceArtifactOutputPath, workspaceRelativePathSchema } from '@playcraft/common/cloud-workspace/runtime';
+const formats = {
+    '.png': ['image', 'image/png'], '.jpg': ['image', 'image/jpeg'], '.jpeg': ['image', 'image/jpeg'],
+    '.webp': ['image', 'image/webp'], '.gif': ['image', 'image/gif'], '.avif': ['image', 'image/avif'], '.svg': ['image', 'image/svg+xml'],
+    '.hdr': ['image', 'image/vnd.radiance'], '.exr': ['image', 'image/x-exr'],
+    '.ktx': ['image', 'image/ktx'], '.ktx2': ['image', 'image/ktx2'], '.dds': ['image', 'image/vnd-ms.dds'],
+    '.mp4': ['video', 'video/mp4'], '.webm': ['video', 'video/webm'], '.mov': ['video', 'video/quicktime'],
+    '.mp3': ['audio', 'audio/mpeg'], '.wav': ['audio', 'audio/wav'], '.ogg': ['audio', 'audio/ogg'], '.m4a': ['audio', 'audio/mp4'], '.flac': ['audio', 'audio/flac'],
+    '.glb': ['model', 'model/gltf-binary'], '.gltf': ['model', 'model/gltf+json'], '.obj': ['model', 'text/plain'], '.fbx': ['model', 'application/octet-stream'], '.stl': ['model', 'model/stl'], '.usdz': ['model', 'model/vnd.usdz+zip'],
+    '.md': ['document', 'text/markdown'], '.txt': ['document', 'text/plain'], '.pdf': ['document', 'application/pdf'],
+    '.html': ['document', 'text/html'], '.csv': ['document', 'text/csv'], '.docx': ['document', 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'],
+    '.pptx': ['document', 'application/vnd.openxmlformats-officedocument.presentationml.presentation'], '.xlsx': ['document', 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'],
+    '.zip': ['file', 'application/zip'],
+};
+export function artifactFormat(path) { return formats[extname(path).toLowerCase()]; }
+export function artifactMime(path) { return artifactFormat(path)?.[1] ?? 'application/octet-stream'; }
+/** Reject every redirected path segment, including links that happen to remain in the workspace. */
+export async function artifactPath(root, path) {
+    const parsed = workspaceRelativePathSchema.safeParse(path);
+    if (!parsed.success)
+        throw new Error('invalid_artifact_path');
+    const actualRoot = await realpath(root);
+    let target = actualRoot;
+    for (const part of parsed.data.split('/')) {
+        target = join(target, part);
+        if ((await lstat(target)).isSymbolicLink())
+            throw new Error('invalid_artifact_path');
+    }
+    if (!(await realpath(target)).startsWith(`${actualRoot}${sep}`))
+        throw new Error('invalid_artifact_path');
+    return target;
+}
+export async function artifactDirectory(root, relative) {
+    let target = await realpath(root);
+    for (const part of workspaceRelativePathSchema.parse(relative).split('/')) {
+        target = join(target, part);
+        await mkdir(target, { mode: 0o700 }).catch(error => { if (error.code !== 'EEXIST')
+            throw error; });
+        const stat = await lstat(target);
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            throw new Error('invalid_artifact_directory');
+    }
+    return target;
+}
+/** Copies the exact bytes observed, and refuses a file changed while being copied. */
+export async function snapshotArtifactFile(root, path, objects, role = 'primary') {
+    const target = await artifactPath(root, path);
+    const source = await open(target, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const temporary = join(objects, `${randomUUID()}.tmp`);
+    let output;
+    try {
+        const before = await source.stat();
+        if (!before.isFile() || before.nlink !== 1 || before.size > WORKSPACE_ARTIFACT_MAX_BYTES)
+            throw new Error('artifact_file_unavailable');
+        // Objects are written by whichever identity generates the artifact and read by the other.
+        output = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o660);
+        await output.chmod(0o660);
+        const hash = createHash('sha256'), buffer = Buffer.allocUnsafe(64 * 1024);
+        let size = 0;
+        for (;;) {
+            const { bytesRead } = await source.read(buffer, 0, buffer.length, size);
+            if (!bytesRead)
+                break;
+            size += bytesRead;
+            if (size > WORKSPACE_ARTIFACT_MAX_BYTES)
+                throw new Error('artifact_file_unavailable');
+            const chunk = buffer.subarray(0, bytesRead);
+            hash.update(chunk);
+            let written = 0;
+            while (written < bytesRead)
+                written += (await output.write(chunk, written, bytesRead - written)).bytesWritten;
+        }
+        const after = await source.stat();
+        if (before.size !== size || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs)
+            throw new Error('artifact_file_changed');
+        await output.sync();
+        await output.close();
+        output = undefined;
+        const sha256 = hash.digest('hex');
+        await link(temporary, join(objects, sha256)).catch(async (error) => {
+            if (error.code !== 'EEXIST')
+                throw error;
+            const existing = await open(join(objects, sha256), constants.O_RDONLY | constants.O_NOFOLLOW);
+            try {
+                if (!(await existing.stat()).isFile() || (await existing.stat()).size !== size)
+                    throw new Error('artifact_snapshot_invalid');
+            }
+            finally {
+                await existing.close();
+            }
+        });
+        return { path, size, sha256, mimeType: artifactMime(path), role };
+    }
+    finally {
+        await source.close();
+        await output?.close();
+        await unlink(temporary).catch(error => { if (error.code !== 'ENOENT')
+            throw error; });
+    }
+}
+function resourcePath(primary, uri) {
+    if (uri.startsWith('data:'))
+        return undefined;
+    if (/^[a-z][a-z\d+.-]*:/i.test(uri) || uri.startsWith('/') || uri.includes('\\') || uri.includes('?') || uri.includes('#'))
+        throw new Error('invalid_artifact_resource');
+    const decoded = decodeURIComponent(uri);
+    const path = posix.normalize(posix.join(posix.dirname(primary), decoded));
+    if (!isWorkspaceArtifactOutputPath(path) || path.split('/').some(part => part.startsWith('.')))
+        throw new Error('invalid_artifact_resource');
+    return path;
+}
+async function smallText(root, path) {
+    const target = await artifactPath(root, path);
+    if ((await lstat(target)).size > 8 * 1024 * 1024)
+        throw new Error('artifact_metadata_too_large');
+    return readFile(target, 'utf8');
+}
+async function binaryModelDocument(root, path) {
+    const handle = await open(await artifactPath(root, path), constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const header = Buffer.alloc(20);
+        const read = await handle.read(header, 0, header.length, 0);
+        if (read.bytesRead < 20 || header.readUInt32LE(0) !== 0x46546c67)
+            return undefined;
+        const size = (await handle.stat()).size, length = header.readUInt32LE(12);
+        if (header.readUInt32LE(4) !== 2 || header.readUInt32LE(8) !== size || header.readUInt32LE(16) !== 0x4e4f534a
+            || length < 2 || length > 8 * 1024 * 1024 || length + 20 > size)
+            throw new Error('artifact_model_invalid');
+        const bytes = Buffer.alloc(length);
+        let offset = 0;
+        while (offset < length) {
+            const part = await handle.read(bytes, offset, length - offset, 20 + offset);
+            if (!part.bytesRead)
+                throw new Error('artifact_model_invalid');
+            offset += part.bytesRead;
+        }
+        return JSON.parse(bytes.toString('utf8').replace(/\0+$/, ''));
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** Only explicit model references become members; neighboring names never imply a relationship. */
+export async function artifactResources(root, path) {
+    const resources = new Set();
+    const add = (from, uri) => { const result = resourcePath(from, uri); if (result)
+        resources.add(result); };
+    const extension = extname(path).toLowerCase();
+    if (extension === '.gltf' || extension === '.glb') {
+        const body = (extension === '.gltf' ? JSON.parse(await smallText(root, path)) : await binaryModelDocument(root, path));
+        if (body)
+            for (const resource of [...(body.buffers ?? []), ...(body.images ?? [])])
+                if (typeof resource.uri === 'string')
+                    add(path, resource.uri);
+    }
+    else if (extname(path).toLowerCase() === '.obj') {
+        for (const line of (await smallText(root, path)).split(/\r?\n/)) {
+            const material = /^\s*mtllib\s+(.+?)\s*$/.exec(line)?.[1];
+            if (material)
+                add(path, material);
+        }
+        for (const material of [...resources]) {
+            for (const line of (await smallText(root, material)).split(/\r?\n/)) {
+                const texture = /^\s*(?:map_\w+|bump|disp|decal|norm)\s+(\S.*?)\s*$/.exec(line)?.[1];
+                // Options require a material parser; do not guess the filename from an option list.
+                if (texture && !texture.startsWith('-'))
+                    add(material, texture);
+            }
+        }
+    }
+    if (resources.size > 255)
+        throw new Error('artifact_too_many_resources');
+    return [...resources].sort();
+}
+export async function snapshotArtifactBundle(root, path, objects, thumbnailPath) {
+    if (!isWorkspaceArtifactOutputPath(path) || (thumbnailPath !== undefined && !isWorkspaceArtifactOutputPath(thumbnailPath)))
+        throw new Error('invalid_artifact_path');
+    const resources = await artifactResources(root, path);
+    const files = [await snapshotArtifactFile(root, path, objects)];
+    for (const resource of resources)
+        if (resource !== path)
+            files.push(await snapshotArtifactFile(root, resource, objects, 'resource'));
+    if (thumbnailPath && !files.some(file => file.path === thumbnailPath))
+        files.push(await snapshotArtifactFile(root, thumbnailPath, objects, 'thumbnail'));
+    if (files.reduce((size, file) => size + file.size, 0) > WORKSPACE_ARTIFACT_MAX_BYTES)
+        throw new Error('artifact_bundle_too_large');
+    return files;
+}
+export function artifactBundleDigest(files) {
+    return createHash('sha256').update(JSON.stringify([...files].sort((a, b) => a.path.localeCompare(b.path)).map(file => [file.path, file.sha256, file.role]))).digest('hex');
+}
+export function relativeArtifactPath(root, path) {
+    const target = resolve(path), prefix = `${resolve(root)}${sep}`;
+    if (!target.startsWith(prefix))
+        throw new Error('invalid_artifact_path');
+    return workspaceRelativePathSchema.parse(target.slice(prefix.length).split(sep).join('/'));
+}