@abot-ai/runtime 1.5.0 → 1.6.0

package/dist/src/runtime/automations/retention.js

@@ -0,0 +1,134 @@
+export const AUTOMATION_DETAIL_RETENTION_MS = 30 * 24 * 60 * 60_000;
+export const AUTOMATION_REPORT_RETENTION_MS = 90 * 24 * 60 * 60_000;
+const MAX_RESULT_CLEANUP = 64;
+const MAX_SNAPSHOT_CLEANUP = 32;
+function hasUnresolvedEffect(state, runId) {
+    return state.attempts.some((attempt) => attempt.runId === runId &&
+        hasUnresolvedAttemptEffect(attempt));
+}
+function hasUnresolvedAttemptEffect(attempt) {
+    if (attempt.state === "started")
+        return true;
+    if (attempt.state !== "uncertain")
+        return false;
+    // Late evidence resolves resource uncertainty without rewriting the historical outcome.
+    if (attempt.lateSettlement?.status === "succeeded")
+        return false;
+    if (attempt.lateSettlement?.status === "failed")
+        return false;
+    return true;
+}
+function olderThan(terminalAt, now, ageMs) {
+    return terminalAt !== undefined && Date.parse(terminalAt) <= now - ageMs;
+}
+function updateExecution(state, current, patch) {
+    const next = { ...current, ...patch, revision: current.revision + 1 };
+    state.executions[state.executions.indexOf(current)] = next;
+    return next;
+}
+function markRunPayloads(state, now, at) {
+    for (const initial of [...state.executions]) {
+        if (!initial.terminalAt || hasUnresolvedEffect(state, initial.id))
+            continue;
+        let execution = initial;
+        if (olderThan(execution.terminalAt, now, AUTOMATION_DETAIL_RETENTION_MS) &&
+            !execution.detailsExpiredAt)
+            execution = updateExecution(state, execution, { detailsExpiredAt: at });
+        if (olderThan(execution.terminalAt, now, AUTOMATION_REPORT_RETENTION_MS) &&
+            !execution.reportExpiredAt)
+            updateExecution(state, execution, { reportExpiredAt: at });
+    }
+}
+function expiredResult(record, executions) {
+    const execution = executions.get(record.runId);
+    return record.kind === "report"
+        ? execution?.reportExpiredAt !== undefined
+        : execution?.detailsExpiredAt !== undefined;
+}
+function snapshotCanExpire(state, record) {
+    if (!record.snapshot)
+        return false;
+    if (!record.claimRunId)
+        return false;
+    const references = state.executions.filter((execution) => execution.inputIds.includes(record.id));
+    return references.length > 0 && references.every((execution) => execution.reportExpiredAt !== undefined && !hasUnresolvedEffect(state, execution.id));
+}
+function markSnapshots(state, at) {
+    let available = MAX_SNAPSHOT_CLEANUP;
+    for (const record of state.inputs) {
+        if (available === 0)
+            break;
+        if (record.snapshotRetiredAt || !snapshotCanExpire(state, record))
+            continue;
+        const outcomeRef = record.outcomeRef ?? inputClaimReport(state, record);
+        if (!outcomeRef)
+            continue;
+        state.inputs[state.inputs.indexOf(record)] = { ...record, outcomeRef, snapshotRetiredAt: at };
+        available -= 1;
+    }
+}
+function inputClaimReport(state, record) {
+    return state.executions.find((execution) => execution.id === record.claimRunId && execution.inputIds.includes(record.id))?.reportRef;
+}
+function ownedSnapshot(record) {
+    const parts = record.snapshot?.attachment.storageRef.split(/[\\/]/u);
+    return Boolean(record.claimRunId && parts?.[0] === record.claimRunId &&
+        parts[1] === record.id && parts.length === 3);
+}
+/** Runs from the existing scheduler tick; marking survives a crash before file cleanup. */
+export async function maintainAutomationRetention(input) {
+    await input.results.reconcileUncommitted(input.persistence);
+    const at = new Date(input.now).toISOString();
+    const pending = await input.persistence.update((state) => {
+        markRunPayloads(state, input.now, at);
+        markSnapshots(state, at);
+        const executions = new Map(state.executions.map((item) => [item.id, item]));
+        return {
+            results: state.results.filter((record) => expiredResult(record, executions))
+                .slice(0, MAX_RESULT_CLEANUP),
+            inputs: state.inputs.filter((record) => record.snapshotRetiredAt && record.snapshot)
+                .slice(0, MAX_SNAPSHOT_CLEANUP),
+        };
+    });
+    const removedResultIds = new Set();
+    const removedInputIds = new Set();
+    let failure;
+    for (const record of pending.results) {
+        try {
+            await input.results.discardUncommitted(record);
+            removedResultIds.add(record.id);
+        }
+        catch (error) {
+            failure ??= error;
+        }
+    }
+    for (const record of pending.inputs) {
+        try {
+            if (!ownedSnapshot(record))
+                throw new Error("automation_snapshot_owner_invalid");
+            if (!input.attachments.deleteAttachment)
+                throw new Error("automation_attachment_cleanup_unavailable");
+            await input.attachments.deleteAttachment(record.snapshot.attachment, {
+                sessionId: record.claimRunId,
+            });
+            removedInputIds.add(record.id);
+        }
+        catch (error) {
+            failure ??= error;
+        }
+    }
+    if (removedResultIds.size || removedInputIds.size) {
+        await input.persistence.update((state) => {
+            const executions = new Map(state.executions.map((item) => [item.id, item]));
+            state.results = state.results.filter((record) => !removedResultIds.has(record.id) || !expiredResult(record, executions));
+            state.inputs = state.inputs.map((record) => {
+                if (!removedInputIds.has(record.id) || !record.snapshotRetiredAt)
+                    return record;
+                const { snapshot: _snapshot, snapshotRetiredAt: _retired, ...metadata } = record;
+                return metadata;
+            });
+        });
+    }
+    if (failure)
+        throw failure;
+}

