@abot-ai/runtime 1.5.0 → 1.6.0

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

@@ -0,0 +1,155 @@
+import { Buffer } from "node:buffer";
+import { AUTOMATION_DRAFT_BATCH_LIMITS, AutomationDraftBatchError, parseAutomationDraftBatch } from "../../automations/draft-batch.js";
+import { AUTOMATION_GRAPH_LIMITS } from "../../automations/limits.js";
+export const AUTOMATION_CREATION_RECIPE_LIMITS = Object.freeze({
+    executableNodes: Math.min(AUTOMATION_GRAPH_LIMITS.executableNodes, AUTOMATION_DRAFT_BATCH_LIMITS.commands),
+    compiledCommands: AUTOMATION_DRAFT_BATCH_LIMITS.commands,
+});
+/** Dispatch by an owned field, including malformed recipes that must be rejected by this compiler. */
+export function hasAutomationCreationRecipe(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    const hasPlainRecordPrototype = prototype === Object.prototype || prototype === null;
+    if (!hasPlainRecordPrototype)
+        return false;
+    return Object.hasOwn(value, "steps");
+}
+function requireRecipeRecord(value, path) {
+    const isRecord = value !== null && typeof value === "object" && !Array.isArray(value);
+    if (!isRecord)
+        throw new AutomationDraftBatchError("automation_recipe_invalid", path);
+    return value;
+}
+function requireRecipeFields(record, allowed, path) {
+    const unknown = Object.keys(record).find((key) => !allowed.includes(key));
+    if (unknown !== undefined)
+        throw new AutomationDraftBatchError("automation_recipe_field_unknown", `${path}.${unknown}`);
+}
+function snapshotRecipe(value) {
+    let serialized;
+    try {
+        serialized = JSON.stringify(value);
+    }
+    catch {
+        throw new AutomationDraftBatchError("automation_recipe_invalid", "recipe");
+    }
+    if (serialized === undefined)
+        throw new AutomationDraftBatchError("automation_recipe_invalid", "recipe");
+    if (Buffer.byteLength(serialized, "utf8") > AUTOMATION_DRAFT_BATCH_LIMITS.bytes)
+        throw new AutomationDraftBatchError("automation_batch_too_large", "recipe");
+    return requireRecipeRecord(JSON.parse(serialized), "recipe");
+}
+function requireRecipeKey(value, path, state) {
+    const hasAliasSyntax = typeof value === "string" && /^[A-Za-z][A-Za-z0-9_-]{0,47}$/u.test(value);
+    if (!hasAliasSyntax)
+        throw new AutomationDraftBatchError("automation_batch_alias_invalid", path);
+    if (value === "root")
+        throw new AutomationDraftBatchError("automation_batch_alias_invalid", path);
+    if (state.keys.has(value))
+        throw new AutomationDraftBatchError("automation_batch_alias_duplicate", path);
+    state.keys.add(value);
+    return value;
+}
+function leafWithDefaults(input, path) {
+    const { key: _key, ...node } = input;
+    if (input.kind === "tool")
+        return { onFailure: "stop", controls: {}, ...node };
+    if (input.kind !== "agent")
+        throw new AutomationDraftBatchError("automation_recipe_step_kind_invalid", `${path}.kind`);
+    return { onFailure: "stop", agentMode: "fast", roleInstructions: "", inputs: {}, tools: [],
+        result: { kind: "text" }, ...node };
+}
+function parseRecipeSequence(value, path, depth, state) {
+    if (depth > AUTOMATION_GRAPH_LIMITS.nestingDepth)
+        throw new AutomationDraftBatchError("automation_graph_too_deep", path);
+    if (!Array.isArray(value))
+        throw new AutomationDraftBatchError("automation_recipe_steps_invalid", path);
+    if (value.length > AUTOMATION_CREATION_RECIPE_LIMITS.executableNodes)
+        throw new AutomationDraftBatchError("automation_recipe_capacity_exceeded", path);
+    return value.map((step, index) => parseRecipeStep(step, `${path}.${index}`, depth, state));
+}
+function parseRecipeStep(value, path, depth, state) {
+    const input = requireRecipeRecord(value, path);
+    const key = requireRecipeKey(input.key, `${path}.key`, state);
+    if (input.kind !== "parallel") {
+        state.leaves += 1;
+        if (state.leaves > AUTOMATION_CREATION_RECIPE_LIMITS.executableNodes)
+            throw new AutomationDraftBatchError("automation_recipe_capacity_exceeded", path);
+        return { key, node: leafWithDefaults(input, path) };
+    }
+    requireRecipeFields(input, ["key", "kind", "branches"], path);
+    if (!Array.isArray(input.branches))
+        throw new AutomationDraftBatchError("automation_parallel_invalid", `${path}.branches`);
+    const branchCountAllowed = input.branches.length >= 2 && input.branches.length <= AUTOMATION_GRAPH_LIMITS.branchesPerGroup;
+    if (!branchCountAllowed)
+        throw new AutomationDraftBatchError("automation_parallel_invalid", `${path}.branches`);
+    const branches = input.branches.map((value, index) => {
+        const branchPath = `${path}.branches.${index}`;
+        const branch = parseRecipeSequence(value, branchPath, depth + 2, state);
+        if (branch.length === 0)
+            throw new AutomationDraftBatchError("automation_parallel_invalid", branchPath);
+        return branch;
+    });
+    return { key, branches };
+}
+function isRecipeParallel(step) {
+    return "branches" in step;
+}
+/** A real executable leaf seeds its branch; no placeholder node is ever generated. */
+function firstRecipeLeaf(step) {
+    if (!isRecipeParallel(step))
+        return step;
+    return firstRecipeLeaf(step.branches[0][0]);
+}
+function emitRecipeLeaf(leaf, parent, index, commands) {
+    commands.push({ as: leaf.key, mutation: {
+            kind: "add_node", parentSequenceId: parent, index, nodeWithoutId: leaf.node,
+        } });
+}
+function emitRecipeParallel(step, parent, index, seeded, commands) {
+    const heads = step.branches.map((branch) => firstRecipeLeaf(branch[0]));
+    for (const [branchIndex, head] of heads.entries()) {
+        const headAlreadyPresent = seeded && branchIndex === 0;
+        if (headAlreadyPresent)
+            continue;
+        emitRecipeLeaf(head, parent, index + branchIndex, commands);
+    }
+    commands.push({ as: step.key, mutation: { kind: "wrap_parallel", nodeIds: heads.map(({ key }) => `$${key}`) } });
+    for (const [branchIndex, branch] of step.branches.entries())
+        emitRecipeSequence(branch, `$${step.key}.branch${branchIndex + 1}`, commands, heads[branchIndex].key);
+}
+function emitRecipeSequence(steps, parent, commands, seededHead) {
+    for (const [index, step] of steps.entries()) {
+        const headAlreadyPresent = index === 0 && seededHead !== undefined;
+        if (isRecipeParallel(step)) {
+            emitRecipeParallel(step, parent, index, headAlreadyPresent, commands);
+            continue;
+        }
+        if (headAlreadyPresent)
+            continue;
+        emitRecipeLeaf(step, parent, index, commands);
+    }
+}
+/** Compile explicit workflow structure into the existing atomic draft language. No persistence or semantic choices. */
+export function compileAutomationCreationRecipe(value) {
+    const input = snapshotRecipe(value);
+    requireRecipeFields(input, ["version", "settings", "steps"], "recipe");
+    if (input.version !== 1)
+        throw new AutomationDraftBatchError("automation_batch_version_invalid", "recipe.version");
+    const state = { keys: new Set(), leaves: 0 };
+    const steps = parseRecipeSequence(input.steps, "recipe.steps", 0, state);
+    const commands = [];
+    if (Object.hasOwn(input, "settings")) {
+        const patch = requireRecipeRecord(input.settings, "recipe.settings");
+        if (Object.keys(patch).length > 0)
+            commands.push({ mutation: { kind: "update_definition", patch } });
+    }
+    // Every leaf and parallel group emits one command; nonempty settings emit one more.
+    const compiledCommandCount = state.keys.size + commands.length;
+    if (compiledCommandCount > AUTOMATION_CREATION_RECIPE_LIMITS.compiledCommands)
+        throw new AutomationDraftBatchError("automation_recipe_capacity_exceeded", "recipe.steps");
+    emitRecipeSequence(steps, "$root", commands);
+    // Canonical limits also apply after defaults and structural commands expand the recipe.
+    return parseAutomationDraftBatch({ version: 1, commands });
+}

