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

package/NOTICE

@@ -0,0 +1,4 @@
+Plico
+Copyright 2026 Plico contributors
+
+This product includes software developed by the Plico contributors.

package/README.md

@@ -1,6 +1,12 @@
 # @plico-ai/runtime
 
-The Plico run engine, event log and tools.
+The Plico runtime: linear agent runs, the durable SQLite event log, tool execution, scripted and provider-backed models, evals, artifacts, approvals and readiness checks.
 
-This is a pre-release placeholder. The first developer preview is in progress at
-https://github.com/ITZSHOAIB/plico. Docs: https://plico.sohab.dev
+Most projects use it through [`@plico-ai/cli`](../cli). Import it directly to embed runs in your own process:
+
+```ts
+import { loadProject } from "@plico-ai/core";
+import { runProject } from "@plico-ai/runtime";
+```
+
+Requires Node `>=22.18`. Wire types come from `@plico-ai/contracts`.

package/dist/artifacts.d.ts

@@ -0,0 +1,10 @@
+import type { ArtifactContent, ArtifactFile, ArtifactFileMetadata, ArtifactSnapshotDetail, ArtifactWorkspace, PlicoEvent } from "./types/index.js";
+export declare function encodeArtifactContent(content: string | Uint8Array): ArtifactContent;
+export declare function decodeArtifactContent(content: ArtifactContent): string | Uint8Array;
+export declare function artifactContentBytes(content: ArtifactContent): Uint8Array;
+export declare function hashArtifactContent(content: ArtifactContent): string;
+export declare function artifactFileMetadata(file: ArtifactFile): ArtifactFileMetadata;
+/** Returns a historical file version using the same replay rules as the workspace projection. */
+export declare function readArtifactVersion(events: PlicoEvent[], path: string, targetVersion: number): ArtifactFile | undefined;
+export declare function buildArtifactWorkspace(runId: string, events: PlicoEvent[]): ArtifactWorkspace | undefined;
+export declare function readArtifactSnapshot(events: PlicoEvent[], snapshotId: string): ArtifactSnapshotDetail | undefined;

package/dist/artifacts.js

@@ -0,0 +1,106 @@
+import { createHash } from "node:crypto";
+export function encodeArtifactContent(content) {
+    return typeof content === "string"
+        ? content
+        : { encoding: "base64", data: Buffer.from(content).toString("base64") };
+}
+export function decodeArtifactContent(content) {
+    if (typeof content === "string")
+        return content;
+    return decodeBase64(content.data);
+}
+export function artifactContentBytes(content) {
+    return typeof content === "string" ? Buffer.from(content, "utf8") : decodeBase64(content.data);
+}
+function decodeBase64(data) {
+    const bytes = Buffer.from(data, "base64");
+    if (bytes.toString("base64") !== data)
+        throw new Error("Artifact content has invalid base64 data.");
+    return bytes;
+}
+export function hashArtifactContent(content) {
+    return createHash("sha256").update(artifactContentBytes(content)).digest("hex");
+}
+export function artifactFileMetadata(file) {
+    return {
+        path: file.path,
+        sizeBytes: artifactContentBytes(file.content).byteLength,
+        mimeType: file.mimeType,
+        version: file.version,
+        contentHash: file.contentHash,
+    };
+}
+function applyFileWritten(files, versions, event) {
+    const path = event.payload.path;
+    const version = event.payload.version ?? (files.get(path)?.version ?? 0) + 1;
+    const contentHash = event.payload.contentHash ?? hashArtifactContent(event.payload.content);
+    const file = {
+        path,
+        content: event.payload.content,
+        mimeType: event.payload.mimeType,
+        version,
+        contentHash,
+    };
+    files.set(path, file);
+    versions.push({
+        path,
+        mimeType: file.mimeType,
+        version,
+        contentHash,
+        runId: event.runId,
+        createdAt: event.timestamp,
+    });
+    return file;
+}
+/** Returns a historical file version using the same replay rules as the workspace projection. */
+export function readArtifactVersion(events, path, targetVersion) {
+    const files = new Map();
+    const versions = [];
+    for (const event of events) {
+        if (event.type !== "artifact.file.written")
+            continue;
+        const file = applyFileWritten(files, versions, event);
+        if (file.path === path && file.version === targetVersion)
+            return file;
+    }
+    return undefined;
+}
+function toSnapshot(event) {
+    return {
+        snapshotId: event.payload.snapshotId,
+        runId: event.runId,
+        fileCount: event.payload.fileCount,
+        createdAt: event.timestamp,
+    };
+}
+export function buildArtifactWorkspace(runId, events) {
+    const created = events.find((event) => event.type === "artifact.workspace.created");
+    if (!created)
+        return undefined;
+    const files = new Map();
+    const versions = [];
+    const snapshots = [];
+    for (const event of events) {
+        if (event.type === "artifact.file.written")
+            applyFileWritten(files, versions, event);
+        if (event.type === "artifact.snapshot.created")
+            snapshots.push(toSnapshot(event));
+    }
+    return {
+        workspaceId: created.payload.workspaceId,
+        runId,
+        files: [...files.values()],
+        versions,
+        snapshots,
+        createdAt: created.timestamp,
+    };
+}
+export function readArtifactSnapshot(events, snapshotId) {
+    const index = events.findIndex((event) => event.type === "artifact.snapshot.created" && event.payload.snapshotId === snapshotId);
+    const snapshot = events[index];
+    // This narrows the event for TypeScript and also returns early when the snapshot is missing.
+    if (snapshot?.type !== "artifact.snapshot.created")
+        return undefined;
+    const workspace = buildArtifactWorkspace(snapshot.runId, events.slice(0, index + 1));
+    return { ...toSnapshot(snapshot), files: workspace?.files ?? [] };
+}

