@plico-ai/runtime 0.0.0-stage → 0.1.0

package/dist/providers/ai-sdk.js

@@ -0,0 +1,154 @@
+import { APICallError, dynamicTool, jsonSchema, streamText, } from "ai";
+import { ModelProviderError } from "../errors.js";
+function toMessages(request) {
+    return request.messages.map((message) => {
+        if (message.role === "system" || message.role === "user")
+            return { role: message.role, content: message.content };
+        if (message.role === "tool")
+            return {
+                role: "tool",
+                content: [
+                    {
+                        type: "tool-result",
+                        toolCallId: message.toolCallId ?? "",
+                        toolName: message.toolName ?? "",
+                        output: { type: "text", value: message.content },
+                    },
+                ],
+            };
+        const metadata = message.providerMetadata;
+        const envelope = metadata && typeof metadata === "object" && !Array.isArray(metadata) ? metadata : undefined;
+        const adapter = envelope?.plicoAdapter;
+        const reasoning = adapter &&
+            typeof adapter === "object" &&
+            !Array.isArray(adapter) &&
+            typeof adapter.reasoning === "string"
+            ? adapter.reasoning
+            : undefined;
+        const providerOptions = (envelope?.sdk ?? metadata);
+        return {
+            role: "assistant",
+            ...(providerOptions === undefined ? {} : { providerOptions }),
+            content: [
+                ...(reasoning ? [{ type: "reasoning", text: reasoning }] : []),
+                ...(message.content ? [{ type: "text", text: message.content }] : []),
+                ...(message.toolCalls ?? []).map((call) => ({
+                    type: "tool-call",
+                    toolCallId: call.id ?? "",
+                    toolName: call.name,
+                    input: call.arguments,
+                    ...(call.providerMetadata === undefined
+                        ? {}
+                        : {
+                            providerOptions: call.providerMetadata,
+                        }),
+                })),
+            ],
+        };
+    });
+}
+function toTools(request) {
+    return Object.fromEntries((request.tools ?? []).map((entry) => [
+        entry.name,
+        dynamicTool({ description: entry.description, inputSchema: jsonSchema(entry.inputSchema) }),
+    ]));
+}
+/** Wraps an AI SDK language model behind the Plico model port. Provider retries are off. */
+export function createAiSdkModelProvider(options) {
+    return {
+        async *stream(request, { signal }) {
+            try {
+                const apiKey = options.apiKeyEnv ? process.env[options.apiKeyEnv] : undefined;
+                if (options.apiKeyEnv && !apiKey)
+                    throw new ModelProviderError("auth", `Missing model provider credential: set ${options.apiKeyEnv}.`);
+                // Setup problems (a missing adapter package, a broken provider module) are local and
+                // actionable, so their message is kept. They are not a network failure and not retried.
+                let model;
+                try {
+                    model = await options.createModel(apiKey);
+                }
+                catch (error) {
+                    throw new ModelProviderError("bad_request", error instanceof Error ? error.message : "Model provider setup failed.");
+                }
+                const response = streamText({
+                    model,
+                    messages: toMessages(request),
+                    tools: toTools(request),
+                    allowSystemInMessages: true,
+                    maxRetries: 0,
+                    streamRetries: 0,
+                    abortSignal: signal,
+                    onError: () => { },
+                });
+                let metadata;
+                let reasoning = "";
+                for await (const part of response.fullStream) {
+                    if (part.type === "text-delta")
+                        yield { type: "text", text: part.text };
+                    else if (part.type === "reasoning-delta")
+                        reasoning += part.text;
+                    else if (part.type === "tool-call")
+                        yield {
+                            type: "tool.call",
+                            call: {
+                                id: part.toolCallId,
+                                name: part.toolName,
+                                arguments: part.input,
+                                ...(part.providerMetadata
+                                    ? { providerMetadata: part.providerMetadata }
+                                    : {}),
+                            },
+                        };
+                    else if (part.type === "finish-step")
+                        metadata = part.providerMetadata;
+                    else if (part.type === "error")
+                        throw part.error;
+                    else if (part.type === "finish") {
+                        if (part.finishReason !== "stop" && part.finishReason !== "tool-calls")
+                            throw new ModelProviderError("bad_request", `Model response did not complete (finish reason: ${part.finishReason}).`);
+                        yield {
+                            type: "finish",
+                            usage: {
+                                inputTokens: part.totalUsage.inputTokens ?? 0,
+                                outputTokens: part.totalUsage.outputTokens ?? 0,
+                            },
+                            ...(!reasoning && metadata === undefined
+                                ? {}
+                                : {
+                                    providerMetadata: {
+                                        ...(metadata === undefined ? {} : { sdk: metadata }),
+                                        ...(reasoning ? { plicoAdapter: { reasoning } } : {}),
+                                    },
+                                }),
+                        };
+                    }
+                }
+            }
+            catch (error) {
+                if (signal.aborted)
+                    throw new ModelProviderError("aborted", "Model request aborted.");
+                if (error instanceof ModelProviderError)
+                    throw error;
+                if (APICallError.isInstance(error)) {
+                    const status = error.statusCode;
+                    if (status === 401 || status === 403)
+                        throw new ModelProviderError("auth", "Model provider authentication failed. Check credentials.");
+                    if (status === 429)
+                        throw new ModelProviderError("rate_limit", "Model provider rate limit reached.");
+                    if (status === 503 || (status !== undefined && status >= 500))
+                        throw new ModelProviderError("overloaded", "Model provider is unavailable.");
+                    if (status !== undefined && status >= 400 && isContextLengthError(error))
+                        throw new ModelProviderError("context_length", "The conversation is too long for the model's context window. Start a new thread, or choose a model with a larger context.");
+                    if (status !== undefined && status >= 400)
+                        throw new ModelProviderError("bad_request", `Model provider rejected the request (HTTP ${status}).`);
+                }
+                throw new ModelProviderError("network", "Model provider request failed.");
+            }
+        },
+    };
+}
+const CONTEXT_LENGTH = /context[_ ]length|context window|prompt is too long|too many tokens|exceeds? the maximum (number of )?tokens|input token count/i;
+/** Providers word this differently, so match the code and message they return for an over-long input. */
+function isContextLengthError(error) {
+    return CONTEXT_LENGTH.test(`${error.message} ${error.responseBody ?? ""}`);
+}