package/dist/src/runtime/capabilities/automation-builder/payload-instructions.d.ts

@@ -0,0 +1,6 @@
+/** Complete grammar is supplied as bounded passive evidence by prepare_draft. */
+export declare const AUTOMATION_BUILDER_PAYLOAD_INSTRUCTIONS = "Return only JSON following authoringReference from prepare_draft. Use version:1 with commands:[{as,mutation}] for existing drafts. Save all related changes together; new nodes omit id and use earlier aliases in bindings. Outputs never pass implicitly. Agent inputs and tool controls are binding maps; payload is a separate binding. Match exact operation schemas and model IDs. Choose each tool's documented output channel: text may be counts/status only; data without pointer passes the whole structured result when provided. Use data pointers only for known fields; agents need declared JSON output for data bindings. Inputs, limits, controls and selected tools replace their entire field. Never invent schedules or execute future steps.";
+export declare const AUTOMATION_BUILDER_CREATE_SUMMARY = "Create the entire connected automation from settings and ordered steps in one write; Runtime generates IDs and positions. Discover with browse_catalog, then prepare_draft for exact schemas and the authoring reference for planJson. Returns revision 1, generated IDs and the exact saved draft for inspection; no empty draft or separate step edits are needed. Saves only a draft; the user grants permissions, publishes and runs it.";
+export declare const AUTOMATION_BUILDER_APPLY_SUMMARY = "Save related edits atomically. Use the saved draft from read_draft or a builder receipt, with its revision as expectedRevision. operationRefs is the full inventory: select refs needed within preparation.operationRefLimit; use separate prepare_draft reads if needed. Returns the saved draft without another read. Invalid/stale plans save nothing. Single-field edits use this operation too. Users retain permission, publication and run control.";
+/** Creation describes workflow content; the capability compiles mechanical mutation structure. */
+export declare const AUTOMATION_BUILDER_CREATION_INSTRUCTIONS = "Return only JSON using {\"version\":1,\"settings\":{...},\"steps\":[{\"key\":\"first\",\"kind\":\"tool\"|\"agent\",...}]}. Follow authoringReference.createPlanExample and creationRules. settings is optional; steps are ordered with unique keys. Runtime generates IDs, parents, indices and mutation wrappers. Bind prior $key results explicitly. Tool steps need title and exact operation; agent steps need title, exact modelProfileId and prompt. Use documented defaults and tool schemas. Choose each operation's output channel: text may be a count/status summary; data without pointer passes its whole structured result when provided. Field pointers require known fields. Result and acceptance are sibling agent fields. A parallel step is {key,kind:parallel,branches:[stepArrays]}. Leave unspecified timing to the user. Save only an inactive draft; never execute future steps.";

