@plico-ai/runtime 0.0.0-stage → 0.1.0

package/dist/engine/types.d.ts

@@ -0,0 +1,97 @@
+export interface StepOptions {
+    /** Extra attempts inside one step. Defaults to 0: the step runs once unless the process dies inside it. */
+    retries?: number;
+    /** When supplied, only errors accepted by this predicate are retried. */
+    shouldRetry?: (error: unknown) => boolean;
+}
+export interface StepAttempt {
+    /** Zero-based attempt number within this step. */
+    attempt: number;
+    /** Aborts when the run is cancelled, so a long step can stop early. */
+    signal: AbortSignal;
+}
+export interface RunContext {
+    readonly runId: string;
+    /** Aborts when the run is cancelled. */
+    readonly signal: AbortSignal;
+    /**
+     * Runs `fn` and records its result. When the run is replayed, the recorded result is returned
+     * and `fn` does not run. Results are stored as JSON, so `undefined` properties are dropped.
+     * A step runs at least once: a process that dies inside it runs it again on recovery.
+     */
+    step<T>(name: string, fn: (attempt: StepAttempt) => T | Promise<T>, options?: StepOptions): Promise<T>;
+    /**
+     * Holds the run until a signal named `name` arrives or the timeout passes. A signal that arrived
+     * earlier is used at once. Nothing executes while the run waits: the first time there is nothing
+     * to return, this throws RunSuspended. Let it reach the engine, or catch it and return; the engine
+     * replays the workflow from its recorded steps once the wait can end. Use a unique name per wait.
+     */
+    wait<T = unknown>(name: string, options?: WaitOptions): Promise<WaitOutcome<T>>;
+}
+/** How a run ended for now. A waiting run may carry what the workflow returned before it stopped. */
+export type RunOutcome<O> = {
+    state: "completed";
+    output: O;
+} | {
+    state: "waiting";
+    output?: O;
+} | {
+    state: "cancelled";
+    output?: O;
+};
+/** `ignored`: the run had already finished or been cancelled. */
+export type CancelResult = "accepted" | "ignored" | "unknown";
+/** `ignored`: a decision arrived late, twice, or for a finished run. The first one wins. */
+export type SignalResult = "accepted" | "ignored" | "unknown";
+export interface WaitOptions {
+    /** Ends the wait as a timeout this long after it is first reached. No timeout by default. */
+    timeoutMs?: number;
+}
+/** A timeout is its own outcome, so a caller can tell it from a decision. */
+export type WaitOutcome<T> = {
+    kind: "signal";
+    value: T;
+} | {
+    kind: "timeout";
+};
+export type Workflow<I, O> = (ctx: RunContext, input: I) => Promise<O>;
+export interface RunHandle<O> {
+    readonly runId: string;
+    result(): Promise<RunOutcome<O>>;
+}
+export type ExecutionState = "running" | "waiting" | "completed" | "failed" | "cancelled";
+export interface ExecutionStatus {
+    state: ExecutionState;
+}
+export interface RecoveredRun<O = unknown> {
+    runId: string;
+    state: "completed" | "waiting" | "failed" | "cancelled";
+    error?: string;
+    output?: O;
+}
+export interface Engine {
+    /** Registers the run and begins executing it in the background. */
+    start<I, O>(runId: string, workflow: Workflow<I, O>, input: I): Promise<RunHandle<O>>;
+    /** Starts the run and waits until it completes or stops to wait. */
+    run<I, O>(runId: string, workflow: Workflow<I, O>, input: I): Promise<RunOutcome<O>>;
+    /** Continues an unfinished run from its recorded steps, whoever held it. */
+    resume<I, O>(runId: string, workflow: Workflow<I, O>): Promise<RunOutcome<O>>;
+    /**
+     * Delivers a decision to the wait named `name`. The first signal for a name wins; one that comes
+     * after the wait ended changes nothing. A run waiting in this process continues at once; any other
+     * continues when `recover` next runs.
+     */
+    signal(runId: string, name: string, value: unknown): Promise<SignalResult>;
+    /**
+     * Continues every run whose worker died or let its lease run out, and every waiting run whose
+     * wait can now end. `resolve` picks the workflow for a run; return undefined to leave it alone.
+     */
+    recover<I, O>(resolve: (runId: string, input: I) => Workflow<I, O> | undefined): Promise<RecoveredRun<O>[]>;
+    /**
+     * Cancels a run. A step that is running gets its abort signal fired; a waiting run ends at once
+     * where it holds the run, or when `recover` next runs. The workflow sees RunCancelled at its next
+     * step or wait and returns.
+     */
+    cancel(runId: string): Promise<CancelResult>;
+    status(runId: string): Promise<ExecutionStatus | undefined>;
+}

