@abot-ai/runtime 1.5.0 → 1.6.0

package/dist/src/runtime/automations/publication-validation.js

@@ -0,0 +1,162 @@
+import { resolveModelSelection } from "../model/model-selection.js";
+import { validateToolNormalInvocationInput, validateToolNormalInvocationPayload, } from "../../capabilities/normal-invocation/validator.js";
+import { compileAutomationGraph } from "./graph-validation.js";
+import { sourceAttachmentIssue } from "./source-attachment-access.js";
+import { validateAutomationWorkingDirectory } from "./working-directory.js";
+import { normalizeAutomationSchedule, requireAutomationScheduleOccurrence, hasAutomationScheduleTimingChanged } from "../scheduler/automation-schedule.js";
+import { validateTimeZone } from "../scheduler/schedule-validation.js";
+import { SchedulerValidationError } from "../scheduler/validation-error.js";
+import { automationTriggerSchedule } from "./trigger-schedule.js";
+function validateTriggerSchedule(definition, now, timeZone, checkScheduleReadiness, existingSchedule) {
+    const trigger = definition.trigger;
+    if (trigger.kind === "manual")
+        return [];
+    if (trigger.kind !== "schedule" && trigger.kind !== "folder")
+        return [];
+    const schedule = automationTriggerSchedule(trigger);
+    try {
+        const normalized = normalizeAutomationSchedule(schedule, now, existingSchedule);
+        if (!checkScheduleReadiness)
+            return [];
+        validateTimeZone(timeZone);
+        if (!hasAutomationScheduleTimingChanged(normalized, timeZone, existingSchedule))
+            return [];
+        requireAutomationScheduleOccurrence(normalized, timeZone, now);
+        return [];
+    }
+    catch (error) {
+        if (!(error instanceof SchedulerValidationError))
+            throw error;
+        return [{ code: error.code, message: error.message,
+                path: trigger.kind === "schedule" ? "trigger.schedule" : "trigger.checkEveryMs" }];
+    }
+}
+function matchesOperation(candidate, selected) {
+    return candidate.toolName === selected.toolName &&
+        candidate.operationId === selected.operationId &&
+        candidate.contractVersion === selected.contractVersion;
+}
+function validateToolNodeInputs(node, operation) {
+    const issues = [];
+    for (const required of operation.input.required) {
+        if (!Object.hasOwn(node.controls, required))
+            issues.push({
+                code: "automation_tool_input_missing",
+                path: `nodes.${node.id}.controls.${required}`,
+                message: `Configure the required ${required} input before publishing.`,
+            });
+    }
+    const literalValues = {};
+    for (const [name, binding] of Object.entries(node.controls)) {
+        if (!Object.hasOwn(operation.input.properties, name))
+            issues.push({
+                code: "automation_tool_input_invalid",
+                path: `nodes.${node.id}.controls.${name}`,
+                message: "This input is not part of the selected operation.",
+            });
+        else if (binding.kind === "literal")
+            literalValues[name] = binding.value;
+    }
+    const contract = {
+        operationId: operation.operationId,
+        summary: operation.label,
+        input: {
+            ...operation.input,
+            required: operation.input.required.filter((name) => Object.hasOwn(literalValues, name)),
+        },
+        effect: operation.effect,
+        approval: operation.approval,
+        ...(operation.payload ? { payload: operation.payload } : {}),
+    };
+    const literalInput = validateToolNormalInvocationInput(contract, literalValues);
+    if (!literalInput.ok)
+        issues.push({
+            code: "automation_tool_input_invalid",
+            path: `nodes.${node.id}.controls`,
+            message: literalInput.issue,
+        });
+    if (operation.payload?.minBytes && !node.payload)
+        issues.push({
+            code: "automation_tool_input_missing",
+            path: `nodes.${node.id}.payload`,
+            message: "Configure the required text input before publishing.",
+        });
+    if (node.payload?.kind === "literal") {
+        const payloadIssue = validateToolNormalInvocationPayload(contract, node.payload.value);
+        if (payloadIssue)
+            issues.push({
+                code: "automation_tool_input_invalid",
+                path: `nodes.${node.id}.payload`,
+                message: payloadIssue,
+            });
+    }
+    return issues;
+}
+export function validateAutomationPublication(input) {
+    const workingDirectoryIssue = validateAutomationWorkingDirectory(input.definition.workingDirectory);
+    if (workingDirectoryIssue)
+        return [workingDirectoryIssue];
+    const compiled = compileAutomationGraph(input.definition);
+    if (!compiled.ok)
+        return compiled.issues;
+    const issues = validateTriggerSchedule(input.definition, input.now ?? Date.now(), input.timeZone ?? "UTC", input.checkScheduleReadiness !== false, input.existingSchedule);
+    let sourceMayReceiveGeneratedFiles = false;
+    if (input.definition.trigger.kind !== "manual" && input.definition.trigger.kind !== "schedule" &&
+        input.definition.trigger.kind !== "folder") {
+        issues.push({ code: "automation_graph_invalid", path: "trigger", message: "Choose a supported trigger." });
+    }
+    for (const step of compiled.graph.steps) {
+        const node = step.node;
+        const sourceIssue = sourceAttachmentIssue(node, input.operations);
+        if (sourceIssue)
+            issues.push({
+                code: sourceIssue,
+                path: `nodes.${node.id}.${node.kind === "agent" ? "inputs" : "controls"}`,
+                message: "Select an operation that accepts frozen source files, or remove this snapshot binding.",
+            });
+        const selections = node.kind === "tool"
+            ? [node.operation]
+            : node.tools.map((tool) => tool.operation);
+        for (const [index, selected] of selections.entries()) {
+            const operation = input.operations.find((entry) => matchesOperation(entry, selected));
+            const path = node.kind === "tool"
+                ? `nodes.${node.id}.operation`
+                : `nodes.${node.id}.tools.${index}`;
+            if (!operation) {
+                issues.push({ code: "automation_operation_unavailable", path, message: "Grant and configure this operation before publishing." });
+                continue;
+            }
+            if (node.kind === "tool")
+                issues.push(...validateToolNodeInputs(node, operation));
+            if (operation.effect !== "read_only")
+                sourceMayReceiveGeneratedFiles = true;
+            if (operation.approval === "always" && input.grantMode !== "full_plus") {
+                issues.push({ code: "automation_approval_required", path, message: "This operation needs an interactive approval in Full mode." });
+            }
+        }
+        if (node.kind !== "agent")
+            continue;
+        const selection = resolveModelSelection({
+            agentMode: node.agentMode,
+            modelPreference: { profileId: node.modelProfileId, scope: "all" },
+            modelPolicy: input.config.models,
+            modelExecutionPolicies: input.config.modelExecutionPolicies,
+        });
+        if (selection.execution.primaryProfileId !== node.modelProfileId) {
+            issues.push({
+                code: "automation_model_unavailable",
+                path: `nodes.${node.id}.modelProfileId`,
+                message: "The selected model profile is not available for this Agent.",
+            });
+        }
+    }
+    if (input.definition.source && sourceMayReceiveGeneratedFiles &&
+        input.definition.source.excludePatterns.length === 0) {
+        issues.push({
+            code: "automation_source_exclusions_required",
+            path: "source.excludePatterns",
+            message: "Exclude output and archive paths so generated files do not re-enter this folder workflow.",
+        });
+    }
+    return issues;
+}