package/dist/src/runtime/capabilities/automation-builder/payload-instructions.js

@@ -0,0 +1,6 @@
+/** Complete grammar is supplied as bounded passive evidence by prepare_draft. */
+export const AUTOMATION_BUILDER_PAYLOAD_INSTRUCTIONS = "Return only JSON following authoringReference from prepare_draft. Use version:1 with commands:[{as,mutation}] for existing drafts. Save all related changes together; new nodes omit id and use earlier aliases in bindings. Outputs never pass implicitly. Agent inputs and tool controls are binding maps; payload is a separate binding. Match exact operation schemas and model IDs. Choose each tool's documented output channel: text may be counts/status only; data without pointer passes the whole structured result when provided. Use data pointers only for known fields; agents need declared JSON output for data bindings. Inputs, limits, controls and selected tools replace their entire field. Never invent schedules or execute future steps.";
+export const AUTOMATION_BUILDER_CREATE_SUMMARY = "Create the entire connected automation from settings and ordered steps in one write; Runtime generates IDs and positions. Discover with browse_catalog, then prepare_draft for exact schemas and the authoring reference for planJson. Returns revision 1, generated IDs and the exact saved draft for inspection; no empty draft or separate step edits are needed. Saves only a draft; the user grants permissions, publishes and runs it.";
+export const AUTOMATION_BUILDER_APPLY_SUMMARY = "Save related edits atomically. Use the saved draft from read_draft or a builder receipt, with its revision as expectedRevision. operationRefs is the full inventory: select refs needed within preparation.operationRefLimit; use separate prepare_draft reads if needed. Returns the saved draft without another read. Invalid/stale plans save nothing. Single-field edits use this operation too. Users retain permission, publication and run control.";
+/** Creation describes workflow content; the capability compiles mechanical mutation structure. */
+export const AUTOMATION_BUILDER_CREATION_INSTRUCTIONS = "Return only JSON using {\"version\":1,\"settings\":{...},\"steps\":[{\"key\":\"first\",\"kind\":\"tool\"|\"agent\",...}]}. Follow authoringReference.createPlanExample and creationRules. settings is optional; steps are ordered with unique keys. Runtime generates IDs, parents, indices and mutation wrappers. Bind prior $key results explicitly. Tool steps need title and exact operation; agent steps need title, exact modelProfileId and prompt. Use documented defaults and tool schemas. Choose each operation's output channel: text may be a count/status summary; data without pointer passes its whole structured result when provided. Field pointers require known fields. Result and acceptance are sibling agent fields. A parallel step is {key,kind:parallel,branches:[stepArrays]}. Leave unspecified timing to the user. Save only an inactive draft; never execute future steps.";

package/dist/src/runtime/capabilities/automation-builder/payload-schema.d.ts

@@ -0,0 +1,3 @@
+import type { ModelGatewayJsonSchemaFormat } from "../../../model-gateway/types.js";
+/** Structural generation grammar. Canonical parsers own route exclusivity, references, bounds and graph semantics. */
+export declare const AUTOMATION_BUILDER_PAYLOAD_FORMAT: ModelGatewayJsonSchemaFormat;

package/dist/src/runtime/capabilities/automation-builder/payload-schema.js

