@alisio/core 0.1.0-alpha.20 → 0.1.0-alpha.22

package/dist/index.js

@@ -1,9 +1,30 @@
 /** @alisio/core public API: embed the Alisio agent programmatically. */
 export * from "@alisio/sdk";
-export { activeAgentCatalog, agentCatalogFromState, agentPickerItems, agentRunOptions, BUILTIN_AGENTS, DEFAULT_AGENT_ID, mainAgentFromRecord, resolveActiveAgent, } from "./agents/active.js";
+export { AGENT_COMMAND_PREFIX, activeAgentCatalog, agentCatalogFromState, agentCommandDescriptors, agentCommandName, agentIdFromCommand, agentPickerItems, agentRunOptions, BUILTIN_AGENTS, DEFAULT_AGENT_ID, mainAgentFromRecord, resolveActiveAgent, } from "./agents/active.js";
+export { agentModelCapabilities, agentModelLabels, agentModelOptions, DEFAULT_EFFORT_LEVELS, fitAgentSettings, } from "./agents/capabilities.js";
+export { AGENT_AUTHORING_SKILL_NAMES, CREATE_AGENT_SKILL, } from "./agents/create-agent-skill.js";
+export { AGENT_ID_PATTERN, AGENT_LIMITS, AGENT_REASONING_SUMMARIES, AGENT_TEXT_FORMATS, AGENT_VERBOSITIES, AgentNotFoundError, AgentScopeStore, agentIdFromName, agentScopeDir, parseAgentFile, RESERVED_AGENT_IDS, slugify, validateAgentDefinitionInput, } from "./agents/definitions.js";
+export { AGENT_DRAFT_INSTRUCTIONS, AGENT_DRAFT_MAX_DESCRIPTION, agentAuthoringGuidance, agentDraftRequest, generateAgentDraft, parseAgentDraft, } from "./agents/draft.js";
+export { AgentDefinitionService, mergeAgentScopes, } from "./agents/service.js";
+export { AGENT_TEMPLATES, agentTemplate } from "./agents/templates.js";
+export { CapabilityGrants, toGrantWire, } from "./analysis/capabilities.js";
+export { CsvParser, decodeTextBytes, detectDelimiter } from "./analysis/data/csv.js";
+export { DatasetService, DEFAULT_DATASET_LIMITS, datasetFormat, PageParamError, toDatasetRef, XLSX_REMEDY, } from "./analysis/data/datasets.js";
+export { DataEngine, DataError, } from "./analysis/data/engine-client.js";
+export { guardSql } from "./analysis/data/sql-guard.js";
+export { detectHintHost, installHintsMarkdown, installHintsText, parseOsRelease, pythonInstallHints, } from "./analysis/install-hints.js";
+export { AnalysisJanitor, SWEEP_INTERVAL_MS, } from "./analysis/janitor.js";
+export { AnalysisJobs, } from "./analysis/jobs.js";
+export { containerName, OciRuntime, ociRunArgs, parseDigests, } from "./analysis/oci.js";
+export { AnalysisRerun, } from "./analysis/rerun.js";
+export { AnalysisRuntimeManager, ExtrasInstallError, installPreview, setupCommand, venvInterpreter, } from "./analysis/runtime-manager.js";
+export { analysisStatus } from "./analysis/status.js";
 export { createApplication, enabledBuiltins, } from "./application.js";
+export { classifyArtifact, extensionOf, fileType as artifactFileType, isPreviewable, KIND_LABELS, viewerContentType, } from "./artifacts/kinds.js";
+export { createArtifactPublisher } from "./artifacts/publisher.js";
+export { ArtifactRejected, ArtifactStore, readHead as readArtifactHead, slugify as artifactSlug, toRef, } from "./artifacts/store.js";
 export { BUILTIN_COMMANDS, CommandCatalog, } from "./commands/catalog.js";