package/dist/src/runtime/automations/publication.d.ts

@@ -0,0 +1,33 @@
+import type { RuntimeConfig, ToolRegistry } from "../ports.js";
+import type { SchedulerService } from "../scheduler/contracts.js";
+import type { AutomationDraftManager } from "./draft-management.js";
+import type { AutomationPersistence } from "./persistence.js";
+import type { AutomationGrantManager } from "./permission-grants.js";
+import type { AutomationGraphIssue } from "./graph-validation.js";
+export declare class AutomationPublicationError extends Error {
+    readonly issues: readonly AutomationGraphIssue[];
+    constructor(issues: readonly AutomationGraphIssue[]);
+}
+export declare function createAutomationPublicationService(options: {
+    config: RuntimeConfig;
+    drafts: AutomationDraftManager;
+    grants: AutomationGrantManager;
+    persistence: AutomationPersistence;
+    scheduler: SchedulerService;
+    tools: ToolRegistry;
+    timeZone: string;
+    now?: () => number;
+}): {
+    publish: (automationId: string, expectedRevision: number) => Promise<{
+        definition: Readonly<{
+            id: string;
+            automationId: string;
+            revision: number;
+            definition: import("./definition-contracts.js").AutomationRevision;
+            publishedAt: string;
+            dependencyFingerprint?: string;
+        }>;
+        job: import("../scheduler/contracts.js").SchedulerAutomationJob;
+    }>;
+};
+export type AutomationPublicationService = ReturnType<typeof createAutomationPublicationService>;

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