package/dist/engine/types.js

@@ -0,0 +1 @@
+export {};

package/dist/env.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Loads `<root>/.env` into `process.env` without replacing variables that are already set, and
+ * returns the file path, or `undefined` when the project has none. Values are never logged.
+ */
+export declare function loadProjectEnv(root: string): string | undefined;
+/** The `.env` files this process loaded through {@link loadProjectEnv}. */
+export declare function loadedEnvFiles(): string[];

package/dist/env.js

@@ -0,0 +1,19 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+const loaded = new Set();
+/**
+ * Loads `<root>/.env` into `process.env` without replacing variables that are already set, and
+ * returns the file path, or `undefined` when the project has none. Values are never logged.
+ */
+export function loadProjectEnv(root) {
+    const file = join(root, ".env");
+    if (!existsSync(file))
+        return undefined;
+    process.loadEnvFile(file);
+    loaded.add(file);
+    return file;
+}
+/** The `.env` files this process loaded through {@link loadProjectEnv}. */
+export function loadedEnvFiles() {
+    return [...loaded];
+}

package/dist/errors.d.ts

@@ -0,0 +1,18 @@
+import type { PlicoEventPayloads } from "@plico-ai/contracts";
+export declare class RuntimeDiagnosticError extends Error {
+    readonly payload: PlicoEventPayloads["run.error"];
+    constructor(payload: PlicoEventPayloads["run.error"]);
+}
+export declare class RunWaitingError extends Error {
+    readonly output: string | undefined;
+    constructor(output: string | undefined);
+}
+export declare function errorMessage(error: unknown): string;
+export declare function runtimeErrorPayload(error: unknown): PlicoEventPayloads["run.error"];
+export type ModelErrorKind = "rate_limit" | "overloaded" | "auth" | "bad_request" | "context_length" | "aborted" | "network";
+/** Provider adapters normalize errors to these provider-neutral kinds. */
+export declare class ModelProviderError extends Error {
+    readonly kind: ModelErrorKind;
+    readonly retryable: boolean;
+    constructor(kind: ModelErrorKind, message: string);
+}

package/dist/errors.js

@@ -0,0 +1,40 @@
+export class RuntimeDiagnosticError extends Error {
+    payload;
+    constructor(payload) {
+        super(typeof payload.message === "string" ? payload.message : "Runtime diagnostic error");
+        this.payload = payload;
+    }
+}
+export class RunWaitingError extends Error {
+    output;
+    constructor(output) {
+        super("Run waiting for approval");
+        this.output = output;
+    }
+}
+export function errorMessage(error) {
+    if (error instanceof Error && error.message) {
+        return error.message;
+    }
+    return "Unknown runtime error";
+}
+export function runtimeErrorPayload(error) {
+    if (error instanceof RuntimeDiagnosticError) {
+        return error.payload;
+    }
+    return {
+        phase: "runtime",
+        message: errorMessage(error),
+    };
+}
+/** Provider adapters normalize errors to these provider-neutral kinds. */
+export class ModelProviderError extends Error {
+    kind;
+    retryable;
+    constructor(kind, message) {
+        super(message);
+        this.kind = kind;
+        this.name = "ModelProviderError";
+        this.retryable = kind === "rate_limit" || kind === "overloaded" || kind === "network";
+    }
+}