-export { configFile, configHome, configSchema, isSettableSettingKey, loadConfig, loadConfigWithProvenance, overridesSavedProviderProfile, setConfigValue, setGlobalMcpAllow, setMcpServerEnabled, setProjectPluginEnabled, setProjectSkillEnabled, settableSettings, stateHome, } from "./config.js";
+export { configFile, configHome, configSchema, isSettableSettingKey, loadConfig, loadConfigWithProvenance, OCI_IMAGE_PATTERN, overridesSavedProviderProfile, setConfigValue, setGlobalMcpAllow, setMcpServerEnabled, setProjectPluginEnabled, setProjectSkillEnabled, settableSettings, stateHome, } from "./config.js";
 export { checkpointInstructions, completeText, effectiveContextBudget, estimateTokens, MAX_TRUSTED_WINDOW, parseCheckpointOutput, planCompaction, renderCheckpoint, serializeForSummary, shouldCompact, shouldCompactContext, summarize, } from "./core/compaction.js";
 export { ToolRegistry } from "./core/registry.js";
 export { AgentRunner, defaultTokenBudget, } from "./core/runner.js";
@@ -19,16 +40,20 @@ export { ProjectContext, } from "./resources/context.js";
 export { expandSlashPrompt, loadPromptTemplates, parsePromptTemplate, promptSources, renderPromptTemplate, splitArguments, } from "./resources/prompts.js";
 export { Skills, skillRoots, } from "./resources/skills.js";
 export { PathAccess, } from "./runtime/access.js";
-export { BlobStore } from "./runtime/blobs.js";
+export { BlobStore, BlobTooLarge } from "./runtime/blobs.js";
 export { clipLines, unifiedPatch } from "./runtime/diff.js";
 export { exists, fileSize, readHead, readJson, readText, which } from "./runtime/fs.js";
+export { newId, ulid } from "./runtime/ids.js";
 export { defaultGlobalRoots, isPathSpec, PLUGIN_KEYWORD, resolvePluginSpec, } from "./runtime/modules.js";
-export { findWorkspace, inside, outsideRootsMessage, safePath } from "./runtime/paths.js";
+export { findWorkspace, inside, outsideRootsMessage, safePath, workspaceKey, } from "./runtime/paths.js";
 export { isMissingCommand, RIPGREP_INSTALL_HINT, runProcess, } from "./runtime/process.js";
 export { isSqliteExperimentalWarning, openDatabase } from "./runtime/sqlite.js";
 export { SQLiteStore } from "./runtime/store.js";
+export { crc32, writeZip } from "./runtime/zip.js";
 export { ChildSessions } from "./sessions/children.js";
 export { formatSideQuestion, SIDE_QUESTION_DESCRIPTION, SIDE_QUESTION_HISTORY_LIMIT, SIDE_QUESTION_INSTRUCTIONS, SIDE_QUESTION_MAX_CHARS, SIDE_QUESTION_USAGE, SIDE_QUESTIONS_NAMESPACE, SideQuestions, sideTranscript, } from "./sessions/side-questions.js";
 export { composeSideBySide, DefaultAlisioMascot, DefaultStartupScreen, infoSection, mascotSection, padEnd, pluginsSection, renderStartup, sanitizeLine, shortenPath, startupTips, stripAnsi, tipsSection, titleSection, truncate, visibleWidth, welcomeSection, } from "./startup/index.js";
+export { formatBytes, NOT_SANDBOXED } from "./tools/analysis.js";
+export { ARTIFACT_READ_MAX, exportedPaths } from "./tools/artifacts.js";
 export { hash, objectSchema, registerStandard } from "./tools/standard.js";
 export { getTrust, hashProjectConfig, hasProjectResources, listTrust, resolveTrust, revokeTrust, setTrust, trustStorePath, } from "./trust.js";

package/dist/mcp/rich.js

@@ -227,6 +227,10 @@ export function renderUiBlockText(block) {
                 block.title ? `[progress: ${block.title}]` : "[progress]",
                 ...block.steps.map((step) => `- [${step.status}] ${step.label}${step.detail ? ` (${step.detail})` : ""}`),
             ].join("\n");