@@ -0,0 +1,97 @@
+import { requireUnarchivedAutomation } from "./archive-management.js";
+import { readAutomationCatalog } from "./catalog.js";
+import { currentAutomationGrant } from "./permission-grants.js";
+import { validateAutomationPublication } from "./publication-validation.js";
+import { fingerprintAutomationDependencies } from "./dependency-fingerprint.js";
+import { automationTriggerSchedule, publishedAutomationScheduleTiming } from "./trigger-schedule.js";
+export class AutomationPublicationError extends Error {
+    issues;
+    constructor(issues) {
+        super("automation_graph_invalid");
+        this.issues = issues;
+    }
+}
+function commitDefinition(state, automationId, expectedRevision, record) {
+    requireUnarchivedAutomation(state, automationId);
+    const current = state.drafts.find((item) => item.automationId === automationId);
+    if (!current || current.revision !== expectedRevision)
+        throw new Error("automation_revision_conflict");
+    if (state.definitions.some((item) => item.automationId === automationId && item.revision === expectedRevision))
+        throw new Error("automation_already_published");
+    state.definitions.push(record);
+}
+function requirePublicationGrantRevision(state, environmentId, automationId, expectedGrantRevision) {
+    const latest = currentAutomationGrant(state.grants, environmentId, automationId);
+    if ((latest?.grantRevision ?? null) !== expectedGrantRevision)
+        throw new Error("automation_grant_revision_conflict");
+}
+export function createAutomationPublicationService(options) {
+    const now = options.now ?? Date.now;
+    async function publish(automationId, expectedRevision) {
+        const draft = await options.drafts.get(automationId);
+        if (!draft || draft.revision !== expectedRevision)
+            throw new Error("automation_revision_conflict");
+        if (draft.archivedAt)
+            throw new Error("automation_archived");
+        const grant = await options.grants.get(automationId);
+        const catalog = await readAutomationCatalog({
+            automationId,
+            environmentId: options.config.runtimeId,
+            config: options.config,
+            tools: options.tools,
+            persistence: options.persistence,
+        });
+        const job = await options.scheduler.getAutomationJob(automationId);
+        const state = await options.persistence.read();
+        const issues = validateAutomationPublication({
+            definition: draft.definition,
+            config: options.config,
+            operations: catalog.operations,
+            grantMode: grant?.mode ?? "full_access",
+            now: now(),
+            timeZone: options.timeZone,
+            existingSchedule: publishedAutomationScheduleTiming(state, job, draft.definition.trigger),
+        });
+        if (issues.length > 0)
+            throw new AutomationPublicationError(issues);
+        const record = {
+            id: `definition:${automationId}:${draft.revision}`,
+            automationId,
+            revision: draft.revision,
+            definition: structuredClone(draft.definition),
+            publishedAt: new Date(now()).toISOString(),
+            dependencyFingerprint: fingerprintAutomationDependencies({
+                definition: draft.definition,
+                config: options.config,
+                operations: catalog.operations,
+            }),
+        };
+        const schedule = automationTriggerSchedule(record.definition.trigger);
+        const commit = (state, candidate) => {
+            requirePublicationGrantRevision(state, options.config.runtimeId, automationId, grant?.grantRevision ?? null);
+            commitDefinition(state, automationId, expectedRevision, record);
+            // This callback mutates only the transaction candidate; a conflict
+            // rejects both the definition and job before either is published.
+            const publicationJobChanged = job &&
+                (candidate.id !== job.id || candidate.revision !== job.revision + 1);
+            if (publicationJobChanged)
+                throw new Error("automation_revision_conflict");
+        };
+        const publishedJob = job
+            ? await options.scheduler.updateAutomationJob(job.id, {
+                definitionRevision: record.revision,
+                title: record.definition.title,
+                schedule,
+                timeZone: options.timeZone,
+            }, commit)
+            : await options.scheduler.createAutomationJob({
+                automationId,
+                definitionRevision: record.revision,
+                title: record.definition.title,
+                schedule,
+                timeZone: options.timeZone,
+            }, commit);
+        return { definition: record, job: publishedJob };
+    }
+    return { publish };
+}

