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

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

package/dist/run/run-project.js

@@ -0,0 +1,222 @@
+import { randomUUID } from "node:crypto";
+import { isAbsolute, resolve } from "node:path";
+import { SpanStatusCode } from "@opentelemetry/api";
+import { validateProject } from "@plico-ai/core";
+import { createEngine, createMemoryJournal, RunCancelled, } from "../engine/index.js";
+import { RunWaitingError, runtimeErrorPayload } from "../errors.js";
+import { InMemoryEventLog } from "../events.js";
+import { discoverTools } from "../tools/index.js";
+import { finalizeRun } from "./finalize.js";
+import { ignoredWhenPinned, pinInstructions } from "./pinned-instructions.js";
+import { recordTools } from "./record-tools.js";
+import { runDefaultDryRun } from "./strategies/default-dry.js";
+import { runProviderBackedRun } from "./strategies/provider.js";
+import { runScriptedDryRun } from "./strategies/scripted.js";
+import { startRunSpan, storeSpanContext, tracedContext, } from "./tracing.js";
+export async function runProject(root, options = {}) {
+    const engine = options.engine ?? createEngine({ journal: createMemoryJournal() });
+    const runId = options.runId ?? `run-${randomUUID()}`;
+    const span = startRunSpan(runId);
+    const input = {
+        root: resolve(root),
+        displayRoot: root,
+        startedAt: new Date().toISOString(),
+        traceContext: storeSpanContext(span),
+        ...(options.message === undefined ? {} : { message: options.message }),
+        ...(options.threadId === undefined ? {} : { threadId: options.threadId }),
+        ...(options.metadata === undefined ? {} : { metadata: options.metadata }),
+        ...(options.context === undefined ? {} : { context: options.context }),
+        ...(options.history === undefined ? {} : { history: options.history }),
+        ...(options.script === undefined ? {} : { script: options.script }),
+        // Always recorded for a script, so recovery can tell a run that may call handlers from one
+        // journaled before this flag existed.
+        ...(options.script !== undefined || options.mockTools === true
+            ? { mockTools: options.mockTools === true }
+            : {}),
+        ...(options.providerRecoveryKey === undefined
+            ? {}
+            : { providerRecoveryKey: options.providerRecoveryKey }),
+    };
+    let firstExecution = true;
+    const outcome = await engine
+        .run(runId, async (ctx, journaled) => {
+        const executionSpan = firstExecution
+            ? span
+            : startRunSpan(ctx.runId, journaled.traceContext);
+        firstExecution = false;
+        try {
+            const result = await runLoop(ctx, journaled, options, executionSpan);
+            if (result.status === "failed")
+                executionSpan.setStatus({ code: SpanStatusCode.ERROR });
+            return result;
+        }
+        catch (error) {
+            executionSpan.setStatus({ code: SpanStatusCode.ERROR });
+            throw error;
+        }
+        finally {
+            executionSpan.end();
+        }
+    }, input)
+        .finally(() => span.end());
+    if (outcome.output === undefined)
+        throw new Error(`Run ${runId} stopped without a result.`);
+    return outcome.output;
+}
+/**
+ * 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 async function recoverRuns(options) {
+    const recovered = await options.engine.recover((_runId, input) => {
+        const filter = options.recoveryFilter;
+        if (filter &&
+            (!isAbsolute(input.root) ||
+                projectIdentity(input.root) !== projectIdentity(filter.projectRoot) ||
+                (filter.providerOnly === true && input.message === undefined) ||
+                (input.message !== undefined &&
+                    (!input.providerRecoveryKey ||
+                        !filter.providerRecoveryKey ||
+                        input.providerRecoveryKey !== filter.providerRecoveryKey))))
+            return undefined;
+        const { provider: _provider, ...withoutProvider } = options;
+        return async (ctx, journaled) => {
+            const span = startRunSpan(ctx.runId, input.traceContext);
+            options.onRecoveryStarted?.(ctx.runId);
+            try {
+                const result = input.message === undefined
+                    ? isLegacyScript(input)
+                        ? await failRecovery(ctx, journaled, options, "recovery", legacyScriptMessage)
+                        : await runLoop(ctx, journaled, withoutProvider, span)
+                    : options.provider === undefined
+                        ? await failRecovery(ctx, journaled, options, "provider", "Cannot recover provider-backed run without a provider.")
+                        : await runLoop(ctx, journaled, options, span);
+                if (result.status === "failed")
+                    span.setStatus({ code: SpanStatusCode.ERROR });
+                return result;
+            }
+            catch (error) {
+                span.setStatus({ code: SpanStatusCode.ERROR });
+                throw error;
+            }
+            finally {
+                span.end();
+                options.onRecoverySettled?.(ctx.runId);
+            }
+        };
+    });
+    return recovered.map(({ runId, state, error, output }) => ({
+        runId,
+        state: output && output.status !== "running" ? output.status : state,
+        ...(error === undefined ? {} : { error }),
+    }));
+}
+function projectIdentity(root) {
+    const absolute = resolve(root);
+    return process.platform === "win32" ? absolute.toLowerCase() : absolute;
+}
+const legacyScriptMessage = "This scripted run was started by an older Plico that did not record whether its tools may run, so it is not resumed. Start it again.";
+/**
+ * A script journaled before runs recorded `mockTools`. It may have come from an API caller, so
+ * resuming it could run handlers that caller should never reach; it fails instead.
+ */
+function isLegacyScript(input) {
+    return input.script !== undefined && !("mockTools" in input);
+}
+async function failRecovery(ctx, input, options, phase, message) {
+    const events = await InMemoryEventLog.open(ctx.runId, options.eventStore);
+    const validation = await validateProject(input.root);
+    if (events.all().length === 0) {
+        await events.append("run.started", {
+            projectRoot: input.displayRoot ?? input.root,
+            projectName: validation.project?.config.name ?? "",
+        });
+        options.onStarted?.(ctx.runId);
+    }
+    events.continueAfterReplay();
+    await events.append("run.error", { phase, message });
+    await events.append("run.failed", { phase });
+    return finalizeRun({
+        runId: ctx.runId,
+        projectRoot: input.displayRoot ?? input.root,
+        projectName: validation.project?.config.name ?? "",
+        status: "failed",
+        startedAt: input.startedAt,
+        events: events.all(),
+        eventStore: options.eventStore,
+    });
+}
+async function runLoop(ctx, input, options, span) {
+    const { runId } = ctx;
+    const { root, startedAt } = input;
+    const displayRoot = input.displayRoot ?? root;
+    const validation = await validateProject(root);
+    const events = await InMemoryEventLog.open(runId, options.eventStore);
+    const errors = events.all().some((event) => event.type === "instructions.composed")
+        ? validation.errors.filter((issue) => !ignoredWhenPinned(issue))
+        : validation.errors;
+    const newlyStarted = events.all().length === 0;
+    await events.append("run.started", {
+        projectRoot: displayRoot,
+        projectName: validation.project?.config.name ?? "",
+        ...(input.threadId === undefined ? {} : { threadId: input.threadId }),
+        ...(input.metadata === undefined ? {} : { metadata: input.metadata }),
+        ...(input.context === undefined ? {} : { context: input.context }),
+    });
+    if (newlyStarted)
+        options.onStarted?.(runId);
+    if (errors.length > 0 || !validation.project) {
+        await events.append("run.error", { phase: "validation", issues: errors });
+        await events.append("run.failed", { phase: "validation" });
+        return finalizeRun({
+            runId,
+            projectRoot: displayRoot,
+            projectName: "",
+            status: "failed",
+            startedAt,
+            events: events.all(),
+            errors,
+            eventStore: options.eventStore,
+        });
+    }
+    const { project } = validation;
+    ctx = tracedContext(ctx, span, project.config.model);
+    const summary = {
+        runId,
+        projectRoot: displayRoot,
+        projectName: project.config.name,
+        startedAt,
+        eventStore: options.eventStore,
+    };
+    try {
+        const { instructions, skills } = await pinInstructions(project, events);
+        const tools = await discoverTools(project);
+        await recordTools(project.root, tools, events);
+        const output = options.provider !== undefined
+            ? await runProviderBackedRun(ctx, options.provider, input.message, instructions.content, tools, events, options.eventStore, project.config.model, project.config, input.history, skills)
+            : input.script === undefined
+                ? await runDefaultDryRun(project, events)
+                : await runScriptedDryRun(ctx, input.script, tools, events, options.eventStore, project.config, input.mockTools === true);
+        await events.append("run.completed", {
+            ...(output === undefined ? {} : { output }),
+        });
+        return await finalizeRun({ ...summary, status: "completed", output, events: events.all() });
+    }
+    catch (error) {
+        if (error instanceof RunWaitingError) {
+            return finalizeRun({
+                ...summary,
+                status: "waiting",
+                output: error.output,
+                events: events.all(),
+            });
+        }
+        if (error instanceof RunCancelled) {
+            await events.append("run.cancelled", {});
+            return finalizeRun({ ...summary, status: "cancelled", events: events.all() });
+        }
+        await events.append("run.error", runtimeErrorPayload(error));
+        await events.append("run.failed", { phase: "runtime" });
+        return finalizeRun({ ...summary, status: "failed", events: events.all() });
+    }
+}

