@sema-agent/core 7.15.0 → 7.17.0

package/dist/tools/artifact/artifact-tool.js

@@ -0,0 +1,351 @@
+import { createHash } from "node:crypto";
+import { Type } from "typebox";
+import { ARTIFACT_FAILURE_RESULT_CODE, ARTIFACT_HOST_ERROR_CODE, ARTIFACT_LIST_SCOPES, ARTIFACT_PLANE_CONTENT_ORIGIN, ARTIFACT_PUBLISH_CONTEXTS, } from "../../core/artifact-host.js";
+import { ARTIFACT_TOOL_NAME, toolFace } from "../../core/tool-catalog-entries.js";
+import { errorResult } from "../../core/tools.js";
+import { inlineUntrusted } from "../../core/untrusted-text.js";
+import { actionDescription, artifactDescription, PARAM_TEXT, urlDescription } from "./artifact-text.js";
+const MAX_FILES_PER_PUBLISH = 255;
+const LIST_LIMIT_DEFAULT = 25;
+const LIST_LIMIT_MAX = 100;
+const BINARY_NOTE_MEDIA = new Set(["application/json", "application/javascript", "text/javascript", "image/svg+xml", "application/xml"]);
+const MEDIA_BY_EXT = new Map(Object.entries({
+    html: "text/html", htm: "text/html", css: "text/css", js: "text/javascript", mjs: "text/javascript", json: "application/json",
+    md: "text/markdown", txt: "text/plain", csv: "text/csv", xml: "application/xml", 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", wasm: "application/wasm", pdf: "application/pdf", mp3: "audio/mpeg", mp4: "video/mp4",
+}));
+export function mediaTypeOf(path) {
+    const dot = path.lastIndexOf(".");
+    return (dot >= 0 ? MEDIA_BY_EXT.get(path.slice(dot + 1).toLowerCase()) : undefined) ?? "application/octet-stream";
+}
+export function isTextMedia(mediaType) {
+    if (mediaType === undefined)
+        return false;
+    const essence = mediaType.split(";")[0].trim().toLowerCase();
+    return essence.startsWith("text/") || BINARY_NOTE_MEDIA.has(essence);
+}
+export function artifactAttemptId(runId, toolCallId, occurrence = 0) {
+    const h = createHash("sha256").update(runId).update("|").update(toolCallId).update("|").update(String(occurrence)).digest("hex");
+    return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20, 32)}`;
+}
+const basenameOf = (p) => {
+    const i = Math.max(p.lastIndexOf("/"), p.lastIndexOf("\\"));
+    return i >= 0 ? p.slice(i + 1) : p;
+};
+export function normalizePublishedPath(raw) {
+    if (raw.length === 0)
+        return { ok: false, reason: "is empty" };
+    if (raw.includes("\0"))
+        return { ok: false, reason: "contains a NUL byte" };
+    if (raw.includes("\\"))
+        return { ok: false, reason: "contains a backslash (use forward slashes)" };
+    if (raw.startsWith("/"))
+        return { ok: false, reason: "is root-relative (no leading slash)" };
+    const path = raw.normalize("NFC");
+    for (const seg of path.split("/"))
+        if (seg === "" || seg === "." || seg === "..")
+            return { ok: false, reason: "contains an empty, `.` or `..` segment" };
+    return { ok: true, path };
+}
+function renderSnapshotMeta(s) {
+    const meta = ["title", "description", "favicon", "label"].filter((k) => s[k] !== undefined).map((k) => `${k}: ${inlineUntrusted(s[k], 200)}`);
+    return meta.length === 0 ? "" : `${meta.join("\n")}\n`;
+}
+function renderFile(f) {
+    const head = `--- ${inlineUntrusted(f.path, 200)} (${inlineUntrusted(f.mediaType ?? "application/octet-stream", 80)}, ${String(f.content.byteLength).slice(0, 20)} bytes) ---`;
+    return isTextMedia(f.mediaType) ? `${head}\n${Buffer.from(f.content).toString("utf8")}` : `${head}\n[binary content, not shown]`;
+}
+const isRecord = (x) => x !== null && typeof x === "object";
+const everyItem = (x, pred) => Array.isArray(x) && x.every(pred);
+const optString = (v) => v === undefined || typeof v === "string";
+const isRef = (x) => isRecord(x) && typeof x["url"] === "string" && typeof x["slug"] === "string" && typeof x["version"] === "string" && optString(x["title"]);
+const isFile = (x) => isRecord(x) && typeof x["path"] === "string" && x["content"] instanceof Uint8Array && optString(x["mediaType"]);
+const isSnapshot = (x) => isRecord(x) && everyItem(x["files"], isFile) && optString(x["title"]) && optString(x["description"]) && optString(x["favicon"]) && optString(x["label"]);
+const failureWord = (x, allowed) => isRecord(x) && typeof x["code"] === "string" && allowed.includes(x["code"]);
+const OUTCOME_SHAPE = {
+    publish: (o) => isRecord(o) &&
+        (o["ok"] === true
+            ? isRef(o["ref"])
+            : o["ok"] === false &&
+                (o["code"] === "conflict"
+                    ? typeof o["currentVersion"] === "string" && (o["current"] === "reread" || isSnapshot(o["current"]))
+                    : failureWord(o, ["url_foreign", "forbidden", "payload_too_large", "not_found", "force_refused", "refused"]) && typeof o["message"] === "string")),
+    list: (o) => isRecord(o) &&
+        (o["ok"] === true
+            ? everyItem(o["rows"], (r) => isRef(r) && isRecord(r) && (r["owner"] === "mine" || r["owner"] === "shared") && typeof r["updatedAt"] === "string") && typeof o["truncated"] === "boolean"
+            : o["ok"] === false && failureWord(o, ["refused"]) && typeof o["message"] === "string"),
+    read: (o) => isRecord(o) && (o["ok"] === true ? isRef(o["ref"]) && typeof o["content"] === "string" && typeof o["isolatedSummary"] === "boolean" : o["ok"] === false && failureWord(o, ["not_found", "forbidden"]) && typeof o["message"] === "string"),
+    list_files: (o) => isRecord(o) && (o["ok"] === true ? everyItem(o["entries"], (e) => isRecord(e) && typeof e["path"] === "string" && typeof e["bytes"] === "number" && optString(e["mediaType"])) : o["ok"] === false && failureWord(o, ["not_found", "forbidden"]) && typeof o["message"] === "string"),
+    read_file: (o) => isRecord(o) && (o["ok"] === true ? isFile(o["file"]) : o["ok"] === false && failureWord(o, ["not_found", "forbidden"]) && typeof o["message"] === "string"),
+};
+function callHost(action, fn, signal) {
+    if (signal?.aborted)
+        return Promise.resolve({ ok: false, kind: "aborted", message: "the call was aborted before the host was reached" });
+    return new Promise((resolve) => {
+        const onAbort = () => resolve({ ok: false, kind: "aborted", message: "the call was aborted while the host was working" });
+        signal?.addEventListener("abort", onAbort, { once: true });
+        let p;
+        try {
+            p = Promise.resolve(fn());
+        }
+        catch (err) {
+            signal?.removeEventListener("abort", onAbort);
+            resolve({ ok: false, kind: "threw", message: err instanceof Error ? err.message : String(err) });
+            return;
+        }
+        p.then((value) => resolve(OUTCOME_SHAPE[action](value) ? { ok: true, value } : { ok: false, kind: "malformed", message: `the ${action} answer was outside the host contract` }), (err) => resolve({ ok: false, kind: "threw", message: err instanceof Error ? err.message : String(err) })).finally(() => signal?.removeEventListener("abort", onAbort));
+    });
+}
+function buildSchema(caps) {
+    const has = (a) => caps.actions.includes(a);
+    const props = {
+        action: Type.Optional(Type.Unsafe({ type: "string", enum: [...caps.actions], description: actionDescription(caps.actions) })),
+        file_path: Type.Optional(Type.String({ description: PARAM_TEXT.filePath })),
+        url: Type.Optional(Type.String({ maxLength: 2048, description: urlDescription(caps.actions) })),
+        title: Type.Optional(Type.String({ maxLength: 200, description: PARAM_TEXT.title })),
+        description: Type.Optional(Type.String({ maxLength: 1000, description: PARAM_TEXT.description })),
+        favicon: Type.Optional(Type.String({ maxLength: 32, description: PARAM_TEXT.favicon })),
+        label: Type.Optional(Type.String({ maxLength: 60, description: PARAM_TEXT.label })),
+        baseVersion: Type.Optional(Type.String({ maxLength: 200, description: PARAM_TEXT.baseVersion })),
+        force: Type.Optional(Type.Boolean({ description: PARAM_TEXT.force })),
+        publishContext: Type.Optional(Type.Unsafe({ type: "string", enum: [...ARTIFACT_PUBLISH_CONTEXTS], description: PARAM_TEXT.publishContext })),
+    };
+    if (caps.multiFile) {
+        props["files"] = Type.Optional(Type.Array(Type.Object({ path: Type.String(), file_path: Type.String() }), { maxItems: MAX_FILES_PER_PUBLISH, description: PARAM_TEXT.files }));
+    }
+    if (has("list")) {
+        props["scope"] = Type.Optional(Type.Unsafe({ type: "string", enum: [...ARTIFACT_LIST_SCOPES], description: PARAM_TEXT.scope }));
+        props["limit"] = Type.Optional(Type.Integer({ minimum: 1, maximum: LIST_LIMIT_MAX, description: PARAM_TEXT.limit }));
+    }
+    if (has("read_file"))
+        props["path"] = Type.Optional(Type.String({ maxLength: 1024, description: PARAM_TEXT.path }));
+    return Type.Object(props);
+}
+const invalid = (text) => errorResult(`Error (Artifact): ${text}`, { type: "artifact", invalidArguments: true });
+const typed = (code, text, extra = {}) => errorResult(`Error (Artifact): ${text}`, { type: "artifact", code: ARTIFACT_FAILURE_RESULT_CODE[code], ...extra });
+export function createArtifactTool(opts) {
+    const { host, capabilities: caps, runId, taskId, sessionId, agentName, readLocalFile } = opts;
+    const versions = new Map();
+    const bindings = new Map();
+    const occurrences = new Map();
+    const hasAction = (a) => caps.actions.includes(a);
+    const rememberRef = (ref) => {
+        versions.set(ref.url, ref.version);
+    };
+    const attemptIdOf = (ctx) => {
+        const n = occurrences.get(ctx.toolCallId) ?? 0;
+        occurrences.set(ctx.toolCallId, n + 1);
+        return artifactAttemptId(runId, ctx.toolCallId, n);
+    };
+    const contextFor = (attemptId) => ({
+        taskId,
+        ...(sessionId !== undefined ? { sessionId } : {}),
+        ...(agentName !== undefined ? { agentName } : {}),
+        runId,
+        attemptId,
+    });
+    const hostError = (verb, fault, url) => {
+        if (caps.plane === "local-stub" && fault.kind === "threw") {
+            return errorResult(`Error (Artifact): the local artifact stub failed before committing (${inlineUntrusted(fault.message, 200)}). Nothing was published; the call can be repeated.`, {
+                type: "artifact", code: ARTIFACT_HOST_ERROR_CODE, outcome: "not_executed", plane: caps.plane,
+            });
+        }
+        const verifiable = hasAction("read") && url !== "";
+        return errorResult(`Error (Artifact): the artifact host did not answer the ${verb.slice(0, 20)} (${inlineUntrusted(fault.message, 200)}). Whether it was applied is not known.${verifiable ? ` Verify with action: "read" on ${url.slice(0, 200)} before repeating the call.` : ""}`, {
+            type: "artifact", code: ARTIFACT_HOST_ERROR_CODE, outcome: "unknown", plane: caps.plane,
+        });
+    };
+    const notFoundOrForbidden = (code, url, message) => code === "not_found"
+        ? typed(code, `no artifact at ${inlineUntrusted(url, 200)} (${inlineUntrusted(message, 200)}).`, { url })
+        : typed(code, `${inlineUntrusted(url, 200)} is not accessible to this session (${inlineUntrusted(message, 200)}).`, { url });
+    const readRefusal = (path, r) => {
+        switch (r.reason) {
+            case "refused":
+                return errorResult(r.text.slice(0, 4000), r.details);
+            case "too_large":
+                return typed("payload_too_large", `${inlineUntrusted(path, 200)} is ${String(r.size).slice(0, 20)} bytes; this host accepts at most ${String(r.limit).slice(0, 20)} bytes for it${r.judgedOn === "metadata" ? " (the file was not read)" : " (it grew past its declared size while being read)"}.`, { limit: r.limit, measured: r.size, judgedOn: r.judgedOn });
+            case "not_a_file":
+                return invalid(`${inlineUntrusted(path, 200)} is a ${inlineUntrusted(r.kind, 20)}, not a regular file.`);
+            default: {
+                const _exhaustive = r;
+                return _exhaustive;
+            }
+        }
+    };
+    async function publish(a, ctx) {
+        const attemptId = attemptIdOf(ctx);
+        if (a.file_path === undefined)
+            return invalid("`file_path` is required to publish.");
+        const files = [];
+        const budget = Math.min(caps.maxFileBytes, caps.maxTotalBytes);
+        const first = await readLocalFile(a.file_path, budget, ctx.signal);
+        if (!first.ok)
+            return readRefusal(a.file_path, first);
+        files.push({ path: basenameOf(a.file_path), content: first.bytes, mediaType: mediaTypeOf(a.file_path) });
+        let total = first.bytes.byteLength;
+        const url = a.url ?? bindings.get(first.key);
+        if (url === undefined && (a.force === true || a.baseVersion !== undefined)) {
+            return invalid("`force` and `baseVersion` only apply to an update — pass `url`, or republish the same file path this session already published.");
+        }
+        if (a.files !== undefined && a.files.length > 0) {
+            if (!caps.multiFile)
+                return invalid("this artifact host publishes single files only; `files` is not accepted.");
+            const seen = new Set([files[0].path.normalize("NFC").toLowerCase()]);
+            for (const entry of a.files) {
+                const norm = normalizePublishedPath(entry.path);
+                if (!norm.ok)
+                    return invalid(`files entry ${inlineUntrusted(entry.path, 120)} ${norm.reason.slice(0, 80)}.`);
+                const fold = norm.path.toLowerCase();
+                if (seen.has(fold))
+                    return invalid(`files entry ${inlineUntrusted(norm.path, 120)} collides with another published path.`);
+                seen.add(fold);
+                const left = caps.maxTotalBytes - total;
+                if (left <= 0)
+                    return typed("payload_too_large", `the files already total ${String(total).slice(0, 20)} bytes; this host accepts at most ${String(caps.maxTotalBytes).slice(0, 20)} bytes per version.`, { limit: caps.maxTotalBytes, measured: total });
+                const r = await readLocalFile(entry.file_path, Math.min(caps.maxFileBytes, left), ctx.signal);
+                if (!r.ok)
+                    return readRefusal(entry.file_path, r);
+                total += r.bytes.byteLength;
+                files.push({ path: norm.path, content: r.bytes, mediaType: mediaTypeOf(norm.path) });
+            }
+        }
+        const baseVersion = a.baseVersion ?? (url !== undefined ? versions.get(url) : undefined);
+        const req = {
+            ...(url !== undefined ? { url } : {}),
+            files,
+            ...(a.title !== undefined ? { title: a.title } : {}),
+            ...(a.description !== undefined ? { description: a.description } : {}),
+            ...(a.favicon !== undefined ? { favicon: a.favicon } : {}),
+            ...(a.label !== undefined ? { label: a.label } : {}),
+            ...(baseVersion !== undefined ? { baseVersion } : {}),
+            ...(a.force === true ? { force: true } : {}),
+            publishContext: a.publishContext ?? "plain",
+        };
+        const call = await callHost("publish", () => host.publish(req, contextFor(attemptId)), ctx.signal);
+        if (!call.ok)
+            return hostError("publish", call, inlineUntrusted(url ?? "", 200));
+        const out = call.value;
+        if (out.ok) {
+            rememberRef(out.ref);
+            bindings.set(first.key, out.ref.url);
+            const title = out.ref.title !== undefined ? ` — ${inlineUntrusted(out.ref.title, 120)}` : "";
+            return {
+                content: `Published ${inlineUntrusted(out.ref.url, 300)} (version ${inlineUntrusted(out.ref.version, 60)})${title}.`,
+                details: { type: "artifact", action: "publish", plane: caps.plane, ref: out.ref, update: url !== undefined },
+            };
+        }
+        if (out.code === "conflict") {
+            const snapshot = out.current;
+            if (snapshot !== "reread" && url !== undefined)
+                versions.set(url, out.currentVersion);
+            const handedBack = snapshot === "reread"
+                ? hasAction("read")
+                    ? `The current content was not handed back; read it with action: "read" on ${inlineUntrusted(url ?? "", 200)}.`
+                    : "The current content was not handed back by the host."
+                : `Current content follows.\n${renderSnapshotMeta(snapshot)}${snapshot.files.map(renderFile).join("\n")}`;
+            return errorResult(`Error (Artifact): publish conflict — ${inlineUntrusted(url ?? "", 200)} is at version ${inlineUntrusted(out.currentVersion, 60)}, this publish was based on ${inlineUntrusted(baseVersion ?? "", 60)}. Merge your changes onto the current content and publish again. ${handedBack}`, { type: "artifact", code: ARTIFACT_FAILURE_RESULT_CODE.conflict, url, currentVersion: out.currentVersion, current: snapshot === "reread" ? "reread" : { ...snapshot, files: snapshot.files.map((f) => ({ path: f.path, bytes: f.content.byteLength, mediaType: f.mediaType })) } });
+        }
+        switch (out.code) {
+            case "url_foreign":
+                return typed(out.code, `${inlineUntrusted(url ?? "", 200)} is not an artifact this host (or this run) published; nothing was published (${inlineUntrusted(out.message, 200)}).`, { url });
+            case "forbidden":
+                return typed(out.code, `${inlineUntrusted(url ?? "", 200)} is not this session's to update; nothing was published (${inlineUntrusted(out.message, 200)}).`, { url });
+            case "payload_too_large":
+                return typed(out.code, `the host refused the payload as too large; nothing was published (${inlineUntrusted(out.message, 200)}).`);
+            case "not_found":
+                return typed(out.code, `no artifact at ${inlineUntrusted(url ?? "", 200)}; nothing was published (${inlineUntrusted(out.message, 200)}).`, { url });
+            case "force_refused":
+                return typed(out.code, `the host refused to overwrite with force; nothing was published (${inlineUntrusted(out.message, 200)}). Merge onto the current version instead.`, { url });
+            case "refused":
+                return typed(out.code, `the host refused the publish; nothing was published (${inlineUntrusted(out.message, 200)}).`);
+            default: {
+                const _exhaustive = out;
+                return _exhaustive;
+            }
+        }
+    }
+    async function list(a, ctx) {
+        const attemptId = attemptIdOf(ctx);
+        const scope = a.scope ?? "mine";
+        const limit = a.limit ?? LIST_LIMIT_DEFAULT;
+        const call = await callHost("list", () => host.list({ scope, limit }, contextFor(attemptId)), ctx.signal);
+        if (!call.ok)
+            return hostError("list", call, "");
+        const out = call.value;
+        if (!out.ok)
+            return typed("refused", `the host refused the listing (${inlineUntrusted(out.message, 200)}).`);
+        const lines = out.rows.map((r) => `${inlineUntrusted(r.url, 300)}  v${inlineUntrusted(r.version, 40)}  ${inlineUntrusted(r.updatedAt, 40)}  (${r.owner})${r.title !== undefined ? `  ${inlineUntrusted(r.title, 120)}` : ""}`);
+        const body = lines.length === 0 ? "nothing listed" : lines.join("\n");
+        return { content: `${body}${out.truncated ? "\n(more artifacts exist; raise `limit` to see them)" : ""}`, details: { type: "artifact", action: "list", plane: caps.plane, scope, rows: out.rows, truncated: out.truncated } };
+    }
+    async function read(a, ctx) {
+        const attemptId = attemptIdOf(ctx);
+        if (a.url === undefined)
+            return invalid("`url` is required to read an artifact.");
+        const call = await callHost("read", () => host.read({ url: a.url }, contextFor(attemptId)), ctx.signal);
+        if (!call.ok)
+            return hostError("read", call, inlineUntrusted(a.url, 200));
+        const out = call.value;
+        if (!out.ok)
+            return notFoundOrForbidden(out.code, a.url, out.message);
+        rememberRef(out.ref);
+        const head = out.isolatedSummary ? `[isolated summary of a shared artifact — ${inlineUntrusted(out.ref.url, 300)}, version ${inlineUntrusted(out.ref.version, 60)}]\n` : "";
+        return { content: `${head}${out.content}`, details: { type: "artifact", action: "read", plane: caps.plane, ref: out.ref, isolatedSummary: out.isolatedSummary } };
+    }
+    async function listFiles(a, ctx) {
+        const attemptId = attemptIdOf(ctx);
+        if (a.url === undefined)
+            return invalid("`url` is required to list an artifact's files.");
+        const call = await callHost("list_files", () => host.listFiles({ url: a.url }, contextFor(attemptId)), ctx.signal);
+        if (!call.ok)
+            return hostError("list_files", call, inlineUntrusted(a.url, 200));
+        const out = call.value;
+        if (!out.ok)
+            return notFoundOrForbidden(out.code, a.url, out.message);
+        const lines = out.entries.map((e) => `${inlineUntrusted(e.path, 200)}  ${String(e.bytes).slice(0, 20)} bytes${e.mediaType !== undefined ? `  ${inlineUntrusted(e.mediaType, 80)}` : ""}`);
+        return { content: lines.length === 0 ? "no files" : lines.join("\n"), details: { type: "artifact", action: "list_files", plane: caps.plane, url: a.url, entries: out.entries } };
+    }
+    async function readFile(a, ctx) {
+        const attemptId = attemptIdOf(ctx);
+        if (a.url === undefined || a.path === undefined)
+            return invalid("`url` and `path` are required to read a published file.");
+        const call = await callHost("read_file", () => host.readFile({ url: a.url, path: a.path }, contextFor(attemptId)), ctx.signal);
+        if (!call.ok)
+            return hostError("read_file", call, inlineUntrusted(a.url, 200));
+        const out = call.value;
+        if (!out.ok)
+            return notFoundOrForbidden(out.code, a.url, out.message);
+        return { content: renderFile(out.file), details: { type: "artifact", action: "read_file", plane: caps.plane, url: a.url, path: out.file.path, bytes: out.file.content.byteLength, mediaType: out.file.mediaType } };
+    }
+    return {
+        name: ARTIFACT_TOOL_NAME,
+        ...toolFace("artifact"),
+        contentOrigin: ARTIFACT_PLANE_CONTENT_ORIGIN[caps.plane],
+        description: artifactDescription(caps.plane, caps.actions),
+        parameters: buildSchema(caps),
+        prepareArguments: (args) => (isRecord(args) && args["action"] === undefined ? { ...args, action: "publish" } : args),
+        execute: (args, ctx) => {
+            const a = args;
+            const action = a.action ?? "publish";
+            if (!hasAction(action))
+                return invalid(`action ${inlineUntrusted(String(action), 40)} is not available on this artifact host.`);
+            switch (action) {
+                case "publish":
+                    return publish(a, ctx);
+                case "list":
+                    return list(a, ctx);
+                case "read":
+                    return read(a, ctx);
+                case "list_files":
+                    return listFiles(a, ctx);
+                case "read_file":
+                    return readFile(a, ctx);
+                default: {
+                    const _exhaustive = action;
+                    return _exhaustive;
+                }
+            }
+        },
+    };
+}