package/dist/src/runtime/automations/replay-preparation.d.ts

@@ -0,0 +1,7 @@
+import type { RuntimeAttachmentStore } from "../attachments/store.js";
+import type { PreparedAutomationOccurrence, SchedulerAutomationJob, SchedulerAutomationRun } from "../scheduler/contracts.js";
+import type { AutomationPersistence } from "./persistence.js";
+export declare function createAutomationReplayPreparer(options: {
+    persistence: AutomationPersistence;
+    attachments: RuntimeAttachmentStore;
+}): (job: SchedulerAutomationJob, previous: SchedulerAutomationRun, _candidateRunId: string) => Promise<PreparedAutomationOccurrence>;

package/dist/src/runtime/automations/replay-preparation.js

@@ -0,0 +1,59 @@
+function requireRetainedInput(state, inputId) {
+    const record = state.inputs.find((item) => item.id === inputId);
+    if (!record?.snapshot || record.snapshotRetiredAt || record.eligibility === "baseline" ||
+        record.snapshot.contentVersion !== record.contentVersion)
+        throw new Error("automation_replay_input_unavailable");
+    return {
+        id: record.id,
+        contentVersion: record.contentVersion,
+        storageRef: record.snapshot.attachment.storageRef,
+    };
+}
+export function createAutomationReplayPreparer(options) {
+    return async (job, previous, _candidateRunId) => {
+        const state = await options.persistence.read();
+        const definition = state.definitions.find((item) => item.automationId === previous.target.automationId &&
+            item.revision === previous.target.definitionRevision)?.definition;
+        if (!definition)
+            throw new Error("automation_definition_not_found");
+        const prior = state.executions.find((item) => item.id === previous.id);
+        if (!prior || prior.automationId !== previous.target.automationId ||
+            prior.definitionRevision !== previous.target.definitionRevision)
+            throw new Error("automation_replay_input_unavailable");
+        const inputIds = [...prior.inputIds];
+        if (definition.source && inputIds.length === 0)
+            throw new Error("automation_replay_input_unavailable");
+        const retained = inputIds.map((id) => requireRetainedInput(state, id));
+        for (const input of retained) {
+            const record = state.inputs.find((item) => item.id === input.id);
+            await options.attachments.resolveAttachment(record.snapshot.attachment);
+        }
+        return {
+            kind: "ready",
+            inputIds,
+            commit: (current, runId) => {
+                const liveDefinition = current.definitions.find((item) => item.automationId === previous.target.automationId &&
+                    item.revision === previous.target.definitionRevision);
+                const livePrior = current.executions.find((item) => item.id === previous.id);
+                if (!liveDefinition || !livePrior ||
+                    livePrior.inputIds.length !== inputIds.length ||
+                    livePrior.inputIds.some((id, index) => id !== inputIds[index]))
+                    throw new Error("automation_replay_input_changed");
+                for (const input of retained) {
+                    const live = requireRetainedInput(current, input.id);
+                    if (live.contentVersion !== input.contentVersion ||
+                        live.storageRef !== input.storageRef)
+                        throw new Error("automation_replay_input_changed");
+                }
+                current.executions.push({
+                    id: runId,
+                    automationId: job.target.automationId,
+                    definitionRevision: previous.target.definitionRevision,
+                    revision: 1,
+                    inputIds,
+                    nodes: [],
+                });
+            },
+        };
+    };
+}

package/dist/src/runtime/automations/result-capacity.d.ts

