@abot-ai/runtime 1.5.0 → 1.6.0

package/dist/src/runtime/automations/archive-management.d.ts

@@ -0,0 +1,26 @@
+import type { AutomationPersistence } from "./persistence.js";
+import type { AutomationJournalState } from "./storage-records.js";
+export declare function requireUnarchivedAutomation(state: AutomationJournalState, automationId: string): void;
+export declare function createAutomationArchiveManager(options: {
+    persistence: AutomationPersistence;
+    now?: () => number;
+}): {
+    archive: (automationId: string, expectedRevision: number) => Promise<Readonly<{
+        id: string;
+        automationId: string;
+        revision: number;
+        definition: import("./definition-contracts.js").AutomationRevision;
+        updatedAt: string;
+        archivedAt?: string;
+        storageRevision?: number;
+    }>>;
+    restore: (automationId: string, expectedRevision: number) => Promise<Readonly<{
+        id: string;
+        automationId: string;
+        revision: number;
+        definition: import("./definition-contracts.js").AutomationRevision;
+        updatedAt: string;
+        archivedAt?: string;
+        storageRevision?: number;
+    }>>;
+};

package/dist/src/runtime/automations/archive-management.js

@@ -0,0 +1,50 @@
+import { hasActiveAutomationRun } from "../scheduler/automation-run-records.js";
+import { isAutomationSchedulerJob } from "../scheduler/scheduler-target.js";
+export function requireUnarchivedAutomation(state, automationId) {
+    if (state.drafts.some((draft) => draft.automationId === automationId && draft.archivedAt !== undefined))
+        throw new Error("automation_archived");
+}
+export function createAutomationArchiveManager(options) {
+    const now = options.now ?? Date.now;
+    async function changeArchiveState(automationId, expectedRevision, archived) {
+        if (!Number.isSafeInteger(expectedRevision) || expectedRevision < 1)
+            throw new Error("automation_revision_conflict");
+        return options.persistence.updateWithScheduler((scheduler, state) => {
+            const index = state.drafts.findIndex((draft) => draft.automationId === automationId);
+            const draft = state.drafts[index];
+            if (!draft)
+                throw new Error("automation_not_found");
+            if (draft.revision !== expectedRevision)
+                throw new Error("automation_revision_conflict");
+            const job = scheduler.jobs.find((candidate) => isAutomationSchedulerJob(candidate) &&
+                candidate.target.automationId === automationId);
+            const published = state.definitions.some((definition) => definition.automationId === automationId);
+            if (!job || !published)
+                throw new Error("automation_not_published");
+            if (hasActiveAutomationRun(scheduler, automationId))
+                throw new Error("automation_run_active");
+            if ((draft.archivedAt !== undefined) === archived)
+                return draft;
+            const at = new Date(now()).toISOString();
+            // Content revisions and published execution definitions remain unchanged.
+            const next = {
+                ...draft, updatedAt: at,
+                storageRevision: (draft.storageRevision ?? draft.revision) + 1,
+            };
+            if (archived)
+                next.archivedAt = at;
+            else
+                delete next.archivedAt;
+            job.state = "paused";
+            job.nextRunAt = null;
+            job.updatedAt = at;
+            job.revision += 1;
+            state.drafts[index] = next;
+            return next;
+        });
+    }
+    return {
+        archive: (automationId, expectedRevision) => changeArchiveState(automationId, expectedRevision, true),
+        restore: (automationId, expectedRevision) => changeArchiveState(automationId, expectedRevision, false),
+    };
+}

package/dist/src/runtime/automations/binding-resolution.d.ts

@@ -0,0 +1,28 @@
+import type { CapabilityJsonValue } from "../orchestration/capability-adapters/result.js";
+import type { SourceFileSnapshot, ValueBinding } from "./definition-contracts.js";
+export type SettledNodeResult = Readonly<{
+    status: "succeeded" | "skipped" | "failed" | "cancelled" | "interrupted";
+    text?: string;
+    data?: CapabilityJsonValue;
+    resultRef?: string;
+}>;
+export type BranchResult = Readonly<{
+    nodeId: string;
+    status: SettledNodeResult["status"];
+    resultRef?: string;
+}>;
+export type AutomationBindingContext = Readonly<{
+    runId?: string;
+    runInputs: Readonly<Record<string, CapabilityJsonValue>>;
+    sourceFiles: readonly SourceFileSnapshot[];
+    nodeResults: ReadonlyMap<string, SettledNodeResult>;
+    branchResults: ReadonlyMap<string, readonly BranchResult[]>;
+}>;
+export type AutomationBindingResolution = Readonly<{
+    ok: true;
+    value: CapabilityJsonValue;
+}> | Readonly<{
+    ok: false;
+    code: "automation_dependency_missing" | "automation_output_pointer_invalid";
+}>;
+export declare function resolveAutomationBinding(binding: ValueBinding, context: AutomationBindingContext): AutomationBindingResolution;

