@plico-ai/runtime 0.0.0-reserved.0 → 0.1.0

package/dist/readiness/check-readiness.js

@@ -0,0 +1,33 @@
+import { join } from "node:path";
+import { checkArtifactAccess } from "./checks/artifact-access.js";
+import { checkArtifacts } from "./checks/artifacts.js";
+import { checkEnv } from "./checks/env.js";
+import { checkEvals } from "./checks/evals.js";
+import { checkPersistence } from "./checks/persistence.js";
+import { checkProject } from "./checks/project.js";
+import { checkProvider } from "./checks/provider.js";
+import { checkServerConfig } from "./checks/server-config.js";
+import { checkStudio } from "./checks/studio.js";
+import { checkThreadStore } from "./checks/thread-store.js";
+import { checkTools } from "./checks/tools.js";
+import { openDatabase } from "./open-database.js";
+export async function checkReadiness(projectRoot, options = {}) {
+    const projectCheck = await checkProject(projectRoot);
+    const diagnostics = [...projectCheck.diagnostics];
+    if (!projectCheck.project) {
+        return summarize(projectRoot, diagnostics);
+    }
+    const databasePath = options.databasePath ?? join(projectRoot, ".plico", "plico.sqlite");
+    const database = openDatabase(databasePath, options.eventStore);
+    diagnostics.push(...checkEnv(projectRoot), ...checkProvider(projectCheck.project.config.model), checkArtifactAccess(projectCheck.project.config), ...(await checkTools(projectCheck.project)), ...(await checkEvals(projectRoot, database.eventStore)), ...checkThreadStore(database.eventStore, options.threadStore), ...(await checkPersistence(databasePath, database)), ...(await checkArtifacts(projectRoot)), ...(await checkServerConfig(projectRoot)), ...(await checkStudio(options.studioPath)));
+    return summarize(projectRoot, diagnostics);
+}
+function summarize(projectRoot, diagnostics) {
+    const count = (severity) => diagnostics.filter((d) => d.severity === severity).length;
+    return {
+        projectRoot,
+        timestamp: new Date().toISOString(),
+        diagnostics,
+        summary: { ok: count("ok"), warning: count("warning"), error: count("error") },
+    };
+}

package/dist/readiness/checks/approval-policy.d.ts

@@ -0,0 +1,5 @@
+import type { LoadedProject } from "@plico-ai/core";
+import type { DeclaredTool, ReadinessDiagnostic } from "../../types/index.js";
+export declare function checkApprovalPolicy(project: LoadedProject, tools: DeclaredTool[], options?: {
+    toolsComplete?: boolean;
+}): ReadinessDiagnostic[];

package/dist/readiness/checks/approval-policy.js

@@ -0,0 +1,19 @@
+import { makeDiagnostic } from "../diagnostic.js";
+export function checkApprovalPolicy(project, tools, options = {}) {
+    const toolsComplete = options.toolsComplete ?? true;
+    const names = new Set(tools.map((tool) => tool.name));
+    const diagnostics = toolsComplete
+        ? Object.keys(project.config.approvals?.tools ?? {})
+            .filter((name) => !names.has(name))
+            .map((name) => makeDiagnostic("warning", "approvals.policy", `Approval policy refers to undeclared tool "${name}".`, "plico.config.ts"))
+        : [];
+    for (const tool of tools) {
+        if (tool.approval.required && project.config.approvals?.tools?.[tool.name] === "none") {
+            diagnostics.push(makeDiagnostic("warning", "approvals.policy", `Tool "${tool.name}" requires approval in its declaration; the "none" override has no effect.`));
+        }
+    }
+    if (diagnostics.length === 0 && toolsComplete) {
+        diagnostics.push(makeDiagnostic("ok", "approvals.policy", `Approval policy checked against ${tools.length} declared tool(s).`));
+    }
+    return diagnostics;
+}

package/dist/readiness/checks/artifact-access.d.ts

@@ -0,0 +1,3 @@
+import type { ProjectConfig } from "@plico-ai/contracts";
+import type { ReadinessDiagnostic } from "../../types/index.js";
+export declare function checkArtifactAccess(config: ProjectConfig): ReadinessDiagnostic;