package/dist/run/strategies/approval.d.ts

@@ -0,0 +1,9 @@
+import type { RunContext } from "../../engine/index.js";
+import type { InMemoryEventLog } from "../../events.js";
+export declare function approvalWaitName(requestId: string): string;
+/**
+ * Holds the run on its approval wait. The first time there is no decision it stops the loop with
+ * RunWaitingError so the caller can report the run as waiting. After a decision it returns when the
+ * tool may run and fails the run for a denial or a timeout, with a different message for each.
+ */
+export declare function awaitApproval(ctx: RunContext, requestId: string, toolName: string, output: string | undefined, events: InMemoryEventLog, timeoutMs?: number): Promise<void>;

package/dist/run/strategies/approval.js

@@ -0,0 +1,42 @@
+import { RunSuspended } from "../../engine/index.js";
+import { RuntimeDiagnosticError, RunWaitingError } from "../../errors.js";
+export function approvalWaitName(requestId) {
+    return `approval:${requestId}`;
+}
+/**
+ * Holds the run on its approval wait. The first time there is no decision it stops the loop with
+ * RunWaitingError so the caller can report the run as waiting. After a decision it returns when the
+ * tool may run and fails the run for a denial or a timeout, with a different message for each.
+ */
+export async function awaitApproval(ctx, requestId, toolName, output, events, timeoutMs) {
+    let outcome;
+    try {
+        outcome = await ctx.wait(approvalWaitName(requestId), {
+            ...(timeoutMs === undefined ? {} : { timeoutMs }),
+        });
+    }
+    catch (error) {
+        if (error instanceof RunSuspended)
+            throw new RunWaitingError(output);
+        throw error;
+    }
+    if (outcome.kind === "timeout") {
+        throw new RuntimeDiagnosticError({
+            phase: "approval",
+            toolName,
+            message: `Approval for ${toolName} timed out.`,
+        });
+    }
+    await events.append("approval.decided", {
+        requestId,
+        approved: outcome.value?.approved === true,
+        ...(outcome.value?.context === undefined ? {} : { context: outcome.value.context }),
+    });
+    if (outcome.value?.approved !== true) {
+        throw new RuntimeDiagnosticError({
+            phase: "approval",
+            toolName,
+            message: `Approval for ${toolName} was denied.`,
+        });
+    }
+}