@@ -0,0 +1,105 @@
+import { AUTOMATION_DRAFT_BATCH_LIMITS } from "../../automations/draft-batch.js";
+import { AUTOMATION_GRAPH_LIMITS, DEFAULT_AUTOMATION_LIMITS } from "../../automations/limits.js";
+import { AUTOMATION_CREATION_RECIPE_LIMITS } from "./creation-recipe.js";
+function object(properties, optional = []) {
+    return { type: "object", properties, additionalProperties: false,
+        required: Object.keys(properties).filter((name) => !optional.includes(name)) };
+}
+function text(minLength = 0) {
+    return { type: "string", ...(minLength ? { minLength } : {}) };
+}
+function choices(...values) {
+    return { type: "string", enum: values };
+}
+function array(items, maxItems, minItems = 0) {
+    return { type: "array", items, maxItems, ...(minItems ? { minItems } : {}) };
+}
+function map(values, maxProperties = 64) {
+    return { type: "object", additionalProperties: values, maxProperties };
+}
+function nullable(value) {
+    return { anyOf: [value, { type: "null" }] };
+}
+const identifier = text(1);
+const integer = { type: "integer", minimum: 1, maximum: Number.MAX_SAFE_INTEGER };
+const index = { type: "integer", minimum: 0, maximum: AUTOMATION_GRAPH_LIMITS.executableNodes };
+const operationReference = object({ toolName: text(1), operationId: text(1), contractVersion: integer });
+const operation = { $ref: "#/$defs/operationReference" };
+const valueBinding = { anyOf: [
+        object({ kind: choices("literal"), value: {} }),
+        object({ kind: choices("run_input"), input: text(1) }),
+        object({ kind: choices("run_file"), fileName: text(1) }),
+        object({ kind: choices("source_files") }),
+        object({ kind: choices("source_file"), index: { type: "integer", minimum: 0, maximum: 99 },
+            field: choices("snapshot_path", "original_path", "version") }),
+        object({ kind: choices("node_result"), nodeId: identifier, select: choices("text") }),
+        object({ kind: choices("node_result"), nodeId: identifier, select: choices("data"), pointer: text() }, ["pointer"]),
+        object({ kind: choices("branch_results"), parallelNodeId: identifier }),
+    ] };
+const binding = { $ref: "#/$defs/valueBinding" };
+// The descriptor map is JSON data whose exact flat-schema subset is checked by the graph owner.
+// Keeping it opaque also avoids interpreting an output field named maxLength as a provider constraint.
+const resultSchema = object({ type: choices("object"), additionalProperties: { type: "boolean", const: false },
+    properties: map({ type: "object", additionalProperties: true }, 16), required: array(text(1), 16) });
+const result = { anyOf: [object({ kind: choices("text") }), object({ kind: choices("json"), schema: resultSchema })] };
+const acceptance = array(object({ field: text(1), equals: { anyOf: [
+            { type: "string" }, { type: "number" }, { type: "boolean" },
+        ] } }), 64);
+const selectedTools = array(object({ operation, usage: choices("available", "required") }), 64);
+const agentTools = { $ref: "#/$defs/selectedTools" };
+const savedOrigin = object({ agentId: text(1), revision: integer });
+const sharedNode = { title: text(1), onFailure: choices("stop", "skip") };
+const toolFields = { operation, controls: map(binding), payload: binding };
+const agentFields = { modelProfileId: text(1), agentMode: choices("fast", "reasoning", "deep"),
+    roleInstructions: text(), prompt: text(), inputs: map(binding), tools: agentTools,
+    result, acceptance, savedAgentOrigin: savedOrigin };
+const toolNode = object({ kind: choices("tool"), ...sharedNode, ...toolFields }, ["payload"]);
+const agentNode = object({ kind: choices("agent"), ...sharedNode, ...agentFields }, ["acceptance", "savedAgentOrigin"]);
+const editableNodeFields = { ...sharedNode, ...toolFields, ...agentFields, payload: nullable(binding) };
+const nodePatch = object(editableNodeFields, Object.keys(editableNodeFields));
+const schedule = { anyOf: [
+        object({ kind: choices("timer"), delayMs: integer }),
+        object({ kind: choices("once"), at: text(1) }),
+        object({ kind: choices("interval"), everyMs: integer, anchorAt: text(1) }, ["anchorAt"]),
+        object({ kind: choices("daily"), at: text(5) }),
+        object({ kind: choices("weekly"), at: text(5),
+            weekdays: array({ type: "integer", minimum: 0, maximum: 6 }, 7, 1) }),
+        object({ kind: choices("monthly"), at: text(5), dayOfMonth: { type: "integer", minimum: 1, maximum: 31 } }),
+    ] };
+const trigger = { anyOf: [object({ kind: choices("manual") }), object({ kind: choices("schedule"), schedule }),
+        object({ kind: choices("folder"), checkEveryMs: integer,
+            minimumEligibleFiles: { type: "integer", minimum: 1, maximum: AUTOMATION_GRAPH_LIMITS.sourceFilesPerBatch } }),
+    ] };
+const source = object({ sourceId: text(), location: object({ kind: choices("runtime_path"), path: text() }),
+    includePatterns: array(text(), 64), excludePatterns: array(text(), 64),
+    recursive: { type: "boolean" }, includeExisting: { type: "boolean" }, mode: choices("per_file", "batch"),
+    maxBatchFiles: { type: "integer", minimum: 1, maximum: AUTOMATION_GRAPH_LIMITS.sourceFilesPerBatch } });
+const limits = object(Object.fromEntries(Object.keys(DEFAULT_AUTOMATION_LIMITS).map((name) => [name, integer])));
+const definitionFields = { title: text(), objective: text(), workingDirectory: nullable(text()),
+    trigger, source: nullable(source), inputs: map({}), limits };
+const definitionPatch = object(definitionFields, Object.keys(definitionFields));
+const addNodeMutation = object({ kind: choices("add_node"), parentSequenceId: identifier, index,
+    nodeWithoutId: { anyOf: [toolNode, agentNode] } });
+const wrapParallelMutation = object({ kind: choices("wrap_parallel"),
+    nodeIds: array(identifier, AUTOMATION_GRAPH_LIMITS.branchesPerGroup, 2) });
+const command = { anyOf: [
+        object({ as: text(1), mutation: addNodeMutation }, ["as"]),
+        object({ mutation: object({ kind: choices("update_node"), nodeId: identifier, patch: nodePatch }) }),
+        object({ mutation: object({ kind: choices("update_definition"), patch: { $ref: "#/$defs/definitionPatch" } }) }),
+        object({ mutation: object({ kind: choices("remove_node"), nodeId: identifier }) }),
+        object({ mutation: object({ kind: choices("move_node"), nodeId: identifier, parentSequenceId: identifier, index }) }),
+        object({ as: text(1), mutation: wrapParallelMutation }, ["as"]),
+    ] };
+const recipeStep = { anyOf: [
+        object({ key: text(1), kind: choices("tool"), ...sharedNode, ...toolFields }, ["onFailure", "controls", "payload"]),
+        object({ key: text(1), kind: choices("agent"), ...sharedNode, ...agentFields }, ["onFailure", "agentMode", "roleInstructions", "inputs", "tools", "result", "acceptance", "savedAgentOrigin"]),
+        object({ key: text(1), kind: choices("parallel"), branches: array(array({ $ref: "#/properties/steps/items" }, AUTOMATION_CREATION_RECIPE_LIMITS.executableNodes, 1), AUTOMATION_GRAPH_LIMITS.branchesPerGroup, 2) }),
+    ] };
+const schema = { ...object({ version: { type: "integer", const: 1 },
+        commands: array(command, AUTOMATION_DRAFT_BATCH_LIMITS.commands, 1),
+        settings: { $ref: "#/$defs/definitionPatch" }, steps: array(recipeStep, AUTOMATION_CREATION_RECIPE_LIMITS.executableNodes),
+    }, ["commands", "settings", "steps"]), $defs: { valueBinding, definitionPatch, operationReference, selectedTools } };
+/** Structural generation grammar. Canonical parsers own route exclusivity, references, bounds and graph semantics. */
+export const AUTOMATION_BUILDER_PAYLOAD_FORMAT = Object.freeze({
+    type: "json_schema", name: "automation_draft_plan", strict: false, schema,
+});