package/dist/providers/configured.d.ts

@@ -0,0 +1,17 @@
+import type { ProjectConfig } from "@plico-ai/contracts";
+import type { ModelProvider } from "../types/index.js";
+type ModelConfig = NonNullable<ProjectConfig["model"]>;
+export declare function supportsModelProvider(provider: string): boolean;
+/**
+ * The model port for a project's configured model. A provider outside the native list comes from
+ * `providers/<name>.ts` and needs the project root; without it there is no adapter.
+ */
+export declare function createConfiguredModelProvider(model: ModelConfig, projectRoot?: string): ModelProvider | undefined;
+/** Hash the provider target and credential without storing either secret in the journal. */
+export declare function modelProviderRecoveryKey(model: ModelConfig): string;
+/**
+ * Hash only the account and credential. A queued run has not called a model yet, so changing the
+ * configured model must not strand its reservation.
+ */
+export declare function modelProviderAccountKey(model: ModelConfig): string;
+export {};

package/dist/providers/configured.js

@@ -0,0 +1,60 @@
+import { createHash } from "node:crypto";
+import { NATIVE_MODEL_PROVIDERS } from "@plico-ai/core";
+import { createAiSdkModelProvider } from "./ai-sdk.js";
+import { createOpenAICompatibleProvider } from "./openai-compatible.js";
+import { createProjectModuleProvider } from "./project-module.js";
+import { nativeProvider, resolveModelEndpoint } from "./registry.js";
+export function supportsModelProvider(provider) {
+    return NATIVE_MODEL_PROVIDERS.includes(provider);
+}
+/**
+ * The model port for a project's configured model. A provider outside the native list comes from
+ * `providers/<name>.ts` and needs the project root; without it there is no adapter.
+ */
+export function createConfiguredModelProvider(model, projectRoot) {
+    const { apiKeyEnv, baseURL } = resolveModelEndpoint(model);
+    const native = nativeProvider(model.provider);
+    if (native)
+        return createAiSdkModelProvider({
+            apiKeyEnv,
+            createModel: async (apiKey) => (await native.create({
+                model: model.name,
+                apiKey: apiKey ?? "",
+                baseURL,
+            })),
+        });
+    if (model.provider === "openai-compatible")
+        return createOpenAICompatibleProvider({
+            model: model.name,
+            baseURL,
+            ...(apiKeyEnv ? { apiKeyEnv } : {}),
+        });
+    if (!projectRoot)
+        return undefined;
+    return createProjectModuleProvider(projectRoot, model.provider, {
+        model: model.name,
+        apiKeyEnv,
+        ...(model.baseURL ? { baseURL: model.baseURL } : {}),
+    });
+}
+function hashParts(parts) {
+    return createHash("sha256").update(JSON.stringify(parts)).digest("hex");
+}
+/** Hash the provider target and credential without storing either secret in the journal. */
+export function modelProviderRecoveryKey(model) {
+    const { apiKeyEnv, baseURL } = resolveModelEndpoint(model);
+    return hashParts([
+        model.provider,
+        model.name,
+        baseURL,
+        (apiKeyEnv ? process.env[apiKeyEnv] : "") ?? "",
+    ]);
+}
+/**
+ * Hash only the account and credential. A queued run has not called a model yet, so changing the
+ * configured model must not strand its reservation.
+ */
+export function modelProviderAccountKey(model) {
+    const { apiKeyEnv, baseURL } = resolveModelEndpoint(model);
+    return hashParts([model.provider, baseURL, (apiKeyEnv ? process.env[apiKeyEnv] : "") ?? ""]);
+}