@@ -0,0 +1,5 @@
+import type { AutomationJournalState } from "./storage-records.js";
+/** Hard environment-wide bound while retained reports and replay inputs exist. */
+export declare const MAX_AUTOMATION_RESULT_BYTES: number;
+export declare function remainingAutomationResultBytes(state: AutomationJournalState): number;
+export declare function requireAutomationResultCapacity(state: AutomationJournalState, newBytes: number): void;

package/dist/src/runtime/automations/result-capacity.js

@@ -0,0 +1,9 @@
+/** Hard environment-wide bound while retained reports and replay inputs exist. */
+export const MAX_AUTOMATION_RESULT_BYTES = 256 * 1024 * 1024;
+export function remainingAutomationResultBytes(state) {
+    return MAX_AUTOMATION_RESULT_BYTES - state.results.reduce((bytes, item) => bytes + item.sizeBytes, 0);
+}
+export function requireAutomationResultCapacity(state, newBytes) {
+    if (newBytes > remainingAutomationResultBytes(state))
+        throw new Error("automation_artifact_budget_exhausted");
+}

package/dist/src/runtime/automations/result-publication.d.ts

@@ -0,0 +1,10 @@
+import type { AutomationPersistence } from "./persistence.js";
+import type { AutomationResultStore } from "./result-store.js";
+import type { AutomationResultRecord } from "./storage-records.js";
+/** File cleanup requires a readable durable head, including after uncertain publication. */
+export declare function publishAutomationResult<T>(options: {
+    persistence: AutomationPersistence;
+    results: AutomationResultStore;
+    record: AutomationResultRecord;
+    publish(): Promise<T>;
+}): Promise<T>;

package/dist/src/runtime/automations/result-publication.js

@@ -0,0 +1,21 @@
+/** File cleanup requires a readable durable head, including after uncertain publication. */
+export async function publishAutomationResult(options) {
+    try {
+        return await options.publish();
+    }
+    catch (error) {
+        const state = await options.persistence.read().catch(() => undefined);
+        // A visible manifest may contain this record even when its directory sync
+        // failed. The poisoned journal refuses reads until durable reacquisition.
+        const definitelyUncommitted = state &&
+            !state.results.some((record) => record.id === options.record.id);
+        if (definitelyUncommitted)
+            await options.results.discardUncommitted(options.record).catch(() => undefined);
+        throw error;
+    }
+    finally {
+        // An unreadable head leaves bytes on disk, but not permanently active in
+        // memory. Existing maintenance reconciles them after reacquisition.
+        await options.results.releasePublication(options.record);
+    }
+}

package/dist/src/runtime/automations/result-store.d.ts

@@ -0,0 +1,17 @@
+import type { AutomationResultRecord } from "./storage-records.js";
+import type { AutomationPersistence } from "./persistence.js";
+export declare function createAutomationResultStore(runtimeDir: string): {
+    save: (input: {
+        runId: string;
+        nodeId?: string;
+        kind: AutomationResultRecord["kind"];
+        value: unknown;
+        maxBytes: number;
+        at?: string;
+    }) => Promise<AutomationResultRecord>;
+    read: (record: AutomationResultRecord) => Promise<unknown>;
+    discardUncommitted: (record: AutomationResultRecord) => Promise<void>;
+    releasePublication: (record: AutomationResultRecord) => Promise<void>;
+    reconcileUncommitted: (persistence: AutomationPersistence) => Promise<void>;
+};
+export type AutomationResultStore = ReturnType<typeof createAutomationResultStore>;

package/dist/src/runtime/automations/result-store.js