package/dist/src/runtime/capabilities/automation-builder/tool-contract.d.ts

@@ -0,0 +1,65 @@
+export declare const automationBuilderToolContract: {
+    readonly version: 1;
+    readonly operations: readonly [{
+        readonly operationId: "create_automation_draft";
+        readonly summary: "Create the entire connected automation from settings and ordered steps in one write; Runtime generates IDs and positions. Discover with browse_catalog, then prepare_draft for exact schemas and the authoring reference for planJson. Returns revision 1, generated IDs and the exact saved draft for inspection; no empty draft or separate step edits are needed. Saves only a draft; the user grants permissions, publishes and runs it.";
+        readonly effect: "mutating";
+        readonly approval: "request_policy";
+        readonly fixedParams: {
+            readonly action: "create_automation_draft";
+        };
+        readonly input: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly title: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly maxLength: 160;
+                };
+            };
+            readonly required: readonly ["title"];
+        };
+        readonly selectionControlIds: readonly ["title"];
+        readonly payload: {
+            readonly instructions: "Return only JSON using {\"version\":1,\"settings\":{...},\"steps\":[{\"key\":\"first\",\"kind\":\"tool\"|\"agent\",...}]}. Follow authoringReference.createPlanExample and creationRules. settings is optional; steps are ordered with unique keys. Runtime generates IDs, parents, indices and mutation wrappers. Bind prior $key results explicitly. Tool steps need title and exact operation; agent steps need title, exact modelProfileId and prompt. Use documented defaults and tool schemas. Choose each operation's output channel: text may be a count/status summary; data without pointer passes its whole structured result when provided. Field pointers require known fields. Result and acceptance are sibling agent fields. A parallel step is {key,kind:parallel,branches:[stepArrays]}. Leave unspecified timing to the user. Save only an inactive draft; never execute future steps.";
+            readonly kind: "raw_text";
+            readonly param: "planJson";
+            readonly minBytes: 2;
+            readonly maxBytes: number;
+        };
+    }, {
+        readonly operationId: "apply_automation_draft_changes";
+        readonly summary: "Save related edits atomically. Use the saved draft from read_draft or a builder receipt, with its revision as expectedRevision. operationRefs is the full inventory: select refs needed within preparation.operationRefLimit; use separate prepare_draft reads if needed. Returns the saved draft without another read. Invalid/stale plans save nothing. Single-field edits use this operation too. Users retain permission, publication and run control.";
+        readonly effect: "mutating";
+        readonly approval: "request_policy";
+        readonly fixedParams: {
+            readonly action: "apply_automation_draft_changes";
+        };
+        readonly input: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly automationId: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly maxLength: 128;
+                };
+                readonly expectedRevision: {
+                    readonly type: "integer";
+                    readonly minimum: 1;
+                    readonly maximum: 2147483647;
+                };
+            };
+            readonly required: readonly ["automationId", "expectedRevision"];
+        };
+        readonly selectionControlIds: readonly ["automationId", "expectedRevision"];
+        readonly payload: {
+            readonly kind: "raw_text";
+            readonly param: "planJson";
+            readonly minBytes: 2;
+            readonly maxBytes: number;
+            readonly instructions: "Return only JSON following authoringReference from prepare_draft. Use version:1 with commands:[{as,mutation}] for existing drafts. Save all related changes together; new nodes omit id and use earlier aliases in bindings. Outputs never pass implicitly. Agent inputs and tool controls are binding maps; payload is a separate binding. Match exact operation schemas and model IDs. Choose each tool's documented output channel: text may be counts/status only; data without pointer passes the whole structured result when provided. Use data pointers only for known fields; agents need declared JSON output for data bindings. Inputs, limits, controls and selected tools replace their entire field. Never invent schedules or execute future steps.";
+        };
+    }];
+};

