@abot-ai/runtime 1.5.0 → 1.6.0

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

@@ -0,0 +1,86 @@
+import { Buffer } from "node:buffer";
+import { findAutomationStep } from "../../automations/step-evidence-effects.js";
+export function isAutomationAuthoringInputAction(action) {
+    return ["bind_step_result", "set_step_literal", "select_agent_tool"].includes(action);
+}
+function requiredText(params, name) {
+    const value = params[name];
+    if (typeof value !== "string" || !value.trim())
+        throw new Error(`automation_${name}_required`);
+    return value.trim();
+}
+function positiveInteger(params, name) {
+    const value = params[name];
+    if (!Number.isSafeInteger(value) || Number(value) < 1)
+        throw new Error(`automation_${name}_invalid`);
+    return Number(value);
+}
+function literalValue(params) {
+    const source = params.valueJson;
+    if (typeof source !== "string" || Buffer.byteLength(source, "utf8") > 4_096)
+        throw new Error("automation_graph_invalid");
+    try {
+        return JSON.parse(source);
+    }
+    catch {
+        throw new Error("automation_graph_invalid");
+    }
+}
+function sameOperation(left, right) {
+    return left.toolName === right.toolName && left.operationId === right.operationId &&
+        left.contractVersion === right.contractVersion;
+}
+function selectedToolsPatch(node, params) {
+    if (node.kind !== "agent")
+        throw new Error("automation_graph_invalid");
+    const operation = { toolName: requiredText(params, "toolName"),
+        operationId: requiredText(params, "operationId"), contractVersion: positiveInteger(params, "contractVersion") };
+    const selected = { operation, usage: params.usage };
+    const existing = node.tools.findIndex((tool) => sameOperation(tool.operation, operation));
+    const tools = node.tools.filter((tool, index) => index === existing || !sameOperation(tool.operation, operation));
+    const isNewSelection = existing < 0;
+    if (isNewSelection)
+        return { tools: [...tools, selected] };
+    return { tools: tools.map((tool, index) => index === existing ? selected : tool) };
+}
+function resultBinding(definition, params) {
+    const sourceNodeId = requiredText(params, "sourceNodeId");
+    const sourceFound = findAutomationStep(definition.body, sourceNodeId) !== null;
+    if (!sourceFound)
+        throw new Error("automation_dependency_missing");
+    return { kind: "node_result", nodeId: sourceNodeId, select: params.select,
+        ...(params.pointer === undefined ? {} : { pointer: params.pointer }) };
+}
+function bindingPatch(action, definition, node, params) {
+    const inputName = requiredText(params, "inputName");
+    const isLiteralBinding = action === "set_step_literal";
+    const binding = isLiteralBinding ? { kind: "literal", value: literalValue(params) }
+        : resultBinding(definition, params);
+    const field = node.kind === "agent" ? "inputs" : "controls";
+    const current = node.kind === "agent" ? node.inputs : node.controls;
+    return { [field]: { ...current, [inputName]: binding } };
+}
+/** The parser and revision-checked draft service remain the sole mutation authority. */
+export async function executeAutomationAuthoringInput(service, params) {
+    const action = requiredText(params, "action");
+    if (!isAutomationAuthoringInputAction(action))
+        throw new Error("automation_action_unknown");
+    const automationId = requiredText(params, "automationId");
+    const expectedRevision = positiveInteger(params, "expectedRevision");
+    const draft = await service.getDraft(automationId);
+    if (!draft)
+        throw new Error("automation_not_found");
+    const revisionMatches = draft.revision === expectedRevision;
+    if (!revisionMatches)
+        throw new Error("automation_revision_conflict");
+    const nodeId = requiredText(params, "nodeId");
+    const node = findAutomationStep(draft.definition.body, nodeId);
+    if (!node)
+        throw new Error("automation_dependency_missing");
+    const isToolSelection = action === "select_agent_tool";
+    const patch = isToolSelection ? selectedToolsPatch(node, params)
+        : bindingPatch(action, draft.definition, node, params);
+    const next = await service.updateDraft(automationId, expectedRevision, { kind: "update_node", nodeId, patch });
+    return { automationId, revision: next.revision, newNodeIds: [],
+        ...(next.definition.source ? { sourceId: next.definition.source.sourceId } : {}) };
+}

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

@@ -0,0 +1,5 @@
+/** Shared admission bounds for preparation reads and their authoring receipts. */
+export declare const AUTOMATION_AUTHORING_PREPARATION_LIMITS: {
+    readonly operationRefs: 16;
+    readonly outputBytes: 65536;
+};

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

@@ -0,0 +1,5 @@
+/** Shared admission bounds for preparation reads and their authoring receipts. */
+export const AUTOMATION_AUTHORING_PREPARATION_LIMITS = {
+    operationRefs: 16,
+    outputBytes: 65_536,
+};

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;
+}>;