@abot-ai/runtime 1.4.0 → 1.6.0

package/dist/src/runtime/capabilities/automations/authoring-preparation.d.ts

@@ -0,0 +1,483 @@
+import type { AutomationService } from "../../automations/service.js";
+type CatalogService = Pick<AutomationService, "catalog">;
+/** Read one canonical snapshot and resolve only explicitly selected operation identities. */
+export declare function readAutomationAuthoringPreparation(service: CatalogService, params: Readonly<Record<string, unknown>>): Promise<{
+    kind: "automation_authoring_preparation_v1";
+    authority: "runtime_registry";
+    catalogScope: {
+        kind: "automation";
+        automationId: string;
+    } | {
+        kind: "pre_draft";
+        automationId?: undefined;
+    };
+    presenceEffect: "authoring_reference_not_user_intent_or_execution";
+    grantsPermissions: false;
+    executesWorkflow: false;
+    maxBytes: 65536;
+    operations: {
+        granted: boolean;
+        toolName: string;
+        operationId: string;
+        contractVersion: number;
+        label: string;
+        pluginName?: string;
+        catalogGroups: readonly import("../../../capabilities/tool-types.js").ToolCatalogGroup[];
+        toolDescription?: string;
+        permissionMode: "full_access" | "full_plus";
+        effect: "read_only" | "mutating" | "mixed";
+        approval: "request_policy" | "always";
+        input: import("../../../capabilities/tool-types.js").ToolNormalInvocationInput;
+        payload?: import("../../../capabilities/tool-types.js").ToolNormalInvocationPayload;
+        attachmentInput?: import("../../../capabilities/tool-types.js").ToolNormalInvocationAttachmentInput;
+        selectionControlIds?: readonly string[];
+        ref: string;
+    }[];
+    models: {
+        items: {
+            provider?: string | undefined;
+            id: string;
+            label: string;
+            labelTruncated: boolean;
+        }[];
+        offset: number;
+        totalCount: number;
+        omittedCount: number;
+        nextOffset: number | null;
+    };
+    savedAgents: {
+        items: {
+            agentId: string;
+            revision: number;
+            title: string;
+            titleTruncated: boolean;
+            modelProfileId: string;
+        }[];
+        offset: number;
+        totalCount: number;
+        omittedCount: number;
+        nextOffset: number | null;
+    };
+    authoringReference: {
+        readonly kind: "automation_authoring_reference_v1";
+        readonly version: 1;
+        readonly authority: "capability_contract";
+        readonly purpose: "Construct or edit an ABot Studio draft using the canonical batch language.";
+        readonly applicability: "Only while authoring the draft requested by the user; replace example values with exact selected catalog references and user requirements.";
+        readonly presenceEffect: "Does not add user intent or authorize workflow execution, permission grants, publication, activation, or running an automation.";
+        readonly permissions: {
+            readonly kind: "automation_authoring_permissions_v1";
+            readonly version: 1;
+            readonly authority: "capability_contract";
+            readonly purpose: "Interpret catalog fields while authoring the user-requested Studio draft.";
+            readonly applicability: "Only the returned catalogScope and selected future workflow operations.";
+            readonly presenceEffect: "Reference only; does not authorize draft changes, permission grants, publication, activation or execution.";
+            readonly inventory: "Future workflow tools only; excludes Studio editing and scheduling tools. Their absence here does not establish current chat capability availability.";
+            readonly grantsPermissions: "False means this read grants no permissions; it does not report the current chat's permissions.";
+            readonly granted: "granted and grantedOperations describe the future workflow's existing grant in catalogScope. False does not prevent drafting that operation; execution still requires the applicable grant.";
+            readonly permissionMode: "Required permission mode for future workflow execution, not the current chat mode.";
+            readonly scope: "pre_draft has no automation identity or saved grant. automation identifies the requested grant scope; it does not prove a draft exists.";
+            readonly currentChat: "This catalog does not determine current chat authoring permission. Use the active runtime capability contract and approval policy.";
+        };
+        readonly bounds: {
+            readonly batch: Readonly<{
+                commands: 32;
+                bytes: number;
+            }>;
+            readonly recipe: Readonly<{
+                executableNodes: number;
+                compiledCommands: 32;
+            }>;
+            readonly graph: Readonly<{
+                executableNodes: 64;
+                branchesPerGroup: 8;
+                nestingDepth: 4;
+                sourceFilesPerBatch: 100;
+                sourceBatchBytes: number;
+                eligibleInputRecords: 1000;
+                inputMetadataBytes: number;
+            }>;
+        };
+        readonly createPlanExample: {
+            readonly version: 1;
+            readonly settings: {
+                readonly objective: "Requested workflow outcome";
+            };
+            readonly steps: readonly [{
+                readonly key: "evidence";
+                readonly kind: "tool";
+                readonly title: "Read structured evidence";
+                readonly operation: {
+                    readonly toolName: "catalog_tool";
+                    readonly operationId: "catalog_operation";
+                    readonly contractVersion: 1;
+                };
+            }, {
+                readonly key: "analysis";
+                readonly kind: "agent";
+                readonly title: "Analyze evidence";
+                readonly modelProfileId: "catalog_model_id";
+                readonly prompt: "Analyze the supplied evidence.";
+                readonly inputs: {
+                    readonly evidence: {
+                        readonly kind: "node_result";
+                        readonly nodeId: "$evidence";
+                        readonly select: "data";
+                    };
+                };
+            }];
+        };
+        readonly creationRules: "New drafts use settings + ordered steps with unique keys and node shapes below. Runtime fills IDs, parents, indices and commands. Defaults: onFailure=stop; tool controls={}; agentMode=fast, roleInstructions='', inputs={}, tools=[], result={kind:'text'}. Override explicitly. Bind earlier results via $key. Parallel: {key,kind:'parallel',branches:[[steps],[steps]]}; branches are ordered and nonempty. Edit with commands; never mix commands and steps.";
+        readonly creationCapacity: `Budget 32: leaf=1, parallel group=1, nonempty settings=1; total across all branches. With settings, max ${number} flat steps. Oversize rejects atomically: automation_recipe_capacity_exceeded. Expand with later draft edits.`;
+        readonly planExample: {
+            readonly version: 1;
+            readonly commands: readonly [{
+                readonly as: "first";
+                readonly mutation: {
+                    readonly kind: "add_node";
+                    readonly parentSequenceId: "$root";
+                    readonly index: 0;
+                    readonly nodeWithoutId: {
+                        readonly kind: "tool";
+                        readonly title: "Read evidence";
+                        readonly onFailure: "stop";
+                        readonly operation: {
+                            readonly toolName: "catalog_tool";
+                            readonly operationId: "catalog_operation";
+                            readonly contractVersion: 1;
+                        };
+                        readonly controls: {};
+                    };
+                };
+            }];
+        };
+        readonly mutations: {
+            add_node: {
+                kind: "add_node";
+                parentSequenceId: string;
+                index: number;
+                nodeWithoutId: {
+                    readonly kind: "agent";
+                    readonly title: "Analyze evidence";
+                    readonly onFailure: "stop";
+                    readonly modelProfileId: "catalog_model_id";
+                    readonly agentMode: "fast";
+                    readonly roleInstructions: "Analyze the supplied evidence.";
+                    readonly prompt: "Return the requested result using only the supplied evidence.";
+                    readonly inputs: {};
+                    readonly tools: readonly [];
+                    readonly result: {
+                        readonly kind: "text";
+                    };
+                };
+            };
+            update_node: {
+                kind: "update_node";
+                nodeId: string;
+                patch: {
+                    title: string;
+                };
+            };
+            update_definition: {
+                kind: "update_definition";
+                patch: {
+                    objective: string;
+                };
+            };
+            remove_node: {
+                kind: "remove_node";
+                nodeId: string;
+            };
+            move_node: {
+                kind: "move_node";
+                nodeId: string;
+                parentSequenceId: string;
+                index: number;
+            };
+            wrap_parallel: {
+                kind: "wrap_parallel";
+                nodeIds: string[];
+            };
+        };
+        readonly transaction: "Commands apply atomically in order; invalid/stale plans save nothing. Create revision 1; apply checks automationId/expectedRevision and increments once. Inspect draft/aliases; re-read uncertain state. operationRefs is full inventory: prepare only needed refs within preparation.operationRefLimit per read; use more reads if needed, then save one edit. Refs imply no access or availability.";
+        readonly emptyDrafts: "A metadata-only update_definition command can create an empty draft; removing the final step can reset one. Empty drafts cannot publish or run. To start with only a saved agent: prepare_draft returns savedAgents summaries, create_automation_draft with settings and steps:[], then add_saved_agent using the returned automationId/revision/rootSequenceId and the exact saved agentId/agentRevision. Do not invent a placeholder step or copy an unknown saved-agent configuration.";
+        readonly identities: {
+            readonly generated: "Never supply a new node id. Optional command as names an add_node or wrap_parallel result. Names: letter then up to 47 letters/digits/_/-, unique within the plan, never root.";
+            readonly references: "$root is the existing root sequence. $name refers to an earlier command's as. A wrapped group's branches are $name.branch1, $name.branch2, etc., in original sibling order. Existing nodes use exact IDs from read_draft or the receipt.";
+            readonly substitution: "Aliases resolve only identity fields and node_result/branch_results bindings. They never interpolate prompts, paths, or literal values. Aliases from a previous plan must use their receipt's exact IDs.";
+            readonly placement: "Indices are zero-based. add_node creates tool or agent nodes only. wrap_parallel needs 2–8 adjacent executable siblings; it creates one sequence per selected step. Insert or move more steps into its branch aliases. Parent must be a sequence.";
+        };
+        readonly nodes: {
+            readonly tool: {
+                readonly kind: "tool";
+                readonly title: "Read evidence";
+                readonly onFailure: "stop";
+                readonly operation: {
+                    readonly toolName: "catalog_tool";
+                    readonly operationId: "catalog_operation";
+                    readonly contractVersion: 1;
+                };
+                readonly controls: {};
+            };
+            readonly agent: {
+                readonly kind: "agent";
+                readonly title: "Analyze evidence";
+                readonly onFailure: "stop";
+                readonly modelProfileId: "catalog_model_id";
+                readonly agentMode: "fast";
+                readonly roleInstructions: "Analyze the supplied evidence.";
+                readonly prompt: "Return the requested result using only the supplied evidence.";
+                readonly inputs: {};
+                readonly tools: readonly [];
+                readonly result: {
+                    readonly kind: "text";
+                };
+            };
+            readonly operationReference: {
+                readonly toolName: "catalog_tool";
+                readonly operationId: "catalog_operation";
+                readonly contractVersion: 1;
+            };
+            readonly bounds: {
+                readonly maxTitleLength: 160;
+                readonly maxInstructionLength: 8192;
+                readonly maxBindings: 64;
+                readonly maxSelectedTools: 64;
+            };
+            readonly payloadExample: {
+                kind: "literal";
+                value: string;
+            };
+            readonly toolPolicy: "controls maps operation input names to bindings, never plain values. Supply required controls from the selected operation schema. payload is optional, only for operations declaring a payload; it is one binding, separate from controls.";
+            readonly agentPolicy: "Exact modelProfileId from catalog; agentMode=fast|reasoning|deep; onFailure=stop|skip. inputs are named bindings. Placement alone passes no prior output. roleInstructions/prompt assign only this step; the workflow objective is background.";
+            readonly selectedToolExamples: ({
+                operation: {
+                    readonly toolName: "catalog_tool";
+                    readonly operationId: "catalog_operation";
+                    readonly contractVersion: 1;
+                };
+                usage: "available";
+            } | {
+                operation: {
+                    readonly toolName: "catalog_tool";
+                    readonly operationId: "catalog_operation";
+                    readonly contractVersion: 1;
+                };
+                usage: "required";
+            })[];
+            readonly toolUsage: "available permits optional use; required demands at least one successful execution of that exact operation. Neither grants permission. Do not mark a conditional action required when a valid outcome may omit it. Do not execute future steps while authoring.";
+            readonly result: {
+                readonly text: {
+                    readonly kind: "text";
+                };
+                readonly json: {
+                    readonly kind: "json";
+                    readonly schema: {
+                        readonly type: "object";
+                        readonly additionalProperties: false;
+                        readonly properties: {
+                            readonly title: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                                readonly maxLength: 160;
+                            };
+                            readonly ready: {
+                                readonly type: "boolean";
+                            };
+                            readonly items: {
+                                readonly type: "array";
+                                readonly minItems: 0;
+                                readonly maxItems: 3;
+                                readonly items: {
+                                    readonly type: "string";
+                                    readonly minLength: 1;
+                                    readonly maxLength: 400;
+                                };
+                            };
+                        };
+                        readonly required: readonly ["title", "ready", "items"];
+                    };
+                };
+            };
+            readonly resultSchemaBounds: Readonly<{
+                maxProperties: 16;
+                maxStringLength: 4096;
+                maxArrayItems: 64;
+            }>;
+            readonly resultPolicy: "JSON results must be exactly one object matching the declared flat schema: at most 16 properties, strings at most 4096 characters, arrays at most 64 scalar items. No nested objects, unbounded strings, or string enum schemas. An agent must declare JSON output before its result can use select:data; select:text carries its entire serialized response.";
+            readonly schemaPropertyExamples: {
+                text: {
+                    type: "string";
+                    minLength: number;
+                    maxLength: 4096;
+                };
+                number: {
+                    type: "number";
+                    minimum: number;
+                    maximum: number;
+                };
+                integer: {
+                    type: "integer";
+                    minimum: number;
+                    maximum: number;
+                };
+                boolean: {
+                    type: "boolean";
+                };
+                array: {
+                    type: "array";
+                    minItems: number;
+                    maxItems: number;
+                    items: {
+                        type: "string";
+                        minLength: number;
+                        maxLength: number;
+                    };
+                };
+            };
+            readonly acceptanceExample: {
+                field: string;
+                equals: true;
+            }[];
+            readonly acceptancePolicy: "Optional acceptance compares required scalar JSON fields to string/number/boolean values of the same type. A mismatch fails the step under onFailure, not a conditional branch. Use [] to clear. No if/else graph construct exists.";
+        };
+        readonly bindings: {
+            readonly examples: {
+                readonly literal: {
+                    readonly kind: "literal";
+                    readonly value: "Exact JSON value";
+                };
+                readonly runInput: {
+                    readonly kind: "run_input";
+                    readonly input: "topic";
+                };
+                readonly runFile: {
+                    readonly kind: "run_file";
+                    readonly fileName: "report.md";
+                };
+                readonly sourceFiles: {
+                    readonly kind: "source_files";
+                };
+                readonly sourceFile: {
+                    readonly kind: "source_file";
+                    readonly index: 0;
+                    readonly field: "snapshot_path";
+                };
+                readonly earlierText: {
+                    readonly kind: "node_result";
+                    readonly nodeId: "$first";
+                    readonly select: "text";
+                };
+                readonly earlierWholeData: {
+                    readonly kind: "node_result";
+                    readonly nodeId: "$first";
+                    readonly select: "data";
+                };
+                readonly earlierData: {
+                    readonly kind: "node_result";
+                    readonly nodeId: "$analysis";
+                    readonly select: "data";
+                    readonly pointer: "/title";
+                };
+                readonly branches: {
+                    readonly kind: "branch_results";
+                    readonly parallelNodeId: "$group";
+                };
+            };
+            readonly channels: {
+                readonly text: "Tool display output; may be counts/status only, not serialized data.";
+                readonly data: "Structured tool output, when provided. Omit pointer to pass it whole, without knowing field names.";
+            };
+            readonly policy: "Use literal for constants, run_input for definition.inputs. node_result needs a succeeded earlier node; no implicit output. Select the operation's documented channel: data for records/ids, text when sufficient. Optional data-only RFC6901 pointer: /field, /items/0; escape ~ as ~0 and / as ~1. Never invent fields or execute future steps to inspect output.";
+            readonly files: "run_file resolves a new file for each run under its working directory; fileName is one portable filename, no path. source_files requires a configured source and an agent consumer. source_file index selects the frozen batch entry; field=snapshot_path|original_path|version.";
+            readonly parallel: "branch_results is agent-only after the referenced parallel join; it supplies each branch's settled tail output/status. A failed/skipped source has no successful node_result for downstream bindings.";
+        };
+        readonly definition: {
+            readonly editableFields: readonly ["title", "objective", "workingDirectory", "trigger", "source", "inputs", "limits"];
+            readonly replacement: "A patch merges top-level fields only; inputs, controls, tools, result, acceptance, source, trigger and limits replace their entire field. Keep existing entries when changing part. Limits require all seven keys.";
+            readonly workingDirectory: "Omit to preserve the current/default directory; set an absolute path on the Runtime host to override; null removes the override. Never use '.' or another relative path.";
+            readonly removals: {
+                readonly definitionPatch: {
+                    readonly workingDirectory: null;
+                    readonly source: null;
+                };
+                readonly toolNodePatch: {
+                    readonly payload: null;
+                };
+            };
+            readonly triggers: ({
+                kind: "manual";
+                schedule?: undefined;
+                checkEveryMs?: undefined;
+                minimumEligibleFiles?: undefined;
+            } | {
+                kind: "schedule";
+                schedule: {
+                    readonly kind: "daily";
+                    readonly at: "09:00";
+                };
+                checkEveryMs?: undefined;
+                minimumEligibleFiles?: undefined;
+            } | {
+                kind: "folder";
+                checkEveryMs: number;
+                minimumEligibleFiles: number;
+                schedule?: undefined;
+            })[];
+            readonly schedules: readonly [{
+                readonly kind: "timer";
+                readonly delayMs: 60000;
+            }, {
+                readonly kind: "once";
+                readonly at: "2030-01-01T09:00:00Z";
+            }, {
+                readonly kind: "interval";
+                readonly everyMs: 3600000;
+            }, {
+                readonly kind: "interval";
+                readonly everyMs: 3600000;
+                readonly anchorAt: "2030-01-01T09:00:00Z";
+            }, {
+                readonly kind: "daily";
+                readonly at: "09:00";
+            }, {
+                readonly kind: "weekly";
+                readonly at: "09:00";
+                readonly weekdays: [1, 3, 5];
+            }, {
+                readonly kind: "monthly";
+                readonly at: "09:00";
+                readonly dayOfMonth: 1;
+            }];
+            readonly schedulePolicy: "Wrap schedule in {kind:'schedule',schedule:<variant>}. Calendar at is HH:mm; weekdays 0–6 (Sunday=0), dayOfMonth 1–31. timer/interval durations are positive milliseconds; once/anchorAt use ISO instants. Time zone belongs to publication/scheduler host policy, not to trigger or schedule JSON. Unspecified timing remains a user decision.";
+            readonly sourceExample: {
+                readonly sourceId: "";
+                readonly location: {
+                    readonly kind: "runtime_path";
+                    readonly path: "/absolute/runtime/inbox";
+                };
+                readonly includePatterns: readonly ["*.txt"];
+                readonly excludePatterns: readonly ["output/**", "archive/**"];
+                readonly recursive: false;
+                readonly includeExisting: false;
+                readonly mode: "per_file";
+                readonly maxBatchFiles: 100;
+            };
+            readonly sourcePolicy: "sourceId:'' generates an ID on update_definition; preserve an existing sourceId to edit it. mode=per_file|batch; source_files/source_file bindings require a source. Exclude generated output/archive paths. IncludeExisting determines first activation's existing-file intake; saving a draft never starts intake.";
+            readonly inputsExample: {
+                readonly topic: "User-configured topic";
+            };
+            readonly limits: Readonly<{
+                maxConcurrentNodes: number;
+                maxModelCallsPerRun: number;
+                maxToolCallsPerRun: number;
+                maxRunDurationMs: number;
+                maxRunsPerDay: number;
+                maxStoredArtifactBytes: number;
+                stopReportDeadlineMs: number;
+            }>;
+            readonly limitsPolicy: "All limits are positive safe integers. maxConcurrentNodes<=64; stopReportDeadlineMs<=maxRunDurationMs; their sum<=2147483647. Limits are per-run caps except maxRunsPerDay. A run cap is not a per-operation quota.";
+        };
+    };
+}>;
+export {};