package/dist/providers/openai-compatible.d.ts

@@ -0,0 +1,8 @@
+import type { ModelProvider } from "../types/index.js";
+export interface OpenAICompatibleProviderOptions {
+    model: string;
+    apiKeyEnv?: string;
+    baseURL?: string;
+    fetch?: typeof globalThis.fetch;
+}
+export declare function createOpenAICompatibleProvider(options: OpenAICompatibleProviderOptions): ModelProvider;

package/dist/providers/openai-compatible.js

@@ -0,0 +1,14 @@
+import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
+import { createAiSdkModelProvider } from "./ai-sdk.js";
+export function createOpenAICompatibleProvider(options) {
+    return createAiSdkModelProvider({
+        apiKeyEnv: options.apiKeyEnv ?? "OPENAI_API_KEY",
+        createModel: (apiKey) => createOpenAICompatible({
+            name: "plico",
+            baseURL: options.baseURL ?? "https://api.openai.com/v1",
+            ...(apiKey ? { apiKey } : {}),
+            includeUsage: true,
+            ...(options.fetch ? { fetch: options.fetch } : {}),
+        })(options.model),
+    });
+}

package/dist/providers/project-module.d.ts

@@ -0,0 +1,7 @@
+import type { ModelProvider } from "../types/index.js";
+/** A provider the project supplies in `providers/<name>.ts`, run behind the Plico model port. */
+export declare function createProjectModuleProvider(root: string, provider: string, input: {
+    model: string;
+    apiKeyEnv: string | undefined;
+    baseURL?: string;
+}): ModelProvider;

package/dist/providers/project-module.js

@@ -0,0 +1,29 @@
+import { pathToFileURL } from "node:url";
+import { findProjectProviderFile } from "@plico-ai/core";
+import { register } from "tsx/esm/api";
+import { createAiSdkModelProvider } from "./ai-sdk.js";
+let registered = false;
+/** A provider the project supplies in `providers/<name>.ts`, run behind the Plico model port. */
+export function createProjectModuleProvider(root, provider, input) {
+    return createAiSdkModelProvider({
+        apiKeyEnv: input.apiKeyEnv,
+        createModel: async (apiKey) => {
+            const file = await findProjectProviderFile(root, provider);
+            if (!file)
+                throw new Error(`Missing model provider module: providers/${provider}.ts`);
+            if (!registered) {
+                register();
+                registered = true;
+            }
+            const loaded = (await import(pathToFileURL(file).href));
+            if (typeof loaded.default !== "function")
+                throw new Error(`providers/${provider} must export a function by default.`);
+            const options = {
+                model: input.model,
+                ...(apiKey ? { apiKey } : {}),
+                ...(input.baseURL ? { baseURL: input.baseURL } : {}),
+            };
+            return (await loaded.default(options));
+        },
+    });
+}

