@abot-ai/runtime 1.5.0 → 1.7.0

package/dist/src/runtime/automations/snapshot-staging.js

@@ -0,0 +1,126 @@
+import { mkdir, readdir, readFile, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { syncJournalDirectory, syncJournalDirectoryPath, writeJournalJson } from "../scheduler/journal-durability.js";
+const MAX_STAGED_CLEANUP = 64;
+const MARKER_KIND = "automation_snapshot_preparation_v1";
+const SAFE_OWNER = /^[A-Za-z0-9_-][A-Za-z0-9._-]*$/u;
+function requireSnapshotOwner(runId) {
+    if (!SAFE_OWNER.test(runId))
+        throw new Error("automation_snapshot_owner_invalid");
+}
+function hasCommittedSnapshotOwner(state, runId) {
+    if (state.executions.some((execution) => execution.id === runId))
+        return true;
+    return state.inputs.some((record) => record.snapshot?.attachment.storageRef.split(/[\\/]/u)[0] === runId);
+}
+/** Only explicit durable preparation markers authorize orphan cleanup in the shared attachment store. */
+export function createAutomationSnapshotStaging(options) {
+    const directory = join(options.runtimeDir, "automation-snapshot-preparations");
+    const active = new Set();
+    let reconciliation;
+    async function removeMarker(runId) {
+        await rm(join(directory, `${runId}.json`), { force: true });
+        await syncJournalDirectory(directory);
+    }
+    async function begin(runId) {
+        requireSnapshotOwner(runId);
+        if (active.has(runId))
+            throw new Error("automation_snapshot_preparation_active");
+        active.add(runId);
+        try {
+            await mkdir(directory, { recursive: true, mode: 0o700 });
+            await syncJournalDirectoryPath(directory);
+            await writeJournalJson(join(directory, `${runId}.json`), { kind: MARKER_KIND, runId });
+        }
+        catch (error) {
+            active.delete(runId);
+            throw error;
+        }
+    }
+    async function discard(runId) {
+        requireSnapshotOwner(runId);
+        try {
+            // Keep the active owner until an older reconciliation has finished with
+            // its pre-claim journal snapshot. New readers observe the settled claim.
+            await reconciliation?.catch(() => undefined);
+            const state = await options.persistence.read().catch(() => undefined);
+            // A publication sync failure may hide a committed claim from this process.
+            // Preserve its marker and bytes for recovery instead of masking that error.
+            if (!state)
+                return;
+            const committed = hasCommittedSnapshotOwner(state, runId);
+            if (!committed)
+                await options.attachments.deleteSessionAttachments(runId);
+            // begin may have failed before creating the marker directory.
+            await removeMarker(runId).catch((error) => {
+                if (error.code !== "ENOENT")
+                    throw error;
+            });
+        }
+        finally {
+            active.delete(runId);
+        }
+    }
+    async function discardAbandonedMarkerWrite(name) {
+        const temporary = /^([A-Za-z0-9_-][A-Za-z0-9._-]*)\.json\.[0-9a-f-]{36}\.tmp$/u.exec(name);
+        if (!temporary)
+            return false;
+        if (active.has(temporary[1]))
+            return false;
+        await rm(join(directory, name), { force: true });
+        return true;
+    }
+    async function reconcileMarkers() {
+        const entries = await readdir(directory, { withFileTypes: true }).catch((error) => {
+            if (error.code === "ENOENT")
+                return [];
+            throw error;
+        });
+        if (!entries.length)
+            return;
+        const state = await options.persistence.read();
+        let cleaned = 0;
+        for (const entry of entries) {
+            if (cleaned === MAX_STAGED_CLEANUP)
+                break;
+            if (!entry.isFile())
+                continue;
+            const discardedTemporary = await discardAbandonedMarkerWrite(entry.name);
+            if (discardedTemporary) {
+                cleaned += 1;
+                continue;
+            }
+            if (!entry.name.endsWith(".json"))
+                continue;
+            const runId = entry.name.slice(0, -5);
+            requireSnapshotOwner(runId);
+            const content = await readFile(join(directory, entry.name), "utf8").catch((error) => {
+                if (error.code === "ENOENT")
+                    return undefined;
+                throw error;
+            });
+            if (content === undefined)
+                continue;
+            const marker = JSON.parse(content);
+            const isOwnedMarker = marker?.kind === MARKER_KIND && marker.runId === runId;
+            if (!isOwnedMarker)
+                throw new Error("automation_snapshot_marker_invalid");
+            const committed = hasCommittedSnapshotOwner(state, runId);
+            const preparationStillActive = !committed && active.has(runId);
+            if (preparationStillActive)
+                continue;
+            if (!committed)
+                await options.attachments.deleteSessionAttachments(runId);
+            await removeMarker(runId);
+            active.delete(runId);
+            cleaned += 1;
+        }
+    }
+    function reconcile() {
+        if (reconciliation)
+            return reconciliation;
+        reconciliation = reconcileMarkers().finally(() => { reconciliation = undefined; });
+        return reconciliation;
+    }
+    return { begin, discard, reconcile };
+}

package/dist/src/runtime/automations/source-attachment-access.d.ts

@@ -0,0 +1,23 @@
+import type { ToolRequestAttachment } from "../../capabilities/tool-types.js";
+import type { AgentNode, OperationRef, SourceFileSnapshot, ToolNode, ValueBinding } from "./definition-contracts.js";
+type AttachmentInput = Readonly<{
+    param: string;
+    acceptedMimeTypes: readonly string[];
+    mode?: Readonly<{
+        param: string;
+        value: string;
+    }>;
+}>;
+export type AttachmentInputOperation = OperationRef & Readonly<{
+    attachmentInput?: AttachmentInput;
+}>;
+export declare function usesSourceFileContents(binding: ValueBinding): boolean;
+export declare function sourceAttachmentIssue(node: AgentNode | ToolNode, operations: readonly AttachmentInputOperation[]): string | null;
+/** Exposes only the frozen inputs selected by this node, under the exact source aliases it receives. */
+export declare function sourceAttachmentsForNode(input: {
+    node: AgentNode | ToolNode;
+    sourceFiles: readonly SourceFileSnapshot[];
+    sourceAttachments: readonly ToolRequestAttachment[];
+    operations: readonly AttachmentInputOperation[];
+}): readonly ToolRequestAttachment[];
+export {};

package/dist/src/runtime/automations/source-attachment-access.js

@@ -0,0 +1,70 @@
+function matchesOperation(left, right) {
+    return left.toolName === right.toolName && left.operationId === right.operationId &&
+        left.contractVersion === right.contractVersion;
+}
+function selectedAttachmentInputs(node, operations) {
+    const selected = node.kind === "agent" ? node.tools.map((item) => item.operation) : [node.operation];
+    return selected.flatMap((operation) => {
+        const capability = operations.find((item) => matchesOperation(item, operation))?.attachmentInput;
+        return capability ? [capability] : [];
+    });
+}
+export function usesSourceFileContents(binding) {
+    return binding.kind === "source_files" ||
+        (binding.kind === "source_file" && binding.field === "snapshot_path");
+}
+export function sourceAttachmentIssue(node, operations) {
+    if (node.kind === "agent") {
+        const needsSourceReader = Object.values(node.inputs).some(usesSourceFileContents);
+        return needsSourceReader && selectedAttachmentInputs(node, operations).length === 0
+            ? "automation_source_reader_unavailable" : null;
+    }
+    const snapshotControls = Object.entries(node.controls).filter(([, binding]) => usesSourceFileContents(binding));
+    if (!snapshotControls.length && !node.payload)
+        return null;
+    if (node.payload && usesSourceFileContents(node.payload))
+        return "automation_source_reader_unavailable";
+    if (!snapshotControls.length)
+        return null;
+    const capability = selectedAttachmentInputs(node, operations)[0];
+    if (!capability || snapshotControls.length !== 1 ||
+        snapshotControls[0][0] !== capability.param)
+        return "automation_source_reader_unavailable";
+    const mode = capability.mode && node.controls[capability.mode.param];
+    return mode && (mode.kind !== "literal" || mode.value !== capability.mode?.value)
+        ? "automation_source_reader_unavailable" : null;
+}
+/** Exposes only the frozen inputs selected by this node, under the exact source aliases it receives. */
+export function sourceAttachmentsForNode(input) {
+    const { node } = input;
+    const bindings = node.kind === "agent" ? Object.values(node.inputs)
+        : [...Object.values(node.controls), ...(node.payload ? [node.payload] : [])];
+    const selected = new Set();
+    for (const binding of bindings) {
+        if (binding.kind === "source_files")
+            input.sourceFiles.forEach((_file, index) => selected.add(index));
+        else if (binding.kind === "source_file" && usesSourceFileContents(binding))
+            selected.add(binding.index);
+    }
+    if (!selected.size)
+        return [];
+    const issue = sourceAttachmentIssue(node, input.operations);
+    if (issue)
+        throw new Error(issue);
+    const accepted = selectedAttachmentInputs(node, input.operations);
+    const handles = [...selected].map((index) => {
+        const attachment = input.sourceAttachments[index];
+        const file = input.sourceFiles[index];
+        if (!attachment || !file)
+            throw new Error("automation_dependency_missing");
+        if (attachment.kind !== "file" || !accepted.some((capability) => capability.acceptedMimeTypes.includes(attachment.mimeType)))
+            throw new Error("automation_source_type_unsupported");
+        return { attachment, file };
+    });
+    if (node.kind === "tool")
+        return handles.map(({ attachment, file }) => ({ ...attachment, id: file.snapshotPath }));
+    return handles.flatMap(({ attachment, file }) => [
+        attachment,
+        { ...attachment, id: file.snapshotPath, name: undefined },
+    ]);
+}

package/dist/src/runtime/automations/source-discovery.d.ts

@@ -0,0 +1,25 @@
+import type { RuntimePaths } from "../ports.js";
+import type { FolderSource } from "./definition-contracts.js";
+export type DiscoveredSourceFile = Readonly<{
+    canonicalPath: string;
+    relativePath: string;
+    sizeBytes: number;
+    mtimeMs: number;
+    ctimeMs: number;
+    kind: "image" | "file";
+    mimeType: string;
+}>;
+export type CapturedSourceFile = DiscoveredSourceFile & Readonly<{
+    bytes: Uint8Array;
+    contentVersion: string;
+}>;
+export declare function discoverSourceFiles(input: {
+    source: FolderSource;
+    paths: RuntimePaths;
+    now?: number;
+}): Promise<{
+    root: string;
+    files: DiscoveredSourceFile[];
+    unstableCount: number;
+}>;
+export declare function captureSourceFile(file: DiscoveredSourceFile): Promise<CapturedSourceFile>;

package/dist/src/runtime/automations/source-discovery.js

@@ -0,0 +1,179 @@
+import { constants } from "node:fs";
+import { createHash } from "node:crypto";
+import { lstat, open, readdir, realpath, stat } from "node:fs/promises";
+import { basename, extname, join, relative, resolve, sep } from "node:path";
+import { createRuntimeToolPathResolver } from "../capabilities/runtime-target-path.js";
+const MAX_SOURCE_ENTRIES = 1_000;
+const MAX_SOURCE_FILE_BYTES = 10 * 1024 * 1024;
+const MIN_STABLE_AGE_MS = 1_000;
+const SUPPORTED_MIME = new Map([
+    [".png", { kind: "image", mimeType: "image/png" }],
+    [".jpg", { kind: "image", mimeType: "image/jpeg" }],
+    [".jpeg", { kind: "image", mimeType: "image/jpeg" }],
+    [".webp", { kind: "image", mimeType: "image/webp" }],
+    [".pdf", { kind: "file", mimeType: "application/pdf" }],
+    [".docx", { kind: "file", mimeType: "application/vnd.openxmlformats-officedocument.wordprocessingml.document" }],
+    [".xlsx", { kind: "file", mimeType: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" }],
+    [".pptx", { kind: "file", mimeType: "application/vnd.openxmlformats-officedocument.presentationml.presentation" }],
+    [".txt", { kind: "file", mimeType: "text/plain" }],
+    [".csv", { kind: "file", mimeType: "text/csv" }],
+    [".md", { kind: "file", mimeType: "text/markdown" }],
+    [".json", { kind: "file", mimeType: "application/json" }],
+    [".rtf", { kind: "file", mimeType: "application/rtf" }],
+]);
+function within(path, root) {
+    const scoped = relative(root, path);
+    return scoped === "" || (scoped !== ".." && !scoped.startsWith(`..${sep}`));
+}
+function glob(pattern) {
+    let expression = "^";
+    for (let index = 0; index < pattern.length; index += 1) {
+        const char = pattern[index];
+        if (char === "*") {
+            if (pattern[index + 1] === "*") {
+                if (pattern[index + 2] === "/") {
+                    expression += "(?:.*/)?";
+                    index += 2;
+                }
+                else {
+                    expression += ".*";
+                    index += 1;
+                }
+            }
+            else
+                expression += "[^/]*";
+            continue;
+        }
+        if (char === "?") {
+            expression += "[^/]";
+            continue;
+        }
+        expression += /[\\^$+?.()|{}\[\]]/u.test(char) ? `\\${char}` : char;
+    }
+    return new RegExp(`${expression}$`, "u");
+}
+function matches(relativePath, patterns) {
+    return patterns.some((pattern) => pattern.test(relativePath) || pattern.test(basename(relativePath)));
+}
+export async function discoverSourceFiles(input) {
+    const resolver = createRuntimeToolPathResolver(input.paths);
+    const resolved = resolver.resolve(input.source.location.path, {
+        requirePath: true,
+        allowedLocations: ["agent_work", "workspace", "host_system"],
+    });
+    const root = await realpath(resolved.absolutePath);
+    const rootStat = await stat(root);
+    if (!rootStat.isDirectory())
+        throw new Error("automation_source_unavailable");
+    const excludedRoots = [input.paths.attachmentsDir,
+        join(input.paths.runtimeDir, "automation-results")].map((path) => resolve(path));
+    if (excludedRoots.some((excluded) => within(root, excluded)))
+        throw new Error("automation_source_unavailable");
+    const includes = input.source.includePatterns.map(glob);
+    const excludes = input.source.excludePatterns.map(glob);
+    const now = input.now ?? Date.now();
+    const files = [];
+    let unstableCount = 0;
+    const directories = [root];
+    let visited = 0;
+    while (directories.length > 0) {
+        const directory = directories.pop();
+        for (const entry of await readdir(directory, { withFileTypes: true })) {
+            visited += 1;
+            if (visited > MAX_SOURCE_ENTRIES)
+                throw new Error("automation_source_capacity_exceeded");
+            const candidate = join(directory, entry.name);
+            if (entry.isSymbolicLink())
+                continue;
+            const canonical = await realpath(candidate).catch(() => null);
+            if (!canonical || !within(canonical, root))
+                continue;
+            if (excludedRoots.some((excluded) => within(canonical, excluded)))
+                continue;
+            const relativePath = relative(root, canonical).replaceAll(sep, "/");
+            if (matches(relativePath, excludes) ||
+                (entry.isDirectory() && matches(`${relativePath}/`, excludes)))
+                continue;
+            if (entry.isDirectory()) {
+                if (input.source.recursive)
+                    directories.push(canonical);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            if (includes.length > 0 && !matches(relativePath, includes))
+                continue;
+            const metadata = await lstat(canonical);
+            if (!metadata.isFile())
+                continue;
+            if (now - metadata.mtimeMs < MIN_STABLE_AGE_MS) {
+                unstableCount += 1;
+                continue;
+            }
+            const supported = SUPPORTED_MIME.get(extname(canonical).toLowerCase());
+            if (!supported || metadata.size > MAX_SOURCE_FILE_BYTES)
+                throw new Error("automation_source_unavailable");
+            files.push({
+                canonicalPath: canonical,
+                relativePath,
+                sizeBytes: metadata.size,
+                mtimeMs: metadata.mtimeMs,
+                ctimeMs: metadata.ctimeMs,
+                ...supported,
+            });
+        }
+    }
+    files.sort((left, right) => left.canonicalPath.localeCompare(right.canonicalPath));
+    return { root, files, unstableCount };
+}
+export async function captureSourceFile(file) {
+    try {
+        return await readStableSourceFile(file);
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error &&
+            ["ENOENT", "ENOTDIR", "ELOOP"].includes(String(error.code)))
+            throw new Error("automation_source_changed", { cause: error });
+        throw error;
+    }
+}
+async function readStableSourceFile(file) {
+    if (await realpath(file.canonicalPath) !== file.canonicalPath)
+        throw new Error("automation_source_changed");
+    const handle = await open(file.canonicalPath, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+        const before = await handle.stat();
+        if (!before.isFile() || before.size > MAX_SOURCE_FILE_BYTES ||
+            before.size !== file.sizeBytes || before.mtimeMs !== file.mtimeMs ||
+            before.ctimeMs !== file.ctimeMs)
+            throw new Error("automation_source_changed");
+        const buffer = Buffer.alloc(before.size + 1);
+        let offset = 0;
+        while (offset < buffer.length) {
+            const { bytesRead } = await handle.read(buffer, offset, buffer.length - offset, offset);
+            if (bytesRead === 0)
+                break;
+            offset += bytesRead;
+        }
+        const after = await handle.stat();
+        const pathAfter = await lstat(file.canonicalPath);
+        const canonicalAfter = await realpath(file.canonicalPath);
+        if (offset !== before.size || after.size !== before.size ||
+            canonicalAfter !== file.canonicalPath ||
+            after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs ||
+            pathAfter.ino !== before.ino || pathAfter.dev !== before.dev ||
+            pathAfter.size !== before.size ||
+            pathAfter.mtimeMs !== before.mtimeMs ||
+            pathAfter.ctimeMs !== before.ctimeMs)
+            throw new Error("automation_source_changed");
+        const bytes = buffer.subarray(0, offset);
+        return {
+            ...file,
+            bytes,
+            contentVersion: createHash("sha256").update(bytes).digest("hex"),
+        };
+    }
+    finally {
+        await handle.close();
+    }
+}

package/dist/src/runtime/automations/starter-template-builder.d.ts

@@ -0,0 +1,5 @@
+import type { AutomationCatalogOperation } from "./catalog.js";
+import type { AutomationRevision } from "./definition-contracts.js";
+import type { AutomationStarter, StarterToolStep } from "./starter-template-contracts.js";
+/** Materialize recipes into the existing graph contract; branch-local results stay local until the join. */
+export declare function buildStarterDefinition(starter: AutomationStarter, base: AutomationRevision, selectOperation: (step: StarterToolStep) => AutomationCatalogOperation | undefined): AutomationRevision;

package/dist/src/runtime/automations/starter-template-builder.js

@@ -0,0 +1,78 @@
+import { randomUUID } from "node:crypto";
+import { parseAutomationDefinition } from "./definition-input.js";
+function nodeId() {
+    return `n_${randomUUID().replaceAll("-", "")}`;
+}
+function requiredResultId(key, ids) {
+    const id = ids.get(key);
+    if (!id)
+        throw new Error("automation_template_invalid");
+    return id;
+}
+function earlierStepText(key, scope) {
+    return { kind: "node_result", nodeId: requiredResultId(key, scope.nodes), select: "text" };
+}
+function runInputBinding(starter, key) {
+    if (!Object.hasOwn(starter.inputs ?? {}, key))
+        throw new Error("automation_template_invalid");
+    return { kind: "run_input", input: key };
+}
+/** Materialize recipes into the existing graph contract; branch-local results stay local until the join. */
+export function buildStarterDefinition(starter, base, selectOperation) {
+    const keys = new Set();
+    function reserveKey(key) {
+        if (keys.has(key))
+            throw new Error("automation_template_invalid");
+        keys.add(key);
+        return nodeId();
+    }
+    function buildSequence(steps, scope) {
+        return { kind: "sequence", id: nodeId(), children: steps.map((step) => buildStep(step, scope)) };
+    }
+    function buildStep(step, scope) {
+        const id = reserveKey(step.key);
+        if (step.kind === "parallel") {
+            const branches = step.branches.map((steps) => {
+                const branchScope = { nodes: new Map(scope.nodes), groups: new Map(scope.groups) };
+                return { sequence: buildSequence(steps, branchScope), scope: branchScope };
+            });
+            for (const branch of branches) {
+                for (const [key, value] of branch.scope.nodes)
+                    scope.nodes.set(key, value);
+                for (const [key, value] of branch.scope.groups)
+                    scope.groups.set(key, value);
+            }
+            scope.groups.set(step.key, id);
+            return { kind: "parallel", id, branches: branches.map((branch) => branch.sequence) };
+        }
+        if (step.kind === "tool") {
+            const operation = selectOperation(step);
+            if (!operation)
+                throw new Error("automation_template_unavailable");
+            const payload = step.payloadFrom ? earlierStepText(step.payloadFrom, scope) : undefined;
+            const controls = Object.fromEntries(Object.entries(step.controls ?? {}).map(([name, value]) => [name, { kind: "literal", value }]));
+            for (const [name, key] of Object.entries(step.controlInputs ?? {}))
+                controls[name] = runInputBinding(starter, key);
+            if (step.outputFile)
+                controls.path = { kind: "run_file", fileName: step.outputFile };
+            scope.nodes.set(step.key, id);
+            return { kind: "tool", id, title: step.title, onFailure: "stop",
+                operation: { toolName: operation.toolName, operationId: operation.operationId,
+                    contractVersion: operation.contractVersion }, controls, ...(payload ? { payload } : {}) };
+        }
+        const inputs = Object.fromEntries(step.sources.map((key) => [key, earlierStepText(key, scope)]));
+        for (const key of step.parallelSources ?? [])
+            inputs[key] = { kind: "branch_results", parallelNodeId: requiredResultId(key, scope.groups) };
+        for (const key of step.runInputs ?? [])
+            inputs[key] = runInputBinding(starter, key);
+        scope.nodes.set(step.key, id);
+        return { kind: "agent", id, title: step.title, onFailure: "stop",
+            modelProfileId: "", agentMode: "fast", roleInstructions: step.role,
+            prompt: step.prompt, inputs, tools: [], result: { kind: "text" } };
+    }
+    const body = buildSequence(starter.steps, { nodes: new Map(), groups: new Map() });
+    return parseAutomationDefinition({ ...base, title: starter.title, objective: starter.objective,
+        inputs: structuredClone(starter.inputs ?? base.inputs), body: { ...body, id: base.body.id },
+        limits: { ...base.limits, ...(starter.maxModelCallsPerRun
+                ? { maxModelCallsPerRun: starter.maxModelCallsPerRun } : {}) } });
+}

package/dist/src/runtime/automations/starter-template-contracts.d.ts

@@ -0,0 +1,42 @@
+import type { AutomationJsonValue } from "./definition-contracts.js";
+export type StarterToolStep = Readonly<{
+    kind: "tool";
+    key: string;
+    title: string;
+    toolName: string;
+    operationId: string;
+    controls?: Readonly<Record<string, AutomationJsonValue>>;
+    controlInputs?: Readonly<Record<string, string>>;
+    effect?: "mutating";
+    payloadFrom?: string;
+    outputFile?: string;
+}>;
+export type StarterAgentStep = Readonly<{
+    kind: "agent";
+    key: string;
+    title: string;
+    role: string;
+    prompt: string;
+    sources: readonly string[];
+    parallelSources?: readonly string[];
+    runInputs?: readonly string[];
+}>;
+export type StarterParallelStep = Readonly<{
+    kind: "parallel";
+    key: string;
+    branches: readonly (readonly StarterStep[])[];
+}>;
+export type StarterStep = StarterToolStep | StarterAgentStep | StarterParallelStep;
+export type AutomationStarter = Readonly<{
+    id: string;
+    title: string;
+    category: string;
+    description: string;
+    setup: string;
+    objective: string;
+    level?: "advanced";
+    highlights?: readonly string[];
+    inputs?: Readonly<Record<string, AutomationJsonValue>>;
+    maxModelCallsPerRun?: number;
+    steps: readonly StarterStep[];
+}>;

package/dist/src/runtime/automations/starter-template-contracts.js

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

package/dist/src/runtime/automations/starter-template-definitions.d.ts

@@ -0,0 +1,3 @@
+import type { AutomationStarter } from "./starter-template-contracts.js";
+/** Recipes use public operations; installation and current contracts decide availability. */
+export declare const AUTOMATION_STARTERS: readonly AutomationStarter[];