@tt-a1i/hive 2.0.1 → 2.1.0

package/dist/src/server/workflow-script-loader.d.ts

@@ -20,14 +20,15 @@ export interface LoadedWorkflow {
     meta: WorkflowMeta;
     scriptPath: string;
     scriptHash: string;
-    /** Transpiled `async function __wf(...) {…}` — the runner evals it via
-     *  `new Function(source + '; return __wf')()` and calls it with the DSL. */
+    /** Transpiled `async function __wf(...) {…}` — the runner executes it in a
+     *  locked-down VM context and calls it with the Hive DSL bridge functions. */
     compiledFunctionSource: string;
 }
 interface ExtractedMeta {
     meta: WorkflowMeta;
     body: string;
 }
+export declare const assertWorkflowScriptIsSandboxable: (source: string) => void;
 export declare const extractMeta: (source: string) => ExtractedMeta;
 export declare const loadWorkflowScriptSource: (source: string, scriptPath: string) => Promise<LoadedWorkflow>;
 export declare const loadWorkflowScriptFile: (absPath: string) => Promise<LoadedWorkflow>;

package/dist/src/server/workflow-script-loader.js

@@ -1,6 +1,165 @@
 import { createHash } from 'node:crypto';
 import { readFile } from 'node:fs/promises';
 const DSL_PARAMS = 'agent, parallel, pipeline, phase, log, workflow, args';
