@plico-ai/runtime 0.0.0-stage → 0.1.0

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;

package/dist/run/pinned-instructions.js

@@ -0,0 +1,36 @@
+import { readSkills } from "@plico-ai/core";
+import { composeInstructions } from "../instructions.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 async function pinInstructions(project, events) {
+    const recorded = events.all().find((event) => event.type === "instructions.composed");
+    if (recorded?.type === "instructions.composed") {
+        await events.append("instructions.composed", recorded.payload);
+        // Runs recorded before skills were pinned fall back to the skills on disk.
+        const skills = recorded.payload.skills ?? (await readSkills(project.root)).skills;
+        return { instructions: { content: recorded.payload.content }, skills };
+    }
+    const { skills } = await readSkills(project.root);
+    const instructions = await composeInstructions(project, skills);
+    await events.append("instructions.composed", {
+        length: instructions.content.length,
+        sources: instructions.sources,
+        content: instructions.content,
+        skills: skills.map(({ name, description, source, body }) => ({
+            name,
+            description,
+            source,
+            body,
+        })),
+    });
+    return { instructions, skills };
+}
+/**
+ * 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 function ignoredWhenPinned(issue) {
+    return issue.path === "agent.md" || issue.path === "skills" || issue.path.startsWith("skills/");
+}

package/dist/run/record-tools.d.ts

@@ -0,0 +1,8 @@
+import type { InMemoryEventLog } from "../events.js";
+import type { DeclaredTool } from "../types/index.js";
+/**
+ * Records the tools a run discovered with a hash of the tool code. A resumed run compares both, so
+ * a changed handler fails the run before the tool runs. Runs recorded without a hash are compared
+ * on their declarations only.
+ */
+export declare function recordTools(root: string, tools: DeclaredTool[], events: InMemoryEventLog): Promise<void>;

package/dist/run/record-tools.js

@@ -0,0 +1,21 @@
+import { fingerprintTools } from "./tool-fingerprint.js";
+/**
+ * Records the tools a run discovered with a hash of the tool code. A resumed run compares both, so
+ * a changed handler fails the run before the tool runs. Runs recorded without a hash are compared
+ * on their declarations only.
+ */
+export async function recordTools(root, tools, events) {
+    const recorded = events.all().find((event) => event.type === "tools.discovered");
+    const legacy = recorded?.type === "tools.discovered" && recorded.payload.fingerprint === undefined;
+    await events.append("tools.discovered", {
+        tools: tools.map((tool) => ({
+            source: tool.source,
+            name: tool.name,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+            capabilities: tool.capabilities,
+            approval: tool.approval,
+        })),
+        ...(legacy ? {} : { fingerprint: await fingerprintTools(root) }),
+    });
+}

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

@@ -0,0 +1,17 @@
+import { type Engine, type RecoveredRun } from "../engine/index.js";
+import type { RunProjectOptions, RunResult } from "../types/index.js";
+export declare function runProject(root: string, options?: RunProjectOptions): Promise<RunResult>;
+/**
+ * Continues runs a dead process left running. The provider and event store come from this process;
+ * the project path, message and script come from the journal.
+ */
+export declare function recoverRuns(options: RunProjectOptions & {
+    engine: Engine;
+    recoveryFilter?: {
+        projectRoot: string;
+        providerRecoveryKey?: string;
+        providerOnly?: boolean;
+    };
+    onRecoveryStarted?: (runId: string) => void;
+    onRecoverySettled?: (runId: string) => void;
+}): Promise<RecoveredRun[]>;