package/dist/src/runtime/automations/binding-resolution.js

@@ -0,0 +1,115 @@
+import { automationRunFilePath } from "./run-file-binding.js";
+const MISSING = Object.freeze({
+    ok: false,
+    code: "automation_dependency_missing",
+});
+function resolvePointer(value, pointer) {
+    if (!pointer.startsWith("/")) {
+        return { ok: false, code: "automation_output_pointer_invalid" };
+    }
+    let selected = value;
+    for (const segment of pointer.slice(1).split("/")) {
+        if (/~(?![01])/u.test(segment)) {
+            return { ok: false, code: "automation_output_pointer_invalid" };
+        }
+        const key = segment.replaceAll("~1", "/").replaceAll("~0", "~");
+        if (key === "__proto__" || key === "constructor" || key === "prototype") {
+            return { ok: false, code: "automation_output_pointer_invalid" };
+        }
+        if (Array.isArray(selected)) {
+            if (!/^(0|[1-9][0-9]*)$/u.test(key))
+                return MISSING;
+            const index = Number(key);
+            if (!Number.isSafeInteger(index) || index >= selected.length)
+                return MISSING;
+            selected = selected[index];
+            continue;
+        }
+        if (typeof selected !== "object" || selected === null || !Object.hasOwn(selected, key)) {
+            return MISSING;
+        }
+        selected = selected[key];
+    }
+    return { ok: true, value: selected };
+}
+function sourceFileValue(file) {
+    return {
+        inputId: file.inputId,
+        sourceId: file.sourceId,
+        originalPath: file.originalPath,
+        snapshotPath: file.snapshotPath,
+        version: file.version,
+        sizeBytes: file.sizeBytes,
+    };
+}
+function selectedSourceField(file, field) {
+    switch (field) {
+        case "snapshot_path": return file.snapshotPath;
+        case "original_path": return file.originalPath;
+        case "version": return file.version;
+    }
+}
+function resolveSettledNodeResult(binding, context) {
+    const result = context.nodeResults.get(binding.nodeId);
+    if (result?.status !== "succeeded")
+        return MISSING;
+    const value = binding.select === "text" ? result.text : result.data;
+    if (value === undefined)
+        return MISSING;
+    if (binding.pointer === undefined)
+        return { ok: true, value };
+    if (binding.select !== "data") {
+        return { ok: false, code: "automation_output_pointer_invalid" };
+    }
+    return resolvePointer(value, binding.pointer);
+}
+function resolveParallelResults(parallelNodeId, context) {
+    const branches = context.branchResults.get(parallelNodeId);
+    if (!branches)
+        return MISSING;
+    const values = [];
+    for (const branch of branches) {
+        if (branch.status !== "succeeded") {
+            values.push({ ...branch });
+            continue;
+        }
+        const result = context.nodeResults.get(branch.nodeId);
+        if (result?.status !== "succeeded")
+            return MISSING;
+        const hasMaterializedOutput = result.text !== undefined || result.data !== undefined;
+        if (!hasMaterializedOutput)
+            return MISSING;
+        values.push({
+            ...branch,
+            ...(result.text !== undefined ? { text: result.text } : {}),
+            ...(result.data !== undefined ? { data: result.data } : {}),
+        });
+    }
+    return { ok: true, value: values };
+}
+export function resolveAutomationBinding(binding, context) {
+    switch (binding.kind) {
+        case "literal":
+            return { ok: true, value: binding.value };
+        case "run_input":
+            return Object.hasOwn(context.runInputs, binding.input)
+                ? { ok: true, value: context.runInputs[binding.input] }
+                : MISSING;
+        case "run_file": {
+            const value = automationRunFilePath(context.runId, binding.fileName);
+            return value === null ? MISSING : { ok: true, value };
+        }
+        case "source_files":
+            return { ok: true, value: context.sourceFiles.map(sourceFileValue) };
+        case "source_file": {
+            const file = context.sourceFiles[binding.index];
+            if (!file)
+                return MISSING;
+            return { ok: true, value: selectedSourceField(file, binding.field) };
+        }
+        case "node_result":
+            return resolveSettledNodeResult(binding, context);
+        case "branch_results":
+            return resolveParallelResults(binding.parallelNodeId, context);
+    }
+}