package/dist/src/runtime/automations/run-file-binding.d.ts

@@ -0,0 +1,3 @@
+/** A portable basename; the runtime owns the per-run directory, never the model. */
+export declare function isAutomationRunFileName(value: unknown): value is string;
+export declare function automationRunFilePath(runId: string | undefined, fileName: string): string | null;

package/dist/src/runtime/automations/run-file-binding.js

@@ -0,0 +1,19 @@
+/** A portable basename; the runtime owns the per-run directory, never the model. */
+export function isAutomationRunFileName(value) {
+    if (typeof value !== "string" || value.length === 0 || value.length > 120)
+        return false;
+    if (value !== value.trim() || value.endsWith("."))
+        return false;
+    if (value === "." || value === "..")
+        return false;
+    if (/[<>:"/\\|?*\u0000-\u001f]/u.test(value))
+        return false;
+    return !/^(?:CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])(?:\.|$)/iu.test(value);
+}
+export function automationRunFilePath(runId, fileName) {
+    if (!runId || !/^[A-Za-z0-9_-]{1,128}$/u.test(runId))
+        return null;
+    if (!isAutomationRunFileName(fileName))
+        return null;
+    return `automation-output/${runId}/${fileName}`;
+}

package/dist/src/runtime/automations/run-output-summary.d.ts

@@ -0,0 +1,25 @@
+import type { AutomationRevision } from "./definition-contracts.js";
+import type { AutomationPersistence } from "./persistence.js";
+import type { AutomationResultStore } from "./result-store.js";
+import { type AutomationSavedOutput } from "./step-evidence-output.js";
+import type { AutomationJournalState, AutomationNodeStateRecord } from "./storage-records.js";
+export type AutomationRunOutputEntry = Readonly<{
+    nodeId: string;
+    title: string;
+    stepStatus: AutomationNodeStateRecord["status"];
+    availability: "available" | "expired" | "unavailable";
+    output: AutomationSavedOutput | null;
+    errorCode?: string;
+}>;
+export type AutomationRunOutputSummary = Readonly<{
+    entries: readonly AutomationRunOutputEntry[];
+    omitted: number;
+}>;
+/** A transient preview of terminal producers, never another persisted report or outcome. */
+export declare function readAutomationRunOutputSummary(options: {
+    state: AutomationJournalState;
+    runId: string;
+    definition: AutomationRevision;
+    results: Pick<AutomationResultStore, "read">;
+    persistence: Pick<AutomationPersistence, "read">;
+}): Promise<AutomationRunOutputSummary>;

package/dist/src/runtime/automations/run-output-summary.js

@@ -0,0 +1,54 @@
+import { compileAutomationGraph } from "./graph-validation.js";
+import { projectAutomationSavedOutput } from "./step-evidence-output.js";
+const MAX_RUN_OUTPUTS = 4;
+function findOwnedExecution(state, runId, definition) {
+    return state.executions.find((item) => item.id === runId &&
+        item.automationId === definition.automationId &&
+        item.definitionRevision === definition.revision);
+}
+function terminalOutputSteps(definition) {
+    const compiled = compileAutomationGraph(definition);
+    if (!compiled.ok)
+        return [];
+    const predecessors = new Set(compiled.graph.steps.flatMap((step) => step.dependsOn));
+    return compiled.graph.steps.filter((step) => !predecessors.has(step.id));
+}
+/** A transient preview of terminal producers, never another persisted report or outcome. */
+export async function readAutomationRunOutputSummary(options) {
+    const { state, runId, definition } = options;
+    const execution = findOwnedExecution(state, runId, definition);
+    const terminalSteps = terminalOutputSteps(definition);
+    let expiryRead;
+    function detailsExpiredDuringRead() {
+        expiryRead ??= options.persistence.read().then((latest) => Boolean(findOwnedExecution(latest, runId, definition)?.detailsExpiredAt), () => false);
+        return expiryRead;
+    }
+    async function readEntry(step) {
+        const settled = execution?.nodes.find((item) => item.nodeId === step.id);
+        const base = {
+            nodeId: step.id, title: step.node.title, stepStatus: settled?.status ?? "pending",
+            ...(settled?.errorCode ? { errorCode: settled.errorCode } : {}),
+        };
+        if (execution?.detailsExpiredAt)
+            return { ...base, availability: "expired", output: null };
+        if (!settled?.resultRef)
+            return { ...base, availability: "unavailable", output: null };
+        const record = state.results.find((item) => item.id === settled.resultRef &&
+            item.runId === runId && item.nodeId === step.id && item.kind === "node_output");
+        if (!record)
+            return { ...base, availability: "unavailable", output: null };
+        try {
+            const saved = await options.results.read(record);
+            const output = projectAutomationSavedOutput(saved, false);
+            return { ...base, availability: "available", output };
+        }
+        catch {
+            // Retention publishes expiry before deleting bytes. Missing/corrupt output
+            // must not hide the independently retained compact report.
+            const expired = await detailsExpiredDuringRead();
+            return { ...base, availability: expired ? "expired" : "unavailable", output: null };
+        }
+    }
+    const entries = await Promise.all(terminalSteps.slice(0, MAX_RUN_OUTPUTS).map(readEntry));
+    return { entries, omitted: Math.max(0, terminalSteps.length - MAX_RUN_OUTPUTS) };
+}

package/dist/src/runtime/automations/run-report.d.ts

@@ -0,0 +1,83 @@
+import type { SchedulerAutomationRun } from "../scheduler/contracts.js";
+import type { AutomationRevision } from "./definition-contracts.js";
+import type { AutomationPersistence } from "./persistence.js";
+import type { AutomationResultStore } from "./result-store.js";
+import type { AutomationAttemptRecord, AutomationExecutionRecord, AutomationResultRecord } from "./storage-records.js";
+import { type AutomationRunEffectSummary } from "./step-evidence-effects.js";
+export type AutomationRunReport = Readonly<{
+    runId: string;
+    automationId: string;
+    definitionRevision: number;
+    outcome: "succeeded" | "completed_with_skips" | "failed" | "cancelled" | "interrupted" | "missed";
+    startedAt: string | null;
+    finishedAt: string;
+    inputIds: readonly string[];
+    inputVersions: readonly Readonly<{
+        inputId: string;
+        sourceId: string;
+        canonicalPath: string;
+        contentVersion: string;
+    }>[];
+    nodeResults: readonly Readonly<{
+        nodeId: string;
+        title?: string;
+        status: string;
+        errorCode?: string;
+        resultRef?: string;
+    }>[];
+    uncertainEffects: readonly Readonly<{
+        nodeId: string;
+        attemptId: string;
+    }>[];
+    /** Supplemental evidence does not change the terminal run outcome. */
+    lateEvidence: readonly Readonly<{
+        nodeId: string;
+        attemptId: string;
+        revision: number;
+        observedAt: string;
+        status: "succeeded" | "failed" | "rejected";
+        errorCode?: string;
+    }>[];
+    artifacts: readonly Readonly<{
+        id: string;
+        nodeId?: string;
+        kind: string;
+    }>[];
+    effectSummary?: AutomationRunEffectSummary;
+    modelCalls: number | null;
+    toolCalls: number | null;
+    /** Admitted attempts consume the tool limit even when execution is rejected. */
+    toolAttempts?: number;
+}>;
+export declare function verifiedToolCallCount(summary: AutomationRunEffectSummary | undefined, admittedAttempts: number): number | null;
+export declare function createAutomationReportService(options: {
+    persistence: AutomationPersistence;
+    results: AutomationResultStore;
+    now?: () => number;
+}): {
+    create: (input: {
+        run: SchedulerAutomationRun;
+        definition: AutomationRevision;
+        outcome: AutomationRunReport["outcome"];
+    }) => Promise<{
+        report: AutomationRunReport;
+        record: AutomationResultRecord;
+    }>;
+};
+export declare function buildAutomationRunReport(input: {
+    run: SchedulerAutomationRun;
+    definition: AutomationRevision;
+    execution: AutomationExecutionRecord;
+    inputs: readonly {
+        id: string;
+        sourceId: string;
+        canonicalPath: string;
+        contentVersion: string;
+    }[];
+    attempts: readonly Pick<AutomationAttemptRecord, "id" | "nodeId" | "state" | "lateSettlement">[];
+    results: readonly AutomationResultRecord[];
+    outcome: AutomationRunReport["outcome"];
+    finishedAt: string;
+    effectSummary?: AutomationRunEffectSummary;
+}): AutomationRunReport;
+export declare function projectAutomationLateEvidence(attempts: readonly Pick<AutomationAttemptRecord, "id" | "nodeId" | "lateSettlement">[]): AutomationRunReport["lateEvidence"];

package/dist/src/runtime/automations/run-report.js

@@ -0,0 +1,121 @@
+import { remainingAutomationResultBytes, requireAutomationResultCapacity } from "./result-capacity.js";
+import { publishAutomationResult } from "./result-publication.js";
+import { findAutomationStep, readAutomationRunEffectSummary, } from "./step-evidence-effects.js";
+export function verifiedToolCallCount(summary, admittedAttempts) {
+    if (!summary)
+        return admittedAttempts === 0 ? 0 : null;
+    if (summary.unresolvedAttempts > 0)
+        return null;
+    return summary.verifiedExecutions;
+}
+export function createAutomationReportService(options) {
+    const now = options.now ?? Date.now;
+    async function create(input) {
+        const state = await options.persistence.read();
+        const execution = state.executions.find((item) => item.id === input.run.id);
+        if (!execution)
+            throw new Error("automation_run_not_found");
+        const effectSummary = await readAutomationRunEffectSummary({
+            state, results: options.results, runId: input.run.id, definition: input.definition,
+        });
+        const report = buildAutomationRunReport({
+            run: input.run,
+            definition: input.definition,
+            execution,
+            inputs: state.inputs.filter((item) => execution.inputIds.includes(item.id)),
+            attempts: state.attempts.filter((item) => item.runId === input.run.id),
+            results: state.results.filter((item) => item.runId === input.run.id),
+            outcome: input.outcome,
+            finishedAt: new Date(now()).toISOString(),
+            effectSummary,
+        });
+        const usedBytes = state.results
+            .filter((item) => item.runId === input.run.id)
+            .reduce((sum, item) => sum + item.sizeBytes, 0);
+        const remaining = input.definition.limits.maxStoredArtifactBytes - usedBytes;
+        const record = await options.results.save({
+            runId: input.run.id,
+            kind: "report",
+            value: report,
+            maxBytes: Math.min(remaining, remainingAutomationResultBytes(state)),
+            at: report.finishedAt,
+        });
+        await publishAutomationResult({ ...options, record,
+            publish: () => options.persistence.update((current) => {
+                if (!current.executions.some((item) => item.id === input.run.id))
+                    throw new Error("automation_run_not_found");
+                if (current.results.some((item) => item.id === record.id))
+                    throw new Error("automation_result_duplicate");
+                const used = current.results.filter((item) => item.runId === input.run.id)
+                    .reduce((sum, item) => sum + item.sizeBytes, record.sizeBytes);
+                if (used > input.definition.limits.maxStoredArtifactBytes)
+                    throw new Error("automation_artifact_budget_exhausted");
+                requireAutomationResultCapacity(current, record.sizeBytes);
+                current.results.push(record);
+            }),
+        });
+        return { report, record };
+    }
+    return { create };
+}
+export function buildAutomationRunReport(input) {
+    const hasAgent = input.execution.nodes.some((node) => containsAgent(input.definition.body, node.nodeId));
+    return {
+        runId: input.run.id,
+        automationId: input.execution.automationId,
+        definitionRevision: input.execution.definitionRevision,
+        outcome: input.outcome,
+        startedAt: input.run.startedAt ?? null,
+        finishedAt: input.finishedAt,
+        inputIds: input.execution.inputIds,
+        inputVersions: input.inputs.map((item) => ({
+            inputId: item.id,
+            sourceId: item.sourceId,
+            canonicalPath: item.canonicalPath,
+            contentVersion: item.contentVersion,
+        })),
+        nodeResults: input.execution.nodes.map((node) => {
+            const step = findAutomationStep(input.definition.body, node.nodeId);
+            return {
+                nodeId: node.nodeId,
+                ...(step ? { title: step.title } : {}),
+                status: node.status,
+                ...(node.errorCode ? { errorCode: node.errorCode } : {}),
+                ...(node.resultRef ? { resultRef: node.resultRef } : {}),
+            };
+        }),
+        uncertainEffects: input.attempts
+            .filter((attempt) => attempt.state === "uncertain" || attempt.state === "started")
+            .map((attempt) => ({ nodeId: attempt.nodeId, attemptId: attempt.id })),
+        lateEvidence: projectAutomationLateEvidence(input.attempts),
+        artifacts: input.results
+            .filter((result) => result.kind === "artifact")
+            .map((result) => ({
+            id: result.id,
+            ...(result.nodeId ? { nodeId: result.nodeId } : {}),
+            kind: result.kind,
+        })),
+        ...(input.effectSummary ? { effectSummary: input.effectSummary } : {}),
+        modelCalls: input.execution.modelCalls ?? (hasAgent ? null : 0),
+        // A durable pre-dispatch attempt is not proof that the invocation ran.
+        toolCalls: verifiedToolCallCount(input.effectSummary, input.attempts.length),
+        toolAttempts: input.attempts.length,
+    };
+}
+export function projectAutomationLateEvidence(attempts) {
+    return attempts.flatMap((attempt) => attempt.lateSettlement ? [{
+            nodeId: attempt.nodeId,
+            attemptId: attempt.id,
+            ...attempt.lateSettlement,
+        }] : []);
+}
+function containsAgent(node, nodeId) {
+    const stack = [node];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (current.id === nodeId)
+            return current.kind === "agent";
+        stack.push(...(current.children ?? []), ...(current.branches ?? []));
+    }
+    return false;
+}

package/dist/src/runtime/automations/runtime-executor.d.ts

@@ -0,0 +1,16 @@
+import type { RuntimeAttachmentStore } from "../attachments/store.js";
+import type { RuntimeConfig, SessionStore } from "../ports.js";
+import type { SchedulerAutomationExecutor, SchedulerAutomationJob, SchedulerAutomationRun, SchedulerAutomationRunOutcome } from "../scheduler/contracts.js";
+import type { AutomationPersistence } from "./persistence.js";
+import type { AutomationResultStore } from "./result-store.js";
+import type { AutomationToolLifetimes } from "./tool-lifetimes.js";
+export declare function createAutomationRuntimeExecutor(options: {
+    config: RuntimeConfig;
+    sessions?: SessionStore;
+    persistence: AutomationPersistence;
+    attachments: RuntimeAttachmentStore;
+    results: AutomationResultStore;
+    toolLifetimes: AutomationToolLifetimes;
+    execute(job: SchedulerAutomationJob, run: SchedulerAutomationRun, signal: AbortSignal): Promise<SchedulerAutomationRunOutcome>;
+    now?: () => number;
+}): Omit<SchedulerAutomationExecutor, "tryReserve">;