package/dist/providers/registry.d.ts

@@ -0,0 +1,20 @@
+import type { ProjectConfig } from "@plico-ai/contracts";
+type ModelConfig = NonNullable<ProjectConfig["model"]>;
+interface NativeProvider {
+    apiKeyEnv: string;
+    /** The endpoint used when neither the config nor the environment sets one. */
+    baseURL: string;
+    /** Returns an AI SDK language model. Adapter packages may pin another `@ai-sdk/provider` copy, so it is typed loosely here. */
+    create: (input: {
+        model: string;
+        apiKey: string;
+        baseURL: string;
+    }) => Promise<unknown>;
+}
+export declare function nativeProvider(provider: string): NativeProvider | undefined;
+/** The credential variable and endpoint a configured model uses, for the run and the recovery key. */
+export declare function resolveModelEndpoint(model: ModelConfig): {
+    apiKeyEnv: string | undefined;
+    baseURL: string;
+};
+export {};

package/dist/providers/registry.js

@@ -0,0 +1,53 @@
+/** The adapters are optional peer packages, so each loads only when its provider is used. */
+async function load(packageName, importer) {
+    try {
+        return await importer();
+    }
+    catch {
+        throw new Error(`Install ${packageName} to use this model provider: pnpm add ${packageName}`);
+    }
+}
+const OPENAI_URL = "https://api.openai.com/v1";
+const NATIVE = {
+    anthropic: {
+        apiKeyEnv: "ANTHROPIC_API_KEY",
+        baseURL: "https://api.anthropic.com/v1",
+        create: async ({ model, apiKey, baseURL }) => (await load("@ai-sdk/anthropic", () => import("@ai-sdk/anthropic"))).createAnthropic({
+            apiKey,
+            baseURL,
+        })(model),
+    },
+    google: {
+        apiKeyEnv: "GOOGLE_GENERATIVE_AI_API_KEY",
+        baseURL: "https://generativelanguage.googleapis.com/v1beta",
+        create: async ({ model, apiKey, baseURL }) => (await load("@ai-sdk/google", () => import("@ai-sdk/google"))).createGoogleGenerativeAI({
+            apiKey,
+            baseURL,
+        })(model),
+    },
+    openai: {
+        apiKeyEnv: "OPENAI_API_KEY",
+        baseURL: OPENAI_URL,
+        // The chat endpoint is the one every OpenAI-compatible server also speaks.
+        create: async ({ model, apiKey, baseURL }) => (await load("@ai-sdk/openai", () => import("@ai-sdk/openai")))
+            .createOpenAI({ apiKey, baseURL })
+            .chat(model),
+    },
+};
+export function nativeProvider(provider) {
+    return NATIVE[provider];
+}
+/** The credential variable and endpoint a configured model uses, for the run and the recovery key. */
+export function resolveModelEndpoint(model) {
+    const native = nativeProvider(model.provider);
+    const usesOpenAIEnv = model.provider === "openai" || model.provider === "openai-compatible";
+    return {
+        apiKeyEnv: model.apiKeyEnv ??
+            native?.apiKeyEnv ??
+            (model.provider === "openai-compatible" ? "OPENAI_API_KEY" : undefined),
+        baseURL: model.baseURL ??
+            (usesOpenAIEnv ? process.env.OPENAI_BASE_URL : undefined) ??
+            native?.baseURL ??
+            OPENAI_URL,
+    };
+}

package/dist/readiness/check-readiness.d.ts

@@ -0,0 +1,2 @@
+import type { ReadinessOptions, ReadinessReport } from "../types/index.js";
+export declare function checkReadiness(projectRoot: string, options?: ReadinessOptions): Promise<ReadinessReport>;

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>;