@abot-ai/runtime 1.5.0 → 1.7.0

package/dist/src/runtime/capabilities/automation-builder/authoring-reference.d.ts

@@ -0,0 +1,427 @@
+/** Passive capability grammar; examples are shapes, not a proposed workflow or permission grant. */
+export declare const AUTOMATION_AUTHORING_REFERENCE: {
+    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 text 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: "text";
+                };
+            };
+        }];
+    };
+    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: "Saved text.";
+            readonly data: "Separate optional JSON; no implicit Text channel.";
+        };
+        readonly outputChannels: {
+            content: string;
+            metadata: string;
+            conditional: string;
+        };
+        readonly policy: "literal=constants; run_input=definition.inputs; node_result needs prior success. Follow operation.outputChannels; absent=unknown. Whole data needs no pointer. RFC6901 pointers need documented fields (/items/0; ~ as ~0, / as ~1). Never execute steps for output discovery.";
+        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.";
+    };
+};

package/dist/src/runtime/capabilities/automation-builder/authoring-reference.js

@@ -0,0 +1,131 @@
+import { AUTOMATION_DRAFT_BATCH_LIMITS } from "../../automations/draft-batch.js";
+import { AUTOMATION_GRAPH_LIMITS, AUTOMATION_OUTPUT_SCHEMA_LIMITS, DEFAULT_AUTOMATION_LIMITS } from "../../automations/limits.js";
+import { AUTOMATION_CREATION_RECIPE_LIMITS } from "./creation-recipe.js";
+// These private parser bounds are projected here and checked at both boundaries by reference tests.
+const resultSchemaBounds = AUTOMATION_OUTPUT_SCHEMA_LIMITS;
+const nodeBounds = { maxTitleLength: 160, maxInstructionLength: 8_192, maxBindings: 64, maxSelectedTools: 64 };
+const operation = { toolName: "catalog_tool", operationId: "catalog_operation", contractVersion: 1 };
+const tool = { kind: "tool", title: "Read evidence", onFailure: "stop", operation,
+    controls: {},
+};
+const agent = { kind: "agent", title: "Analyze evidence", onFailure: "stop",
+    modelProfileId: "catalog_model_id", agentMode: "fast", roleInstructions: "Analyze the supplied evidence.",
+    prompt: "Return the requested result using only the supplied evidence.", inputs: {}, tools: [],
+    result: { kind: "text" },
+};
+const jsonResult = { kind: "json", schema: { type: "object", additionalProperties: false,
+        properties: { title: { type: "string", minLength: 1, maxLength: 160 }, ready: { type: "boolean" },
+            items: { type: "array", minItems: 0, maxItems: 3,
+                items: { type: "string", minLength: 1, maxLength: 400 } } },
+        required: ["title", "ready", "items"],
+    } };
+const source = { sourceId: "", location: { kind: "runtime_path", path: "/absolute/runtime/inbox" },
+    includePatterns: ["*.txt"], excludePatterns: ["output/**", "archive/**"], recursive: false,
+    includeExisting: false, mode: "per_file", maxBatchFiles: 100,
+};
+const schedules = [
+    { kind: "timer", delayMs: 60_000 }, { kind: "once", at: "2030-01-01T09:00:00Z" },
+    { kind: "interval", everyMs: 3_600_000 },
+    { kind: "interval", everyMs: 3_600_000, anchorAt: "2030-01-01T09:00:00Z" },
+    { kind: "daily", at: "09:00" }, { kind: "weekly", at: "09:00", weekdays: [1, 3, 5] },
+    { kind: "monthly", at: "09:00", dayOfMonth: 1 },
+];
+const bindings = {
+    literal: { kind: "literal", value: "Exact JSON value" },
+    runInput: { kind: "run_input", input: "topic" },
+    runFile: { kind: "run_file", fileName: "report.md" },
+    sourceFiles: { kind: "source_files" },
+    sourceFile: { kind: "source_file", index: 0, field: "snapshot_path" },
+    earlierText: { kind: "node_result", nodeId: "$first", select: "text" },
+    earlierWholeData: { kind: "node_result", nodeId: "$first", select: "data" },
+    earlierData: { kind: "node_result", nodeId: "$analysis", select: "data", pointer: "/title" },
+    branches: { kind: "branch_results", parallelNodeId: "$group" },
+};
+/** Passive capability grammar; examples are shapes, not a proposed workflow or permission grant. */
+export const AUTOMATION_AUTHORING_REFERENCE = {
+    kind: "automation_authoring_reference_v1", version: 1, authority: "capability_contract",
+    purpose: "Construct or edit an ABot Studio draft using the canonical batch language.",
+    applicability: "Only while authoring the draft requested by the user; replace example values with exact selected catalog references and user requirements.",
+    presenceEffect: "Does not add user intent or authorize workflow execution, permission grants, publication, activation, or running an automation.",
+    permissions: {
+        kind: "automation_authoring_permissions_v1", version: 1, authority: "capability_contract",
+        purpose: "Interpret catalog fields while authoring the user-requested Studio draft.",
+        applicability: "Only the returned catalogScope and selected future workflow operations.",
+        presenceEffect: "Reference only; does not authorize draft changes, permission grants, publication, activation or execution.",
+        inventory: "Future workflow tools only; excludes Studio editing and scheduling tools. Their absence here does not establish current chat capability availability.",
+        grantsPermissions: "False means this read grants no permissions; it does not report the current chat's permissions.",
+        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.",
+        permissionMode: "Required permission mode for future workflow execution, not the current chat mode.",
+        scope: "pre_draft has no automation identity or saved grant. automation identifies the requested grant scope; it does not prove a draft exists.",
+        currentChat: "This catalog does not determine current chat authoring permission. Use the active runtime capability contract and approval policy.",
+    },
+    bounds: { batch: AUTOMATION_DRAFT_BATCH_LIMITS, recipe: AUTOMATION_CREATION_RECIPE_LIMITS, graph: AUTOMATION_GRAPH_LIMITS },
+    createPlanExample: { version: 1, settings: { objective: "Requested workflow outcome" }, steps: [
+            { key: "evidence", kind: "tool", title: "Read text evidence", operation },
+            { key: "analysis", kind: "agent", title: "Analyze evidence", modelProfileId: "catalog_model_id",
+                prompt: "Analyze the supplied evidence.",
+                inputs: { evidence: { kind: "node_result", nodeId: "$evidence", select: "text" } } },
+        ] },
+    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.",
+    creationCapacity: `Budget ${AUTOMATION_CREATION_RECIPE_LIMITS.compiledCommands}: leaf=1, parallel group=1, nonempty settings=1; total across all branches. With settings, max ${AUTOMATION_CREATION_RECIPE_LIMITS.compiledCommands - 1} flat steps. Oversize rejects atomically: automation_recipe_capacity_exceeded. Expand with later draft edits.`,
+    planExample: { version: 1, commands: [{ as: "first", mutation: {
+                    kind: "add_node", parentSequenceId: "$root", index: 0, nodeWithoutId: tool,
+                } }] },
+    mutations: {
+        add_node: { kind: "add_node", parentSequenceId: "$root", index: 0, nodeWithoutId: agent },
+        update_node: { kind: "update_node", nodeId: "$first", patch: { title: "Updated title" } },
+        update_definition: { kind: "update_definition", patch: { objective: "Requested workflow outcome" } },
+        remove_node: { kind: "remove_node", nodeId: "$first" },
+        move_node: { kind: "move_node", nodeId: "$first", parentSequenceId: "$group.branch1", index: 1 },
+        wrap_parallel: { kind: "wrap_parallel", nodeIds: ["$first", "$second"] },
+    },
+    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.",
+    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.",
+    identities: {
+        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.",
+        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.",
+        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.",
+        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.",
+    },
+    nodes: { tool, agent, operationReference: operation, bounds: nodeBounds,
+        payloadExample: { kind: "literal", value: "Payload text" },
+        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.",
+        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.",
+        selectedToolExamples: [{ operation, usage: "available" }, { operation, usage: "required" }],
+        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.",
+        result: { text: { kind: "text" }, json: jsonResult },
+        resultSchemaBounds,
+        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.",
+        schemaPropertyExamples: {
+            text: { type: "string", minLength: 0, maxLength: resultSchemaBounds.maxStringLength },
+            number: { type: "number", minimum: 0, maximum: 1 },
+            integer: { type: "integer", minimum: 0, maximum: 100 },
+            boolean: { type: "boolean" },
+            array: { type: "array", minItems: 0, maxItems: 8,
+                items: { type: "string", minLength: 0, maxLength: 160 } },
+        },
+        acceptanceExample: [{ field: "ready", equals: true }],
+        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.", },
+    bindings: { examples: bindings,
+        channels: { text: "Saved text.", data: "Separate optional JSON; no implicit Text channel." },
+        outputChannels: { content: "Substantive output; may be bounded/summarized.",
+            metadata: "IDs, status, counts or receipts; no content body.",
+            conditional: "Depends on operation inputs; do not assume content." },
+        policy: "literal=constants; run_input=definition.inputs; node_result needs prior success. Follow operation.outputChannels; absent=unknown. Whole data needs no pointer. RFC6901 pointers need documented fields (/items/0; ~ as ~0, / as ~1). Never execute steps for output discovery.",
+        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.",
+        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.", },
+    definition: {
+        editableFields: ["title", "objective", "workingDirectory", "trigger", "source", "inputs", "limits"],
+        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.",
+        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.",
+        removals: { definitionPatch: { workingDirectory: null, source: null }, toolNodePatch: { payload: null } },
+        triggers: [{ kind: "manual" }, { kind: "schedule", schedule: schedules[4] },
+            { kind: "folder", checkEveryMs: 300_000, minimumEligibleFiles: 1 }],
+        schedules,
+        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.",
+        sourceExample: source,
+        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.",
+        inputsExample: { topic: "User-configured topic" }, limits: DEFAULT_AUTOMATION_LIMITS,
+        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.",
+    },
+};

package/dist/src/runtime/capabilities/automation-builder/creation-recipe.d.ts

@@ -0,0 +1,9 @@
+import { type AutomationDraftBatch } from "../../automations/draft-batch.js";
+export declare const AUTOMATION_CREATION_RECIPE_LIMITS: Readonly<{
+    executableNodes: number;
+    compiledCommands: 32;
+}>;
+/** Dispatch by an owned field, including malformed recipes that must be rejected by this compiler. */
+export declare function hasAutomationCreationRecipe(value: unknown): boolean;
+/** Compile explicit workflow structure into the existing atomic draft language. No persistence or semantic choices. */
+export declare function compileAutomationCreationRecipe(value: unknown): AutomationDraftBatch;