+        case "artifact": {
+            const a = block.artifact;
+            return `[artifact: ${a.fileName} · ${a.kind} · ${a.bytes} bytes · ${a.id}${a.partial ? " · partial" : ""}${a.status !== "ready" ? ` · ${a.status}` : ""}]`;
+        }
         default: {
             // A kind this build does not know (e.g. persisted by a newer Alisio): keep it readable.
             const kind = String(block.kind ?? "unknown");

package/dist/plugins/host.js

@@ -203,12 +203,20 @@ export class PluginHost {
                 register: (tool) => {
                     const registered = builtin
                         ? tool
-                        : {
-                            ...tool,
-                            name: `${pluginPrefix(plugin.id)}_${tool.name}`,
-                            // Only built-ins may claim the always-allowed internal effect.
-                            ...(tool.effect === "internal" ? { effect: "external" } : {}),
-                        };
+                        : (() => {
+                            // Only built-ins may claim the always-allowed internal effect, a capability
+                            // (finer than the effect) or the artifact publisher (decision D12, v1).
+                            const { capability: _capability, ...rest } = tool;
+                            return {
+                                ...rest,
+                                name: `${pluginPrefix(plugin.id)}_${tool.name}`,
+                                ...(tool.effect === "internal" ? { effect: "external" } : {}),
+                                execute: (input, context) => {
+                                    const { artifacts: _artifacts, approveInstall: _install, ...narrowed } = context;
+                                    return tool.execute(input, narrowed);
+                                },
+                            };
+                        })();
                     const unregister = this.registry.register(registered);
                     this.toolOwners.set(registered.name, plugin.id);
                     return track(() => {

package/dist/runtime/blobs.d.ts

@@ -1,4 +1,9 @@
 import type { Attachment, BlobRef, SqlDatabase } from "@alisio/sdk";
+/** A streamed blob exceeded its size limit. */
+export declare class BlobTooLarge extends Error {
+    readonly limit: number;
+    constructor(limit: number);
+}
 export interface BlobStoreOptions {
     /** Directory that holds `sha256/…` (by default `<state home>/blobs`). */
     root: string;
@@ -17,6 +22,23 @@ export declare class BlobStore {
         width?: number;
         height?: number;
     }): BlobRef;
+    /**
+     * Stores a byte stream (an upload too large to hold in memory, e.g. a dataset) once per content
+     * hash, hashing while it writes. Fails with `BlobTooLarge` as soon as `maxBytes` is exceeded and
+     * leaves nothing behind. The stored type is the declared one; images stay the only blobs that
+     * `attachment()` and the blob route serve.
+     */
+    putStream(stream: AsyncIterable<Uint8Array>, mimeType: string, options: {
+        maxBytes: number;
+    }): Promise<BlobRef>;
+    /**
+     * Retention: deletes the bytes and the row of a blob that is not an image (an uploaded dataset
+     * original). Images are referenced by messages and are never removed here. Returns the freed
+     * bytes (0 when the blob is unknown, an image or already gone).
+     */
+    removeUpload(hash: string): number;
+    /** Hashes of non-image blobs created before `cutoff` (epoch ms): uploaded dataset originals. */
+    uploadsBefore(cutoff: number): string[];
     get(hash: string): {
         bytes: Buffer;
         mimeType: string;

package/dist/runtime/blobs.js

@@ -8,9 +8,18 @@
  * Persisted messages therefore still carry base64 (as legacy inline attachments do).
  */
 import { createHash, randomUUID } from "node:crypto";
-import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { chmodSync, createWriteStream, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { join } from "node:path";
+import { pipeline } from "node:stream/promises";
 const HASH = /^[0-9a-f]{64}$/;
+/** A streamed blob exceeded its size limit. */
+export class BlobTooLarge extends Error {
+    limit;
+    constructor(limit) {
+        super(`The upload exceeds ${limit} bytes`);
+        this.limit = limit;
+    }
+}
 export class BlobStore {
     options;
     constructor(options) {
@@ -61,6 +70,80 @@ export class BlobStore {
             ...(row?.height != null ? { height: Number(row.height) } : {}),
         };
     }
+    /**
+     * Stores a byte stream (an upload too large to hold in memory, e.g. a dataset) once per content
+     * hash, hashing while it writes. Fails with `BlobTooLarge` as soon as `maxBytes` is exceeded and
+     * leaves nothing behind. The stored type is the declared one; images stay the only blobs that
+     * `attachment()` and the blob route serve.
+     */
+    async putStream(stream, mimeType, options) {
+        const mime = mimeType.trim();
+        if (!mime || mime.length > 255)
+            throw new Error("A blob needs a MIME type");
+        const dir = join(this.options.root, "sha256");
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const temp = join(dir, `.tmp-${randomUUID()}`);
+        const hash = createHash("sha256");
+        let size = 0;
+        try {
+            await pipeline(stream, async function* (source) {
+                for await (const chunk of source) {
+                    size += chunk.byteLength;
+                    if (size > options.maxBytes)
+                        throw new BlobTooLarge(options.maxBytes);
+                    hash.update(chunk);
+                    yield chunk;
+                }
+            }, createWriteStream(temp, { mode: 0o600, flags: "wx" }));
+            const digest = hash.digest("hex");
+            const file = this.path(digest);
+            const fileDir = join(dir, digest.slice(0, 2));
+            mkdirSync(fileDir, { recursive: true, mode: 0o700 });
+            chmodSync(fileDir, 0o700);
+            if (existsSync(file))
+                rmSync(temp, { force: true });
+            else
+                renameSync(temp, file);
+            this.options.db
+                .prepare("INSERT OR IGNORE INTO blobs(hash,mime,size,width,height,created_at) VALUES(?,?,?,?,?,?)")
+                .run(digest, mime, statSync(file).size, null, null, Date.now());
+            const row = this.row(digest);
+            return { hash: digest, mimeType: row?.mime ?? mime, bytes: statSync(file).size };
+        }
+        catch (error) {
+            rmSync(temp, { force: true });
+            throw error;
+        }
+    }
+    /**
+     * Retention: deletes the bytes and the row of a blob that is not an image (an uploaded dataset
+     * original). Images are referenced by messages and are never removed here. Returns the freed
+     * bytes (0 when the blob is unknown, an image or already gone).
+     */
+    removeUpload(hash) {
+        if (!HASH.test(hash))
+            return 0;
+        const row = this.row(hash);
+        if (row?.mime.startsWith("image/"))
+            return 0;
+        const file = this.path(hash);
+        let size = 0;
+        try {
+            size = statSync(file).size;
+            rmSync(file, { force: true });
+        }
+        catch {
+            /* Already gone. */
+        }
+        this.options.db.prepare("DELETE FROM blobs WHERE hash=?").run(hash);
+        return size;
+    }
+    /** Hashes of non-image blobs created before `cutoff` (epoch ms): uploaded dataset originals. */
+    uploadsBefore(cutoff) {
+        return this.options.db
+            .prepare("SELECT hash FROM blobs WHERE mime NOT LIKE 'image/%' AND created_at<?")
+            .all(cutoff).map((r) => r.hash);
+    }
     get(hash) {
         if (!HASH.test(hash))
             return undefined;

package/dist/runtime/ids.d.ts

@@ -0,0 +1,8 @@
+/**
+ * A ULID (26 characters, lexicographically sortable by creation time): 48 bits of milliseconds
+ * and 80 random bits. No dependency and no monotonic counter; two ids created in the same
+ * millisecond sort arbitrarily, which is fine for row ids and folder names.
+ */
+export declare function ulid(now?: number): string;
+/** A prefixed id such as `art_01J…` or `exec_01J…`. */
+export declare const newId: (prefix: string, now?: number) => string;

package/dist/runtime/ids.js

@@ -0,0 +1,32 @@
+import { randomBytes } from "node:crypto";
+/** Crockford base32 (no I, L, O, U), the ULID alphabet. */
+const ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+/**
+ * A ULID (26 characters, lexicographically sortable by creation time): 48 bits of milliseconds
+ * and 80 random bits. No dependency and no monotonic counter; two ids created in the same
+ * millisecond sort arbitrarily, which is fine for row ids and folder names.
+ */
+export function ulid(now = Date.now()) {
+    let time = "";
+    let t = Math.max(0, Math.floor(now));
+    for (let i = 0; i < 10; i++) {
+        time = ALPHABET[t % 32] + time;
+        t = Math.floor(t / 32);
+    }
+    const bytes = randomBytes(10);
+    let random = "";
+    // 80 bits → 16 characters of 5 bits each.
+    let buffer = 0, bits = 0;
+    for (const byte of bytes) {
+        buffer = (buffer << 8) | byte;
+        bits += 8;
+        while (bits >= 5) {
+            bits -= 5;
+            random += ALPHABET[(buffer >> bits) & 31];
+        }
+        buffer &= (1 << bits) - 1;
+    }
+    return time + random;
+}
+/** A prefixed id such as `art_01J…` or `exec_01J…`. */
+export const newId = (prefix, now) => `${prefix}_${ulid(now)}`;

package/dist/runtime/paths.d.ts

@@ -8,3 +8,8 @@ export declare function outsideRootsMessage(target: string, reason?: string): st
 /** Mediated path policy; not an OS sandbox and not race-proof against hostile concurrent processes. */
 export declare function safePath(root: string, path: string): Promise<string>;
 export declare function findWorkspace(cwd: string): Promise<string>;
+/**
+ * Opaque, stable key of a workspace path: the first 16 hex characters of its sha256. Core names
+ * per-workspace folders with it and the server exposes it as the web `workspaceId`.
+ */
+export declare const workspaceKey: (path: string) => string;

package/dist/runtime/paths.js

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { lstat, realpath } from "node:fs/promises";
 import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
 export function inside(root, path) {
@@ -50,3 +51,8 @@ export async function findWorkspace(cwd) {
         path = dirname(path);
     }
 }
+/**
+ * Opaque, stable key of a workspace path: the first 16 hex characters of its sha256. Core names
+ * per-workspace folders with it and the server exposes it as the web `workspaceId`.
+ */
+export const workspaceKey = (path) => createHash("sha256").update(path).digest("hex").slice(0, 16);

package/dist/runtime/process.d.ts

@@ -22,4 +22,16 @@ export declare function runProcess(command: string, args: string[], options: {
     onData?: (chunk: string) => void;
     /** On cancellation: SIGTERM the process group, then SIGKILL after this grace (default 5s). */
     killGraceMs?: number;
+    /**
+     * What happens when a stream exceeds `maxBytes`: `kill` (default) stops the process; `truncate`
+     * lets it run and keeps only the LAST `maxBytes` of each stream (the result is `truncated`).
+     */
+    onOverflow?: "kill" | "truncate";
+    /** Full stdout/stderr copies (up to `maxLogBytes` each), independent of `maxBytes`. */
+    logFiles?: {
+        stdout: string;
+        stderr: string;
+    };
+    /** Cap of each log file (default 10 MiB); a marker line notes the cut. */
+    maxLogBytes?: number;
 }): Promise<ProcessResult>;

package/dist/runtime/process.js

@@ -1,4 +1,5 @@
 import { spawn, spawnSync } from "node:child_process";
+import { createWriteStream } from "node:fs";
 /**
  * Detect a spawn failure caused by a missing executable (`ENOENT`), so tools can explain how to
  * install the dependency instead of surfacing the raw OS error.
@@ -76,19 +77,77 @@ export async function runProcess(command, args, options) {
         terminate();
     let size = 0, truncated = false;
     const max = options.maxBytes ?? 32_000;
-    const consume = (stream) => new Promise((resolveText, reject) => {
+    const tailMode = options.onOverflow === "truncate";
+    const maxLog = options.maxLogBytes ?? 10 * 1024 * 1024;
+    const logs = [];
+    const logger = (path) => {
+        if (!path)
+            return undefined;
+        const out = createWriteStream(path, { flags: "w" });
+        out.on("error", () => {
+            /* A log write failure never fails the process run. */
+        });
+        logs.push(out);
+        let written = 0, cut = false;
+        return (chunk) => {
+            if (cut)
+                return;
+            const room = maxLog - written;
+            if (chunk.byteLength > room) {
+                out.write(chunk.subarray(0, Math.max(0, room)));
+                out.write(Buffer.from("\n[log truncated]\n"));
+                cut = true;
+                written = maxLog;
+                return;
+            }
+            out.write(chunk);
+            written += chunk.byteLength;
+        };
+    };
+    const consume = (stream, logPath) => new Promise((resolveText, reject) => {
         const decoder = new TextDecoder();
+        const log = logger(logPath);
         let text = "", done = false;
+        // Tail mode keeps raw buffers and decodes once at the end (a cut may split a character).
+        const tail = [];
+        let tailBytes = 0;
         const finish = () => {
             if (done)
                 return;
             done = true;
-            text += decoder.decode();
+            if (tailMode) {
+                const joined = Buffer.concat(tail);
+                text = new TextDecoder().decode(joined).replace(/^\uFFFD+/, "");
+            }
+            else
+                text += decoder.decode();
             resolveText(text);
         };
         stream.on("data", (value) => {
             if (done)
                 return;
+            log?.(value);
+            if (tailMode) {
+                const live = decoder.decode(value, { stream: true });
+                if (live)
+                    options.onData?.(live);
+                tail.push(value);
+                tailBytes += value.byteLength;
+                while (tailBytes > max && tail.length) {
+                    const first = tail[0];
+                    const excess = tailBytes - max;
+                    if (first.byteLength <= excess) {
+                        tail.shift();
+                        tailBytes -= first.byteLength;
+                    }
+                    else {
+                        tail[0] = first.subarray(excess);
+                        tailBytes -= excess;
+                    }
+                    truncated = true;
+                }
+                return;
+            }
             const remaining = Math.max(0, max - size), slice = value.subarray(0, remaining);
             size += slice.byteLength;
             const chunk = decoder.decode(slice, { stream: true });
@@ -107,8 +166,8 @@ export async function runProcess(command, args, options) {
     });
     try {
         const [stdout, stderr, exitCode] = await Promise.all([
-            consume(child.stdout),
-            consume(child.stderr),
+            consume(child.stdout, options.logFiles?.stdout),
+            consume(child.stderr, options.logFiles?.stderr),
             exited,
         ]);
         signal.throwIfAborted();
@@ -118,5 +177,6 @@ export async function runProcess(command, args, options) {
         signal.removeEventListener("abort", terminate);
         clearTimeout(graceTimer);
         kill();
+        await Promise.all(logs.map((out) => new Promise((resolveLog) => out.end(() => resolveLog()))));
     }
 }

package/dist/runtime/sqlite.d.ts

@@ -1,3 +1,5 @@
 import type { SqlDatabase } from "@alisio/sdk";
 export declare function isSqliteExperimentalWarning(message: string, type?: string): boolean;
+/** Opens an existing database file read-only (no directory or file is created). */
+export declare function openReadOnlyDatabase(path: string): SqlDatabase;
 export declare function openDatabase(path: string): SqlDatabase;

package/dist/runtime/sqlite.js

@@ -34,6 +34,24 @@ function sqlite() {
     return module;
 }
 const plain = (row) => row === undefined || row === null ? undefined : { ...row };
+/** Opens an existing database file read-only (no directory or file is created). */
+export function openReadOnlyDatabase(path) {
+    const db = new (sqlite().DatabaseSync)(path, { readOnly: true });
+    db.exec("PRAGMA query_only=ON;");
+    return {
+        exec: (sql) => db.exec(sql),
+        prepare(sql) {
+            const raw = db.prepare(sql);
+            return {
+                run: (...params) => raw.run(...params),
+                get: (...params) => plain(raw.get(...params)),
+                all: (...params) => raw.all(...params).map((r) => ({ ...r })),
+            };
+        },
+        transaction: (fn) => fn(),
+        close: () => db.close(),
+    };
+}
 export function openDatabase(path) {
     const memory = path === ":memory:";
     const fresh = !memory && !existsSync(path);

package/dist/runtime/store.d.ts

@@ -5,6 +5,11 @@ export declare class SQLiteStore implements SessionStore {
     constructor(path: string);
     /** Forward-only, idempotent migrations. Existing databases keep all rows. */
     private migrate;
+    /**
+     * The root of a session (itself for roots), following `parent_id`. Unknown ids are their own
+     * root, so callers never throw on a session another process has not written yet.
+     */
+    rootOf(id: string): string;
     create(workspace: string, provider: string, model: string): Session;
     private row;
     get(id: string): Session;

package/dist/runtime/store.js

@@ -112,6 +112,81 @@ export class SQLiteStore {
                     this.db.exec("ALTER TABLE workspaces ADD COLUMN archived_at INTEGER");
                 this.db.exec("INSERT OR IGNORE INTO schema_migrations VALUES(5)");
             });
+        if (!has(6))
+            this.db.transaction(() => {
+                // v6 (additive): Python analysis executions, published artifacts, persisted capability
+                // grants (audit included) and tabular datasets (used from the data phase on).
+                this.db.exec(`CREATE TABLE IF NOT EXISTS analysis_executions(
+            id TEXT PRIMARY KEY,
+            session TEXT NOT NULL,
+            root_session TEXT NOT NULL,
+            workspace TEXT NOT NULL,
+            run_id TEXT, call_id TEXT,
+            runtime TEXT NOT NULL CHECK(runtime IN ('managed','oci')),
+            status TEXT NOT NULL CHECK(status IN ('running','completed','failed','cancelled','timed_out')),
+            script_sha256 TEXT NOT NULL,
+            exit_code INTEGER, error TEXT,
+            rel_dir TEXT NOT NULL,
+            rerun_of TEXT,
+            created_at INTEGER NOT NULL, ended_at INTEGER);
+          CREATE INDEX IF NOT EXISTS analysis_executions_session
+            ON analysis_executions(root_session, created_at);
+          CREATE TABLE IF NOT EXISTS artifacts(
+            id TEXT PRIMARY KEY,
+            session TEXT NOT NULL, root_session TEXT NOT NULL, workspace TEXT NOT NULL,
+            run_id TEXT, call_id TEXT,
+            execution_id TEXT REFERENCES analysis_executions(id),
+            source_path TEXT,
+            title TEXT NOT NULL, file_name TEXT NOT NULL,
+            kind TEXT NOT NULL, mime TEXT NOT NULL,
+            bytes INTEGER NOT NULL, file_count INTEGER NOT NULL DEFAULT 1,
+            sha256 TEXT NOT NULL, entry TEXT,
+            rel_dir TEXT NOT NULL,
+            status TEXT NOT NULL CHECK(status IN ('ready','deleted','expired')),
+            provenance TEXT NOT NULL,
+            created_at INTEGER NOT NULL, deleted_at INTEGER,
+            UNIQUE(execution_id, source_path));
+          CREATE INDEX IF NOT EXISTS artifacts_session ON artifacts(root_session, created_at);
+          CREATE TABLE IF NOT EXISTS capability_grants(
+            id TEXT PRIMARY KEY,
+            capability TEXT NOT NULL,
+            session TEXT NOT NULL,
+            workspace TEXT NOT NULL,
+            scope TEXT NOT NULL CHECK(scope IN ('once','session')),
+            decision TEXT NOT NULL CHECK(decision IN ('allow','deny')),
+            source TEXT NOT NULL CHECK(source IN ('tui','web','flag','headless-grant')),
+            call_id TEXT, run_id TEXT, correlation_id TEXT,
+            created_at INTEGER NOT NULL,
+            revoked_at INTEGER, revoked_by TEXT);
+          CREATE INDEX IF NOT EXISTS capability_grants_lookup
+            ON capability_grants(capability, session, scope, decision, revoked_at);
+          CREATE TABLE IF NOT EXISTS datasets(
+            id TEXT PRIMARY KEY,
+            session TEXT NOT NULL, root_session TEXT NOT NULL,
+            name TEXT NOT NULL, format TEXT NOT NULL,
+            sha256 TEXT NOT NULL, bytes INTEGER NOT NULL,
+            blob_hash TEXT,
+            source_path TEXT,
+            db_rel_path TEXT NOT NULL,
+            ingest_version INTEGER NOT NULL,
+            sheets TEXT NOT NULL,
+            created_at INTEGER NOT NULL);
+          INSERT OR IGNORE INTO schema_migrations VALUES(6);`);
+            });
+    }
+    /**
+     * The root of a session (itself for roots), following `parent_id`. Unknown ids are their own
+     * root, so callers never throw on a session another process has not written yet.
+     */
+    rootOf(id) {
+        let current = id;
+        for (let depth = 0; depth < 32; depth++) {
+            const row = this.db.prepare("SELECT parent_id FROM sessions WHERE id=?").get(current);
+            if (!row?.parent_id)
+                return current;
+            current = row.parent_id;
+        }
+        return current;
     }
     create(workspace, provider, model) {
         const id = crypto.randomUUID();

package/dist/runtime/zip.d.ts

@@ -0,0 +1,24 @@
+export type ZipEntry = {
+    name: string;
+    source: string;
+} | {
+    name: string;
+    data: Uint8Array;
+};
+/** CRC-32 (IEEE) of `bytes`, continuing from `crc`. */
+export declare function crc32(bytes: Uint8Array, crc?: number): number;
+/** Something to write the archive to (an HTTP response, a file stream…), honoring backpressure. */
+export interface ZipSink {
+    write(chunk: Buffer): boolean;
+    once(event: "drain", listener: () => void): unknown;
+}
+/**
+ * Writes `entries` as a ZIP archive to `out`, streaming file contents. Entry names use `/` and
+ * must be relative; the caller validates them. Throws when the archive would need ZIP64.
+ */
+export declare function writeZip(entries: ZipEntry[], out: ZipSink, options?: {
+    now?: Date;
+    signal?: AbortSignal;
+}): Promise<{
+    bytes: number;
+}>;