package/dist/engine/context.d.ts

@@ -0,0 +1,16 @@
+import type { Journal } from "./journal.js";
+import type { RunContext } from "./types.js";
+export interface Suspension {
+    name: string;
+    /** Epoch milliseconds, or null when the wait has no timeout. */
+    deadline: number | null;
+}
+export interface EngineContext extends RunContext {
+    /** Set once `wait` has stopped the run. */
+    suspension(): Suspension | undefined;
+    /** True once `step` or `wait` has stopped the run because it was cancelled. */
+    cancelled(): boolean;
+}
+export declare function toJson(value: unknown): string;
+/** The context one execution of a workflow sees. Steps and waits replay from the journal. */
+export declare function createContext(runId: string, journal: Journal, now: () => number, signal: AbortSignal): EngineContext;

package/dist/engine/context.js

@@ -0,0 +1,77 @@
+import { ProjectChangedError, RunCancelled, RunSuspended } from "./errors.js";
+export function toJson(value) {
+    return JSON.stringify(value === undefined ? null : value);
+}
+/** The context one execution of a workflow sees. Steps and waits replay from the journal. */
+export function createContext(runId, journal, now, signal) {
+    let nextStep = 0;
+    let suspended;
+    let stopped = false;
+    async function checkCancel() {
+        if (signal.aborted || (await journal.getRun(runId))?.cancelRequested) {
+            stopped = true;
+            throw new RunCancelled();
+        }
+    }
+    async function endWait(name, outcome) {
+        if (await journal.resolveWait(runId, name, JSON.stringify(outcome)))
+            return outcome;
+        // Someone ended it first; the first outcome stands.
+        const wait = await journal.getWait(runId, name);
+        return JSON.parse(wait?.outcomeJson ?? JSON.stringify(outcome));
+    }
+    return {
+        runId,
+        signal,
+        suspension: () => suspended,
+        cancelled: () => stopped,
+        async step(name, fn, options) {
+            const index = nextStep++;
+            const recorded = await journal.getStep(runId, index);
+            if (recorded) {
+                if (recorded.name !== name) {
+                    throw new ProjectChangedError("step", index, recorded.name, name);
+                }
+                return JSON.parse(recorded.resultJson);
+            }
+            await checkCancel();
+            const retries = options?.retries ?? 0;
+            for (let attempt = 0;; attempt++) {
+                try {
+                    const resultJson = toJson(await fn({ attempt, signal }));
+                    await journal.putStep(runId, index, { name, resultJson });
+                    return JSON.parse(resultJson);
+                }
+                catch (error) {
+                    // A step cut short by cancel is not recorded and not retried.
+                    if (signal.aborted) {
+                        stopped = true;
+                        throw new RunCancelled();
+                    }
+                    if (attempt >= retries || (options?.shouldRetry && !options.shouldRetry(error)))
+                        throw error;
+                }
+            }
+        },
+        async wait(name, options) {
+            await checkCancel();
+            // The deadline is stored when the wait is first reached, so a restart keeps it.
+            await journal.openWait(runId, name, options?.timeoutMs === undefined ? null : now() + options.timeoutMs);
+            const wait = await journal.getWait(runId, name);
+            if (!wait)
+                throw new Error(`Wait ${name} could not be opened.`);
+            if (wait.outcomeJson !== null)
+                return JSON.parse(wait.outcomeJson);
+            const signal = await journal.getSignal(runId, name);
+            if (signal !== undefined) {
+                const outcome = await endWait(name, { kind: "signal", value: JSON.parse(signal) });
+                return outcome;
+            }
+            if (wait.deadline !== null && now() >= wait.deadline) {
+                return (await endWait(name, { kind: "timeout" }));
+            }
+            suspended = { name, deadline: wait.deadline };
+            throw new RunSuspended(name);
+        },
+    };
+}

