@abot-ai/runtime 1.5.0 → 1.7.0

package/dist/src/runtime/automations/draft-batch-aliases.js

@@ -0,0 +1,94 @@
+export class AutomationDraftBatchError extends Error {
+    code;
+    path;
+    commandPath;
+    constructor(code, path, commandPath) {
+        const boundedPath = path.length <= 240 ? path : `${path.slice(0, 240)}…`;
+        super(`${code}:${boundedPath}`);
+        this.code = code;
+        this.path = boundedPath;
+        if (commandPath !== undefined)
+            this.commandPath = commandPath.length <= 240 ? commandPath : `${commandPath.slice(0, 240)}…`;
+        this.name = "AutomationDraftBatchError";
+    }
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function resolveIdentity(value, aliases, path) {
+    if (typeof value !== "string" || !value.startsWith("$"))
+        return value;
+    const resolved = aliases.get(value.slice(1));
+    if (!resolved)
+        throw new AutomationDraftBatchError("automation_batch_alias_unknown", path);
+    return resolved;
+}
+function resolveBinding(value, aliases, path) {
+    if (!isRecord(value))
+        return value;
+    if (value.kind === "node_result")
+        return { ...value, nodeId: resolveIdentity(value.nodeId, aliases, `${path}.nodeId`) };
+    if (value.kind === "branch_results")
+        return { ...value, parallelNodeId: resolveIdentity(value.parallelNodeId, aliases, `${path}.parallelNodeId`) };
+    return value;
+}
+function resolveNodeBindings(node, aliases, path) {
+    const resolved = { ...node };
+    for (const key of ["controls", "inputs"]) {
+        const bindings = node[key];
+        if (!isRecord(bindings))
+            continue;
+        resolved[key] = Object.fromEntries(Object.entries(bindings).map(([name, binding]) => [name, resolveBinding(binding, aliases, `${path}.${key}.${name}`)]));
+    }
+    if (Object.hasOwn(node, "payload"))
+        resolved.payload = resolveBinding(node.payload, aliases, `${path}.payload`);
+    return resolved;
+}
+/** Only canonical identity slots participate; literal contents remain exact. */
+export function resolveDraftBatchMutation(mutation, aliases, path) {
+    const id = (value, field) => resolveIdentity(value, aliases, `${path}.${field}`);
+    switch (mutation.kind) {
+        case "add_node":
+            return { ...mutation, parentSequenceId: id(mutation.parentSequenceId, "parentSequenceId"),
+                nodeWithoutId: resolveNodeBindings(mutation.nodeWithoutId, aliases, `${path}.nodeWithoutId`) };
+        case "update_node":
+            return { ...mutation, nodeId: id(mutation.nodeId, "nodeId"),
+                patch: resolveNodeBindings(mutation.patch, aliases, `${path}.patch`) };
+        case "remove_node":
+            return { ...mutation, nodeId: id(mutation.nodeId, "nodeId") };
+        case "move_node":
+            return { ...mutation, nodeId: id(mutation.nodeId, "nodeId"),
+                parentSequenceId: id(mutation.parentSequenceId, "parentSequenceId") };
+        case "wrap_parallel":
+            return { ...mutation, nodeIds: mutation.nodeIds.map((nodeId, index) => id(nodeId, `nodeIds.${index}`)) };
+        case "update_definition":
+            return mutation;
+    }
+}
+function graphNodes(node) {
+    if (node.kind === "sequence")
+        return [node, ...node.children.flatMap(graphNodes)];
+    if (node.kind === "parallel")
+        return [node, ...node.branches.flatMap(graphNodes)];
+    return [node];
+}
+export function projectDraftBatchAliases(definition, aliases) {
+    const existingIds = new Set(graphNodes(definition.body).map(({ id }) => id));
+    return Object.fromEntries([...aliases].filter(([, id]) => existingIds.has(id)));
+}
+export function registerDraftBatchAlias(alias, mutation, before, after, aliases, path) {
+    const createsAliasTarget = mutation.kind === "add_node" || mutation.kind === "wrap_parallel";
+    if (!createsAliasTarget)
+        throw new AutomationDraftBatchError("automation_batch_alias_target_invalid", path);
+    const previous = new Set(graphNodes(before.body).map(({ id }) => id));
+    const added = graphNodes(after.body).filter(({ id }) => !previous.has(id));
+    const targetKind = mutation.kind === "wrap_parallel" ? "parallel" : mutation.nodeWithoutId.kind;
+    const target = added.find((node) => node.kind === targetKind);
+    if (!target)
+        throw new AutomationDraftBatchError("automation_batch_alias_target_missing", path);
+    aliases.set(alias, target.id);
+    if (target.kind !== "parallel")
+        return;
+    for (const [index, branch] of target.branches.entries())
+        aliases.set(`${alias}.branch${index + 1}`, branch.id);
+}

package/dist/src/runtime/automations/draft-batch.d.ts

@@ -0,0 +1,29 @@
+import type { AutomationRevision } from "./definition-contracts.js";
+import { type DraftMutation } from "./draft-mutations.js";
+import { type AutomationGraphIssue } from "./graph-validation.js";
+import { AutomationDraftBatchError } from "./draft-batch-aliases.js";
+export { AutomationDraftBatchError } from "./draft-batch-aliases.js";
+export declare const AUTOMATION_DRAFT_BATCH_LIMITS: Readonly<{
+    commands: 32;
+    bytes: number;
+}>;
+type DraftBatchCommand = Readonly<{
+    as?: string;
+    mutation: DraftMutation;
+}>;
+export type AutomationDraftBatch = Readonly<{
+    version: 1;
+    commands: readonly DraftBatchCommand[];
+}>;
+export type AutomationDraftBatchResult = Readonly<{
+    definition: AutomationRevision;
+    aliases: Readonly<Record<string, string>>;
+}>;
+export declare class AutomationDraftBatchGraphError extends AutomationDraftBatchError {
+    readonly issues: readonly AutomationGraphIssue[];
+    readonly omittedIssueCount: number;
+    constructor(issues: readonly AutomationGraphIssue[]);
+}
+export declare function parseAutomationDraftBatch(value: unknown): AutomationDraftBatch;
+/** No journal writes occur here; empty roots remain editable drafts, never executable graphs. */
+export declare function applyAutomationDraftBatch(current: AutomationRevision, plan: AutomationDraftBatch, revision: number): AutomationDraftBatchResult;

package/dist/src/runtime/automations/draft-batch.js

@@ -0,0 +1,147 @@
+import { parseAutomationDefinition } from "./definition-input.js";
+import { applyDraftMutation, parseDraftMutation } from "./draft-mutations.js";
+import { compileAutomationGraph } from "./graph-validation.js";
+import { AutomationDraftBatchError, projectDraftBatchAliases, registerDraftBatchAlias, resolveDraftBatchMutation } from "./draft-batch-aliases.js";
+export { AutomationDraftBatchError } from "./draft-batch-aliases.js";
+export const AUTOMATION_DRAFT_BATCH_LIMITS = Object.freeze({ commands: 32, bytes: 32 * 1024 });
+export class AutomationDraftBatchGraphError extends AutomationDraftBatchError {
+    issues;
+    omittedIssueCount;
+    constructor(issues) {
+        super(issues[0].code, issues[0].path);
+        this.issues = issues.slice(0, 8);
+        this.omittedIssueCount = Math.max(0, issues.length - this.issues.length);
+    }
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function requireRecord(value, path) {
+    if (!isRecord(value))
+        throw new AutomationDraftBatchError("automation_batch_invalid", path);
+    return value;
+}
+function requireKnownFields(record, fields, path) {
+    const unknown = Object.keys(record).find((key) => !fields.includes(key));
+    if (unknown !== undefined)
+        throw new AutomationDraftBatchError("automation_batch_field_unknown", `${path}.${unknown}`);
+}
+const MUTATION_FIELDS = {
+    add_node: ["kind", "parentSequenceId", "index", "nodeWithoutId"],
+    update_node: ["kind", "nodeId", "patch"],
+    remove_node: ["kind", "nodeId"],
+    move_node: ["kind", "nodeId", "parentSequenceId", "index"],
+    wrap_parallel: ["kind", "nodeIds"],
+    update_definition: ["kind", "patch"],
+};
+function isKnownMutationKind(value) {
+    if (typeof value !== "string")
+        return false;
+    return Object.hasOwn(MUTATION_FIELDS, value);
+}
+function requireMutationFields(input, fields, path) {
+    const missing = fields.find((field) => !Object.hasOwn(input, field));
+    if (missing !== undefined)
+        throw new AutomationDraftBatchError("automation_batch_field_required", `${path}.${missing}`);
+}
+function parseBatchMutation(value, path) {
+    const input = requireRecord(value, path);
+    requireMutationFields(input, ["kind"], path);
+    if (!isKnownMutationKind(input.kind))
+        throw new AutomationDraftBatchError("automation_batch_mutation_kind_invalid", `${path}.kind`);
+    const fields = MUTATION_FIELDS[input.kind];
+    requireMutationFields(input, fields, path);
+    requireKnownFields(input, fields, path);
+    return withMutationPath(path, () => parseDraftMutation(input));
+}
+function snapshotBatchInput(value) {
+    let serialized;
+    try {
+        serialized = JSON.stringify(value);
+    }
+    catch {
+        throw new AutomationDraftBatchError("automation_batch_invalid", "plan");
+    }
+    if (serialized === undefined)
+        throw new AutomationDraftBatchError("automation_batch_invalid", "plan");
+    if (Buffer.byteLength(serialized, "utf8") > AUTOMATION_DRAFT_BATCH_LIMITS.bytes)
+        throw new AutomationDraftBatchError("automation_batch_too_large", "plan");
+    return JSON.parse(serialized);
+}
+function requireAlias(value, mutation, path, seen) {
+    const isValidAlias = typeof value === "string" && /^[A-Za-z][A-Za-z0-9_-]{0,47}$/u.test(value);
+    if (!isValidAlias || value === "root")
+        throw new AutomationDraftBatchError("automation_batch_alias_invalid", path);
+    if (seen.has(value))
+        throw new AutomationDraftBatchError("automation_batch_alias_duplicate", path);
+    const createsAliasTarget = mutation.kind === "add_node" || mutation.kind === "wrap_parallel";
+    if (!createsAliasTarget)
+        throw new AutomationDraftBatchError("automation_batch_alias_target_invalid", path);
+    seen.add(value);
+    return value;
+}
+function withMutationPath(path, execute) {
+    try {
+        return execute();
+    }
+    catch (error) {
+        if (error instanceof AutomationDraftBatchError)
+            throw error;
+        const definitionIssuePath = error instanceof Error
+            ? /^automation_graph_invalid: (.+)$/u.exec(error.message)?.[1] : undefined;
+        if (definitionIssuePath)
+            throw new AutomationDraftBatchError("automation_graph_invalid", definitionIssuePath, path);
+        const code = error instanceof Error && /^automation_[a-z_]+$/u.test(error.message)
+            ? error.message : "automation_batch_invalid";
+        throw new AutomationDraftBatchError(code, path);
+    }
+}
+export function parseAutomationDraftBatch(value) {
+    const input = requireRecord(snapshotBatchInput(value), "plan");
+    requireKnownFields(input, ["version", "commands"], "plan");
+    if (input.version !== 1)
+        throw new AutomationDraftBatchError("automation_batch_version_invalid", "plan.version");
+    const hasBoundedCommands = Array.isArray(input.commands) && input.commands.length >= 1 &&
+        input.commands.length <= AUTOMATION_DRAFT_BATCH_LIMITS.commands;
+    if (!hasBoundedCommands)
+        throw new AutomationDraftBatchError("automation_batch_commands_invalid", "plan.commands");
+    const aliases = new Set();
+    const commands = input.commands.map((value, index) => {
+        const path = `plan.commands.${index}`;
+        const command = requireRecord(value, path);
+        requireKnownFields(command, ["as", "mutation"], path);
+        const mutation = parseBatchMutation(command.mutation, `${path}.mutation`);
+        if (!Object.hasOwn(command, "as"))
+            return { mutation };
+        return { mutation, as: requireAlias(command.as, mutation, `${path}.as`, aliases) };
+    });
+    return { version: 1, commands };
+}
+function isPermittedEmptyDraft(definition, issues) {
+    if (definition.body.children.length !== 0)
+        return false;
+    if (issues.length !== 1)
+        return false;
+    return issues[0].code === "automation_graph_empty";
+}
+/** No journal writes occur here; empty roots remain editable drafts, never executable graphs. */
+export function applyAutomationDraftBatch(current, plan, revision) {
+    const aliases = new Map([["root", current.body.id]]);
+    let definition = current;
+    for (const [index, command] of plan.commands.entries()) {
+        const path = `plan.commands.${index}`;
+        const mutation = resolveDraftBatchMutation(command.mutation, aliases, `${path}.mutation`);
+        const previous = definition;
+        definition = withMutationPath(`${path}.mutation`, () => applyDraftMutation({ ...definition, revision: current.revision }, mutation));
+        if (command.as)
+            registerDraftBatchAlias(command.as, mutation, previous, definition, aliases, `${path}.as`);
+    }
+    definition = withMutationPath("plan", () => parseAutomationDefinition({ ...definition, revision }));
+    const compiled = compileAutomationGraph(definition);
+    const result = { definition, aliases: projectDraftBatchAliases(definition, aliases) };
+    if (compiled.ok)
+        return result;
+    if (isPermittedEmptyDraft(definition, compiled.issues))
+        return result;
+    throw new AutomationDraftBatchGraphError(compiled.issues);
+}

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

@@ -0,0 +1,53 @@
+import type { AutomationRevision } from "./definition-contracts.js";
+import type { AutomationDraftRecord } from "./storage-records.js";
+import type { AutomationPersistence } from "./persistence.js";
+export type AutomationDraftSummary = Readonly<{
+    id: string;
+    title: string;
+    draftRevision: number;
+    updatedAt: string;
+    publishedRevision?: number;
+    status: "draft" | "paused" | "active" | "archived";
+}>;
+export type AutomationDraftPlanResult = Readonly<{
+    draft: AutomationDraftRecord;
+    aliases: Readonly<Record<string, string>>;
+}>;
+/** Owner-local synchronous admission only; remote service calls omit this callback. */
+export type AutomationDraftPlanAcceptance = (result: AutomationDraftPlanResult) => true;
+export declare function createAutomationDraftManager(options: {
+    persistence: AutomationPersistence;
+    now?: () => number;
+}): {
+    list: () => Promise<AutomationDraftSummary[]>;
+    create: (title: string, buildDefinition?: (empty: AutomationRevision) => AutomationRevision) => Promise<AutomationDraftRecord>;
+    createPlan: (title: string, value: unknown, accept?: AutomationDraftPlanAcceptance) => Promise<{
+        draft: Readonly<{
+            id: string;
+            automationId: string;
+            revision: number;
+            definition: AutomationRevision;
+            updatedAt: string;
+            archivedAt?: string;
+            storageRevision?: number;
+        }>;
+        aliases: Readonly<Record<string, string>>;
+    }>;
+    applyPlan: (automationId: string, expectedRevision: number, value: unknown, accept?: AutomationDraftPlanAcceptance) => Promise<{
+        draft: Readonly<{
+            id: string;
+            automationId: string;
+            revision: number;
+            definition: AutomationRevision;
+            updatedAt: string;
+            archivedAt?: string;
+            storageRevision?: number;
+        }>;
+        aliases: Readonly<Record<string, string>>;
+    }>;
+    get: (automationId: string) => Promise<AutomationDraftRecord | null>;
+    deleteUnpublishedDraft: (automationId: string, expectedRevision: number) => Promise<void>;
+    update: (automationId: string, expectedRevision: number, mutation: unknown) => Promise<AutomationDraftRecord>;
+    validate: (automationId: string) => Promise<import("./graph-validation.js").AutomationGraphCompilation>;
+};
+export type AutomationDraftManager = ReturnType<typeof createAutomationDraftManager>;

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

@@ -0,0 +1,164 @@
+import { randomUUID } from "node:crypto";
+import { requireUnarchivedAutomation } from "./archive-management.js";
+import { createEmptyAutomationDefinition, applyDraftMutation, parseDraftMutation } from "./draft-mutations.js";
+import { compileAutomationGraph } from "./graph-validation.js";
+import { applyAutomationDraftBatch, parseAutomationDraftBatch } from "./draft-batch.js";
+import { readPublishedDraftRestoration, restorePublishedAutomationDraft } from "./draft-restoration.js";
+function isSupportedDraftPlanAcceptance(value) {
+    if (value === undefined)
+        return true;
+    return typeof value === "function";
+}
+function requireDraftPlanAcceptance(result, accept) {
+    if (accept === undefined)
+        return;
+    if (accept(result) !== true)
+        throw new Error("automation_draft_plan_acceptance_invalid");
+}
+function draftStatus(draft, publishedRevision) {
+    if (draft.archivedAt)
+        return "archived";
+    return publishedRevision > 0 ? "paused" : "draft";
+}
+function hasPublishedAutomation(scheduler, state, automationId) {
+    if (state.definitions.some((item) => item.automationId === automationId))
+        return true;
+    return scheduler.jobs.some((job) => job.target?.kind === "automation" &&
+        job.target.automationId === automationId);
+}
+export function createAutomationDraftManager(options) {
+    const now = options.now ?? Date.now;
+    async function list() {
+        const state = await options.persistence.read();
+        return state.drafts
+            .map((draft) => {
+            const publishedRevision = state.definitions
+                .filter((item) => item.automationId === draft.automationId)
+                .reduce((latest, item) => Math.max(latest, item.revision), 0);
+            return {
+                id: draft.automationId,
+                title: draft.definition.title,
+                draftRevision: draft.revision,
+                updatedAt: draft.updatedAt,
+                ...(publishedRevision > 0 ? { publishedRevision } : {}),
+                status: draftStatus(draft, publishedRevision),
+            };
+        })
+            .sort((left, right) => left.title.localeCompare(right.title));
+    }
+    async function create(title, buildDefinition) {
+        return createWithAcceptance(title, buildDefinition);
+    }
+    async function createWithAcceptance(title, buildDefinition, acceptDraft) {
+        const cleanTitle = title.trim();
+        if (!cleanTitle || cleanTitle.length > 160)
+            throw new Error("automation_title_invalid");
+        const automationId = randomUUID();
+        const empty = createEmptyAutomationDefinition(automationId, cleanTitle);
+        const draft = {
+            id: `draft:${automationId}`,
+            automationId,
+            revision: 1,
+            definition: buildDefinition ? buildDefinition(empty) : empty,
+            updatedAt: new Date(now()).toISOString(),
+        };
+        return options.persistence.update((state) => {
+            acceptDraft?.(draft);
+            state.drafts.push(draft);
+            return draft;
+        });
+    }
+    async function get(automationId) {
+        const state = await options.persistence.read();
+        return state.drafts.find((item) => item.automationId === automationId) ?? null;
+    }
+    async function createPlan(title, value, accept) {
+        if (!isSupportedDraftPlanAcceptance(accept))
+            throw new Error("automation_draft_plan_acceptance_invalid");
+        const plan = parseAutomationDraftBatch(value);
+        let aliases = {};
+        const draft = await createWithAcceptance(title, (empty) => {
+            const built = applyAutomationDraftBatch(empty, plan, 1);
+            aliases = built.aliases;
+            return built.definition;
+        }, (candidate) => requireDraftPlanAcceptance({ draft: candidate, aliases }, accept));
+        return { draft, aliases };
+    }
+    async function applyPlan(automationId, expectedRevision, value, accept) {
+        if (!isSupportedDraftPlanAcceptance(accept))
+            throw new Error("automation_draft_plan_acceptance_invalid");
+        if (!Number.isSafeInteger(expectedRevision) || expectedRevision < 1)
+            throw new Error("automation_revision_conflict");
+        const plan = parseAutomationDraftBatch(value);
+        return options.persistence.update((state) => {
+            const index = state.drafts.findIndex((item) => item.automationId === automationId);
+            if (index < 0)
+                throw new Error("automation_not_found");
+            const current = state.drafts[index];
+            requireUnarchivedAutomation(state, automationId);
+            if (current.revision !== expectedRevision)
+                throw new Error("automation_revision_conflict");
+            const built = applyAutomationDraftBatch(current.definition, plan, current.revision + 1);
+            const draft = {
+                ...current, definition: built.definition, revision: built.definition.revision,
+                storageRevision: (current.storageRevision ?? current.revision) + 1,
+                updatedAt: new Date(now()).toISOString(),
+            };
+            const result = { draft, aliases: built.aliases };
+            requireDraftPlanAcceptance(result, accept);
+            state.drafts[index] = draft;
+            return result;
+        });
+    }
+    async function deleteUnpublishedDraft(automationId, expectedRevision) {
+        if (!Number.isSafeInteger(expectedRevision) || expectedRevision < 1)
+            throw new Error("automation_revision_conflict");
+        await options.persistence.updateWithScheduler((scheduler, state) => {
+            const index = state.drafts.findIndex((item) => item.automationId === automationId);
+            if (index < 0)
+                throw new Error("automation_not_found");
+            if (state.drafts[index].revision !== expectedRevision)
+                throw new Error("automation_revision_conflict");
+            if (hasPublishedAutomation(scheduler, state, automationId))
+                throw new Error("automation_draft_published");
+            state.drafts.splice(index, 1);
+            state.grants = state.grants.filter((item) => item.automationId !== automationId);
+        });
+    }
+    async function update(automationId, expectedRevision, mutation) {
+        if (!Number.isSafeInteger(expectedRevision) || expectedRevision < 1)
+            throw new Error("automation_revision_conflict");
+        const publishedRevision = readPublishedDraftRestoration(mutation);
+        if (publishedRevision !== null)
+            return restorePublishedAutomationDraft({
+                persistence: options.persistence, automationId, expectedRevision, publishedRevision, now,
+            });
+        const parsed = parseDraftMutation(mutation);
+        return options.persistence.update((state) => {
+            const index = state.drafts.findIndex((item) => item.automationId === automationId);
+            if (index < 0)
+                throw new Error("automation_not_found");
+            const current = state.drafts[index];
+            requireUnarchivedAutomation(state, automationId);
+            if (current.revision !== expectedRevision)
+                throw new Error("automation_revision_conflict");
+            const definition = applyDraftMutation(current.definition, parsed);
+            const next = {
+                ...current,
+                revision: definition.revision,
+                storageRevision: (current.storageRevision ?? current.revision) + 1,
+                definition,
+                updatedAt: new Date(now()).toISOString(),
+            };
+            state.drafts[index] = next;
+            return next;
+        });
+    }
+    async function validate(automationId) {
+        const draft = await get(automationId);
+        if (!draft)
+            throw new Error("automation_not_found");
+        return compileAutomationGraph(draft.definition);
+    }
+    return { list, create, createPlan, applyPlan, get, deleteUnpublishedDraft, update, validate };
+}

package/dist/src/runtime/automations/draft-mutations.d.ts

@@ -0,0 +1,29 @@
+import type { AutomationRevision } from "./definition-contracts.js";
+export type DraftMutation = Readonly<{
+    kind: "add_node";
+    parentSequenceId: string;
+    index: number;
+    nodeWithoutId: Record<string, unknown>;
+}> | Readonly<{
+    kind: "update_node";
+    nodeId: string;
+    patch: Record<string, unknown>;
+}> | Readonly<{
+    kind: "remove_node";
+    nodeId: string;
+}> | Readonly<{
+    kind: "move_node";
+    nodeId: string;
+    parentSequenceId: string;
+    index: number;
+}> | Readonly<{
+    kind: "wrap_parallel";
+    nodeIds: readonly string[];
+}> | Readonly<{
+    kind: "update_definition";
+    patch: Record<string, unknown>;
+}>;
+export declare function parseDraftMutation(value: unknown): DraftMutation;
+/** A single structural mutation path for manual edits and model-authored edits. */
+export declare function applyDraftMutation(current: AutomationRevision, mutation: DraftMutation): AutomationRevision;
+export declare function createEmptyAutomationDefinition(automationId: string, title: string): AutomationRevision;