package/dist/readiness/checks/artifact-access.js

@@ -0,0 +1,5 @@
+import { makeDiagnostic } from "../diagnostic.js";
+export function checkArtifactAccess(config) {
+    const access = config.artifacts?.access ?? "read-write";
+    return makeDiagnostic("ok", "artifacts.access", `Model-facing artifact tools access is "${access}".`, "plico.config.ts");
+}

package/dist/readiness/checks/artifacts.d.ts

@@ -0,0 +1,6 @@
+import type { ReadinessDiagnostic } from "../../types/index.js";
+/**
+ * Files a run writes are events in the log (ADR 0002), not files in `artifacts/`, so the folder
+ * is only part of the project layout. Its writability says nothing about artifacts and is not checked.
+ */
+export declare function checkArtifacts(projectRoot: string): Promise<ReadinessDiagnostic[]>;

package/dist/readiness/checks/artifacts.js

@@ -0,0 +1,22 @@
+import { access } from "node:fs/promises";
+import { getProjectPaths, getProjectRelativePaths } from "@plico-ai/core";
+import { makeDiagnostic } from "../diagnostic.js";
+/**
+ * Files a run writes are events in the log (ADR 0002), not files in `artifacts/`, so the folder
+ * is only part of the project layout. Its writability says nothing about artifacts and is not checked.
+ */
+export async function checkArtifacts(projectRoot) {
+    const directory = getProjectPaths(projectRoot).directories.artifacts;
+    const folder = `${getProjectRelativePaths().directories.artifacts}/`;
+    try {
+        await access(directory);
+    }
+    catch {
+        return [
+            makeDiagnostic("warning", "artifacts.workspace", `${folder} directory not found. Create it to keep the project layout complete.`),
+        ];
+    }
+    return [
+        makeDiagnostic("ok", "artifacts.workspace", "Artifacts a run writes are stored in the event log, not in this folder", folder),
+    ];
+}

package/dist/readiness/checks/env.d.ts

@@ -0,0 +1,3 @@
+import type { ReadinessDiagnostic } from "@plico-ai/contracts";
+/** Says which `.env` file was loaded. It never reads or prints the values. */
+export declare function checkEnv(projectRoot: string): ReadinessDiagnostic[];

package/dist/readiness/checks/env.js

@@ -0,0 +1,10 @@
+import { join } from "node:path";
+import { loadedEnvFiles } from "../../env.js";
+import { makeDiagnostic } from "../diagnostic.js";
+/** Says which `.env` file was loaded. It never reads or prints the values. */
+export function checkEnv(projectRoot) {
+    const file = join(projectRoot, ".env");
+    if (!loadedEnvFiles().includes(file))
+        return [];
+    return [makeDiagnostic("ok", "env.loaded", "Environment variables loaded from .env.", ".env")];
+}

package/dist/readiness/checks/evals.d.ts

@@ -0,0 +1,2 @@
+import type { EventStore, ReadinessDiagnostic } from "../../types/index.js";
+export declare function checkEvals(projectRoot: string, eventStore: EventStore | undefined): Promise<ReadinessDiagnostic[]>;

package/dist/readiness/checks/evals.js