package/dist/src/runtime/automations/branch-result-projection.d.ts

@@ -0,0 +1,4 @@
+import type { BranchResult, SettledNodeResult } from "./binding-resolution.js";
+import type { CompiledParallelGroup } from "./graph-validation.js";
+/** A join projects only its terminal producers; earlier outputs need explicit bindings. */
+export declare function projectAutomationBranchResults(groups: readonly CompiledParallelGroup[], settled: ReadonlyMap<string, SettledNodeResult>): ReadonlyMap<string, readonly BranchResult[]>;

package/dist/src/runtime/automations/branch-result-projection.js

@@ -0,0 +1,15 @@
+/** A join projects only its terminal producers; earlier outputs need explicit bindings. */
+export function projectAutomationBranchResults(groups, settled) {
+    const projected = new Map();
+    for (const group of groups) {
+        const hasSettledBranchTails = group.tailNodeIds.every((id) => settled.has(id));
+        if (!hasSettledBranchTails)
+            continue;
+        projected.set(group.id, group.tailNodeIds.map((nodeId) => {
+            const result = settled.get(nodeId);
+            return { nodeId, status: result.status,
+                ...(result.resultRef ? { resultRef: result.resultRef } : {}) };
+        }));
+    }
+    return projected;
+}

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

@@ -0,0 +1,76 @@
+import type { ToolNormalInvocationInput, ToolNormalInvocationPayload, ToolNormalInvocationOperation } from "../../capabilities/normal-invocation/contracts.js";
+import type { ToolNormalInvocationAttachmentInput } from "../../capabilities/normal-invocation/contracts.js";
+import type { ToolCatalogGroup } from "../../capabilities/tool-types.js";
+import type { RuntimeConfig, ToolRegistry } from "../ports.js";
+import type { AutomationPersistence } from "./persistence.js";
+export type AutomationCatalogOperation = Readonly<{
+    toolName: string;
+    operationId: string;
+    contractVersion: number;
+    label: string;
+    pluginName?: string;
+    catalogGroups: readonly ToolCatalogGroup[];
+    toolDescription?: string;
+    permissionMode: "full_access" | "full_plus";
+    effect: "read_only" | "mutating" | "mixed";
+    approval: "request_policy" | "always";
+    input: ToolNormalInvocationInput;
+    fixedParams?: ToolNormalInvocationOperation["fixedParams"];
+    payload?: ToolNormalInvocationPayload;
+    attachmentInput?: ToolNormalInvocationAttachmentInput;
+    selectionControlIds?: readonly string[];
+}>;
+export declare function readAutomationCatalog(input: {
+    automationId: string;
+    environmentId: string;
+    config: RuntimeConfig;
+    tools: ToolRegistry;
+    persistence: AutomationPersistence;
+}): Promise<{
+    operations: Readonly<{
+        toolName: string;
+        operationId: string;
+        contractVersion: number;
+        label: string;
+        pluginName?: string;
+        catalogGroups: readonly ToolCatalogGroup[];
+        toolDescription?: string;
+        permissionMode: "full_access" | "full_plus";
+        effect: "read_only" | "mutating" | "mixed";
+        approval: "request_policy" | "always";
+        input: ToolNormalInvocationInput;
+        fixedParams?: ToolNormalInvocationOperation["fixedParams"];
+        payload?: ToolNormalInvocationPayload;
+        attachmentInput?: ToolNormalInvocationAttachmentInput;
+        selectionControlIds?: readonly string[];
+    }>[];
+    grantableOperations: Readonly<{
+        toolName: string;
+        operationId: string;
+        contractVersion: number;
+        label: string;
+        pluginName?: string;
+        catalogGroups: readonly ToolCatalogGroup[];
+        toolDescription?: string;
+        permissionMode: "full_access" | "full_plus";
+        effect: "read_only" | "mutating" | "mixed";
+        approval: "request_policy" | "always";
+        input: ToolNormalInvocationInput;
+        fixedParams?: ToolNormalInvocationOperation["fixedParams"];
+        payload?: ToolNormalInvocationPayload;
+        attachmentInput?: ToolNormalInvocationAttachmentInput;
+        selectionControlIds?: readonly string[];
+    }>[];
+    models: {
+        provider?: string | undefined;
+        id: string;
+        label: string;
+    }[];
+    savedAgents: {
+        id: string;
+        revision: number;
+        title: string;
+        modelProfileId: string;
+        agent: import("./definition-contracts.js").AgentNode;
+    }[];
+}>;

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