package/dist/src/runtime/capabilities/automation-builder/tool-contract.js

@@ -0,0 +1,27 @@
+import { AUTOMATION_DRAFT_BATCH_LIMITS } from "../../automations/draft-batch.js";
+import { AUTOMATION_BUILDER_CREATION_INSTRUCTIONS, AUTOMATION_BUILDER_APPLY_SUMMARY, AUTOMATION_BUILDER_CREATE_SUMMARY, AUTOMATION_BUILDER_PAYLOAD_INSTRUCTIONS } from "./payload-instructions.js";
+const payload = { kind: "raw_text", param: "planJson", minBytes: 2,
+    maxBytes: AUTOMATION_DRAFT_BATCH_LIMITS.bytes, instructions: AUTOMATION_BUILDER_PAYLOAD_INSTRUCTIONS };
+export const automationBuilderToolContract = {
+    version: 1,
+    operations: [
+        {
+            operationId: "create_automation_draft",
+            summary: AUTOMATION_BUILDER_CREATE_SUMMARY,
+            effect: "mutating", approval: "request_policy", fixedParams: { action: "create_automation_draft" },
+            input: { type: "object", additionalProperties: false,
+                properties: { title: { type: "string", minLength: 1, maxLength: 160 } }, required: ["title"] },
+            selectionControlIds: ["title"], payload: { ...payload, instructions: AUTOMATION_BUILDER_CREATION_INSTRUCTIONS },
+        },
+        {
+            operationId: "apply_automation_draft_changes",
+            summary: AUTOMATION_BUILDER_APPLY_SUMMARY,
+            effect: "mutating", approval: "request_policy", fixedParams: { action: "apply_automation_draft_changes" },
+            input: { type: "object", additionalProperties: false,
+                properties: { automationId: { type: "string", minLength: 1, maxLength: 128 },
+                    expectedRevision: { type: "integer", minimum: 1, maximum: 2_147_483_647 } },
+                required: ["automationId", "expectedRevision"] },
+            selectionControlIds: ["automationId", "expectedRevision"], payload,
+        },
+    ],
+};

package/dist/src/runtime/capabilities/automation-builder/tool-module.d.ts

@@ -0,0 +1,4 @@
+import type { ToolModuleDeclaration } from "../../../capabilities/tool-types.js";
+import type { AutomationService } from "../../automations/service.js";
+/** The builder exposes the canonical draft transaction without runtime execution authority. */
+export declare function createAutomationBuilderToolModule(getService: () => AutomationService, ready: () => Promise<void>): ToolModuleDeclaration;

package/dist/src/runtime/capabilities/automation-builder/tool-module.js