package/dist/evals/discover.d.ts

@@ -0,0 +1,3 @@
+import type { EvalCase } from "../types/index.js";
+export declare function discoverEvalCases(evalsDir: string): Promise<EvalCase[]>;
+export declare function digestEvalFixtures(evalsDir: string): Promise<string>;

package/dist/evals/discover.js

@@ -0,0 +1,49 @@
+import { createHash } from "node:crypto";
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+const fixtureSuffix = ".script.json";
+function toEvalCase(file, parsed) {
+    const fixture = (Array.isArray(parsed) ? { script: parsed } : parsed);
+    if (!Array.isArray(fixture?.script)) {
+        throw new Error(`Invalid eval fixture ${file}: expected a step array or a "script" array.`);
+    }
+    const entry = {
+        name: typeof fixture.name === "string" ? fixture.name : file.slice(0, -fixtureSuffix.length),
+        script: fixture.script,
+    };
+    if (typeof fixture.description === "string")
+        entry.description = fixture.description;
+    if (fixture.expect !== undefined)
+        entry.expect = fixture.expect;
+    return entry;
+}
+async function readFixtures(evalsDir) {
+    let entries;
+    try {
+        entries = await readdir(evalsDir);
+    }
+    catch {
+        return [];
+    }
+    const scriptFiles = entries.filter((e) => e.endsWith(fixtureSuffix)).sort();
+    return Promise.all(scriptFiles.map(async (file) => ({ file, raw: await readFile(join(evalsDir, file), "utf8") })));
+}
+function parseFixture(file, raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`Invalid eval fixture ${file}: ${error.message}`);
+    }
+}
+export async function discoverEvalCases(evalsDir) {
+    const fixtures = await readFixtures(evalsDir);
+    return fixtures.map(({ file, raw }) => toEvalCase(file, parseFixture(file, raw)));
+}
+export async function digestEvalFixtures(evalsDir) {
+    const hash = createHash("sha256");
+    for (const { file, raw } of await readFixtures(evalsDir)) {
+        hash.update(`${file}\0${raw}\0`);
+    }
+    return hash.digest("hex");
+}

package/dist/evals/index.d.ts

@@ -0,0 +1,3 @@
+export { discoverEvalCases } from "./discover.js";
+export { evalCaseFromRun } from "./promote.js";
+export { runEvals } from "./run-evals.js";

package/dist/evals/index.js

@@ -0,0 +1,3 @@
+export { discoverEvalCases } from "./discover.js";
+export { evalCaseFromRun } from "./promote.js";
+export { runEvals } from "./run-evals.js";

package/dist/evals/promote.d.ts

@@ -0,0 +1,7 @@
+import type { PlicoEvent, RunStatus } from "@plico-ai/contracts";
+import type { EvalCase } from "../types/index.js";
+/**
+ * Turns a stored run into an eval case. Each tool call keeps the output it produced as the mocked
+ * `result`, so the case replays without running any handler. Files a tool wrote are not carried over.
+ */
+export declare function evalCaseFromRun(name: string, status: RunStatus, events: PlicoEvent[]): EvalCase;

package/dist/evals/promote.js

@@ -0,0 +1,32 @@
+/**
+ * Turns a stored run into an eval case. Each tool call keeps the output it produced as the mocked
+ * `result`, so the case replays without running any handler. Files a tool wrote are not carried over.
+ */
+export function evalCaseFromRun(name, status, events) {
+    const script = [];
+    let output;
+    let pending;
+    for (const event of events) {
+        if (event.type === "assistant.output") {
+            script.push({ type: "assistant.output", content: event.payload.content });
+            output = event.payload.content;
+        }
+        else if (event.type === "tool.call") {
+            pending = {
+                type: "tool.call",
+                toolName: event.payload.toolName,
+                arguments: event.payload.arguments,
+            };
+            script.push(pending);
+        }
+        else if (event.type === "tool.result" && pending) {
+            pending.result = event.payload.result;
+            pending = undefined;
+        }
+    }
+    return {
+        name,
+        script,
+        expect: { status, ...(output === undefined ? {} : { outputContains: output }) },
+    };
+}

