@sema-agent/core/dist/core/artifact-host.js

Stateless, task-oriented AI agent core

import { isAbsoluteForFamily, pathFamilyOf } from "../tools/fs/safety.js";
import { thrownText } from "./thrown-value.js";
export const ARTIFACT_ACTIONS = Object.freeze(["publish", "list", "read", "list_files", "read_file"]);
export const ARTIFACT_PLANES = Object.freeze(["hosted", "local-stub"]);
export const ARTIFACT_COMMIT_CERTAINTIES = Object.freeze(["throw_means_uncommitted", "uncertain"]);
export const ARTIFACT_COMMIT_THROW_OUTCOME = {
    throw_means_uncommitted: "not_executed",
    uncertain: "unknown",
};
export const ARTIFACT_PUBLISH_CONTEXTS = Object.freeze(["pr_review", "workshop", "whiteboard", "prototype", "plain"]);
export const ARTIFACT_LIST_SCOPES = Object.freeze(["mine", "shared", "all"]);
export const ARTIFACT_PLANE_CONTENT_ORIGIN = {
    hosted: "external",
    "local-stub": "local",
};
export const ARTIFACT_ACTION_HOST_METHOD = {
    publish: "publish",
    list: "list",
    read: "read",
    list_files: "listFiles",
    read_file: "readFile",
};
export const ARTIFACT_ACTION_CONCURRENCY_SAFE = {
    publish: false,
    list: true,
    read: true,
    list_files: true,
    read_file: true,
};
export const ARTIFACT_HOST_FAILURE_CODES = Object.freeze(["conflict", "url_foreign", "forbidden", "payload_too_large", "not_found", "force_refused", "refused"]);
export const ARTIFACT_FAILURE_RESULT_CODE = {
    conflict: "artifact.publish_conflict",
    url_foreign: "artifact.url_foreign",
    forbidden: "artifact.forbidden",
    payload_too_large: "artifact.payload_too_large",
    not_found: "artifact.not_found",
    force_refused: "artifact.force_refused",
    refused: "artifact.refused",
};
export const ARTIFACT_HOST_ERROR_CODE = "artifact.host_error";
export const ARTIFACT_CARD = "artifact";
const isPositiveInt = (v) => typeof v === "number" && Number.isSafeInteger(v) && v > 0;
const wordOf = (set, v) => typeof v === "string" && set.includes(v);
export function readArtifactHostCapabilities(host) {
    if (host === null || typeof host !== "object")
        return { ok: false, problem: "artifactHost is not an object" };
    const h = host;
    if (typeof h.capabilities !== "function")
        return { ok: false, problem: "artifactHost.capabilities is not a function" };
    let raw;
    try {
        raw = h.capabilities.call(host);
    }
    catch (err) {
        return { ok: false, problem: `artifactHost.capabilities() threw: ${thrownText(err)}` };
    }
    if (raw === null || typeof raw !== "object")
        return { ok: false, problem: "artifactHost.capabilities() did not return an object" };
    const c = raw;
    const plane = c["plane"];
    if (!wordOf(ARTIFACT_PLANES, plane))
        return { ok: false, problem: `capabilities.plane must be one of ${ARTIFACT_PLANES.join(" | ")}` };
    const actions = c["actions"];
    if (!Array.isArray(actions) || actions.length === 0)
        return { ok: false, problem: "capabilities.actions must be a non-empty array" };
    for (const a of actions)
        if (!wordOf(ARTIFACT_ACTIONS, a))
            return { ok: false, problem: `capabilities.actions carries a word outside ${ARTIFACT_ACTIONS.join(" | ")}` };
    if (new Set(actions).size !== actions.length)
        return { ok: false, problem: "capabilities.actions carries a duplicate" };
    if (!actions.includes("publish"))
        return { ok: false, problem: 'capabilities.actions must include "publish"' };
    if (plane === "local-stub" && (actions.length !== 1 || actions[0] !== "publish"))
        return { ok: false, problem: 'a "local-stub" plane must declare exactly ["publish"]' };
    const commit = c["commit"];
    if (!wordOf(ARTIFACT_COMMIT_CERTAINTIES, commit))
        return { ok: false, problem: `capabilities.commit must be one of ${ARTIFACT_COMMIT_CERTAINTIES.join(" | ")}` };
    if (c["defaultVisibility"] !== "private")
        return { ok: false, problem: 'capabilities.defaultVisibility must be "private"' };
    if (!isPositiveInt(c["maxFileBytes"]))
        return { ok: false, problem: "capabilities.maxFileBytes must be a positive integer" };
    if (!isPositiveInt(c["maxTotalBytes"]))
        return { ok: false, problem: "capabilities.maxTotalBytes must be a positive integer" };
    if (typeof c["multiFile"] !== "boolean")
        return { ok: false, problem: "capabilities.multiFile must be a boolean" };
    const storageDir = c["storageDir"];
    if (plane === "local-stub" && (typeof storageDir !== "string" || storageDir.length === 0 || !isAbsoluteForFamily(pathFamilyOf({ root: storageDir }), storageDir)))
        return { ok: false, problem: 'a "local-stub" plane must declare its absolute storageDir' };
    if (storageDir !== undefined && typeof storageDir !== "string")
        return { ok: false, problem: "capabilities.storageDir must be a string when present" };
    for (const a of actions) {
        const method = ARTIFACT_ACTION_HOST_METHOD[a];
        if (typeof host[method] !== "function")
            return { ok: false, problem: `capabilities.actions declares "${a}" but artifactHost.${method} is not a function` };
    }
    return {
        ok: true,
        capabilities: Object.freeze({
            plane,
            actions: Object.freeze([...actions]),
            commit,
            defaultVisibility: "private",
            maxFileBytes: c["maxFileBytes"],
            maxTotalBytes: c["maxTotalBytes"],
            multiFile: c["multiFile"],
            ...(typeof storageDir === "string" ? { storageDir } : {}),
        }),
    };
}