+const DANGEROUS_WORKFLOW_IDENTIFIERS = new Set([
+    'AsyncFunction',
+    'Bun',
+    'Buffer',
+    'Deno',
+    'Function',
+    'Proxy',
+    'Reflect',
+    'WebAssembly',
+    'XMLHttpRequest',
+    '__proto__',
+    'constructor',
+    'document',
+    'eval',
+    'exports',
+    'fetch',
+    'global',
+    'globalThis',
+    'import',
+    'module',
+    'process',
+    'prototype',
+    'queueMicrotask',
+    'require',
+    'setImmediate',
+    'setInterval',
+    'setTimeout',
+    'this',
+    'window',
+]);
+const META_LITERAL_KEYWORDS = new Set(['false', 'null', 'true']);
+const isIdentStart = (ch) => /[$A-Z_a-z]/.test(ch);
+const isIdentPart = (ch) => /[$0-9A-Z_a-z]/.test(ch);
+const scanCodeTokens = (source) => {
+    const tokens = [];
+    const modes = [
+        { kind: 'code', braceDepth: -1 },
+    ];
+    let i = 0;
+    while (i < source.length) {
+        const mode = modes[modes.length - 1];
+        if (!mode)
+            break;
+        const ch = source.charAt(i);
+        const next = source.charAt(i + 1);
+        if (mode.kind === 'template') {
+            if (ch === '\\') {
+                i += 2;
+                continue;
+            }
+            if (ch === '`') {
+                modes.pop();
+                i += 1;
+                continue;
+            }
+            if (ch === '$' && next === '{') {
+                modes.push({ kind: 'code', braceDepth: 0 });
+                i += 2;
+                continue;
+            }
+            i += 1;
+            continue;
+        }
+        if (ch === '/' && next === '/') {
+            const nl = source.indexOf('\n', i + 2);
+            i = nl === -1 ? source.length : nl + 1;
+            continue;
+        }
+        if (ch === '/' && next === '*') {
+            const end = source.indexOf('*/', i + 2);
+            i = end === -1 ? source.length : end + 2;
+            continue;
+        }
+        if (ch === "'" || ch === '"') {
+            const quote = ch;
+            i += 1;
+            while (i < source.length) {
+                if (source.charAt(i) === '\\') {
+                    i += 2;
+                    continue;
+                }
+                if (source.charAt(i) === quote) {
+                    i += 1;
+                    break;
+                }
+                i += 1;
+            }
+            continue;
+        }
+        if (ch === '`') {
+            modes.push({ kind: 'template', braceDepth: -1 });
+            i += 1;
+            continue;
+        }
+        if (mode.braceDepth >= 0 && ch === '}') {
+            if (mode.braceDepth === 0) {
+                modes.pop();
+            }
+            else {
+                mode.braceDepth -= 1;
+                tokens.push({ index: i, type: 'punct', value: ch });
+            }
+            i += 1;
+            continue;
+        }
+        if (ch === '{') {
+            if (mode.braceDepth >= 0)
+                mode.braceDepth += 1;
+            tokens.push({ index: i, type: 'punct', value: ch });
+            i += 1;
+            continue;
+        }
+        if (/[0-9]/.test(ch)) {
+            const match = /^(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?/.exec(source.slice(i));
+            if (match) {
+                tokens.push({ index: i, type: 'number', value: match[0] });
+                i += match[0].length;
+                continue;
+            }
+        }
+        if (isIdentStart(ch)) {
+            const start = i;
+            i += 1;
+            while (i < source.length && isIdentPart(source.charAt(i)))
+                i += 1;
+            tokens.push({ index: start, type: 'identifier', value: source.slice(start, i) });
+            continue;
+        }
+        if (!/\s/.test(ch))
+            tokens.push({ index: i, type: 'punct', value: ch });
+        i += 1;
+    }
+    return tokens;
+};
+export const assertWorkflowScriptIsSandboxable = (source) => {
+    for (const token of scanCodeTokens(source)) {
+        if (token.type === 'identifier' && DANGEROUS_WORKFLOW_IDENTIFIERS.has(token.value)) {
+            throw new Error(`workflow scripts may not use \`${token.value}\`; use the Hive DSL and put file, shell, network, or validation work inside agent() prompts`);
+        }
+    }
+};
+const assertPlainMetaLiteral = (literal) => {
+    const tokens = scanCodeTokens(literal);
+    for (let i = 0; i < tokens.length; i += 1) {
+        const token = tokens[i];
+        if (!token)
+            continue;
+        if (token.type === 'identifier') {
+            const nextToken = tokens[i + 1];
+            const isObjectKey = nextToken?.type === 'punct' && nextToken.value === ':';
+            if (!isObjectKey && !META_LITERAL_KEYWORDS.has(token.value)) {
+                throw new Error(`workflow meta must be a pure literal; unexpected identifier \`${token.value}\``);
+            }
+        }
+        else if (token.type === 'punct' && !['{', '}', '[', ']', ':', ','].includes(token.value)) {
+            throw new Error(`workflow meta must be a pure literal; unexpected token \`${token.value}\``);
+        }
+    }
+};
 // Find the matching close brace for the object literal whose '{' is at
 // openIndex, ignoring braces inside '...' "..." `...` strings and // /* */
 // comments so they don't miscount the depth.
@@ -56,6 +215,7 @@ export const extractMeta = (source) => {
     const braceStart = source.indexOf('{', m.index + m[0].length - 1);
     const braceEnd = matchBrace(source, braceStart);
     const literal = source.slice(braceStart, braceEnd + 1);
+    assertPlainMetaLiteral(literal);
     let meta;
     try {
         // meta MUST be a pure literal (no calls/vars); eval it in isolation.
@@ -93,6 +253,7 @@ export const loadWorkflowScriptSource = async (source, scriptPath) => {
         throw new Error('workflow scripts may not use `import`; use the ambient DSL + inline schemas');
     }
     const { meta, body } = extractMeta(source);
+    assertWorkflowScriptIsSandboxable(body);
     const wrapped = `async function __wf(${DSL_PARAMS}) {\n${body}\n}`;
     // Lazy-load esbuild: its native binary breaks under jsdom/worker contexts
     // used by the web test suite, so importing it at module-load time would

package/dist/src/server/workspace-store-contract.d.ts

@@ -14,6 +14,8 @@ export interface WorkspaceStore {
     addWorker: (workspaceId: string, input: WorkerInput) => AgentSummary;
     createWorkspace: (path: string, name: string) => WorkspaceSummary;
     deleteWorkspace: (workspaceId: string) => void;
+    deleteWorkspaceData: (workspaceId: string) => void;
+    forgetWorkspace: (workspaceId: string) => void;
     deleteWorker: (workspaceId: string, workerId: string) => void;
     renameWorker: (workspaceId: string, workerId: string, name: string) => AgentSummary;
     getAgent: (workspaceId: string, agentId: string) => AgentSummary;

package/dist/src/server/workspace-store.d.ts

@@ -2,4 +2,4 @@ import type { Database } from 'better-sqlite3';
 import type { WorkerInput, WorkspaceRecord, WorkspaceStore } from './workspace-store-contract.js';
 import { type MessageKindRecord } from './workspace-store-support.js';
 export type { WorkerInput, WorkspaceRecord, WorkspaceStore };
-export declare const createWorkspaceStore: (db: Database, listOpenDispatchKinds: () => MessageKindRecord[]) => WorkspaceStore;
+export declare const createWorkspaceStore: (db: Database, listOpenDispatchKindsInput: (() => MessageKindRecord[]) | MessageKindRecord[]) => WorkspaceStore;

package/dist/src/server/workspace-store.js

@@ -13,7 +13,10 @@ const normalizeWorkerName = (name) => {
         throw new Error('Worker name must be 64 characters or fewer');
     return trimmed;
 };
-export const createWorkspaceStore = (db, listOpenDispatchKinds) => {
+export const createWorkspaceStore = (db, listOpenDispatchKindsInput) => {
+    const listOpenDispatchKinds = typeof listOpenDispatchKindsInput === 'function'
+        ? listOpenDispatchKindsInput
+        : () => listOpenDispatchKindsInput;
     const workspaces = new Map();
     seedWorkspacesFromDb(db, workspaces, listOpenDispatchKinds());
     const syncPendingFromDispatchLedger = (workspace) => {
@@ -40,6 +43,37 @@ export const createWorkspaceStore = (db, listOpenDispatchKinds) => {
         syncPendingFromDispatchLedger(workspace);
         return workspace;
     };
+    const deleteWorkspaceData = (workspaceId) => {
+        const workspace = getWorkspace(workspaceId);
+        const agentIds = workspace.agents.map((agent) => agent.id);
+        db.transaction(() => {
+            db.prepare('DELETE FROM messages WHERE workspace_id = ?').run(workspaceId);
+            db.prepare('DELETE FROM agent_launch_configs WHERE workspace_id = ?').run(workspaceId);
+            db.prepare('DELETE FROM agent_sessions WHERE workspace_id = ?').run(workspaceId);
+            const deleteAgentRuns = db.prepare('DELETE FROM agent_runs WHERE agent_id = ?');
+            for (const agentId of agentIds)
+                deleteAgentRuns.run(agentId);
+            db.prepare('DELETE FROM workers WHERE workspace_id = ?').run(workspaceId);
+            // TIER 1 #4 — cascade workflow tables. Without this, the scheduler's
+            // listDueSchedules keeps firing schedules for the dead workspace
+            // every minute (the startWorkflow then crashes in
+            // getWorkflowAgentId / addWorkerWithLaunch and `nextRunAt` is
+            // rewritten to fire again next tick — a permanent error-spam
+            // loop). Orphan workflow_runs / dispatches would otherwise also
+            // accumulate forever. The dispatches DELETE in particular hits the
+            // workflow-tagged subset; non-workflow dispatches were already
+            // cleared via the deleteWorker cascade above.
+            db.prepare('DELETE FROM workflow_schedules WHERE workspace_id = ?').run(workspaceId);
+            // TIER 2 #3 — also wipe the log table; FK is on run_id, so we
+            // have to clear it BEFORE deleting workflow_runs (the lookup
+            // would otherwise miss the rows we're about to delete).
+            db.prepare(`DELETE FROM workflow_run_logs
+         WHERE run_id IN (SELECT id FROM workflow_runs WHERE workspace_id = ?)`).run(workspaceId);
+            db.prepare('DELETE FROM workflow_runs WHERE workspace_id = ?').run(workspaceId);
+            db.prepare('DELETE FROM dispatches WHERE workspace_id = ?').run(workspaceId);
+            db.prepare('DELETE FROM workspaces WHERE id = ?').run(workspaceId);
+        })();
+    };
     return {
         addWorker(workspaceId, input) {
             const workspace = getWorkspace(workspaceId);
@@ -75,35 +109,11 @@ export const createWorkspaceStore = (db, listOpenDispatchKinds) => {
             return summary;
         },
         deleteWorkspace(workspaceId) {
-            const workspace = getWorkspace(workspaceId);
-            const agentIds = workspace.agents.map((agent) => agent.id);
-            db.transaction(() => {
-                db.prepare('DELETE FROM messages WHERE workspace_id = ?').run(workspaceId);
-                db.prepare('DELETE FROM agent_launch_configs WHERE workspace_id = ?').run(workspaceId);
-                db.prepare('DELETE FROM agent_sessions WHERE workspace_id = ?').run(workspaceId);
-                const deleteAgentRuns = db.prepare('DELETE FROM agent_runs WHERE agent_id = ?');
-                for (const agentId of agentIds)
-                    deleteAgentRuns.run(agentId);
-                db.prepare('DELETE FROM workers WHERE workspace_id = ?').run(workspaceId);
-                // TIER 1 #4 — cascade workflow tables. Without this, the scheduler's
-                // listDueSchedules keeps firing schedules for the dead workspace
-                // every minute (the startWorkflow then crashes in
-                // getWorkflowAgentId / addWorkerWithLaunch and `nextRunAt` is
-                // rewritten to fire again next tick — a permanent error-spam
-                // loop). Orphan workflow_runs / dispatches would otherwise also
-                // accumulate forever. The dispatches DELETE in particular hits the
-                // workflow-tagged subset; non-workflow dispatches were already
-                // cleared via the deleteWorker cascade above.
-                db.prepare('DELETE FROM workflow_schedules WHERE workspace_id = ?').run(workspaceId);
-                // TIER 2 #3 — also wipe the log table; FK is on run_id, so we
-                // have to clear it BEFORE deleting workflow_runs (the lookup
-                // would otherwise miss the rows we're about to delete).
-                db.prepare(`DELETE FROM workflow_run_logs
-           WHERE run_id IN (SELECT id FROM workflow_runs WHERE workspace_id = ?)`).run(workspaceId);
-                db.prepare('DELETE FROM workflow_runs WHERE workspace_id = ?').run(workspaceId);
-                db.prepare('DELETE FROM dispatches WHERE workspace_id = ?').run(workspaceId);
-                db.prepare('DELETE FROM workspaces WHERE id = ?').run(workspaceId);
-            })();
+            deleteWorkspaceData(workspaceId);
+            workspaces.delete(workspaceId);
+        },
+        deleteWorkspaceData,
+        forgetWorkspace(workspaceId) {
             workspaces.delete(workspaceId);
         },
         renameWorker(workspaceId, workerId, name) {

package/dist/src/server/workspace-upload-store.d.ts

@@ -0,0 +1,40 @@
+import type { Database } from 'better-sqlite3';
+export interface SaveWorkspaceUploadInput {
+    workspaceId: string;
+    remoteDeviceId?: string | null;
+    originalName: string;
+    mimeType?: string | null;
+    data: Buffer;
+}
+export interface WorkspaceUploadRecord {
+    id: string;
+    workspaceId: string;
+    remoteDeviceId: string | null;
+    originalName: string;
+    mimeType: string;
+    sizeBytes: number;
+    createdAt: number;
+}
+export interface StagedWorkspaceUploadsDelete {
+    /** Permanently remove the staged blobs once the transaction has committed. */
+    commit: () => void;
+    /** Restore the staged blobs after the surrounding transaction rolled back. */
+    rollback: () => void;
+}
+export declare const createWorkspaceUploadStore: (db: Database, uploadsDir: string) => {
+    saveUpload(input: SaveWorkspaceUploadInput): Promise<WorkspaceUploadRecord>;
+    listUploads(workspaceId: string, limit?: number): WorkspaceUploadRecord[];
+    readUpload(workspaceId: string, uploadId: string): Promise<{
+        data: Buffer;
+        record: WorkspaceUploadRecord;
+    } | undefined>;
+    /**
+     * Phase one of workspace-upload deletion; call inside the data-mutation
+     * transaction. Rows are deleted and blobs renamed to `.deleting-*`
+     * tombstones, but nothing is permanently unlinked until `commit()` runs
+     * after the transaction commits — so a failed COMMIT can still
+     * `rollback()` and restore every blob. Tombstones orphaned by a crash
+     * between the phases are reconciled by the startup sweep.
+     */
+    stageWorkspaceUploadsDelete(workspaceId: string): StagedWorkspaceUploadsDelete;
+};

package/dist/src/server/workspace-upload-store.js

@@ -0,0 +1,295 @@
+import { randomUUID } from 'node:crypto';
+import { readdirSync, renameSync, rmdirSync, unlinkSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { basename, dirname, extname, join, resolve, sep } from 'node:path';
+import { HttpError } from './http-errors.js';
+const DEFAULT_UPLOAD_NAME = 'upload';
+const DEFAULT_MIME_TYPE = 'application/octet-stream';
+const MAX_NAME_LENGTH = 180;
+const MAX_MIME_TYPE_LENGTH = 120;
+const MIME_TYPE_RE = /^[A-Za-z0-9!#$&^_.+-]+\/[A-Za-z0-9!#$&^_.+-]+(?:\s*;\s*[A-Za-z0-9!#$&^_.+-]+=[A-Za-z0-9!#$&^_.+-]+)*$/;
+const stripControlCharacters = (value) => {
+    let result = '';
+    for (const char of value) {
+        const code = char.charCodeAt(0);
+        if (code >= 32 && code !== 127)
+            result += char;
+    }
+    return result;
+};
+const isSafeHeaderValue = (value) => {
+    for (const char of value) {
+        const code = char.charCodeAt(0);
+        if (code < 32 || code > 126 || code === 127)
+            return false;
+    }
+    return true;
+};
+const mapRow = (row) => ({
+    id: row.id,
+    workspaceId: row.workspace_id,
+    remoteDeviceId: row.remote_device_id,
+    originalName: row.original_name,
+    mimeType: row.mime_type,
+    sizeBytes: row.size_bytes,
+    createdAt: row.created_at,
+});
+const sanitizeOriginalName = (value) => {
+    const leaf = stripControlCharacters(basename(value.replaceAll('\\', '/')))
+        .trim()
+        .replace(/\s+/g, ' ');
+    return leaf ? leaf.slice(0, MAX_NAME_LENGTH) : DEFAULT_UPLOAD_NAME;
+};
+const sanitizeMimeType = (value) => {
+    if (!value)
+        return DEFAULT_MIME_TYPE;
+    const trimmed = value.trim();
+    if (!trimmed ||
+        trimmed.length > MAX_MIME_TYPE_LENGTH ||
+        !isSafeHeaderValue(trimmed) ||
+        !MIME_TYPE_RE.test(trimmed)) {
+        return DEFAULT_MIME_TYPE;
+    }
+    return trimmed;
+};
+const safeStorageExtension = (originalName) => {
+    const extension = extname(originalName);
+    if (!extension || extension.length > 16)
+        return '';
+    // Require at least one non-dot character: `extname('foo.')` returns `'.'`,
+    // and win32 silently strips trailing dots on disk, so the stored name would
+    // no longer round-trip with `storage_key`.
+    return /^\.[A-Za-z0-9_-]+$/.test(extension) ? extension : '';
+};
+const isEnoent = (error) => error instanceof Error && 'code' in error && error.code === 'ENOENT';
+const createStorageKey = (workspaceId, uploadId, originalName) => `${workspaceId}/${uploadId}${safeStorageExtension(originalName)}`;
+const resolveStoragePath = (uploadsDir, storageKey) => {
+    const root = resolve(uploadsDir);
+    const candidate = resolve(root, ...storageKey.split('/'));
+    if (candidate === root || !candidate.startsWith(`${root}${sep}`)) {
+        throw new HttpError(500, 'Upload storage key is invalid');
+    }
+    return candidate;
+};
+const readRowDataStrict = async (uploadsDir, row) => {
+    try {
+        return await readFile(resolveStoragePath(uploadsDir, row.storage_key));
+    }
+    catch (error) {
+        if (isEnoent(error))
+            return null;
+        throw new HttpError(500, 'Upload file could not be read');
+    }
+};
+const pruneWorkspaceUploadDir = (uploadsDir, workspaceId) => {
+    try {
+        rmdirSync(resolveStoragePath(uploadsDir, workspaceId));
+    }
+    catch {
+        // Directory may be absent already, or may contain files from a concurrent upload.
+    }
+};
+const removeFile = (path) => {
+    try {
+        unlinkSync(path);
+    }
+    catch {
+        // Best-effort cleanup only. A missing or locked file should not block
+        // workspace deletion or rollback from a failed metadata insert.
+    }
+};
+const restoreStagedFiles = (staged) => {
+    for (let index = staged.length - 1; index >= 0; index -= 1) {
+        const item = staged[index];
+        if (!item)
+            continue;
+        try {
+            renameSync(item.stagedPath, item.originalPath);
+        }
+        catch {
+            // Best effort: if rollback restoration fails, preserve the original
+            // exception because it names the operation that made deletion unsafe.
+        }
+    }
+};
+const STAGED_DELETE_SUFFIX_RE = /\.deleting-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+/**
+ * Reconcile `.deleting-*` tombstones left by a crash between staging and the
+ * surrounding transaction outcome: a surviving DB row means the delete rolled
+ * back, so the blob is restored; no row means it committed, so the blob goes.
+ */
+const sweepStagedUploadFiles = (db, uploadsDir) => {
+    const hasRowForStorageKey = db.prepare('SELECT 1 FROM workspace_uploads WHERE storage_key = ?');
+    let workspaceDirs;
+    try {
+        workspaceDirs = readdirSync(uploadsDir);
+    }
+    catch {
+        return;
+    }
+    for (const workspaceId of workspaceDirs) {
+        let entries;
+        try {
+            entries = readdirSync(join(uploadsDir, workspaceId));
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (!STAGED_DELETE_SUFFIX_RE.test(entry))
+                continue;
+            const stagedPath = join(uploadsDir, workspaceId, entry);
+            const originalName = entry.replace(STAGED_DELETE_SUFFIX_RE, '');
+            try {
+                if (hasRowForStorageKey.get(`${workspaceId}/${originalName}`)) {
+                    renameSync(stagedPath, join(uploadsDir, workspaceId, originalName));
+                }
+                else {
+                    unlinkSync(stagedPath);
+                }
+            }
+            catch {
+                // Locked or vanished tombstones wait for the next boot.
+            }
+        }
+    }
+};
+const stageFilesForDelete = (uploadsDir, rows) => {
+    const staged = [];
+    try {
+        for (const row of rows) {
+            const originalPath = resolveStoragePath(uploadsDir, row.storage_key);
+            const stagedPath = `${originalPath}.deleting-${randomUUID()}`;
+            try {
+                renameSync(originalPath, stagedPath);
+            }
+            catch (error) {
+                if (isEnoent(error))
+                    continue;
+                throw error;
+            }
+            staged.push({ originalPath, stagedPath });
+        }
+    }
+    catch (error) {
+        restoreStagedFiles(staged);
+        if (error instanceof HttpError)
+            throw error;
+        throw new HttpError(500, 'Workspace upload file could not be deleted');
+    }
+    return staged;
+};
+export const createWorkspaceUploadStore = (db, uploadsDir) => {
+    const insertUpload = db.prepare(`INSERT INTO workspace_uploads (
+       id, workspace_id, remote_device_id, original_name, mime_type, size_bytes, storage_key,
+       created_at
+     )
+     SELECT ?, ?, ?, ?, ?, ?, ?, ?
+      WHERE EXISTS (SELECT 1 FROM workspaces WHERE id = ?)`);
+    const workspaceExists = db.prepare('SELECT 1 FROM workspaces WHERE id = ?');
+    const getUpload = db.prepare(`SELECT id, workspace_id, remote_device_id, original_name, mime_type, size_bytes, storage_key,
+            created_at
+       FROM workspace_uploads
+      WHERE workspace_id = ? AND id = ?`);
+    const listUploads = db.prepare(`SELECT id, workspace_id, remote_device_id, original_name, mime_type, size_bytes, storage_key,
+            created_at
+       FROM workspace_uploads
+      WHERE workspace_id = ?
+      ORDER BY created_at DESC, id DESC
+      LIMIT ?`);
+    const listUploadsForDelete = db.prepare(`SELECT id, workspace_id, remote_device_id, original_name, mime_type, size_bytes, storage_key,
+            created_at
+       FROM workspace_uploads
+      WHERE workspace_id = ?`);
+    const deleteWorkspaceRows = db.prepare('DELETE FROM workspace_uploads WHERE workspace_id = ?');
+    sweepStagedUploadFiles(db, uploadsDir);
+    return {
+        async saveUpload(input) {
+            if (!workspaceExists.get(input.workspaceId)) {
+                throw new HttpError(404, 'Workspace not found');
+            }
+            const now = Date.now();
+            const originalName = sanitizeOriginalName(input.originalName);
+            const id = randomUUID();
+            const storageKey = createStorageKey(input.workspaceId, id, originalName);
+            const storagePath = resolveStoragePath(uploadsDir, storageKey);
+            const row = {
+                id,
+                workspace_id: input.workspaceId,
+                remote_device_id: input.remoteDeviceId ?? null,
+                original_name: originalName,
+                mime_type: sanitizeMimeType(input.mimeType),
+                size_bytes: input.data.byteLength,
+                storage_key: storageKey,
+                created_at: now,
+            };
+            try {
+                await mkdir(dirname(storagePath), { recursive: true });
+                // Async IO keeps a 100MB write from stalling every PTY/WebSocket on
+                // the event loop; `wx` keeps the no-clobber guarantee. The INSERT's
+                // WHERE EXISTS guard plus the removeFile cleanup below still cover a
+                // workspace deleted while the write was in flight.
+                await writeFile(storagePath, input.data, { flag: 'wx' });
+            }
+            catch {
+                throw new HttpError(500, 'Upload could not be saved');
+            }
+            try {
+                const result = insertUpload.run(row.id, row.workspace_id, row.remote_device_id, row.original_name, row.mime_type, row.size_bytes, row.storage_key, row.created_at, row.workspace_id);
+                if (result.changes !== 1) {
+                    removeFile(storagePath);
+                    throw new HttpError(404, 'Workspace not found');
+                }
+            }
+            catch (error) {
+                removeFile(storagePath);
+                if (error instanceof HttpError)
+                    throw error;
+                // Raw driver errors (e.g. "database or disk is full") would otherwise
+                // reach the client via the app-level error serializer.
+                throw new HttpError(500, 'Upload could not be saved');
+            }
+            return mapRow(row);
+        },
+        listUploads(workspaceId, limit = 50) {
+            const safeLimit = Number.isSafeInteger(limit) ? Math.min(Math.max(limit, 1), 100) : 50;
+            return listUploads.all(workspaceId, safeLimit).map(mapRow);
+        },
+        async readUpload(workspaceId, uploadId) {
+            const row = getUpload.get(workspaceId, uploadId);
+            if (!row)
+                return undefined;
+            const data = await readRowDataStrict(uploadsDir, row);
+            if (!data)
+                return undefined;
+            return { data, record: mapRow(row) };
+        },
+        /**
+         * Phase one of workspace-upload deletion; call inside the data-mutation
+         * transaction. Rows are deleted and blobs renamed to `.deleting-*`
+         * tombstones, but nothing is permanently unlinked until `commit()` runs
+         * after the transaction commits — so a failed COMMIT can still
+         * `rollback()` and restore every blob. Tombstones orphaned by a crash
+         * between the phases are reconciled by the startup sweep.
+         */
+        stageWorkspaceUploadsDelete(workspaceId) {
+            const rows = listUploadsForDelete.all(workspaceId);
+            const staged = stageFilesForDelete(uploadsDir, rows);
+            try {
+                deleteWorkspaceRows.run(workspaceId);
+            }
+            catch (error) {
+                restoreStagedFiles(staged);
+                throw error;
+            }
+            return {
+                commit: () => {
+                    for (const item of staged)
+                        removeFile(item.stagedPath);
+                    pruneWorkspaceUploadDir(uploadsDir, workspaceId);
+                },
+                rollback: () => restoreStagedFiles(staged),
+            };
+        },
+    };
+};

package/dist/src/shared/scenario-presets.d.ts

@@ -0,0 +1,32 @@
+import type { WorkerRole } from './types.js';
+/**
+ * Scenario team presets — the data behind "one-click team assembly".
+ *
+ * Lives in `src/shared/` (same pattern as `open-targets.ts`) because both
+ * sides consume it as a value import: the server route materializes the
+ * workers, the web UI renders the cards and prefills the goal template.
+ * Everything here is pure data — no node imports, safe to bundle.
+ */
+export type ScenarioId = 'build_review_test' | 'research_factcheck' | 'docs_pipeline';
+export interface ScenarioWorkerSpec {
+    /** Stable stem for the server-generated worker name (`<stem>-<suffix>`). */
+    nameStem: string;
+    role: WorkerRole;
+    /**
+     * Role contract for `custom` workers, injected as the worker description
+     * (startup prompt + every dispatch). Built-in roles omit this and fall back
+     * to their default description from `role-templates.ts`.
+     */
+    descriptionOverride?: string;
+}
+export interface ScenarioPreset {
+    id: ScenarioId;
+    workers: ScenarioWorkerSpec[];
+    /** Placeholder goal the UI prefills for the user to edit before applying. */
+    goalTemplate: {
+        en: string;
+        zh: string;
+    };
+}
+export declare const SCENARIO_PRESETS: ScenarioPreset[];
+export declare const getScenarioPreset: (id: string) => ScenarioPreset | undefined;