@@ -0,0 +1,67 @@
+import { currentAutomationGrant, permitsAutomationOperation } from "./permission-grants.js";
+const EXCLUDED_RUNNING_TOOLS = new Set(["schedules", "automations", "automation_builder"]);
+export async function readAutomationCatalog(input) {
+    const prepared = await input.tools.prepareRequest?.() ?? input.tools;
+    const state = await input.persistence.read();
+    const grant = currentAutomationGrant(state.grants, input.environmentId, input.automationId);
+    const grantableOperations = [];
+    const operations = [];
+    for (const registration of prepared.listNormalInvocations?.() ?? []) {
+        if (EXCLUDED_RUNNING_TOOLS.has(registration.toolName))
+            continue;
+        const permissionMode = registration.definition.requiredPermissionMode ?? "full_access";
+        for (const operation of registration.contract.operations) {
+            const entry = {
+                toolName: registration.toolName,
+                operationId: operation.operationId,
+                contractVersion: registration.contract.version,
+                label: operation.summary,
+                ...(registration.definition.pluginName
+                    ? { pluginName: registration.definition.pluginName }
+                    : {}),
+                catalogGroups: registration.definition.catalogGroups ?? [],
+                ...(registration.definition.description
+                    ? { toolDescription: registration.definition.description }
+                    : {}),
+                permissionMode,
+                effect: operation.effect,
+                approval: operation.approval,
+                input: operation.input,
+                ...(operation.fixedParams ? { fixedParams: operation.fixedParams } : {}),
+                ...(operation.payload ? { payload: operation.payload } : {}),
+                ...(operation.attachmentInput
+                    ? { attachmentInput: operation.attachmentInput }
+                    : {}),
+                ...(operation.selectionControlIds
+                    ? { selectionControlIds: operation.selectionControlIds } : {}),
+            };
+            grantableOperations.push(entry);
+            const reference = {
+                toolName: entry.toolName,
+                operationId: entry.operationId,
+                contractVersion: entry.contractVersion,
+            };
+            if (permitsAutomationOperation(grant, input.environmentId, input.automationId, reference, permissionMode))
+                operations.push(entry);
+        }
+    }
+    const models = Object.entries(input.config.models?.profiles ?? {}).map(([id, profile]) => ({
+        id,
+        label: profile.label ?? id,
+        ...(profile.provider ? { provider: profile.provider } : {}),
+    }));
+    const latestAgents = new Map();
+    for (const saved of state.savedAgents) {
+        const previous = latestAgents.get(saved.agentId);
+        if (!previous || saved.revision > previous.revision)
+            latestAgents.set(saved.agentId, saved);
+    }
+    const savedAgents = [...latestAgents.values()].map((saved) => ({
+        id: saved.agentId,
+        revision: saved.revision,
+        title: saved.agent.title,
+        modelProfileId: saved.agent.modelProfileId,
+        agent: saved.agent,
+    }));
+    return { operations, grantableOperations, models, savedAgents };
+}

package/dist/src/runtime/automations/definition-contracts.d.ts