package/dist/src/runtime/capabilities/automations/authoring-preparation.js

@@ -0,0 +1,51 @@
+import { AUTOMATION_AUTHORING_REFERENCE } from "../automation-builder/authoring-reference.js";
+import { AUTOMATION_AUTHORING_PREPARATION_LIMITS } from "./authoring-preparation-limits.js";
+import { AUTOMATION_CATALOG_OPERATION_REF_MAX_LENGTH, automationAuthoringCatalogScope, automationCatalogOperationRef, projectAutomationAuthoringCatalogIndex, requireAutomationCatalogScope, } from "./authoring-catalog.js";
+function isBoundedOperationRef(value) {
+    if (typeof value !== "string")
+        return false;
+    if (value.length < 1 || value.length > AUTOMATION_CATALOG_OPERATION_REF_MAX_LENGTH)
+        return false;
+    return value.trim() === value;
+}
+function requirePreparationOperationRefs(value) {
+    if (!Array.isArray(value))
+        throw new Error("automation_preparation_operation_refs_invalid");
+    if (value.length > AUTOMATION_AUTHORING_PREPARATION_LIMITS.operationRefs)
+        throw new Error("automation_preparation_operation_refs_invalid");
+    if (!value.every(isBoundedOperationRef))
+        throw new Error("automation_preparation_operation_refs_invalid");
+    if (new Set(value).size !== value.length)
+        throw new Error("automation_preparation_duplicate_operation_ref");
+    return value;
+}
+/** Read one canonical snapshot and resolve only explicitly selected operation identities. */
+export async function readAutomationAuthoringPreparation(service, params) {
+    const automationId = requireAutomationCatalogScope(params);
+    const operationRefs = requirePreparationOperationRefs(params.operationRefs);
+    const catalog = await service.catalog(automationId);
+    const available = new Map(catalog.grantableOperations.map((operation) => [automationCatalogOperationRef(operation), operation]));
+    const granted = new Set(catalog.operations.map(automationCatalogOperationRef));
+    const operations = operationRefs.map((ref) => {
+        const selected = available.get(ref);
+        if (!selected)
+            throw new Error("automation_catalog_operation_not_found");
+        const { fixedParams: _fixedParams, ...operation } = selected;
+        return { ref, ...operation, granted: granted.has(ref) };
+    });
+    const { models, savedAgents } = projectAutomationAuthoringCatalogIndex(catalog, 0, automationId);
+    const result = {
+        kind: "automation_authoring_preparation_v1",
+        authority: "runtime_registry",
+        catalogScope: automationAuthoringCatalogScope(automationId),
+        presenceEffect: "authoring_reference_not_user_intent_or_execution",
+        grantsPermissions: false,
+        executesWorkflow: false,
+        maxBytes: AUTOMATION_AUTHORING_PREPARATION_LIMITS.outputBytes,
+        operations, models, savedAgents,
+        authoringReference: AUTOMATION_AUTHORING_REFERENCE,
+    };
+    if (Buffer.byteLength(JSON.stringify(result), "utf8") > AUTOMATION_AUTHORING_PREPARATION_LIMITS.outputBytes)
+        throw new Error("automation_preparation_output_too_large");
+    return result;
+}