package/dist/run/strategies/default-dry.d.ts

@@ -0,0 +1,3 @@
+import type { LoadedProject } from "@plico-ai/core";
+import type { InMemoryEventLog } from "../../events.js";
+export declare function runDefaultDryRun(project: LoadedProject, events: InMemoryEventLog): Promise<string>;

package/dist/run/strategies/default-dry.js

@@ -0,0 +1,5 @@
+export async function runDefaultDryRun(project, events) {
+    const output = `Dry run complete for ${project.config.name}.`;
+    await events.append("assistant.output", { content: output });
+    return output;
+}

package/dist/run/strategies/provider.d.ts

@@ -0,0 +1,6 @@
+import type { ProjectConfig } from "@plico-ai/contracts";
+import { type Skill } from "@plico-ai/core";
+import { type RunContext } from "../../engine/index.js";
+import type { InMemoryEventLog } from "../../events.js";
+import type { DeclaredTool, EventStore, ModelProvider } from "../../types/index.js";
+export declare function runProviderBackedRun(ctx: RunContext, provider: ModelProvider, message: string | undefined, instructions: string, tools: DeclaredTool[], events: InMemoryEventLog, eventStore: EventStore | undefined, model: ProjectConfig["model"], config: ProjectConfig, history?: Array<Pick<import("../../types/index.js").ProviderMessage, "role" | "content">>, skills?: Skill[]): Promise<string>;