package/dist/tools/artifact/local-stub.d.ts

@@ -0,0 +1,26 @@
+import { type ArtifactCallContext, type ArtifactHost, type ArtifactHostCapabilities, type ArtifactPublishOutcome, type ArtifactPublishRequest, type ArtifactRef } from "../../core/artifact-host.js";
+export declare const EVAL_STUB_URL_PREFIX = "eval-stub://artifact/";
+export declare const LOCAL_STUB_MAX_FILE_BYTES: number;
+export declare const LOCAL_STUB_MAX_TOTAL_BYTES: number;
+export interface LocalArtifactStubOptions {
+    /** The storage directory. Required: the library never guesses a location on the host filesystem. Contract: it must
+     *  lie OUTSIDE every root the run may write or read (the task root, `additionalDirectories`,
+     *  `additionalReadDirectories`); the engine refuses to mount a stub whose store is inside one — a ledger the model
+     *  can edit through the fs tools is not a trust boundary. */
+    dir: string;
+}
+export declare class LocalArtifactStub implements ArtifactHost {
+    #private;
+    readonly dir: string;
+    constructor(opts: LocalArtifactStubOptions);
+    capabilities(): ArtifactHostCapabilities;
+    onMount(runId: string): void;
+    /** The slugs a run may name through `url` (inspection; a copy). */
+    ownMinted(runId: string): ReadonlySet<string>;
+    publish(req: ArtifactPublishRequest, ctx: ArtifactCallContext): Promise<ArtifactPublishOutcome>;
+    /** The ledger rows (inspection for hosts and tests; a copy). */
+    rows(): ReadonlyArray<ArtifactRef>;
+    /** The published paths of one version (inspection). */
+    versionFiles(slug: string, version: number): string[];
+}
+export declare function localArtifactStub(opts: LocalArtifactStubOptions): LocalArtifactStub;