package/dist/src/runtime/capabilities/automations/draft-index.d.ts

@@ -0,0 +1,14 @@
+import type { AutomationService } from "../../automations/service.js";
+/** A small, passive index for recovering an exact draft ID before reading or editing it. */
+export declare function readAutomationDraftIndex(service: AutomationService, offset: unknown): Promise<{
+    kind: "automation_draft_index_v1";
+    grantsPermissions: false;
+    drafts: {
+        automationId: string;
+        title: string;
+        revision: number;
+        status: "active" | "paused" | "draft" | "archived";
+    }[];
+    nextOffset: number | null;
+    omittedCount: number;
+}>;

package/dist/src/runtime/capabilities/automations/draft-index.js

@@ -0,0 +1,26 @@
+const PAGE_SIZE = 50;
+function isAutomationDraftIndexOffset(value) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value))
+        return false;
+    if (value < 0)
+        return false;
+    return value <= 2_147_483_647;
+}
+/** A small, passive index for recovering an exact draft ID before reading or editing it. */
+export async function readAutomationDraftIndex(service, offset) {
+    if (!isAutomationDraftIndexOffset(offset))
+        throw new Error("automation_offset_invalid");
+    const listed = await service.list();
+    const ordered = [...listed].sort((left, right) => left.title.localeCompare(right.title) || left.id.localeCompare(right.id));
+    const page = ordered.slice(offset, offset + PAGE_SIZE);
+    const omittedCount = Math.max(0, ordered.length - offset - page.length);
+    return {
+        kind: "automation_draft_index_v1",
+        grantsPermissions: false,
+        drafts: page.map(({ id, title, draftRevision, status }) => ({
+            automationId: id, title, revision: draftRevision, status,
+        })),
+        nextOffset: omittedCount > 0 ? offset + page.length : null,
+        omittedCount,
+    };
+}