package/dist/evals/run-evals.d.ts

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

package/dist/evals/run-evals.js

@@ -0,0 +1,69 @@
+import { getProjectPaths } from "@plico-ai/core";
+import { runProject } from "../run/index.js";
+import { digestEvalFixtures, discoverEvalCases } from "./discover.js";
+export async function runEvals(projectRoot, options = {}) {
+    const evalsDir = getProjectPaths(projectRoot).directories.evals;
+    const cases = await discoverEvalCases(evalsDir);
+    const fixturesDigest = await digestEvalFixtures(evalsDir);
+    const results = [];
+    for (const evalCase of cases) {
+        const runId = `eval-${evalCase.name.replace(/[^a-z0-9_-]/gi, "_")}-${crypto.randomUUID().slice(0, 8)}`;
+        const runOpts = {
+            script: evalCase.script,
+            mockTools: true,
+            runId,
+        };
+        if (options.eventStore !== undefined)
+            runOpts.eventStore = options.eventStore;
+        const result = await runProject(projectRoot, runOpts);
+        const diagnostics = [];
+        let passed = true;
+        if (evalCase.expect?.status && result.status !== evalCase.expect.status) {
+            passed = false;
+            diagnostics.push(`Expected status "${evalCase.expect.status}" but got "${result.status}"`);
+        }
+        if (!evalCase.expect?.status && result.status !== "completed") {
+            passed = false;
+            diagnostics.push(`Run ended with status "${result.status}"`);
+        }
+        if (evalCase.expect?.outputContains) {
+            const output = result.output ?? "";
+            if (!output.includes(evalCase.expect.outputContains)) {
+                passed = false;
+                diagnostics.push(`Expected output to contain "${evalCase.expect.outputContains}" but got "${output}"`);
+            }
+        }
+        for (const event of result.events) {
+            if (event.type === "run.error" && typeof event.payload.message === "string")
+                diagnostics.push(event.payload.message);
+        }
+        if (result.errors?.length) {
+            for (const err of result.errors) {
+                diagnostics.push(`${err.path}: ${err.message}`);
+            }
+        }
+        const entry = {
+            name: evalCase.name,
+            status: passed ? "pass" : "fail",
+            runId: result.runId,
+            runStatus: result.status,
+        };
+        if (evalCase.description !== undefined)
+            entry.description = evalCase.description;
+        if (result.output !== undefined)
+            entry.output = result.output;
+        if (diagnostics.length > 0)
+            entry.diagnostics = diagnostics;
+        results.push(entry);
+    }
+    const passed = results.filter((r) => r.status === "pass").length;
+    const failed = results.filter((r) => r.status === "fail").length;
+    const summary = { total: results.length, passed, failed, results };
+    await options.eventStore?.persistEvalReport({
+        schemaVersion: 1,
+        ...summary,
+        evaluatedAt: new Date().toISOString(),
+        fixturesDigest,
+    });
+    return summary;
+}

package/dist/events.d.ts

@@ -0,0 +1,28 @@
+import type { EventStreamType, PlicoEventPayloads } from "@plico-ai/contracts";
+import type { EventStore, PlicoEvent, PlicoEventType } from "./types/index.js";
+export declare const runStreamType: EventStreamType;
+/**
+ * Build the terminal failure pair both recovery paths append. The caller supplies the tail so
+ * appending to an event store and inserting directly into SQLite share one sequencing scheme.
+ */
+export declare function runFailureEvents(runId: string, last: {
+    sequence: number;
+    type: string;
+} | undefined, message: string, timestamp?: string): PlicoEvent[];
+export declare class InMemoryEventLog {
+    #private;
+    private readonly runId;
+    private readonly store;
+    /**
+     * Opens the log of a run that may have started before. The loop emits the same events again when
+     * it replays; events already stored are matched, not written twice.
+     */
+    static open(runId: string, store: EventStore | undefined): Promise<InMemoryEventLog>;
+    constructor(runId: string, store?: EventStore | undefined);
+    append<T extends PlicoEventType>(type: T, payload: PlicoEventPayloads[T]): Promise<PlicoEvent>;
+    /** Skip previously persisted live chunks when replaying a model step. */
+    skipModelDeltas(turn: number): void;
+    /** Continue after the recorded tail when recovery cannot replay the workflow. */
+    continueAfterReplay(): void;
+    all(): PlicoEvent[];
+}