@@ -0,0 +1,108 @@
+import { Buffer } from "node:buffer";
+import { AUTOMATION_TOOL_EVENT_PRESENTATION } from "../automations/event-presentation.js";
+import { automationDraftPreparationReceipt } from "../automations/draft-operation-refs.js";
+import { AutomationDraftReceiptCapacityError, prepareAutomationDraftReceipt } from "../automations/draft-receipt-admission.js";
+import { AUTOMATION_DRAFT_BATCH_LIMITS, AutomationDraftBatchError, AutomationDraftBatchGraphError } from "../../automations/draft-batch.js";
+import { automationBuilderToolContract } from "./tool-contract.js";
+import { AUTOMATION_BUILDER_PAYLOAD_FORMAT } from "./payload-schema.js";
+import { compileAutomationCreationRecipe, hasAutomationCreationRecipe } from "./creation-recipe.js";
+function requiredText(params, key) {
+    const value = params[key];
+    if (typeof value !== "string" || !value.trim())
+        throw new Error(`automation_${key}_required`);
+    return value.trim();
+}
+function expectedRevision(params) {
+    const value = params.expectedRevision;
+    const validRevision = Number.isSafeInteger(value) && Number(value) >= 1;
+    if (!validRevision)
+        throw new Error("automation_revision_conflict");
+    return Number(value);
+}
+function parsePlanPayload(params) {
+    const payload = params.planJson;
+    if (typeof payload !== "string")
+        throw new AutomationDraftBatchError("automation_batch_invalid", "plan");
+    const withinByteLimit = Buffer.byteLength(payload, "utf8") <= AUTOMATION_DRAFT_BATCH_LIMITS.bytes;
+    if (!withinByteLimit)
+        throw new AutomationDraftBatchError("automation_batch_too_large", "plan");
+    try {
+        return JSON.parse(payload);
+    }
+    catch {
+        throw new AutomationDraftBatchError("automation_batch_invalid", "plan");
+    }
+}
+function requireAcceptedDraftReceipt(output) {
+    if (!output)
+        throw new Error("automation_draft_plan_acceptance_missing");
+    return output;
+}
+async function execute(service, params) {
+    const action = requiredText(params, "action");
+    const plan = parsePlanPayload(params);
+    const operation = automationBuilderToolContract.operations.find(({ operationId }) => operationId === action);
+    if (!operation)
+        throw new Error("automation_action_unknown");
+    let acceptedOutput;
+    const accept = ({ draft, aliases }) => {
+        const receipt = { automationId: draft.automationId, revision: draft.revision,
+            rootSequenceId: draft.definition.body.id, aliases,
+            draft, ...automationDraftPreparationReceipt(draft.definition) };
+        acceptedOutput = prepareAutomationDraftReceipt(receipt, {
+            tool: "automation_builder", operation, params, mutationEvidence: true,
+        });
+        return true;
+    };
+    if (action === "create_automation_draft") {
+        const creationPlan = hasAutomationCreationRecipe(plan) ? compileAutomationCreationRecipe(plan) : plan;
+        await service.createDraftPlan(requiredText(params, "title"), creationPlan, accept);
+        return requireAcceptedDraftReceipt(acceptedOutput);
+    }
+    await service.applyDraftPlan(requiredText(params, "automationId"), expectedRevision(params), plan, accept);
+    return requireAcceptedDraftReceipt(acceptedOutput);
+}
+function failureDetails(error) {
+    if (error instanceof AutomationDraftReceiptCapacityError)
+        return error.details;
+    if (error instanceof AutomationDraftBatchGraphError)
+        return { code: error.code, path: error.path, issues: error.issues, omittedIssueCount: error.omittedIssueCount };
+    if (error instanceof AutomationDraftBatchError)
+        return { code: error.code, path: error.path,
+            ...(error.commandPath ? { commandPath: error.commandPath } : {}) };
+    return { code: error instanceof Error ? error.message : String(error) };
+}
+/** The builder exposes the canonical draft transaction without runtime execution authority. */
+export function createAutomationBuilderToolModule(getService, ready) {
+    return {
+        definition: {
+            name: "automation_builder",
+            eventPresentation: {
+                ...AUTOMATION_TOOL_EVENT_PRESENTATION,
+                metadata: {
+                    ...AUTOMATION_TOOL_EVENT_PRESENTATION.metadata,
+                    inputPreview: { param: "planJson", kind: "string", maxLength: 500, preserveWhitespace: true },
+                    contentLength: { param: "planJson", kind: "length" },
+                },
+            },
+            description: "Build or update a complete connected ABot Studio draft with one atomic canonical plan. Use this for multi-step authoring; automations provides discovery, reads and individual edits. Future workflow actions are data to configure, not actions to perform while authoring. The user retains permission, publication and run control.",
+            routingCapability: "semantic_mutation", catalogGroups: ["automations"],
+            developmentRoles: ["auxiliary"], controlsRefinement: "mechanical_when_complete",
+            payloadChannelSpec: { params: ["planJson"], outputParam: "planJson", generationMode: "raw_text",
+                stages: [{ outputParam: "planJson", responseFormat: AUTOMATION_BUILDER_PAYLOAD_FORMAT }] },
+        },
+        normalInvocation: automationBuilderToolContract,
+        async implementation(params, context) {
+            try {
+                await ready();
+                context?.abortSignal?.throwIfAborted();
+                return await execute(getService(), params);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return { ok: false, output: JSON.stringify(failureDetails(error)), error: message,
+                    producedNewInformation: false, data: { mutationEvidence: false } };
+            }
+        },
+    };
+}

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