package/dist/engine/engine.d.ts

@@ -0,0 +1,12 @@
+import type { Journal } from "./journal.js";
+import type { Engine } from "./types.js";
+export interface EngineOptions {
+    journal: Journal;
+    /** Names this engine's hold on runs. Must be unique per live process. */
+    workerId?: string;
+    /** How long a worker holds a run before another may take it. Renewed while the run executes. */
+    leaseMs?: number;
+    now?: () => number;
+}
+export declare const defaultLeaseMs = 30000;
+export declare function createEngine({ journal, workerId, leaseMs, now, }: EngineOptions): Engine;

package/dist/engine/engine.js

@@ -0,0 +1,235 @@
+import { randomUUID } from "node:crypto";
+import { createContext, toJson } from "./context.js";
+import { RunCancelled, RunSuspended } from "./errors.js";
+export const defaultLeaseMs = 30_000;
+export function createEngine({ journal, workerId = randomUUID(), leaseMs = defaultLeaseMs, now = Date.now, }) {
+    const lease = () => ({ workerId, until: now() + leaseMs });
+    /** Runs this process can continue by itself when a signal or timeout arrives. */
+    const registered = new Map();
+    /** Runs executing in this process right now. */
+    const active = new Set();
+    const timers = new Map();
+    /** Aborts the step a run is executing here when it is cancelled. */
+    const controllers = new Map();
+    function stopTimer(runId) {
+        clearTimeout(timers.get(runId));
+        timers.delete(runId);
+    }
+    /** Runs the workflow, replaying it each time a wait ends, until it completes or must wait. */
+    async function execute(runId, workflow, input) {
+        registered.set(runId, { workflow, input });
+        stopTimer(runId);
+        const controller = new AbortController();
+        controllers.set(runId, controller);
+        const heartbeat = setInterval(() => {
+            journal.renew(runId, lease()).catch(() => undefined);
+            // Cancel may have been requested from another process.
+            journal
+                .getRun(runId)
+                .then((run) => run?.cancelRequested && controller.abort())
+                .catch(() => undefined);
+        }, leaseMs / 3);
+        heartbeat.unref();
+        try {
+            for (;;) {
+                const ctx = createContext(runId, journal, now, controller.signal);
+                let output;
+                let returned = false;
+                try {
+                    output = await workflow(ctx, input);
+                    returned = true;
+                }
+                catch (error) {
+                    if (!(error instanceof RunSuspended || error instanceof RunCancelled))
+                        throw error;
+                }
+                if (ctx.cancelled()) {
+                    await journal.setState(runId, "cancelled");
+                    registered.delete(runId);
+                    return returned ? { state: "cancelled", output: output } : { state: "cancelled" };
+                }
+                const suspension = ctx.suspension();
+                if (!suspension) {
+                    await journal.setState(runId, "completed");
+                    registered.delete(runId);
+                    return { state: "completed", output: output };
+                }
+                await journal.setState(runId, "waiting");
+                // A signal or timeout that landed while the run was stopping must not be lost.
+                const wait = await journal.getWait(runId, suspension.name);
+                const ready = (await journal.getRun(runId))?.cancelRequested === true ||
+                    (await journal.getSignal(runId, suspension.name)) !== undefined ||
+                    (wait?.deadline != null && now() >= wait.deadline);
+                if (ready) {
+                    if (await journal.claimWaiting(runId, lease()))
+                        continue;
+                    // Another worker took the run; report what this execution produced before it stopped.
+                    return returned ? { state: "waiting", output: output } : { state: "waiting" };
+                }
+                if (suspension.deadline !== null) {
+                    const delay = Math.max(0, suspension.deadline - now());
+                    const timer = setTimeout(() => resumeHere(runId).catch(() => undefined), delay);
+                    timer.unref();
+                    timers.set(runId, timer);
+                }
+                return returned ? { state: "waiting", output: output } : { state: "waiting" };
+            }
+        }
+        catch (error) {
+            await journal.setState(runId, "failed");
+            registered.delete(runId);
+            throw error;
+        }
+        finally {
+            clearInterval(heartbeat);
+            controllers.delete(runId);
+            active.delete(runId);
+        }
+    }
+    /** Continues a waiting run this process started, once its wait can end. */
+    async function resumeHere(runId) {
+        const known = registered.get(runId);
+        if (!known || active.has(runId))
+            return;
+        active.add(runId);
+        try {
+            const run = await journal.getRun(runId);
+            if (run?.state !== "waiting") {
+                active.delete(runId);
+                return;
+            }
+            if (!(await journal.claimWaiting(runId, lease()))) {
+                active.delete(runId);
+                return;
+            }
+        }
+        catch (error) {
+            active.delete(runId);
+            throw error;
+        }
+        // Everything the run did is in the event log; its outcome here has no reader.
+        execute(runId, known.workflow, known.input).catch(() => undefined);
+    }
+    async function start(runId, workflow, input) {
+        const inputJson = toJson(input);
+        if (!(await journal.begin(runId, inputJson, lease()))) {
+            throw new Error(`Run ${runId} already exists.`);
+        }
+        active.add(runId);
+        const result = execute(runId, workflow, JSON.parse(inputJson));
+        // The handle's reader observes the failure; this keeps an unread handle from crashing the process.
+        result.catch(() => undefined);
+        return { runId, result: () => result };
+    }
+    return {
+        start,
+        async run(runId, workflow, input) {
+            return (await start(runId, workflow, input)).result();
+        },
+        async resume(runId, workflow) {
+            const run = await journal.getRun(runId);
+            if (!run)
+                throw new Error(`Run ${runId} is unknown.`);
+            if (run.state === "completed" || run.state === "cancelled")
+                throw new Error(`Run ${runId} already finished.`);
+            if (run.state === "running") {
+                const stale = (await journal.listStale(workerId, now())).find((item) => item.runId === runId);
+                if (!stale || !(await journal.claim(runId, lease(), stale.held)))
+                    throw new Error(`Run ${runId} is held by a live worker or its lease changed.`);
+            }
+            else if (!(await (run.state === "waiting"
+                ? journal.claimWaiting(runId, lease())
+                : journal.claim(runId, lease())))) {
+                throw new Error(`Run ${runId} could not be claimed.`);
+            }
+            active.add(runId);
+            return execute(runId, workflow, JSON.parse(run.inputJson));
+        },
+        async signal(runId, name, value) {
+            const run = await journal.getRun(runId);
+            if (!run)
+                return "unknown";
+            if (["completed", "failed", "cancelled"].includes(run.state))
+                return "ignored";
+            const wait = await journal.getWait(runId, name);
+            if (wait?.outcomeJson != null)
+                return "ignored";
+            if (wait?.deadline != null && now() >= wait.deadline) {
+                // The deadline passed first: the wait ends as a timeout and this decision is late.
+                await journal.resolveWait(runId, name, JSON.stringify({ kind: "timeout" }));
+                resumeHere(runId).catch(() => undefined);
+                return "ignored";
+            }
+            if (!(await journal.putSignal(runId, name, toJson(value))))
+                return "ignored";
+            resumeHere(runId).catch(() => undefined);
+            return "accepted";
+        },
+        async cancel(runId) {
+            const run = await journal.getRun(runId);
+            if (!run)
+                return "unknown";
+            if (!(await journal.requestCancel(runId)))
+                return "ignored";
+            const running = controllers.get(runId);
+            if (running)
+                running.abort();
+            else
+                resumeHere(runId).catch(() => undefined);
+            return "accepted";
+        },
+        async recover(resolve) {
+            for (const { runId, deadline } of await journal.listWaiting()) {
+                if (active.has(runId) || registered.has(runId))
+                    continue;
+                const run = await journal.getRun(runId);
+                if (!run || run.state !== "waiting")
+                    continue;
+                const input = JSON.parse(run.inputJson);
+                const workflow = resolve(runId, input);
+                if (!workflow)
+                    continue;
+                registered.set(runId, { workflow, input });
+                if (deadline !== null) {
+                    const timer = setTimeout(() => resumeHere(runId).catch(() => undefined), Math.max(0, deadline - now()));
+                    timer.unref();
+                    timers.set(runId, timer);
+                }
+            }
+            const candidates = [
+                ...(await journal.listStale(workerId, now())).map((item) => ({ ...item, waiting: false })),
+                ...(await journal.listReady(now())).map((item) => ({ ...item, waiting: true })),
+            ];
+            const recovered = [];
+            for (const { runId, held, waiting } of candidates) {
+                if (active.has(runId))
+                    continue;
+                const run = await journal.getRun(runId);
+                if (!run)
+                    continue;
+                const input = JSON.parse(run.inputJson);
+                const workflow = resolve(runId, input);
+                if (!workflow ||
+                    !(await (waiting
+                        ? journal.claimWaiting(runId, lease(), held)
+                        : journal.claim(runId, lease(), held))))
+                    continue;
+                active.add(runId);
+                recovered.push(execute(runId, workflow, input).then((outcome) => ({
+                    runId,
+                    state: outcome.state,
+                    ...(outcome.output === undefined ? {} : { output: outcome.output }),
+                }), (error) => ({
+                    runId,
+                    state: "failed",
+                    error: error instanceof Error ? error.message : String(error),
+                })));
+            }
+            return Promise.all(recovered);
+        },
+        async status(runId) {
+            const run = await journal.getRun(runId);
+            return run && { state: run.state };
+        },
+    };
+}

