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

package/dist/application.js

@@ -2,6 +2,15 @@ import { realpath } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { AgentDefinitionService } from "./agents/service.js";
+import { CapabilityGrants } from "./analysis/capabilities.js";
+import { DatasetService } from "./analysis/data/datasets.js";
+import { AnalysisJanitor } from "./analysis/janitor.js";
+import { AnalysisJobs } from "./analysis/jobs.js";
+import { OciRuntime } from "./analysis/oci.js";
+import { AnalysisRerun } from "./analysis/rerun.js";
+import { AnalysisRuntimeManager } from "./analysis/runtime-manager.js";
+import { createArtifactPublisher } from "./artifacts/publisher.js";
+import { ArtifactStore } from "./artifacts/store.js";
 import { configFile, configHome, loadConfigWithProvenance, overridesSavedProviderProfile, setConfigValue, setGlobalMcpAllow, setMcpServerEnabled, setProjectPluginEnabled, setProjectSkillEnabled, stateHome, } from "./config.js";
 import { completeText } from "./core/compaction.js";
 import { ToolRegistry } from "./core/registry.js";
@@ -268,6 +277,105 @@ export async function createApplication(options = {}) {
             config: config.websearch,
             resolveExtension: () => plugins.extensions.resolve("websearch"),
         }, pathAccess);
+        // Python analysis and artifacts live next to the session database (like attachment blobs).
+        const stateRoot = options.db && options.db !== ":memory:" ? dirname(options.db) : stateHome();
+        const artifacts = new ArtifactStore({
+            root: stateRoot,
+            db: store.db,
+            limits: {
+                maxFiles: config.analysis.limits.maxFiles,
+                maxFileBytes: config.analysis.limits.maxFileBytes,
+                maxOutputBytes: config.analysis.limits.maxOutputBytes,
+            },
+        });
+        const capabilityGrants = new CapabilityGrants({
+            db: store.db,
+            rootOf: (id) => store.rootOf(id),
+        });
+        const analysisRuntime = options.analysisRuntime ??
+            new AnalysisRuntimeManager({
+                stateDir: stateRoot,
+                ...(options.python ? { python: options.python } : {}),
+            });
+        const analysisJobs = new AnalysisJobs({ root: stateRoot, db: store.db });
+        // Container mode (`analysis.runtime: "oci"`): read from the live config on every call.
+        let ociRuntime;
+        const oci = {
+            mode: () => config.analysis.runtime,
+            runtime: () => {
+                const key = JSON.stringify(config.analysis.oci);
+                if (ociRuntime?.key !== key)
+                    ociRuntime = {
+                        key,
+                        runtime: new OciRuntime({ ...config.analysis.oci }, options.analysisOci),
+                    };
+                return ociRuntime.runtime;
+            },
+        };
+        // Tabular datasets (one SQLite file each); XLSX needs the discovered Python.
+        const datasets = new DatasetService({
+            root: stateRoot,
+            db: store.db,
+            limits: config.analysis.data,
+            python: analysisRuntime,
+        });
+        const analysisRerun = new AnalysisRerun({ jobs: analysisJobs, store: artifacts, datasets });
+        // Retention: a sweep at most every 24 h, launched in the background after the start.
+        const janitor = new AnalysisJanitor({
+            root: stateRoot,
+            db: store.db,
+            artifacts,
+            datasets,
+            blobs,
+            retention: () => config.analysis.retention,
+            ...(options.analysisSweepDelayMs !== undefined
+                ? { initialDelayMs: options.analysisSweepDelayMs }
+                : {}),
+        });
+        // R4: nothing is registered with analysis disabled or under --read-only. Startup only looks
+        // for candidate interpreters with `stat`; no process is launched until the first call.
+        const analysisEnabled = config.analysis.enabled && !options.readOnly;
+        if (analysisEnabled) {
+            const [candidates, active] = await Promise.all([
+                analysisRuntime.candidates(),
+                analysisRuntime.activeRuntime(),
+            ]);
+            const { registerAnalysisTools } = await import("./tools/analysis.js");
+            registerAnalysisTools(registry, {
+                store: artifacts,
+                jobs: analysisJobs,
+                runtime: analysisRuntime,
+                datasets,
+                oci,
+                rerun: analysisRerun,
+                rootOf: (id) => store.rootOf(id),
+                // Read live: a changed `analysis.limits.*` setting applies to the next call.
+                limits: {
+                    get timeoutMs() {
+                        return config.analysis.limits.timeoutMs;
+                    },
+                    get maxLogBytes() {
+                        return config.analysis.limits.maxLogBytes;
+                    },
+                },
+                startup: { candidates: candidates.length > 0, extras: active?.extras ?? [] },
+            });
+            const { registerArtifactTools } = await import("./tools/artifacts.js");
+            registerArtifactTools(registry, { store: artifacts, rootOf: (id) => store.rootOf(id) });
+        }
+        // Data tools only read (effect `read`): they stay available under --read-only.
+        if (config.analysis.enabled) {
+            const { registerDataTools } = await import("./tools/data.js");
+            registerDataTools(registry, { datasets, rootOf: (id) => store.rootOf(id) });
+        }
+        const sessionWorkspace = (sessionId) => {
+            try {
+                return store.get(sessionId).workspace;
+            }
+            catch {
+                return workspace;
+            }
+        };
         const { registerPluginInstallTool } = await import("./plugins/install.js");
         registerPluginInstallTool(registry, { readOnly: !!options.readOnly });
         if ((options.allowMcp || mcpAllow) && !options.readOnly)
