@abot-ai/runtime 1.4.0 → 1.6.0

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

@@ -0,0 +1,130 @@
+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 structured 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: "data" } } },
+        ] },
+    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: "Tool display output; may be counts/status only, not serialized data.",
+            data: "Structured tool output, when provided. Omit pointer to pass it whole, without knowing field names." },
+        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.",
+        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;

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;