package/dist/engine/errors.d.ts

@@ -0,0 +1,12 @@
+export declare class ProjectChangedError extends Error {
+    constructor(what: "step" | "event", index: number, recorded: string, current: string);
+}
+/** Thrown by `ctx.wait` when the run must stop and wait. Not a failure. */
+export declare class RunSuspended extends Error {
+    readonly waitName: string;
+    constructor(waitName: string);
+}
+/** Thrown by `ctx.step` and `ctx.wait` once the run is cancelled. Not a failure. */
+export declare class RunCancelled extends Error {
+    constructor();
+}

package/dist/engine/errors.js

@@ -0,0 +1,19 @@
+export class ProjectChangedError extends Error {
+    constructor(what, index, recorded, current) {
+        super(`Project changed during run: ${what} ${index + 1} was "${recorded}", now "${current}".`);
+    }
+}
+/** Thrown by `ctx.wait` when the run must stop and wait. Not a failure. */
+export class RunSuspended extends Error {
+    waitName;
+    constructor(waitName) {
+        super(`Run is waiting for ${waitName}.`);
+        this.waitName = waitName;
+    }
+}
+/** Thrown by `ctx.step` and `ctx.wait` once the run is cancelled. Not a failure. */
+export class RunCancelled extends Error {
+    constructor() {
+        super("Run was cancelled.");
+    }
+}