package/dist/run/strategies/provider.js

@@ -0,0 +1,193 @@
+import { randomUUID } from "node:crypto";
+import { setTimeout as delay } from "node:timers/promises";
+import { ARTIFACT_TOOL_NAMES } from "@plico-ai/core";
+import { RunCancelled } from "../../engine/index.js";
+import { ModelProviderError, RuntimeDiagnosticError } from "../../errors.js";
+import { approvalTimeoutMs, decideApproval } from "../../policy/approval.js";
+import { createArtifactModelTools } from "../../tools/artifact-model-tools.js";
+import { createSkillModelTool } from "../../tools/skill-model-tool.js";
+import { runToolStep } from "../tool-step.js";
+import { nameToolStep } from "../tracing.js";
+import { awaitApproval } from "./approval.js";
+export async function runProviderBackedRun(ctx, provider, message, instructions, tools, events, eventStore, model, config, history = [], skills = []) {
+    const maxSteps = model?.maxSteps ?? 10;
+    if (!message) {
+        throw new RuntimeDiagnosticError({
+            phase: "provider",
+            message: "A user message is required when running with a provider. Provide --message or pipe input via stdin.",
+        });
+    }
+    await events.append("input.received", { content: message });
+    const artifactTools = await createArtifactModelTools();
+    const skillTools = skills.length > 0 ? [await createSkillModelTool(skills)] : [];
+    const toolsByName = new Map([...tools, ...artifactTools, ...skillTools].map((tool) => [tool.name, tool]));
+    const artifactAccess = config.artifacts?.access ?? "read-write";
+    const providerTools = [...tools, ...artifactTools, ...skillTools]
+        .filter((tool) => isArtifactToolAllowed(tool.name, artifactAccess))
+        .map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+    }));
+    const messages = [
+        { role: "system", content: instructions },
+        ...(history ?? []),
+        { role: "user", content: message },
+    ];
+    let output;
+    for (let turn = 0; turn < maxSteps; turn++) {
+        const modelRequest = {
+            messages,
+            maxSteps,
+            tools: providerTools,
+        };
+        await events.append("model.request", {
+            ...(model ? { model: { provider: model.provider, name: model.name } } : {}),
+            messages: modelRequest.messages,
+            maxSteps: modelRequest.maxSteps,
+            tools: providerTools,
+        });
+        const modelResponse = await ctx.step(`model:${turn}`, async ({ signal, attempt }) => {
+            events.skipModelDeltas(turn);
+            if (attempt > 0)
+                await delay((model?.retryDelayMs ?? 100) * 2 ** (attempt - 1), undefined, { signal });
+            const attemptId = randomUUID();
+            await events.append("model.attempt", { turn, attemptId });
+            let content = "";
+            const toolCalls = [];
+            let providerMetadata;
+            let usage;
+            for await (const chunk of provider.stream(modelRequest, { signal })) {
+                if (chunk.type === "text") {
+                    content += chunk.text;
+                    await events.append("model.delta", { turn, attemptId, text: chunk.text });
+                }
+                else if (chunk.type === "tool.call")
+                    toolCalls.push(chunk.call);
+                else {
+                    usage = chunk.usage;
+                    providerMetadata = chunk.providerMetadata;
+                }
+            }
+            if (signal.aborted)
+                throw new RunCancelled();
+            if (!usage)
+                throw new Error("Model stream ended without a finish.");
+            return {
+                content,
+                usage,
+                attemptId,
+                ...(providerMetadata === undefined ? {} : { providerMetadata }),
+                ...(toolCalls.length ? { toolCalls } : {}),
+            };
+        }, {
+            retries: model?.retries ?? 2,
+            shouldRetry: (error) => error instanceof ModelProviderError && error.retryable,
+        });
+        events.skipModelDeltas(turn);
+        await events.append("model.response", {
+            attemptId: modelResponse.attemptId,
+            ...(modelResponse.providerMetadata === undefined
+                ? {}
+                : { providerMetadata: modelResponse.providerMetadata }),
+            content: modelResponse.content,
+            usage: modelResponse.usage,
+            toolCalls: modelResponse.toolCalls,
+        });
+        if (modelResponse.toolCalls === undefined || modelResponse.toolCalls.length === 0) {
+            const finalContent = modelResponse.content;
+            if (finalContent) {
+                await events.append("assistant.output", { content: finalContent });
+                output = finalContent;
+            }
+            return output ?? finalContent;
+        }
+        messages.push({
+            role: "assistant",
+            content: modelResponse.content,
+            toolCalls: modelResponse.toolCalls,
+            ...(modelResponse.providerMetadata === undefined
+                ? {}
+                : { providerMetadata: modelResponse.providerMetadata }),
+        });
+        for (const [callIndex, toolCall] of modelResponse.toolCalls.entries()) {
+            if (!isArtifactToolAllowed(toolCall.name, artifactAccess)) {
+                throw new RuntimeDiagnosticError({
+                    phase: "tool.access",
+                    toolName: toolCall.name,
+                    message: `Artifact tool ${toolCall.name} is disabled by artifacts.access="${artifactAccess}".`,
+                });
+            }
+            const tool = toolsByName.get(toolCall.name);
+            if (!tool) {
+                throw new RuntimeDiagnosticError({
+                    phase: "tool.validation",
+                    toolName: toolCall.name,
+                    message: `Provider requested unknown tool: ${toolCall.name}`,
+                });
+            }
+            await events.append("tool.call", {
+                toolName: tool.name,
+                arguments: toolCall.arguments,
+            });
+            const parsedInput = await tool.parseInput(toolCall.arguments);
+            if (!parsedInput.success) {
+                throw new RuntimeDiagnosticError({
+                    phase: "tool.validation",
+                    toolName: tool.name,
+                    message: `Tool ${tool.name} arguments invalid: ${parsedInput.error}`,
+                });
+            }
+            const approval = decideApproval(tool, config);
+            if (approval.required) {
+                const requestId = `${ctx.runId}:${turn}:${callIndex}`;
+                await events.append("approval.requested", {
+                    requestId,
+                    toolName: tool.name,
+                    arguments: toolCall.arguments,
+                    approval,
+                });
+                await events.append("run.waiting", {
+                    requestId,
+                    toolName: tool.name,
+                    ...(output === undefined ? {} : { output }),
+                });
+                await awaitApproval(ctx, requestId, tool.name, output, events, approvalTimeoutMs(config));
+            }
+            let result;
+            try {
+                const idempotencyKey = `${ctx.runId}:${turn}:${callIndex}`;
+                nameToolStep(ctx, `tool:${turn}:${callIndex}`, tool.name);
+                result = await runToolStep(ctx, events, eventStore, tool, parsedInput.value, `tool:${turn}:${callIndex}`, idempotencyKey);
+            }
+            catch (error) {
+                if (error instanceof RunCancelled)
+                    throw error;
+                throw new RuntimeDiagnosticError({
+                    phase: "runtime",
+                    toolName: tool.name,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+            }
+            messages.push({
+                role: "tool",
+                content: JSON.stringify(result),
+                toolName: tool.name,
+                ...(toolCall.id === undefined ? {} : { toolCallId: toolCall.id }),
+            });
+        }
+    }
+    throw new RuntimeDiagnosticError({
+        phase: "provider",
+        message: `Maximum steps reached (${maxSteps}).`,
+    });
+}
+function isArtifactToolAllowed(toolName, access) {
+    if (!ARTIFACT_TOOL_NAMES.includes(toolName))
+        return true;
+    if (access === "off")
+        return false;
+    if (access === "read-only" && (toolName === "write_file" || toolName === "edit_file"))
+        return false;
+    return true;
+}

package/dist/run/strategies/scripted.d.ts

@@ -0,0 +1,5 @@
+import type { ProjectConfig } from "@plico-ai/contracts";
+import { type RunContext } from "../../engine/index.js";
+import type { InMemoryEventLog } from "../../events.js";
+import type { DeclaredTool, DryRunScriptStep, EventStore } from "../../types/index.js";
+export declare function runScriptedDryRun(ctx: RunContext, script: DryRunScriptStep[], tools: DeclaredTool[], events: InMemoryEventLog, eventStore: EventStore | undefined, config: ProjectConfig, mockTools?: boolean): Promise<string | undefined>;