@@ -0,0 +1,128 @@
+import type { ToolNormalInvocationInput } from "../../capabilities/normal-invocation/contracts.js";
+import type { AgentMode } from "../../shared/types.js";
+import type { CapabilityJsonValue } from "../orchestration/capability-adapters/result.js";
+import type { SchedulerScheduleInput } from "../scheduler/contracts.js";
+import type { AutomationLimits } from "./limits.js";
+export type AutomationJsonValue = CapabilityJsonValue;
+export type AutomationOutputSchema = ToolNormalInvocationInput;
+export type AutomationTrigger = Readonly<{
+    kind: "manual";
+}> | Readonly<{
+    kind: "schedule";
+    schedule: SchedulerScheduleInput;
+}> | Readonly<{
+    kind: "folder";
+    checkEveryMs: number;
+    minimumEligibleFiles: number;
+}>;
+export type FolderSource = Readonly<{
+    sourceId: string;
+    location: Readonly<{
+        kind: "runtime_path";
+        path: string;
+    }>;
+    includePatterns: readonly string[];
+    excludePatterns: readonly string[];
+    recursive: boolean;
+    includeExisting: boolean;
+    mode: "per_file" | "batch";
+    maxBatchFiles: number;
+}>;
+export type OperationRef = Readonly<{
+    toolName: string;
+    operationId: string;
+    contractVersion: number;
+}>;
+export type ValueBinding = Readonly<{
+    kind: "literal";
+    value: AutomationJsonValue;
+}> | Readonly<{
+    kind: "run_input";
+    input: string;
+}> | Readonly<{
+    kind: "run_file";
+    fileName: string;
+}> | Readonly<{
+    kind: "source_files";
+}> | Readonly<{
+    kind: "source_file";
+    index: number;
+    field: "snapshot_path" | "original_path" | "version";
+}> | Readonly<{
+    kind: "node_result";
+    nodeId: string;
+    select: "text" | "data";
+    pointer?: string;
+}> | Readonly<{
+    kind: "branch_results";
+    parallelNodeId: string;
+}>;
+export type AutomationNodeBase = Readonly<{
+    id: string;
+    title: string;
+    onFailure: "stop" | "skip";
+}>;
+export type ToolNode = AutomationNodeBase & Readonly<{
+    kind: "tool";
+    operation: OperationRef;
+    controls: Readonly<Record<string, ValueBinding>>;
+    payload?: ValueBinding;
+}>;
+export type AgentNode = AutomationNodeBase & Readonly<{
+    kind: "agent";
+    modelProfileId: string;
+    agentMode: AgentMode;
+    roleInstructions: string;
+    prompt: string;
+    inputs: Readonly<Record<string, ValueBinding>>;
+    tools: readonly Readonly<{
+        operation: OperationRef;
+        usage: "available" | "required";
+    }>[];
+    result: Readonly<{
+        kind: "text";
+    }> | Readonly<{
+        kind: "json";
+        schema: AutomationOutputSchema;
+    }>;
+    acceptance?: readonly Readonly<{
+        field: string;
+        equals: string | number | boolean;
+    }>[];
+    savedAgentOrigin?: Readonly<{
+        agentId: string;
+        revision: number;
+    }>;
+}>;
+export type SequenceNode = Readonly<{
+    kind: "sequence";
+    id: string;
+    children: readonly WorkflowNode[];
+}>;
+export type ParallelNode = Readonly<{
+    kind: "parallel";
+    id: string;
+    branches: readonly SequenceNode[];
+}>;
+export type WorkflowNode = SequenceNode | ParallelNode | AgentNode | ToolNode;
+export type AutomationRevision = Readonly<{
+    schemaVersion: 1;
+    automationId: string;
+    revision: number;
+    title: string;
+    objective: string;
+    workingDirectory?: string;
+    trigger: AutomationTrigger;
+    source?: FolderSource;
+    inputs: Readonly<Record<string, AutomationJsonValue>>;
+    body: SequenceNode;
+    limits: AutomationLimits;
+}>;
+export type SourceFileSnapshot = Readonly<{
+    inputId: string;
+    sourceId: string;
+    originalPath: string;
+    snapshotPath: string;
+    version: string;
+    sizeBytes: number;
+}>;

package/dist/src/runtime/automations/definition-contracts.js

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

package/dist/src/runtime/automations/definition-input.d.ts

@@ -0,0 +1,3 @@
+import type { AutomationRevision } from "./definition-contracts.js";
+/** Parse untrusted editor/authoring JSON before the graph walker touches it. */
+export declare function parseAutomationDefinition(value: unknown): AutomationRevision;