@@ -0,0 +1,53 @@
+import { access } from "node:fs/promises";
+import { getProjectPaths, getProjectRelativePaths } from "@plico-ai/core";
+import { digestEvalFixtures, discoverEvalCases } from "../../evals/discover.js";
+import { makeDiagnostic } from "../diagnostic.js";
+export async function checkEvals(projectRoot, eventStore) {
+    const evalsDir = getProjectPaths(projectRoot).directories.evals;
+    const folder = `${getProjectRelativePaths().directories.evals}/`;
+    try {
+        await access(evalsDir);
+    }
+    catch {
+        return [
+            makeDiagnostic("warning", "evals.fixtures", `${folder} directory not found. Create ${folder} to add eval fixtures.`),
+        ];
+    }
+    let cases;
+    try {
+        cases = await discoverEvalCases(evalsDir);
+    }
+    catch (error) {
+        return [makeDiagnostic("error", "evals.fixtures", error.message)];
+    }
+    const fixtures = cases.length === 0
+        ? makeDiagnostic("warning", "evals.fixtures", "No .script.json eval fixtures found. Add evals to track behavior.")
+        : makeDiagnostic("ok", "evals.fixtures", `${cases.length} eval fixture(s) found`);
+    return eventStore
+        ? [fixtures, await readEvalResults(eventStore, await digestEvalFixtures(evalsDir))]
+        : [fixtures];
+}
+async function readEvalResults(eventStore, fixturesDigest) {
+    try {
+        return describeEvalResults(await eventStore.getLatestEvalReport(), fixturesDigest);
+    }
+    catch (error) {
+        return makeDiagnostic("error", "evals.results", `Could not read eval results: ${error.message}`);
+    }
+}
+function describeEvalResults(report, fixturesDigest) {
+    if (!report) {
+        return makeDiagnostic("warning", "evals.results", "No eval runs have been executed. Run plico eval to see results.");
+    }
+    if (report.fixturesDigest !== fixturesDigest) {
+        return makeDiagnostic("warning", "evals.results", "Eval fixtures changed since the latest run. Run plico eval to refresh results.");
+    }
+    if (report.total === 0) {
+        return makeDiagnostic("warning", "evals.results", "The latest eval run found no fixtures.");
+    }
+    if (report.failed > 0) {
+        const names = report.results.filter((r) => r.status === "fail").map((r) => r.name);
+        return makeDiagnostic("error", "evals.results", `${report.failed}/${report.total} eval(s) failed in the latest run: ${names.join(", ")}`);
+    }
+    return makeDiagnostic("ok", "evals.results", `${report.passed}/${report.total} eval(s) passed (${report.evaluatedAt})`);
+}

package/dist/readiness/checks/persistence.d.ts

@@ -0,0 +1,3 @@
+import type { ReadinessDiagnostic } from "../../types/index.js";
+import type { ReadinessDatabase } from "../open-database.js";
+export declare function checkPersistence(dbPath: string, database: ReadinessDatabase): Promise<ReadinessDiagnostic[]>;

package/dist/readiness/checks/persistence.js