@@ -0,0 +1,109 @@
+import { createHash, randomUUID } from "node:crypto";
+import { Buffer } from "node:buffer";
+import { mkdir, readFile, readdir, rm } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { syncJournalDirectory, writeJournalJson } from "../scheduler/journal-durability.js";
+const OWNED_FILE = /^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.json$/u;
+const MAX_UNCOMMITTED_CLEANUP = 64;
+export function createAutomationResultStore(runtimeDir) {
+    const directory = join(runtimeDir, "automation-results");
+    const activePublications = new Set();
+    let reconciliation;
+    function recordPath(record) {
+        const match = OWNED_FILE.exec(`${record.id}.json`);
+        if (!match || record.storageRef !== `automation-results/${record.id}.json`)
+            throw new Error("automation_result_ref_invalid");
+        return join(directory, `${record.id}.json`);
+    }
+    async function save(input) {
+        if (!Number.isSafeInteger(input.maxBytes) || input.maxBytes < 1)
+            throw new Error("automation_artifact_budget_exhausted");
+        let serialized;
+        try {
+            serialized = JSON.stringify(input.value);
+        }
+        catch {
+            throw new Error("automation_output_invalid");
+        }
+        if (typeof serialized !== "string")
+            throw new Error("automation_output_invalid");
+        const bytes = Buffer.byteLength(serialized, "utf8");
+        if (bytes > input.maxBytes)
+            throw new Error("automation_artifact_budget_exhausted");
+        const id = randomUUID();
+        const storageRef = `automation-results/${id}.json`;
+        const digest = createHash("sha256").update(serialized).digest("hex");
+        activePublications.add(id);
+        try {
+            await mkdir(directory, { recursive: true, mode: 0o700 });
+            await syncJournalDirectory(dirname(directory));
+            await writeJournalJson(join(directory, `${id}.json`), input.value);
+        }
+        catch (error) {
+            activePublications.delete(id);
+            throw error;
+        }
+        return {
+            id,
+            runId: input.runId,
+            ...(input.nodeId ? { nodeId: input.nodeId } : {}),
+            kind: input.kind,
+            storageRef,
+            digest,
+            sizeBytes: bytes,
+            createdAt: input.at ?? new Date().toISOString(),
+        };
+    }
+    async function read(record) {
+        const content = await readFile(recordPath(record), "utf8");
+        const digest = createHash("sha256").update(content).digest("hex");
+        if (digest !== record.digest || Buffer.byteLength(content, "utf8") !== record.sizeBytes)
+            throw new Error("automation_result_corrupt");
+        return JSON.parse(content);
+    }
+    async function discardUncommitted(record) {
+        await rm(recordPath(record), { force: true });
+    }
+    async function releasePublication(record) {
+        recordPath(record);
+        // A scan may hold a pre-commit journal snapshot. Keep this ID protected
+        // until that scan finishes; subsequent scans observe the published head.
+        await reconciliation?.catch(() => undefined);
+        activePublications.delete(record.id);
+    }
+    async function reconcileFiles(persistence) {
+        const entries = await readdir(directory, { withFileTypes: true }).catch((error) => {
+            if (error.code === "ENOENT")
+                return [];
+            throw error;
+        });
+        if (!entries.length)
+            return;
+        const state = await persistence.read();
+        const committed = new Set(state.results.map((record) => record.id));
+        let cleaned = 0;
+        for (const entry of entries) {
+            if (cleaned === MAX_UNCOMMITTED_CLEANUP)
+                break;
+            if (!entry.isFile())
+                continue;
+            const match = OWNED_FILE.exec(entry.name);
+            if (!match)
+                continue;
+            const id = match[1];
+            if (committed.has(id) || activePublications.has(id))
+                continue;
+            await rm(join(directory, entry.name), { force: true });
+            cleaned += 1;
+        }
+        if (cleaned)
+            await syncJournalDirectory(directory);
+    }
+    function reconcileUncommitted(persistence) {
+        if (reconciliation)
+            return reconciliation;
+        reconciliation = reconcileFiles(persistence).finally(() => { reconciliation = undefined; });
+        return reconciliation;
+    }
+    return { save, read, discardUncommitted, releasePublication, reconcileUncommitted };
+}

package/dist/src/runtime/automations/retention.d.ts

@@ -0,0 +1,12 @@
+import type { RuntimeAttachmentStore } from "../attachments/store.js";
+import type { AutomationPersistence } from "./persistence.js";
+import type { AutomationResultStore } from "./result-store.js";
+export declare const AUTOMATION_DETAIL_RETENTION_MS: number;
+export declare const AUTOMATION_REPORT_RETENTION_MS: number;
+/** Runs from the existing scheduler tick; marking survives a crash before file cleanup. */
+export declare function maintainAutomationRetention(input: {
+    persistence: AutomationPersistence;
+    results: AutomationResultStore;
+    attachments: RuntimeAttachmentStore;
+    now: number;
+}): Promise<void>;