package/dist/events.js

@@ -0,0 +1,104 @@
+import { ProjectChangedError } from "./engine/index.js";
+export const runStreamType = "run";
+/**
+ * Build the terminal failure pair both recovery paths append. The caller supplies the tail so
+ * appending to an event store and inserting directly into SQLite share one sequencing scheme.
+ */
+export function runFailureEvents(runId, last, message, timestamp = new Date().toISOString()) {
+    const events = [];
+    let sequence = last?.sequence ?? 0;
+    if (last?.type !== "run.error") {
+        sequence += 1;
+        events.push({
+            schemaVersion: 1,
+            streamType: "run",
+            streamId: runId,
+            runId,
+            id: `evt-${String(sequence).padStart(4, "0")}`,
+            sequence,
+            timestamp,
+            type: "run.error",
+            payload: { phase: "runtime", message },
+        });
+    }
+    sequence += 1;
+    events.push({
+        schemaVersion: 1,
+        streamType: "run",
+        streamId: runId,
+        runId,
+        id: `evt-${String(sequence).padStart(4, "0")}`,
+        sequence,
+        timestamp,
+        type: "run.failed",
+        payload: { phase: "runtime" },
+    });
+    return events;
+}
+export class InMemoryEventLog {
+    runId;
+    store;
+    #events = [];
+    #replayed = 0;
+    #cursor = 0;
+    /**
+     * Opens the log of a run that may have started before. The loop emits the same events again when
+     * it replays; events already stored are matched, not written twice.
+     */
+    static async open(runId, store) {
+        const log = new InMemoryEventLog(runId, store);
+        if (store)
+            log.#events.push(...(await store.getEvents(runId)));
+        log.#replayed = log.#events.length;
+        return log;
+    }
+    constructor(runId, store = undefined) {
+        this.runId = runId;
+        this.store = store;
+    }
+    async append(type, payload) {
+        if (this.#cursor < this.#replayed) {
+            const recorded = this.#events[this.#cursor];
+            if (recorded.type !== type || JSON.stringify(recorded.payload) !== JSON.stringify(payload)) {
+                // Later events (the failure) are appended after what the earlier attempt stored.
+                this.#cursor = this.#replayed;
+                throw new ProjectChangedError("event", this.#cursor, recorded.type, type);
+            }
+            this.#cursor += 1;
+            return recorded;
+        }
+        const sequence = this.#events.length + 1;
+        // TypeScript cannot prove this generic object is a union member; callers are checked against PlicoEventPayloads[T].
+        const event = {
+            schemaVersion: 1,
+            streamType: runStreamType,
+            streamId: this.runId,
+            runId: this.runId,
+            id: `evt-${String(sequence).padStart(4, "0")}`,
+            sequence,
+            timestamp: new Date().toISOString(),
+            type,
+            payload,
+        };
+        await this.store?.appendEvent(event);
+        this.#events.push(event);
+        return event;
+    }
+    /** Skip previously persisted live chunks when replaying a model step. */
+    skipModelDeltas(turn) {
+        while (this.#cursor < this.#replayed) {
+            const event = this.#events[this.#cursor];
+            if ((event?.type !== "model.delta" && event?.type !== "model.attempt") ||
+                event.payload.turn !== turn)
+                break;
+            this.#cursor++;
+        }
+    }
+    /** Continue after the recorded tail when recovery cannot replay the workflow. */
+    continueAfterReplay() {
+        this.#cursor = this.#replayed;
+    }
+    all() {
+        return [...this.#events];
+    }
+}

package/dist/guards.d.ts

@@ -0,0 +1 @@
+export declare function isRecord(value: unknown): value is Record<string, unknown>;

package/dist/guards.js

@@ -0,0 +1,3 @@
+export function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+export { buildArtifactWorkspace, readArtifactSnapshot, readArtifactVersion } from "./artifacts.js";
+export { createEngine, createMemoryJournal, createSqliteEngine, type Engine, type Journal, ProjectChangedError, type RecoveredRun, type RunContext, type Workflow, } from "./engine/index.js";
+export { loadedEnvFiles, loadProjectEnv } from "./env.js";
+export { type ModelErrorKind, ModelProviderError } from "./errors.js";
+export { evalCaseFromRun, runEvals } from "./evals/index.js";
+export { runFailureEvents } from "./events.js";
+export { composeInstructions } from "./instructions.js";
+export { createConfiguredModelProvider, modelProviderAccountKey, modelProviderRecoveryKey, supportsModelProvider, } from "./providers/configured.js";
+export { createOpenAICompatibleProvider, type OpenAICompatibleProviderOptions, } from "./providers/openai-compatible.js";
+export { checkReadiness } from "./readiness/index.js";
+export { recoverRuns, runProject } from "./run/index.js";
+export { normalizeScript, ScriptValidationError } from "./script.js";
+export { createSqliteEventStore } from "./storage/index.js";
+export { matchesMetadata } from "./storage/metadata.js";
+export { createSqliteThreadStore, ThreadBusyError, type ThreadStore, } from "./storage/sqlite/threads.js";
+export { createThreadTitler, type ThreadTitler } from "./threads/titler.js";
+export { discoverTools } from "./tools/index.js";
+export type { ArtifactContent, ArtifactFile, ArtifactFileInput, ArtifactFileMetadata, ArtifactSnapshot, ArtifactSnapshotDetail, ArtifactVersion, ArtifactWorkspace, ComposedInstructions, CreateSqliteEventStoreOptions, DeclaredTool, DiagnosticSeverity, DryRunScriptStep, EvalCase, EvalCaseResult, EvalExpectation, EvalReport, EvalSummary, EventStore, JsonSchema, ModelChunk, ModelProvider, ModelRequest, ModelResponse, ModelToolCall, PlicoEvent, PlicoEventType, ProviderMessage, ReadinessDiagnostic, ReadinessOptions, ReadinessReport, RunEvalsOptions, RunProjectOptions, RunResult, RunStatus, RunSummary, ToolApprovalPolicy, ToolArtifactContext, ToolArtifactFile, ToolDefinition, ToolHandlerContext, ToolInputParseResult, ToolInputSchema, ZodInputParseResult, ZodInputSchema, } from "./types/index.js";

package/dist/index.js

@@ -0,0 +1,17 @@
+export { buildArtifactWorkspace, readArtifactSnapshot, readArtifactVersion } from "./artifacts.js";
+export { createEngine, createMemoryJournal, createSqliteEngine, ProjectChangedError, } from "./engine/index.js";
+export { loadedEnvFiles, loadProjectEnv } from "./env.js";
+export { ModelProviderError } from "./errors.js";
+export { evalCaseFromRun, runEvals } from "./evals/index.js";
+export { runFailureEvents } from "./events.js";
+export { composeInstructions } from "./instructions.js";
+export { createConfiguredModelProvider, modelProviderAccountKey, modelProviderRecoveryKey, supportsModelProvider, } from "./providers/configured.js";
+export { createOpenAICompatibleProvider, } from "./providers/openai-compatible.js";
+export { checkReadiness } from "./readiness/index.js";
+export { recoverRuns, runProject } from "./run/index.js";
+export { normalizeScript, ScriptValidationError } from "./script.js";
+export { createSqliteEventStore } from "./storage/index.js";
+export { matchesMetadata } from "./storage/metadata.js";
+export { createSqliteThreadStore, ThreadBusyError, } from "./storage/sqlite/threads.js";
+export { createThreadTitler } from "./threads/titler.js";
+export { discoverTools } from "./tools/index.js";

package/dist/instructions.d.ts

@@ -0,0 +1,4 @@
+import { type LoadedProject, type Skill } from "@plico-ai/core";
+import type { ComposedInstructions } from "./types/index.js";
+/** The agent's instructions plus a list of skills. A skill's full text loads on demand. */
+export declare function composeInstructions(project: LoadedProject, loaded?: Skill[]): Promise<ComposedInstructions>;

package/dist/instructions.js

@@ -0,0 +1,23 @@
+import { readFile } from "node:fs/promises";
+import { getProjectPaths, getProjectRelativePaths, parseAgentFile, readSkills, SKILL_TOOL_NAME, } from "@plico-ai/core";
+/** The agent's instructions plus a list of skills. A skill's full text loads on demand. */
+export async function composeInstructions(project, loaded) {
+    const projectPaths = getProjectPaths(project.root);
+    const sources = [getProjectRelativePaths().agentFile];
+    const parts = [parseAgentFile(await readFile(projectPaths.agentFile, "utf8")).body];
+    const skills = loaded ?? (await readSkills(project.root)).skills;
+    if (skills.length > 0) {
+        sources.push(...skills.map((skill) => skill.source));
+        parts.push([
+            "## Skills",
+            "",
+            `Call ${SKILL_TOOL_NAME} with a skill's name to read its full instructions before you use it.`,
+            "",
+            ...skills.map((skill) => `- ${skill.name}: ${skill.description}`),
+        ].join("\n"));
+    }
+    return {
+        sources,
+        content: parts.map((part) => part.trimEnd()).join("\n\n"),
+    };
+}

package/dist/policy/approval.d.ts

@@ -0,0 +1,8 @@
+import type { ProjectConfig } from "@plico-ai/contracts";
+import type { DeclaredTool } from "../types/tools.js";
+export type ApprovalDecision = "none" | "required";
+export declare function decideApproval(tool: DeclaredTool, config: ProjectConfig): {
+    required: boolean;
+    reason?: string;
+};
+export declare function approvalTimeoutMs(config: ProjectConfig): number;

package/dist/policy/approval.js

@@ -0,0 +1,27 @@
+export function decideApproval(tool, config) {
+    const policy = config.approvals;
+    const override = policy?.tools?.[tool.name];
+    let decision;
+    if (override === "required" || override === "none") {
+        decision = override;
+    }
+    else if (tool.approval.required) {
+        decision = "required";
+    }
+    else if (policy?.default === "required") {
+        decision = "required";
+    }
+    else {
+        decision = "none";
+    }
+    // Config can escalate but never silently drop a tool-declared requirement.
+    if (tool.approval.required && decision === "none") {
+        decision = "required";
+    }
+    return tool.approval.reason
+        ? { required: decision === "required", reason: tool.approval.reason }
+        : { required: decision === "required" };
+}
+export function approvalTimeoutMs(config) {
+    return config.approvals?.timeoutMs ?? 30 * 60 * 1000;
+}

package/dist/providers/ai-sdk.d.ts

@@ -0,0 +1,10 @@
+import { type LanguageModel } from "ai";
+import type { ModelProvider } from "../types/index.js";
+export interface AiSdkProviderOptions {
+    /** The variable that holds the credential. Without one, the model is built with no key. */
+    apiKeyEnv?: string | undefined;
+    /** Builds the AI SDK model once the credential is known. */
+    createModel: (apiKey: string | undefined) => LanguageModel | Promise<LanguageModel>;
+}
+/** Wraps an AI SDK language model behind the Plico model port. Provider retries are off. */
+export declare function createAiSdkModelProvider(options: AiSdkProviderOptions): ModelProvider;