@@ -0,0 +1,61 @@
+import { access, constants } from "node:fs/promises";
+import { dirname } from "node:path";
+import { makeDiagnostic } from "../diagnostic.js";
+export async function checkPersistence(dbPath, database) {
+    if (database.openError !== undefined) {
+        return [cannotRead(database.openError, dbPath)];
+    }
+    if (database.eventStore) {
+        try {
+            await database.eventStore.listRuns();
+        }
+        catch (error) {
+            return [cannotRead(error.message, dbPath)];
+        }
+    }
+    // An attached store is already open for writing, so only its reads need proving.
+    if (database.attached) {
+        return [makeDiagnostic("ok", "persistence.storage", "Event store is attached")];
+    }
+    if (database.eventStore) {
+        const writable = (await exists(dbPath, constants.W_OK)) && (await exists(dirname(dbPath), constants.W_OK));
+        return writable
+            ? [makeDiagnostic("ok", "persistence.storage", "Database is writable", dbPath)]
+            : [makeDiagnostic("error", "persistence.storage", "Database is not writable", dbPath)];
+    }
+    // Read-only probe: the database can be created later if the nearest existing
+    // ancestor directory is writable. Readiness must never touch the filesystem.
+    if (await isCreatable(dbPath)) {
+        return [
+            makeDiagnostic("warning", "persistence.storage", "Database file does not exist yet but its location is writable. Run plico run --dry --persist to initialize.", dbPath),
+        ];
+    }
+    return [
+        makeDiagnostic("error", "persistence.storage", "Persistence path is not writable", dbPath),
+    ];
+}
+function cannotRead(reason, dbPath) {
+    return makeDiagnostic("error", "persistence.storage", `Database cannot be read: ${reason}`, dbPath);
+}
+async function isCreatable(path) {
+    let current = dirname(path);
+    while (true) {
+        if (await exists(current, constants.W_OK))
+            return true;
+        if (await exists(current, constants.F_OK))
+            return false;
+        const parent = dirname(current);
+        if (parent === current)
+            return false;
+        current = parent;
+    }
+}
+async function exists(path, mode) {
+    try {
+        await access(path, mode);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/readiness/checks/project.d.ts

@@ -0,0 +1,7 @@
+import { type LoadedProject } from "@plico-ai/core";
+import type { ReadinessDiagnostic } from "../../types/index.js";
+export interface ProjectCheck {
+    diagnostics: ReadinessDiagnostic[];
+    project: LoadedProject | undefined;
+}
+export declare function checkProject(projectRoot: string): Promise<ProjectCheck>;

package/dist/readiness/checks/project.js

@@ -0,0 +1,21 @@
+import { validateProject } from "@plico-ai/core";
+import { makeDiagnostic } from "../diagnostic.js";
+export async function checkProject(projectRoot) {
+    const diagnostics = [];
+    const validation = await validateProject(projectRoot);
+    if (!validation.ok || !validation.project) {
+        for (const issue of validation.errors ?? []) {
+            const subsystem = issue.path.startsWith("tools/") ? "tools.discovery" : "project.structure";
+            diagnostics.push(makeDiagnostic("error", subsystem, issue.message, issue.path));
+        }
+        for (const issue of validation.warnings ?? []) {
+            diagnostics.push(makeDiagnostic("warning", "project.structure", issue.message, issue.path));
+        }
+        return { diagnostics, project: validation.project };
+    }
+    diagnostics.push(makeDiagnostic("ok", "project.structure", "Project is valid", "plico.config.ts"));
+    for (const issue of validation.warnings ?? []) {
+        diagnostics.push(makeDiagnostic("warning", "project.structure", issue.message, issue.path));
+    }
+    return { diagnostics, project: validation.project };
+}

package/dist/readiness/checks/provider.d.ts

@@ -0,0 +1,2 @@
+import type { ProjectConfig, ReadinessDiagnostic } from "@plico-ai/contracts";
+export declare function checkProvider(model: ProjectConfig["model"]): ReadinessDiagnostic[];

package/dist/readiness/checks/provider.js

@@ -0,0 +1,20 @@
+import { resolveModelEndpoint } from "../../providers/registry.js";
+import { makeDiagnostic } from "../diagnostic.js";
+export function checkProvider(model) {
+    if (!model)
+        return [
+            makeDiagnostic("warning", "provider.config", "No model configured. Add model settings for real provider runs.", "plico.config.ts"),
+        ];
+    const { apiKeyEnv } = resolveModelEndpoint(model);
+    if (!apiKeyEnv)
+        return [
+            makeDiagnostic("ok", "provider.credentials", "The project supplies its own provider credentials."),
+        ];
+    if (!process.env[apiKeyEnv])
+        return [
+            makeDiagnostic("warning", "provider.credentials", `Set ${apiKeyEnv} to run the configured model.`),
+        ];
+    return [
+        makeDiagnostic("ok", "provider.credentials", "Model provider credentials are configured."),
+    ];
+}

package/dist/readiness/checks/server-config.d.ts

@@ -0,0 +1,2 @@
+import type { ReadinessDiagnostic } from "../../types/index.js";
+export declare function checkServerConfig(projectRoot: string): Promise<ReadinessDiagnostic[]>;

package/dist/readiness/checks/server-config.js

@@ -0,0 +1,13 @@
+import { loadProject } from "@plico-ai/core";
+import { makeDiagnostic } from "../diagnostic.js";
+export async function checkServerConfig(projectRoot) {
+    try {
+        await loadProject(projectRoot);
+        return [makeDiagnostic("ok", "server.config", "Project config loads successfully for server")];
+    }
+    catch {
+        return [
+            makeDiagnostic("warning", "server.config", "plico.config.ts could not be loaded. Server may not start."),
+        ];
+    }
+}

package/dist/readiness/checks/studio.d.ts

@@ -0,0 +1,2 @@
+import type { ReadinessDiagnostic } from "../../types/index.js";
+export declare function checkStudio(studioPath: string | undefined): Promise<ReadinessDiagnostic[]>;

package/dist/readiness/checks/studio.js

@@ -0,0 +1,16 @@
+import { access } from "node:fs/promises";
+import { join } from "node:path";
+import { makeDiagnostic } from "../diagnostic.js";
+export async function checkStudio(studioPath) {
+    if (studioPath === undefined)
+        return [];
+    try {
+        await access(join(studioPath, "index.html"));
+        return [makeDiagnostic("ok", "studio.assets", "Studio assets are built", studioPath)];
+    }
+    catch {
+        return [
+            makeDiagnostic("warning", "studio.assets", "Studio assets not found. Build them with: pnpm --filter @plico-ai/studio build", studioPath),
+        ];
+    }
+}

package/dist/readiness/checks/thread-store.d.ts

@@ -0,0 +1,3 @@
+import type { ThreadStore } from "../../storage/sqlite/threads.js";
+import type { EventStore, ReadinessDiagnostic } from "../../types/index.js";
+export declare function checkThreadStore(eventStore: EventStore | undefined, threadStore: Pick<ThreadStore, "storageIdentity"> | undefined): ReadinessDiagnostic[];

package/dist/readiness/checks/thread-store.js

@@ -0,0 +1,12 @@
+import { makeDiagnostic } from "../diagnostic.js";
+export function checkThreadStore(eventStore, threadStore) {
+    if (!threadStore)
+        return [];
+    const sharesIdentity = threadStore.storageIdentity !== undefined &&
+        threadStore.storageIdentity === eventStore?.storageIdentity;
+    return sharesIdentity
+        ? [makeDiagnostic("ok", "threads.store", "Thread and run stores share the same database.")]
+        : [
+            makeDiagnostic("error", "threads.store", "Thread and run stores must use the same database. Thread runs cannot start."),
+        ];
+}

package/dist/readiness/checks/tools.d.ts

@@ -0,0 +1,3 @@
+import { type LoadedProject } from "@plico-ai/core";
+import type { ReadinessDiagnostic } from "../../types/index.js";
+export declare function checkTools(project: LoadedProject): Promise<ReadinessDiagnostic[]>;

package/dist/readiness/checks/tools.js

@@ -0,0 +1,42 @@
+import { join } from "node:path";
+import { getProjectPaths, getProjectRelativePaths } from "@plico-ai/core";
+import { discoverToolFiles, loadToolFile } from "../../tools/index.js";
+import { makeDiagnostic } from "../diagnostic.js";
+import { checkApprovalPolicy } from "./approval-policy.js";
+export async function checkTools(project) {
+    const diagnostics = [];
+    const projectPaths = getProjectPaths(project.root);
+    const relativePaths = getProjectRelativePaths();
+    let toolFiles;
+    try {
+        toolFiles = await discoverToolFiles(project);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        return [
+            makeDiagnostic("error", "tools.discovery", "tools/ directory not found. Create tools/ to declare tools.", relativePaths.directories.tools),
+            ...checkApprovalPolicy(project, [], { toolsComplete: false }),
+        ];
+    }
+    if (toolFiles.length === 0) {
+        diagnostics.push(makeDiagnostic("warning", "tools.discovery", "No tools declared. Add a .tool.ts module to get started."));
+        diagnostics.push(...checkApprovalPolicy(project, []));
+        return diagnostics;
+    }
+    let validCount = 0;
+    const tools = [];
+    for (const entry of toolFiles) {
+        const source = `${relativePaths.directories.tools}/${entry}`;
+        try {
+            tools.push(await loadToolFile(join(projectPaths.directories.tools, entry), source));
+            validCount++;
+        }
+        catch (error) {
+            diagnostics.push(makeDiagnostic("error", "tools.discovery", `Schema validation failed for ${entry}: ${String(error)}`, source));
+        }
+    }
+    diagnostics.push(makeDiagnostic(validCount === toolFiles.length ? "ok" : "warning", "tools.discovery", `${validCount}/${toolFiles.length} tool(s) valid`));
+    diagnostics.push(...checkApprovalPolicy(project, tools, { toolsComplete: validCount === toolFiles.length }));
+    return diagnostics;
+}

package/dist/readiness/diagnostic.d.ts

@@ -0,0 +1,2 @@
+import type { ReadinessDiagnostic } from "../types/index.js";
+export declare function makeDiagnostic(severity: ReadinessDiagnostic["severity"], subsystem: string, message: string, path?: string): ReadinessDiagnostic;

package/dist/readiness/diagnostic.js

@@ -0,0 +1,7 @@
+export function makeDiagnostic(severity, subsystem, message, path) {
+    const result = { severity, subsystem, message };
+    if (path !== undefined) {
+        result.path = path;
+    }
+    return result;
+}

package/dist/readiness/index.d.ts

@@ -0,0 +1 @@
+export { checkReadiness } from "./check-readiness.js";

package/dist/readiness/index.js

@@ -0,0 +1 @@
+export { checkReadiness } from "./check-readiness.js";

package/dist/readiness/open-database.d.ts

@@ -0,0 +1,8 @@
+import type { EventStore } from "../types/index.js";
+export interface ReadinessDatabase {
+    eventStore?: EventStore;
+    /** True when the caller supplied the store, rather than readiness opening one. */
+    attached: boolean;
+    openError?: string;
+}
+export declare function openDatabase(databasePath: string, eventStore: EventStore | undefined): ReadinessDatabase;

package/dist/readiness/open-database.js

@@ -0,0 +1,15 @@
+import { existsSync } from "node:fs";
+import { createSqliteEventStore } from "../storage/index.js";
+export function openDatabase(databasePath, eventStore) {
+    if (eventStore)
+        return { eventStore, attached: true };
+    if (!existsSync(databasePath))
+        return { attached: false };
+    try {
+        const store = createSqliteEventStore({ databasePath, readOnly: true });
+        return { eventStore: store, attached: false };
+    }
+    catch (error) {
+        return { attached: false, openError: error.message };
+    }
+}

package/dist/run/artifact-tool-context.d.ts

@@ -0,0 +1,19 @@
+import type { ArtifactContent, PlicoEvent, PlicoEventPayloads } from "@plico-ai/contracts";
+import type { ToolArtifactContext } from "../types/index.js";
+export interface StagedArtifactWrite {
+    path: string;
+    content: ArtifactContent;
+    mimeType: string;
+    contentHash: string;
+    version: number;
+}
+interface StagedArtifactContext {
+    context: ToolArtifactContext;
+    writes(): StagedArtifactWrite[];
+    workspaceCreated(): boolean;
+    workspaceId: string;
+}
+export declare function createStagedArtifactContext(runId: string, threadId: string | undefined, history: PlicoEvent[]): StagedArtifactContext;
+export declare function validateArtifactPath(path: string): void;
+export declare function artifactWriteEventPayload(write: StagedArtifactWrite): PlicoEventPayloads["artifact.file.written"];
+export {};

package/dist/run/artifact-tool-context.js

@@ -0,0 +1,74 @@
+import { artifactFileMetadata, buildArtifactWorkspace, decodeArtifactContent, encodeArtifactContent, hashArtifactContent, } from "../artifacts.js";
+const maxArtifactContentBytes = 1024 * 1024;
+const maxArtifactPathLength = 1024;
+export function createStagedArtifactContext(runId, threadId, history) {
+    const workspaceId = threadId ? `${threadId}:workspace` : `${runId}:workspace`;
+    const initialWorkspace = buildArtifactWorkspace(workspaceId, history);
+    const files = new Map((initialWorkspace?.files ?? []).map((file) => [file.path, file]));
+    const writesList = [];
+    const context = {
+        async read(path) {
+            const file = files.get(path);
+            if (!file)
+                return undefined;
+            return { ...file, content: decodeArtifactContent(file.content) };
+        },
+        async write(path, content, options) {
+            validateArtifactPath(path);
+            validateArtifactContent(content);
+            const encoded = encodeArtifactContent(content);
+            const file = {
+                path,
+                content: encoded,
+                mimeType: options?.mimeType ??
+                    (typeof content === "string" ? "text/plain" : "application/octet-stream"),
+                version: (files.get(path)?.version ?? 0) + 1,
+                contentHash: hashArtifactContent(encoded),
+            };
+            files.set(path, file);
+            writesList.push({
+                path: file.path,
+                content: file.content,
+                mimeType: file.mimeType,
+                contentHash: file.contentHash,
+                version: file.version,
+            });
+            return { path, version: file.version };
+        },
+        async list() {
+            return [...files.values()].map(artifactFileMetadata);
+        },
+    };
+    return {
+        context,
+        writes: () => [...writesList],
+        workspaceCreated: () => initialWorkspace === undefined && writesList.length > 0,
+        workspaceId,
+    };
+}
+export function validateArtifactPath(path) {
+    const segments = path.split(/[\\/]/);
+    if (path.length === 0 ||
+        path.length > maxArtifactPathLength ||
+        path.startsWith("/") ||
+        path.startsWith("\\") ||
+        /^[a-zA-Z]:/.test(path) ||
+        segments.some((segment) => segment === ".." || segment === "")) {
+        throw new Error(`Invalid artifact path: expected a non-empty relative path without '..' and at most ${maxArtifactPathLength} characters.`);
+    }
+}
+function validateArtifactContent(content) {
+    const sizeBytes = typeof content === "string" ? Buffer.byteLength(content, "utf8") : content.byteLength;
+    if (sizeBytes > maxArtifactContentBytes)
+        throw new Error("Artifact content exceeds the 1 MiB write limit.");
+}
+export function artifactWriteEventPayload(write) {
+    const content = write.content;
+    return {
+        path: write.path,
+        content,
+        mimeType: write.mimeType,
+        contentHash: write.contentHash,
+        version: write.version,
+    };
+}

package/dist/run/finalize.d.ts

@@ -0,0 +1,16 @@
+import type { PlicoEvent, RunResult, RunStatus } from "@plico-ai/contracts";
+import type { ValidationIssue } from "@plico-ai/core";
+import type { EventStore } from "../types/index.js";
+export interface FinalizeRunInput {
+    runId: string;
+    projectRoot: string;
+    projectName: string;
+    status: RunStatus;
+    startedAt: string;
+    events: PlicoEvent[];
+    output?: string | undefined;
+    errors?: ValidationIssue[] | undefined;
+    eventStore?: EventStore | undefined;
+}
+/** Builds the result after the run has stopped or finished. */
+export declare function finalizeRun(input: FinalizeRunInput): Promise<RunResult>;

package/dist/run/finalize.js

@@ -0,0 +1,11 @@
+/** Builds the result after the run has stopped or finished. */
+export async function finalizeRun(input) {
+    const result = {
+        runId: input.runId,
+        status: input.status,
+        ...(input.output === undefined ? {} : { output: input.output }),
+        events: input.events,
+        ...(input.errors === undefined ? {} : { errors: input.errors }),
+    };
+    return result;
+}

package/dist/run/index.d.ts

@@ -0,0 +1 @@
+export { recoverRuns, runProject } from "./run-project.js";

package/dist/run/index.js

@@ -0,0 +1 @@
+export { recoverRuns, runProject } from "./run-project.js";

package/dist/run/pinned-instructions.d.ts

@@ -0,0 +1,18 @@
+import type { ValidationIssue } from "@plico-ai/contracts";
+import { type LoadedProject, type Skill } from "@plico-ai/core";
+import type { InMemoryEventLog } from "../events.js";
+/**
+ * Records the instructions and skills a run starts with. A run that resumes reuses what it
+ * recorded, so editing `agent.md` or a skill while it waits does not change its behaviour.
+ */
+export declare function pinInstructions(project: LoadedProject, events: InMemoryEventLog): Promise<{
+    instructions: {
+        content: string;
+    };
+    skills: Skill[];
+}>;
+/**
+ * A run that already recorded its instructions and skills does not read them again, so an
+ * `agent.md` or skill that is invalid now must not stop it from resuming.
+ */
+export declare function ignoredWhenPinned(issue: ValidationIssue): boolean;