@@ -508,6 +616,7 @@ export async function createApplication(options = {}) {
         const runtimePolicy = {
             write: !!options.allowWrite && !options.readOnly,
             process: !!options.allowProcess && !options.readOnly,
+            ...(options.allowAnalysis && !options.readOnly ? { analysis: true } : {}),
             external: !options.readOnly &&
                 (!!options.allowExternal ||
                     !!options.allowMcp ||
@@ -516,6 +625,19 @@ export async function createApplication(options = {}) {
                     plugins.externalCount > 0 ||
                     registry.list().some((t) => t.name.startsWith("p_"))),
         };
+        /** Model and provider of a session, for the provenance of its artifacts. */
+        const provenanceOf = (sessionId) => {
+            try {
+                const session = store.get(sessionId);
+                return {
+                    ...(session.model ? { model: session.model } : {}),
+                    ...(session.provider ? { provider: session.provider } : {}),
+                };
+            }
+            catch {
+                return {};
+            }
+        };
         const runner = new AgentRunner({
             provider,
             providerFor,
@@ -530,6 +652,33 @@ export async function createApplication(options = {}) {
             contextWindow,
             ...(options.approve && !options.readOnly ? { approve: options.approve } : {}),
             pathAccess,
+            ...(analysisEnabled
+                ? {
+                    capabilities: {
+                        granted: (capability, sessionId) => capabilityGrants.granted(capability, sessionId),
+                        record: (input) => {
+                            capabilityGrants.record({ ...input, workspace: sessionWorkspace(input.sessionId) });
+                        },
+                        source: options.approvalSource ?? "tui",
+                        get runtime() {
+                            return config.analysis.runtime;
+                        },
+                        // A rerun's approval shows the saved script (the input carries only its reference).
+                        preview: async (input, sessionId) => typeof input.rerunOf === "string"
+                            ? analysisRerun.script(input.rerunOf, store.rootOf(sessionId))
+                            : undefined,
+                    },
+                }
+                : {}),
+            artifacts: (call, announce) => createArtifactPublisher(artifacts, {
+                sessionId: call.sessionId,
+                rootSessionId: store.rootOf(call.sessionId),
+                workspace: sessionWorkspace(call.sessionId),
+                runId: call.runId,
+                callId: call.callId,
+                // Public provenance of what produced the artifact (no paths, no keys).
+                provenance: provenanceOf(call.sessionId),
+            }, announce),
             ...(config.websearch.provider === "native"
                 ? { nativeTools: [{ type: config.websearch.nativeToolType }] }
                 : {}),
@@ -612,6 +761,9 @@ export async function createApplication(options = {}) {
                 }
             }
         }
+        // Retention runs in the background (unreferenced timer); never for in-memory test databases.
+        if (analysisEnabled && options.db !== ":memory:")
+            janitor.start();
         return {
             workspace,
             pathAccess,
@@ -621,6 +773,24 @@ export async function createApplication(options = {}) {
             store,
             /** Uploaded attachment bytes; resolve a `BlobRef` with `blobs.attachment(ref)` before a run. */
             blobs,
+            /** Published artifacts of every session (folders under `<state>/artifacts`). */
+            artifacts,
+            /** Persisted capability grants (`analysis.run`) and their audit rows. */
+            capabilityGrants,
+            /** Python discovery and job folders of `python_run`; `enabled` is false under --read-only. */
+            analysis: {
+                enabled: analysisEnabled,
+                runtime: analysisRuntime,
+                jobs: analysisJobs,
+                /** Container runtime of the current configuration (status, pull); mode `managed` ignores it. */
+                oci,
+                rerun: analysisRerun,
+                janitor,
+            },
+            /** Keys a project layer set that only the user layer decides (ignored on load). */
+            configDiagnostics: configProvenance.ignored ?? [],
+            /** Tabular datasets of every session (ingestion, read-only queries, pages). */
+            datasets,
             registry,
             context,
             skills,
@@ -842,6 +1012,29 @@ export async function createApplication(options = {}) {
                                 ? { active: config.agents.active }
                                 : { ...config.agents, effort: String(value) };
                         break;
+                    case "analysis.enabled":
+                        // Tools are registered when the application starts: the change applies to the next
+                        // application (a restart; the web recycles the workspace application).
+                        config.analysis = { ...config.analysis, enabled: value === true };
+                        break;
+                    case "analysis.limits.timeoutMs":
+                        // Read live by python_run on its next call.
+                        config.analysis = {
+                            ...config.analysis,
+                            limits: { ...config.analysis.limits, timeoutMs: Number(value) },
+                        };
+                        break;
+                    case "analysis.retention.jobsDays":
+                    case "analysis.retention.intermediateDays":
+                    case "analysis.retention.artifactsDays": {
+                        // Read by the next sweep.
+                        const leaf = key.slice("analysis.retention.".length);
+                        config.analysis = {
+                            ...config.analysis,
+                            retention: { ...config.analysis.retention, [leaf]: Number(value) },
+                        };
+                        break;
+                    }
                     case "websearch.provider":
                         // Mutated in place (same object identity) so the tool chain's per-call
                         // `websearchCtx.config` sees the new provider on the very next search call.
@@ -998,6 +1191,8 @@ export async function createApplication(options = {}) {
                 // component cannot stall /exit; teardown errors are swallowed for callers.
                 const capped = (work) => Promise.race([work.catch(() => { }), delay(TEARDOWN_STAGE_TIMEOUT_MS)]);
                 try {
+                    janitor.stop();
+                    datasets?.close();
                     await capped(Promise.allSettled([herdr.close(), mcp.close()]));
                 }
                 finally {

package/dist/artifacts/kinds.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Artifact type registry: the kind, the served MIME type and whether a rich client may preview a
+ * published file. The type comes from the extension AND the leading bytes; when they disagree the
+ * most restrictive type wins (`file`, download only). The served `Content-Type` always comes from
+ * here, never from the script that wrote the file.
+ */
+import type { ArtifactKind } from "@alisio/sdk";
+export interface ArtifactType {
+    kind: ArtifactKind;
+    mimeType: string;
+}
+export declare const DOWNLOAD_ONLY: ArtifactType;
+/** Lower-case extension without the dot (`""` when none). */
+export declare const extensionOf: (fileName: string) => string;
+/** Text: no NUL byte in the sampled head and the sample decodes as UTF-8. */
+export declare function looksLikeText(head: Uint8Array): boolean;
+/**
+ * The type of a file from its name and its first bytes (at least 4 KiB is a good sample). An
+ * unknown extension, or bytes that contradict the extension, yield `file` (download only).
+ * An empty file keeps the type of its extension.
+ */
+export declare function classifyArtifact(fileName: string, head: Uint8Array): ArtifactType;
+/** Whether a rich client may preview a file of this name, type and size. */
+export declare function isPreviewable(fileName: string, type: ArtifactType, bytes: number): boolean;
+/** English labels of each kind (the web localizes its own; text surfaces use these). */
+export declare const KIND_LABELS: Record<ArtifactKind, string>;
+/** The type the sandboxed viewer serves for one file (`application/octet-stream` when unknown). */
+export declare const viewerContentType: (fileName: string) => string;
+/**
+ * The registry type of one file inside an artifact (for the authenticated `files/*` route):
+ * the extension and the leading bytes decide, exactly like a published file.
+ */
+export declare function fileType(fileName: string, head: Uint8Array): ArtifactType & {
+    inline: boolean;
+};

package/dist/artifacts/kinds.js

@@ -0,0 +1,177 @@
+const MB = 1024 * 1024;
+const TEXT_PREVIEW = 2 * MB;
+/** Tables are read through paged queries, not loaded whole: the limit is the ingestion limit. */
+const TABLE_PREVIEW = 200 * MB;
+const UTF8 = "; charset=utf-8";
+const OOXML = "application/vnd.openxmlformats-officedocument";
+const text = (kind, mimeType, previewMax = TEXT_PREVIEW) => ({
+    kind,
+    mimeType,
+    magic: "text",
+    previewMax,
+});
+const RULES = {
+    html: text("dashboard", `text/html${UTF8}`, 20 * MB),
+    htm: text("dashboard", `text/html${UTF8}`, 20 * MB),
+    md: text("document", `text/markdown${UTF8}`),
+    markdown: text("document", `text/markdown${UTF8}`),
+    pdf: { kind: "document", mimeType: "application/pdf", magic: "pdf", previewMax: 50 * MB },
+    docx: { kind: "document", mimeType: `${OOXML}.wordprocessingml.document`, magic: "zip" },
+    pptx: { kind: "document", mimeType: `${OOXML}.presentationml.presentation`, magic: "zip" },
+    odt: { kind: "document", mimeType: "application/vnd.oasis.opendocument.text", magic: "zip" },
+    // Tables open in SpreadsheetView (phase 3): CSV/TSV may be windows-1252 or UTF-16, which the
+    // ingestion decodes, so their bytes only have to look like delimited text, not like UTF-8.
+    csv: {
+        kind: "spreadsheet",
+        mimeType: `text/csv${UTF8}`,
+        magic: "delimited",
+        previewMax: TABLE_PREVIEW,
+    },
+    tsv: {
+        kind: "spreadsheet",
+        mimeType: `text/tab-separated-values${UTF8}`,
+        magic: "delimited",
+        previewMax: TABLE_PREVIEW,
+    },
+    xlsx: {
+        kind: "spreadsheet",
+        mimeType: `${OOXML}.spreadsheetml.sheet`,
+        magic: "zip",
+        previewMax: TABLE_PREVIEW,
+    },
+    png: { kind: "image", mimeType: "image/png", magic: "png", previewMax: 20 * MB },
+    jpg: { kind: "image", mimeType: "image/jpeg", magic: "jpeg", previewMax: 20 * MB },
+    jpeg: { kind: "image", mimeType: "image/jpeg", magic: "jpeg", previewMax: 20 * MB },
+    gif: { kind: "image", mimeType: "image/gif", magic: "gif", previewMax: 20 * MB },
+    webp: { kind: "image", mimeType: "image/webp", magic: "webp", previewMax: 20 * MB },
+    svg: text("image", "image/svg+xml", 20 * MB),
+    json: text("data", "application/json"),
+    geojson: text("data", "application/json"),
+    zip: { kind: "archive", mimeType: "application/zip", magic: "zip" },
+};
+for (const ext of ["txt", "log", "sql", "yaml", "yml", "xml", "py", "js", "ts", "r"])
+    RULES[ext] = text("code", `text/plain${UTF8}`);
+export const DOWNLOAD_ONLY = { kind: "file", mimeType: "application/octet-stream" };
+/** Lower-case extension without the dot (`""` when none). */
+export const extensionOf = (fileName) => {
+    const base = fileName.split(/[\\/]/).pop() ?? "";
+    const dot = base.lastIndexOf(".");
+    return dot > 0 ? base.slice(dot + 1).toLowerCase() : "";
+};
+const startsWith = (bytes, signature, at = 0) => bytes.length >= at + signature.length && signature.every((b, i) => bytes[at + i] === b);
+/** Text: no NUL byte in the sampled head and the sample decodes as UTF-8. */
+export function looksLikeText(head) {
+    if (head.includes(0))
+        return false;
+    try {
+        // A cut multi-byte character at the end of the sample is not a decoding failure.
+        new TextDecoder("utf-8", { fatal: true }).decode(head.subarray(0, Math.max(0, head.length - 3)));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function matches(magic, head) {
+    switch (magic) {
+        case "text":
+            return looksLikeText(head);
+        case "delimited":
+            // Text in any of the encodings the ingestion reads: UTF-8, windows-1252 (no NUL bytes) or
+            // UTF-16 with a BOM.
+            return (looksLikeText(head) ||
+                startsWith(head, [0xff, 0xfe]) ||
+                startsWith(head, [0xfe, 0xff]) ||
+                !head.includes(0));
+        case "pdf":
+            return startsWith(head, [0x25, 0x50, 0x44, 0x46, 0x2d]);
+        case "png":
+            return startsWith(head, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+        case "jpeg":
+            return startsWith(head, [0xff, 0xd8, 0xff]);
+        case "gif":
+            return startsWith(head, [0x47, 0x49, 0x46, 0x38]);
+        case "webp":
+            return (startsWith(head, [0x52, 0x49, 0x46, 0x46]) && startsWith(head, [0x57, 0x45, 0x42, 0x50], 8));
+        case "zip":
+            return (startsWith(head, [0x50, 0x4b, 0x03, 0x04]) || startsWith(head, [0x50, 0x4b, 0x05, 0x06]));
+    }
+}
+/**
+ * The type of a file from its name and its first bytes (at least 4 KiB is a good sample). An
+ * unknown extension, or bytes that contradict the extension, yield `file` (download only).
+ * An empty file keeps the type of its extension.
+ */
+export function classifyArtifact(fileName, head) {
+    const rule = RULES[extensionOf(fileName)];
+    if (!rule)
+        return DOWNLOAD_ONLY;
+    if (head.length > 0 && !matches(rule.magic, head))
+        return DOWNLOAD_ONLY;
+    return { kind: rule.kind, mimeType: rule.mimeType };
+}
+/** Whether a rich client may preview a file of this name, type and size. */
+export function isPreviewable(fileName, type, bytes) {
+    if (type.kind === "file" || type.kind === "archive")
+        return false;
+    const rule = RULES[extensionOf(fileName)];
+    return !!rule?.previewMax && rule.mimeType === type.mimeType && bytes <= rule.previewMax;
+}
+/** English labels of each kind (the web localizes its own; text surfaces use these). */
+export const KIND_LABELS = {
+    dashboard: "Dashboard",
+    document: "Document",
+    spreadsheet: "Spreadsheet",
+    image: "Image",
+    data: "Data",
+    code: "Text",
+    archive: "Archive",
+    file: "File",
+};
+/**
+ * Content types of the files of an artifact served by the isolated viewer (spec §14.2): a
+ * multi-file dashboard needs its scripts, styles and fonts with their real types (under
+ * `nosniff` a script served as text never runs). Only that sandboxed route uses this table;
+ * every other route serves the registry type above.
+ */
+const VIEWER_TYPES = {
+    html: `text/html${UTF8}`,
+    htm: `text/html${UTF8}`,
+    css: `text/css${UTF8}`,
+    js: `text/javascript${UTF8}`,
+    mjs: `text/javascript${UTF8}`,
+    json: `application/json${UTF8}`,
+    geojson: `application/json${UTF8}`,
+    csv: `text/csv${UTF8}`,
+    tsv: `text/tab-separated-values${UTF8}`,
+    txt: `text/plain${UTF8}`,
+    md: `text/markdown${UTF8}`,
+    svg: "image/svg+xml",
+    png: "image/png",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    gif: "image/gif",
+    webp: "image/webp",
+    ico: "image/x-icon",
+    woff: "font/woff",
+    woff2: "font/woff2",
+    ttf: "font/ttf",
+    otf: "font/otf",
+    pdf: "application/pdf",
+    mp4: "video/mp4",
+    webm: "video/webm",
+    mp3: "audio/mpeg",
+    wav: "audio/wav",
+};
+/** The type the sandboxed viewer serves for one file (`application/octet-stream` when unknown). */
+export const viewerContentType = (fileName) => VIEWER_TYPES[extensionOf(fileName)] ?? "application/octet-stream";
+/**
+ * The registry type of one file inside an artifact (for the authenticated `files/*` route):
+ * the extension and the leading bytes decide, exactly like a published file.
+ */
+export function fileType(fileName, head) {
+    const type = classifyArtifact(fileName, head);
+    // HTML never renders on the app origin; download-only kinds never render inline.
+    const inline = type.kind !== "file" && type.kind !== "archive" && type.kind !== "dashboard";
+    return { ...type, inline };
+}

package/dist/artifacts/publisher.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The `ToolContext.artifacts` of one tool call: binds the artifact store to the calling session
+ * (and its root), run and call, and announces every publication (`artifact_published`).
+ */
+import type { CoreArtifactPublisher, PublishedArtifactInfo } from "../core/contracts.ts";
+import type { ArtifactOwner, ArtifactStore } from "./store.ts";
+export declare function createArtifactPublisher(store: ArtifactStore, owner: ArtifactOwner, announce: (published: PublishedArtifactInfo) => void): CoreArtifactPublisher;

package/dist/artifacts/publisher.js

@@ -0,0 +1,29 @@
+export function createArtifactPublisher(store, owner, announce) {
+    const done = (published, executionId) => {
+        const info = { ...published, ...(executionId ? { executionId } : {}) };
+        announce(info);
+        return info;
+    };
+    return {
+        async publish(input) {
+            return done(await store.publish(input, owner)).artifact;
+        },
+        async publishText(input) {
+            return done(await store.publishText(input, owner)).artifact;
+        },
+        async publishTextDetailed(input) {
+            return done(await store.publishText(input, owner));
+        },
+        async publishOutputs(staging, options) {
+            const published = await store.publishOutputs(staging, {
+                ...owner,
+                executionId: options.executionId,
+                ...(options.partial ? { partial: true } : {}),
+                ...(options.provenance
+                    ? { provenance: { ...owner.provenance, ...options.provenance } }
+                    : {}),
+            }, options.title ? { title: options.title } : {});
+            return published.map((p) => done(p, options.executionId));
+        },
+    };
+}

package/dist/artifacts/store.d.ts

@@ -0,0 +1,119 @@
+import type { ArtifactKind, ArtifactPublishInput, ArtifactRef, SqlDatabase } from "@alisio/sdk";
+export interface ArtifactLimits {
+    maxFiles: number;
+    maxFileBytes: number;
+    /** Total bytes of one publication (one execution). */
+    maxOutputBytes: number;
+}
+export declare const DEFAULT_ARTIFACT_LIMITS: ArtifactLimits;
+/** Who publishes: the session (and its root), the call that produced the files, provenance. */
+export interface ArtifactOwner {
+    sessionId: string;
+    rootSessionId: string;
+    workspace: string;
+    runId?: string;
+    callId?: string;
+    executionId?: string;
+    partial?: boolean;
+    /** Extra public provenance (runtime, script hash, inputs, model, provider). No paths. */
+    provenance?: Record<string, unknown>;
+}
+export interface PublishedArtifact {
+    artifact: ArtifactRef;
+    /** Absolute path of the file, or of the entry of a multi-file artifact. */
+    path: string;
+    /** Non-fatal notes (e.g. a dashboard reference to a missing file). */
+    warnings: string[];
+}
+export interface ArtifactFile {
+    path: string;
+    bytes: number;
+    sha256: string;
+}
+export interface ArtifactRecord extends ArtifactRef {
+    entry?: string;
+    executionId?: string;
+    runId?: string;
+    callId?: string;
+    provenance: Record<string, unknown>;
+    /** Folder relative to the store root. */
+    relDir: string;
+}
+/** A rejected publication: the message is user-readable and names the offending path. */
+export declare class ArtifactRejected extends Error {
+}
+/** `title` → `[a-z0-9-]`, at most 48 characters (`artifact` when nothing remains). */
+export declare function slugify(title: string): string;
+/** The first bytes of a file (the sample `classifyArtifact` needs). */
+export declare function readHead(path: string): Promise<Uint8Array>;
+/** The public part of a record (what the SDK `ArtifactRef` carries). */
+export declare const toRef: (record: ArtifactRecord) => ArtifactRef;
+export declare class ArtifactStore {
+    private options;
+    readonly limits: ArtifactLimits;
+    private readonly now;
+    constructor(options: {
+        /** State root (`stateHome()` or the folder of `--db`); artifacts live under `artifacts/`. */
+        root: string;
+        db: SqlDatabase;
+        limits?: Partial<ArtifactLimits>;
+        now?: () => number;
+    });
+    get root(): string;
+    /** Session folder of an owner (artifacts of child sessions live with their root). */
+    private sessionDir;
+    /**
+     * Publishes the outputs a script left in `staging`: the entries of `staging/outputs.json`, or
+     * else every top-level file (and every top-level folder; with `index.html` a multi-file
+     * dashboard, otherwise one ZIP archive). Everything or nothing is published.
+     */
+    publishOutputs(staging: string, owner: ArtifactOwner, defaults?: {
+        title?: string;
+    }): Promise<PublishedArtifact[]>;
+    /** Publishes one caller-owned file or directory. */
+    publish(input: ArtifactPublishInput, owner: ArtifactOwner): Promise<PublishedArtifact>;
+    /** Publishes a single text file the caller holds in memory. */
+    publishText(input: {
+        fileName: string;
+        title?: string;
+        text: string;
+    }, owner: ArtifactOwner): Promise<PublishedArtifact>;
+    private scan;
+    private publishAll;
+    private build;
+    /** Artifacts of a root session, newest first. */
+    list(rootSessionId: string, options?: {
+        kind?: ArtifactKind;
+        limit?: number;
+        before?: number;
+        /** Also `deleted` and `expired` rows (the folder is gone, the row remains). */
+        includeDeleted?: boolean;
+        /** Also `expired` rows (retention), but not `deleted` ones. */
+        includeExpired?: boolean;
+    }): ArtifactRecord[];
+    get(id: string): ArtifactRecord | undefined;
+    /** Absolute folder holding `manifest.json` and `files/`. */
+    folder(record: ArtifactRecord): string;
+    /** Absolute path of the file (or the entry of a multi-file artifact). */
+    localPath(record: ArtifactRecord): string;
+    /** Files of an artifact from its manifest, with absolute paths (inside `files/`). */
+    files(record: ArtifactRecord): Promise<Array<ArtifactFile & {
+        abs: string;
+    }>>;
+    /**
+     * One file of a ready artifact by its manifest path (`files/` only, never `manifest.json`):
+     * the path must be listed in the manifest and its real path must stay inside `files/`.
+     */
+    resolveFile(record: ArtifactRecord, path: string): Promise<(ArtifactFile & {
+        abs: string;
+    }) | undefined>;
+    /**
+     * Retention: marks a `ready` artifact `expired` and removes its folder; the row stays so cards
+     * and listings keep showing it as `Expired`. False when it is not `ready`.
+     */
+    markExpired(id: string): Promise<boolean>;
+    /** Ready artifacts created before `cutoff` (epoch ms), oldest first (for the retention sweep). */
+    readyBefore(cutoff: number): ArtifactRecord[];
+    /** Marks an artifact deleted and removes its folder (the row stays for references). */
+    delete(id: string): Promise<boolean>;
+}