package/dist/engine/index.d.ts

@@ -0,0 +1,7 @@
+export { createEngine, defaultLeaseMs, type EngineOptions } from "./engine.js";
+export { ProjectChangedError, RunCancelled, RunSuspended } from "./errors.js";
+export type { Journal, JournalRun, JournalStep, JournalWait, Lease } from "./journal.js";
+export { createMemoryJournal } from "./memory-journal.js";
+export { createSqliteEngine, type SqliteEngineOptions } from "./sqlite-engine.js";
+export { createSqliteJournal } from "./sqlite-journal.js";
+export type { CancelResult, Engine, ExecutionState, ExecutionStatus, RecoveredRun, RunContext, RunHandle, RunOutcome, SignalResult, StepAttempt, StepOptions, WaitOptions, WaitOutcome, Workflow, } from "./types.js";

package/dist/engine/index.js

@@ -0,0 +1,5 @@
+export { createEngine, defaultLeaseMs } from "./engine.js";
+export { ProjectChangedError, RunCancelled, RunSuspended } from "./errors.js";
+export { createMemoryJournal } from "./memory-journal.js";
+export { createSqliteEngine } from "./sqlite-engine.js";
+export { createSqliteJournal } from "./sqlite-journal.js";

package/dist/engine/journal.d.ts