@@ -0,0 +1,78 @@
+export declare const automationAuthoringCatalogOperations: readonly [{
+    readonly operationId: "browse_catalog";
+    readonly summary: "Discover available tools and models before creating a draft; omit automationId for a new workflow. view=index returns 50 compact refs per page; page with nextOffset only if needed. Select needed operation refs for prepare_draft within its per-read limit; use multiple reads if needed, then create the whole connected draft. Legacy view=operation resolves one exact toolName/operationId/contractVersion. Discovery never runs workflow tools or grants access.";
+    readonly effect: "read_only";
+    readonly approval: "request_policy";
+    readonly fixedParams: {
+        readonly action: "browse_catalog";
+    };
+    readonly input: {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly automationId: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 128;
+            };
+            readonly view: {
+                readonly type: "string";
+                readonly enum: readonly ["index", "operation"];
+            };
+            readonly offset: {
+                readonly type: "integer";
+                readonly minimum: 0;
+                readonly maximum: 2147483647;
+            };
+            readonly toolName: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 64;
+            };
+            readonly operationId: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 64;
+            };
+            readonly contractVersion: {
+                readonly type: "integer";
+                readonly minimum: 1;
+                readonly maximum: 2147483647;
+            };
+        };
+        readonly required: readonly ["view"];
+    };
+    readonly selectionControlIds: readonly ["view"];
+}];
+export declare const automationAuthoringPreparationOperation: {
+    readonly operationId: "prepare_draft";
+    readonly summary: "Prepare a draft or related edit. Select operationRefs needed for this edit from browse_catalog or the full inventory in read_draft/builder receipts (up to 16 per read; [] when no tool schemas are needed). Read separate selections if more are needed, then save one atomic edit. Returns exact schemas, models and the authoring reference. Omit automationId for a new draft. Does not create, run, publish or grant access.";
+    readonly effect: "read_only";
+    readonly approval: "request_policy";
+    readonly fixedParams: {
+        readonly action: "prepare_draft";
+    };
+    readonly input: {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly automationId: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 128;
+            };
+            readonly operationRefs: {
+                readonly type: "array";
+                readonly minItems: 0;
+                readonly maxItems: 16;
+                readonly items: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly maxLength: number;
+                };
+            };
+        };
+        readonly required: readonly ["operationRefs"];
+    };
+    readonly selectionControlIds: readonly ["operationRefs"];
+};

package/dist/src/runtime/capabilities/automations/authoring-catalog-contract.js

@@ -0,0 +1,28 @@
+import { AUTOMATION_CATALOG_OPERATION_REF_MAX_LENGTH } from "./authoring-catalog.js";
+import { AUTOMATION_AUTHORING_PREPARATION_LIMITS } from "./authoring-preparation-limits.js";
+const automationId = { type: "string", minLength: 1, maxLength: 128 };
+const operationName = { type: "string", minLength: 1, maxLength: 64 };
+export const automationAuthoringCatalogOperations = [
+    {
+        operationId: "browse_catalog",
+        summary: "Discover available tools and models before creating a draft; omit automationId for a new workflow. view=index returns 50 compact refs per page; page with nextOffset only if needed. Select needed operation refs for prepare_draft within its per-read limit; use multiple reads if needed, then create the whole connected draft. Legacy view=operation resolves one exact toolName/operationId/contractVersion. Discovery never runs workflow tools or grants access.",
+        effect: "read_only", approval: "request_policy", fixedParams: { action: "browse_catalog" },
+        input: { type: "object", additionalProperties: false,
+            properties: { automationId, view: { type: "string", enum: ["index", "operation"] },
+                offset: { type: "integer", minimum: 0, maximum: 2_147_483_647 },
+                toolName: operationName, operationId: operationName,
+                contractVersion: { type: "integer", minimum: 1, maximum: 2_147_483_647 } },
+            required: ["view"] },
+        selectionControlIds: ["view"],
+    },
+];
+export const automationAuthoringPreparationOperation = {
+    operationId: "prepare_draft",
+    summary: `Prepare a draft or related edit. Select operationRefs needed for this edit from browse_catalog or the full inventory in read_draft/builder receipts (up to ${AUTOMATION_AUTHORING_PREPARATION_LIMITS.operationRefs} per read; [] when no tool schemas are needed). Read separate selections if more are needed, then save one atomic edit. Returns exact schemas, models and the authoring reference. Omit automationId for a new draft. Does not create, run, publish or grant access.`,
+    effect: "read_only", approval: "request_policy", fixedParams: { action: "prepare_draft" },
+    input: { type: "object", additionalProperties: false,
+        properties: { automationId, operationRefs: { type: "array", minItems: 0, maxItems: AUTOMATION_AUTHORING_PREPARATION_LIMITS.operationRefs,
+                items: { type: "string", minLength: 1, maxLength: AUTOMATION_CATALOG_OPERATION_REF_MAX_LENGTH } } },
+        required: ["operationRefs"] },
+    selectionControlIds: ["operationRefs"],
+};