package/dist/src/runtime/capabilities/automations/draft-operation-refs.d.ts

@@ -0,0 +1,11 @@
+import type { AutomationRevision } from "../../automations/definition-contracts.js";
+/** Exact draft identities for preparation; presence does not imply current availability or permission. */
+export declare function automationDraftOperationRefs(definition: AutomationRevision): readonly string[];
+/** Full saved-draft inventory, not a preparation selection or permission grant. */
+export declare function automationDraftPreparationReceipt(definition: AutomationRevision): {
+    operationRefs: readonly string[];
+    preparation: {
+        operationRefLimit: 16;
+        requiresSelection: boolean;
+    };
+};

package/dist/src/runtime/capabilities/automations/draft-operation-refs.js

@@ -0,0 +1,37 @@
+import { automationCatalogOperationRef } from "./authoring-catalog.js";
+import { AUTOMATION_AUTHORING_PREPARATION_LIMITS } from "./authoring-preparation-limits.js";
+function collectNodeOperationRefs(node, refs) {
+    if (node.kind === "sequence") {
+        for (const child of node.children)
+            collectNodeOperationRefs(child, refs);
+        return;
+    }
+    if (node.kind === "parallel") {
+        for (const branch of node.branches)
+            collectNodeOperationRefs(branch, refs);
+        return;
+    }
+    if (node.kind === "tool") {
+        refs.add(automationCatalogOperationRef(node.operation));
+        return;
+    }
+    for (const selected of node.tools)
+        refs.add(automationCatalogOperationRef(selected.operation));
+}
+/** Exact draft identities for preparation; presence does not imply current availability or permission. */
+export function automationDraftOperationRefs(definition) {
+    const refs = new Set();
+    collectNodeOperationRefs(definition.body, refs);
+    return [...refs];
+}
+function requiresPreparationSelection(operationRefCount) {
+    return operationRefCount > AUTOMATION_AUTHORING_PREPARATION_LIMITS.operationRefs;
+}
+/** Full saved-draft inventory, not a preparation selection or permission grant. */
+export function automationDraftPreparationReceipt(definition) {
+    const operationRefs = automationDraftOperationRefs(definition);
+    return { operationRefs, preparation: {
+            operationRefLimit: AUTOMATION_AUTHORING_PREPARATION_LIMITS.operationRefs,
+            requiresSelection: requiresPreparationSelection(operationRefs.length),
+        } };
+}

package/dist/src/runtime/capabilities/automations/draft-receipt-admission.d.ts

@@ -0,0 +1,24 @@
+import type { ToolNormalInvocationOperation } from "../../../capabilities/tool-types.js";
+export declare class AutomationDraftReceiptCapacityError extends Error {
+    readonly details: {
+        readonly code: "automation_authoring_receipt_too_large";
+        readonly message: "The complete draft is too large to return through model authoring. No changes were saved. Use Studio to inspect or edit large drafts.";
+        readonly maxResultBytes: number;
+    };
+    constructor();
+}
+/** Validate the complete result once, including references later added for a direct root. */
+export declare function prepareAutomationDraftReceipt(receipt: unknown, admission: Readonly<{
+    tool: "automation_builder" | "automations";
+    operation: ToolNormalInvocationOperation;
+    params: Readonly<Record<string, unknown>>;
+    mutationEvidence: boolean;
+}>): {
+    readonly ok: true;
+    readonly output: string;
+    readonly producedNewInformation: true;
+    readonly data: {
+        readonly mutationEvidence: boolean;
+        readonly currentStateEvidence: true;
+    };
+};