@@ -0,0 +1,65 @@
+import type { ExecutionState } from "./types.js";
+export interface JournalRun {
+    runId: string;
+    state: ExecutionState;
+    inputJson: string;
+    cancelRequested: boolean;
+}
+export interface JournalStep {
+    name: string;
+    resultJson: string;
+}
+/** A worker's hold on a running run. `until` is epoch milliseconds. */
+export interface Lease {
+    workerId: string;
+    until: number;
+}
+export interface JournalWait {
+    /** Epoch milliseconds, or null for a wait with no timeout. */
+    deadline: number | null;
+    /** Set once the wait ended; null while it is open. */
+    outcomeJson: string | null;
+}
+/** The engine's private record of where each run resumes. It never says what happened; events do. */
+export interface Journal {
+    /** Creates the run, held by `lease`. Returns false when the id is already taken. */
+    begin(runId: string, inputJson: string, lease: Lease): Promise<boolean>;
+    getRun(runId: string): Promise<JournalRun | undefined>;
+    setState(runId: string, state: ExecutionState): Promise<void>;
+    /** Extends the lease if `lease.workerId` still holds the run. */
+    renew(runId: string, lease: Lease): Promise<void>;
+    /**
+     * Makes `lease.workerId` the holder and sets the run running. With `expected`, it only does so
+     * when that holder still has the run, so two recoverers cannot both win.
+     */
+    claim(runId: string, lease: Lease, expected?: Lease): Promise<boolean>;
+    /** Atomically claims a waiting run; only one contender can transition it to running. */
+    claimWaiting(runId: string, lease: Lease, expected?: Lease): Promise<boolean>;
+    /** Running runs another worker held and lost: its lease ran out or its process is gone. */
+    listStale(workerId: string, now: number): Promise<Array<{
+        runId: string;
+        held: Lease;
+    }>>;
+    /** Waiting runs that can move on now: a wait has a signal or passed its deadline, or cancel was requested. */
+    listReady(now: number): Promise<Array<{
+        runId: string;
+        held: Lease;
+    }>>;
+    listWaiting(): Promise<Array<{
+        runId: string;
+        deadline: number | null;
+    }>>;
+    /** Marks the run cancelled-on-next-chance. Returns false when it already finished or was marked. */
+    requestCancel(runId: string): Promise<boolean>;
+    getWait(runId: string, name: string): Promise<JournalWait | undefined>;
+    /** Opens the wait with its deadline. A second open changes nothing, so a replay keeps the deadline. */
+    openWait(runId: string, name: string, deadline: number | null): Promise<void>;
+    /** Ends the wait. Returns false when it had already ended. */
+    resolveWait(runId: string, name: string, outcomeJson: string): Promise<boolean>;
+    /** Stores a signal. Returns false when one is already stored for the name. */
+    putSignal(runId: string, name: string, valueJson: string): Promise<boolean>;
+    getSignal(runId: string, name: string): Promise<string | undefined>;
+    getStep(runId: string, index: number): Promise<JournalStep | undefined>;
+    /** Records a step once. A second write at the same index changes nothing. */
+    putStep(runId: string, index: number, step: JournalStep): Promise<void>;
+}

package/dist/engine/journal.js

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

package/dist/engine/memory-journal.d.ts

@@ -0,0 +1,2 @@
+import type { Journal } from "./journal.js";
+export declare function createMemoryJournal(): Journal;