@abot-ai/runtime 1.5.0 → 1.6.0

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,36 @@
+import { projectToolTargetReferences } from "../../adapters/registered-tool-worker-capabilities/result-evidence.js";
+import { CAPABILITY_ADAPTER_RESULT_SERIALIZED_MAX_BYTES, normalizeCapabilityAdapterResult, } from "../../orchestration/capability-adapters/result.js";
+export class AutomationDraftReceiptCapacityError extends Error {
+    details = {
+        code: "automation_authoring_receipt_too_large",
+        message: "The complete draft is too large to return through model authoring. No changes were saved. Use Studio to inspect or edit large drafts.",
+        maxResultBytes: CAPABILITY_ADAPTER_RESULT_SERIALIZED_MAX_BYTES,
+    };
+    constructor() { super("automation_authoring_receipt_too_large"); }
+}
+function isOversizedDraftReceipt(result) {
+    if (result.ok)
+        return false;
+    return result.code === "result_too_large";
+}
+/** Validate the complete result once, including references later added for a direct root. */
+export function prepareAutomationDraftReceipt(receipt, admission) {
+    const output = { ok: true, output: JSON.stringify(receipt), producedNewInformation: true,
+        data: { mutationEvidence: admission.mutationEvidence, currentStateEvidence: true } };
+    // These descriptors are only inputs to the existing target projector, never emitted actions.
+    const selectedTargets = (admission.operation.selectionControlIds ?? []).map((key) => ({
+        type: "selected_control",
+        target: typeof admission.params[key] === "string" ? admission.params[key] : undefined,
+    }));
+    const references = projectToolTargetReferences(selectedTargets);
+    const normalized = normalizeCapabilityAdapterResult({
+        kind: "registered_tool_execution_result_v1", authority: "registered_plugin", status: "executed",
+        result: { ...output, tool: admission.tool, progress: false },
+        ...(references.length > 0 ? { references } : {}),
+    });
+    if (normalized.ok)
+        return output;
+    if (isOversizedDraftReceipt(normalized))
+        throw new AutomationDraftReceiptCapacityError();
+    throw new Error("automation_authoring_receipt_invalid");
+}

package/dist/src/runtime/capabilities/automations/event-presentation.d.ts

@@ -0,0 +1,3 @@
+import type { ToolEventPresentation } from "../../../capabilities/tool-types.js";
+/** Use the same declared call fields and bounded result excerpt as plugin tools. */
+export declare const AUTOMATION_TOOL_EVENT_PRESENTATION: ToolEventPresentation;

package/dist/src/runtime/capabilities/automations/event-presentation.js

@@ -0,0 +1,18 @@
+/** Use the same declared call fields and bounded result excerpt as plugin tools. */
+export const AUTOMATION_TOOL_EVENT_PRESENTATION = {
+    metadata: {
+        automationAction: { param: "action", kind: "string" },
+        automationId: { param: "automationId", kind: "string" },
+        automationTitle: { param: "title", kind: "string" },
+        expectedRevision: { param: "expectedRevision", kind: "number" },
+        nodeId: { param: "nodeId", kind: "string" },
+        agentId: { param: "agentId", kind: "string" },
+        view: { param: "view", kind: "string" },
+        offset: { param: "offset", kind: "number" },
+        toolName: { param: "toolName", kind: "string" },
+        operationId: { param: "operationId", kind: "string" },
+    },
+    resultMetadata: {
+        outputPreview: { path: "output", kind: "preview" },
+    },
+};

package/dist/src/runtime/capabilities/automations/model-tool-contract.d.ts

@@ -0,0 +1,3 @@
+import type { ToolNormalInvocationContract } from "../../../capabilities/tool-types.js";
+/** The model writes connected graphs through automation_builder; direct legacy actions stay supported. */
+export declare const automationModelToolContract: ToolNormalInvocationContract;

package/dist/src/runtime/capabilities/automations/model-tool-contract.js

@@ -0,0 +1,34 @@
+import { automationDraftToolContract } from "./tool-contract.js";
+import { automationAuthoringPreparationOperation } from "./authoring-catalog-contract.js";
+import { AUTOMATION_AUTHORING_PREPARATION_LIMITS } from "./authoring-preparation-limits.js";
+function authoringOperation(operationId) {
+    const operation = [...automationDraftToolContract.operations, automationAuthoringPreparationOperation]
+        .find((candidate) => candidate.operationId === operationId);
+    if (!operation)
+        throw new Error(`automation_authoring_contract_missing:${operationId}`);
+    return { ...operation, selectionControlIds: operation.input.required };
+}
+/** These reads need complete selected inputs, not another model call to fill optional controls. */
+function completeAuthoringRead(operationId, fields) {
+    const operation = authoringOperation(operationId);
+    return { ...operation, input: { ...operation.input,
+            properties: Object.fromEntries(fields.map((field) => [field, operation.input.properties[field]])),
+            required: fields }, selectionControlIds: fields };
+}
+const catalogIndex = completeAuthoringRead("browse_catalog", ["offset"]);
+/** The model writes connected graphs through automation_builder; direct legacy actions stay supported. */
+export const automationModelToolContract = {
+    version: automationDraftToolContract.version,
+    operations: [
+        { ...catalogIndex, fixedParams: { ...catalogIndex.fixedParams, view: "index" },
+            summary: "Discover available workflow tools, models and saved agents without creating a draft. Start at offset 0; use nextOffset only if more references are needed. Select needed operation refs for prepare_draft within its per-read limit; use multiple reads if needed, then save the entire connected workflow with create_automation_draft. This reads configuration only; it does not run future steps or grant access." },
+        { ...completeAuthoringRead("prepare_draft", ["operationRefs"]),
+            summary: `Prepare authoring from selected operationRefs needed for this edit. Copy 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). Existing refs need no rediscovery; read separate selections if more are needed. Returns schemas, models and the authoring reference. Then save one atomic create_automation_draft or apply_automation_draft_changes. Creates no draft and runs no workflow steps.` },
+        completeAuthoringRead("list_drafts", ["offset"]),
+        authoringOperation("read_draft"),
+        authoringOperation("validate_draft"),
+        { ...authoringOperation("add_saved_agent"),
+            summary: "Reuse an exact saved-agent revision in an existing draft. For a NEW workflow made solely from saved agents, first use create_automation_draft with a definition-only plan, then insert saved revisions using its returned IDs and revision. Never invent a placeholder step. Reusing a saved agent does not inherit an automation permission grant." },
+        authoringOperation("save_agent"),
+    ],
+};

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

@@ -0,0 +1,3 @@
+import type { ToolNormalInvocationContract } from "../../../capabilities/tool-types.js";
+/** Draft-only authoring. No permission, publish, activation or run control. */
+export declare const automationDraftToolContract: ToolNormalInvocationContract;

package/dist/src/runtime/capabilities/automations/tool-contract.js

@@ -0,0 +1,65 @@
+import { automationAuthoringCatalogOperations } from "./authoring-catalog-contract.js";
+import { automationAuthoringInputOperations } from "./authoring-input-contracts.js";
+const text = (maximum = 4_096) => ({
+    type: "string", minLength: 1, maxLength: maximum,
+});
+const optionalText = (maximum = 4_096) => ({
+    type: "string", minLength: 0, maxLength: maximum,
+});
+const id = text(128);
+const revision = {
+    type: "integer", minimum: 1, maximum: 2_147_483_647,
+};
+const index = {
+    type: "integer", minimum: 0, maximum: 64,
+};
+const choice = (...values) => ({
+    type: "string", enum: values,
+});
+const common = { automationId: id, expectedRevision: revision };
+const node = { ...common, nodeId: id };
+function operation(operationId, summary, properties, required, effect = "mutating", selectionControlIds) {
+    return {
+        operationId, summary, effect, approval: "request_policy",
+        fixedParams: { action: operationId },
+        input: { type: "object", additionalProperties: false, properties, required },
+        ...(selectionControlIds === undefined ? {} : { selectionControlIds }),
+    };
+}
+/** Draft-only authoring. No permission, publish, activation or run control. */
+export const automationDraftToolContract = {
+    version: 1,
+    operations: [
+        operation("create_draft", "Create a NEW empty automation draft. The receipt provides its exact automation ID, root sequence ID and revision for subsequent edits. To continue an existing draft, use list_drafts and read_draft instead.", { title: text(160) }, ["title"]),
+        operation("list_drafts", "Find existing automation drafts by title and exact ID without opening or changing them. Returns up to 50 compact summaries; pass nextOffset as offset for another page, then read_draft by exact ID before editing.", { offset: { type: "integer", minimum: 0, maximum: 2_147_483_647 } }, [], "read_only"),
+        operation("read_draft", "Read the current draft by exact automation ID, including node IDs, revision and the full operationRefs inventory. preparation declares the per-read limit and whether a smaller selection is required for prepare_draft. Builder writes already return the exact saved draft; read when state is unknown or after a revision conflict.", { automationId: id }, ["automationId"], "read_only", ["automationId"]),
+        ...automationAuthoringCatalogOperations,
+        { ...operation("catalog", "List the first compact page of tools available to the FUTURE automation workflow, plus models and saved agents. This is not the Studio editing API. Follow nextOffset with browse_catalog view=index; get exact inputs with view=operation. Discovery never executes workflow steps or grants permission.", { automationId: id }, ["automationId"], "read_only", ["automationId"]),
+            fixedParams: { action: "catalog", projection: "index" } },
+        operation("validate_draft", "Check the current draft for publication issues without publishing or running it.", { automationId: id }, ["automationId"], "read_only", ["automationId"]),
+        operation("set_details", "Set the draft title, objective or working directory. The working directory must be an absolute path on the Runtime host; omit it to keep the current setting, or send an empty string to use the configured default.", { ...common, title: optionalText(160), objective: optionalText(), workingDirectory: optionalText(1_024) }, ["automationId", "expectedRevision"]),
+        operation("set_trigger_manual", "Use a manual trigger for this draft.", common, ["automationId", "expectedRevision"], "mutating", ["automationId", "expectedRevision"]),
+        operation("set_trigger_schedule", "Set a schedule trigger. scheduleJson is only the scheduler schedule object, not a whole automation definition.", { ...common, scheduleJson: text(2_048) }, ["automationId", "expectedRevision", "scheduleJson"]),
+        operation("set_trigger_folder", "Set a folder trigger and its scan cadence. Configure source separately.", { ...common, checkEveryMs: { type: "integer", minimum: 1_000, maximum: 31_536_000_000 }, minimumEligibleFiles: { type: "integer", minimum: 1, maximum: 100 } }, ["automationId", "expectedRevision", "checkEveryMs", "minimumEligibleFiles"]),
+        operation("set_folder_source", "Set the runtime-accessible folder and exclusions. New source IDs are generated by the draft owner. Exclude output and archive paths from collection.", { ...common, path: text(1_024), mode: choice("per_file", "batch"), recursive: { type: "boolean" }, includeExisting: { type: "boolean" }, maxBatchFiles: { type: "integer", minimum: 1, maximum: 100 }, includePatterns: { type: "array", items: text(256), minItems: 0, maxItems: 64 }, excludePatterns: { type: "array", items: text(256), minItems: 0, maxItems: 64 } }, ["automationId", "expectedRevision", "path", "mode", "recursive", "includeExisting", "maxBatchFiles"]),
+        operation("remove_folder_source", "Remove the optional folder source.", common, ["automationId", "expectedRevision"]),
+        operation("set_run_inputs", "Set named static run inputs using a bounded JSON object, not a whole automation definition.", { ...common, inputsJson: text() }, ["automationId", "expectedRevision", "inputsJson"]),
+        operation("set_limits", "Set only supplied positive run limits; omitted limits keep their current values.", { ...common, maxConcurrentNodes: revision, maxModelCallsPerRun: revision, maxToolCallsPerRun: revision, maxRunDurationMs: revision, maxRunsPerDay: revision, maxStoredArtifactBytes: revision, stopReportDeadlineMs: revision }, ["automationId", "expectedRevision"]),
+        operation("add_agent", "Add an agent at the exact position. Placement does not pass earlier outputs; use the returned node ID with bind_step_result to connect each needed earlier result.", { ...common, parentSequenceId: id, index, title: optionalText(160), modelProfileId: optionalText(128), agentMode: choice("fast", "reasoning", "deep"), roleInstructions: optionalText(), prompt: optionalText(), onFailure: choice("stop", "skip") }, ["automationId", "expectedRevision", "parentSequenceId", "index", "title", "modelProfileId", "agentMode", "roleInstructions", "prompt", "onFailure"]),
+        operation("add_saved_agent", "Add an exact saved-agent revision as a draft step. It does not inherit an automation grant.", { ...common, parentSequenceId: id, index, agentId: id, agentRevision: revision }, ["automationId", "expectedRevision", "parentSequenceId", "index", "agentId", "agentRevision"]),
+        operation("add_tool", "Add a tool step by exact catalog operation reference. Set each input with set_step_literal or bind_step_result; advanced bindings use set_tool_controls.", { ...common, parentSequenceId: id, index, title: optionalText(160), toolName: text(64), operationId: text(64), contractVersion: revision, onFailure: choice("stop", "skip") }, ["automationId", "expectedRevision", "parentSequenceId", "index", "title", "toolName", "operationId", "contractVersion", "onFailure"]),
+        operation("edit_agent", "Edit selected agent fields without rewriting its other configuration.", { ...node, modelProfileId: optionalText(128), agentMode: choice("fast", "reasoning", "deep"), roleInstructions: optionalText(), prompt: optionalText() }, ["automationId", "expectedRevision", "nodeId"]),
+        operation("set_step_policy", "Set a step's title or failure behavior; skip continues after a failed step, stop ends the run.", { ...node, title: optionalText(160), onFailure: choice("stop", "skip") }, ["automationId", "expectedRevision", "nodeId"]),
+        ...automationAuthoringInputOperations,
+        operation("set_agent_inputs", "Advanced: replace all named agent inputs with canonical bindings JSON. Prefer bind_step_result for one earlier result. Example: {\"source\":{\"kind\":\"node_result\",\"nodeId\":\"<id>\",\"select\":\"text\"}}. Unbound outputs are not passed.", { ...node, bindingsJson: text() }, ["automationId", "expectedRevision", "nodeId", "bindingsJson"]),
+        operation("set_agent_tools", "Advanced: replace all selected operations with a bounded JSON array of operation/usage objects. Prefer select_agent_tool for one operation. This does not grant any operation.", { ...node, toolsJson: text() }, ["automationId", "expectedRevision", "nodeId", "toolsJson"]),
+        operation("set_agent_result", "Set one agent's text or structured JSON result declaration using a bounded JSON fragment.", { ...node, resultJson: text() }, ["automationId", "expectedRevision", "nodeId", "resultJson"]),
+        operation("set_agent_acceptance", "Set one agent's bounded acceptance checks as a JSON array; use [] to clear checks.", { ...node, acceptanceJson: text() }, ["automationId", "expectedRevision", "nodeId", "acceptanceJson"]),
+        operation("set_tool_controls", "Replace this tool step's named inputs. An earlier result uses {\"kind\":\"node_result\",\"nodeId\":\"<prior-id>\",\"select\":\"text\"}. For a new output file per run, bind its path to {\"kind\":\"run_file\",\"fileName\":\"report.md\"}; this resolves inside the working directory under a unique run folder.", { ...node, bindingsJson: text() }, ["automationId", "expectedRevision", "nodeId", "bindingsJson"]),
+        operation("set_tool_payload", "Bind this tool step's payload to one ValueBinding. To pass an earlier result, use {\"kind\":\"node_result\",\"nodeId\":\"<prior-id>\",\"select\":\"text\"}.", { ...node, payloadJson: text() }, ["automationId", "expectedRevision", "nodeId", "payloadJson"]),
+        operation("remove_step", "Remove one step by its exact node ID.", node, ["automationId", "expectedRevision", "nodeId"]),
+        operation("move_step", "Move one step to an exact sequence and position.", { ...node, parentSequenceId: id, index }, ["automationId", "expectedRevision", "nodeId", "parentSequenceId", "index"]),
+        operation("parallel_steps", "Fork adjacent executable sibling steps into parallel branches that rejoin before the following step. Pass 2–8 exact node IDs.", { ...common, nodeIds: { type: "array", items: id, minItems: 2, maxItems: 8 } }, ["automationId", "expectedRevision", "nodeIds"]),
+        operation("save_agent", "Save one existing draft agent as a reusable versioned template. It copies its configured role and tools, without bound run inputs, grants or run history.", { ...node, agentId: id, expectedAgentRevision: revision }, ["automationId", "expectedRevision", "nodeId"]),
+    ],
+};

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

@@ -0,0 +1,4 @@
+import type { ToolModuleDeclaration } from "../../../capabilities/tool-types.js";
+import type { AutomationService } from "../../automations/service.js";
+/** The caller injects the single environment service after tool registry construction. */
+export declare function createAutomationDraftToolModule(getService: () => AutomationService, ready: () => Promise<void>): ToolModuleDeclaration;

package/dist/src/runtime/capabilities/automations/tool-module.js

@@ -0,0 +1,286 @@
+import { Buffer } from "node:buffer";
+import { AUTOMATION_TOOL_EVENT_PRESENTATION } from "./event-presentation.js";
+import { automationDraftPreparationReceipt } from "./draft-operation-refs.js";
+import { AutomationDraftReceiptCapacityError, prepareAutomationDraftReceipt } from "./draft-receipt-admission.js";
+import { readAutomationDraftIndex } from "./draft-index.js";
+import { automationModelToolContract } from "./model-tool-contract.js";
+import { readAutomationAuthoringPreparation } from "./authoring-preparation.js";
+import { automationAuthoringCatalogScope, readAutomationAuthoringCatalog, readAutomationAuthoringCatalogIndex } from "./authoring-catalog.js";
+import { AUTOMATION_AUTHORING_REFERENCE } from "../automation-builder/authoring-reference.js";
+import { executeAutomationAuthoringInput, isAutomationAuthoringInputAction, } from "./authoring-inputs.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 requiredInteger(params, key, minimum = 0) {
+    const value = params[key];
+    if (!Number.isSafeInteger(value) || Number(value) < minimum)
+        throw new Error(`automation_${key}_invalid`);
+    return Number(value);
+}
+function jsonFragment(params, key) {
+    const source = requiredText(params, key);
+    if (Buffer.byteLength(source, "utf8") > 4_096)
+        throw new Error("automation_graph_invalid");
+    try {
+        return JSON.parse(source);
+    }
+    catch {
+        throw new Error("automation_graph_invalid");
+    }
+}
+function jsonObject(params, key) {
+    const value = jsonFragment(params, key);
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("automation_graph_invalid");
+    return value;
+}
+function jsonArray(params, key) {
+    const value = jsonFragment(params, key);
+    if (!Array.isArray(value))
+        throw new Error("automation_graph_invalid");
+    return value;
+}
+function supplied(params, keys) {
+    const patch = Object.fromEntries(keys
+        .filter((key) => params[key] !== undefined)
+        .map((key) => [key, params[key]]));
+    if (Object.keys(patch).length === 0)
+        throw new Error("automation_graph_invalid");
+    return patch;
+}
+function nodeIds(node) {
+    if (node.kind === "sequence")
+        return [node.id, ...node.children.flatMap(nodeIds)];
+    if (node.kind === "parallel")
+        return [node.id, ...node.branches.flatMap(nodeIds)];
+    return [node.id];
+}
+function changedIds(before, after) {
+    const previous = new Set(nodeIds(before.body));
+    return nodeIds(after.body).filter((id) => !previous.has(id));
+}
+async function mutate(service, params, mutation) {
+    const automationId = requiredText(params, "automationId");
+    const expectedRevision = requiredInteger(params, "expectedRevision", 1);
+    const before = await service.getDraft(automationId);
+    if (!before)
+        throw new Error("automation_not_found");
+    const next = await service.updateDraft(automationId, expectedRevision, mutation);
+    return {
+        automationId,
+        revision: next.revision,
+        newNodeIds: changedIds(before.definition, next.definition),
+        ...(next.definition.source ? { sourceId: next.definition.source.sourceId } : {}),
+    };
+}
+async function execute(service, params) {
+    const action = requiredText(params, "action");
+    if (action === "create_draft") {
+        const draft = await service.create(requiredText(params, "title"));
+        return { automationId: draft.automationId, revision: draft.revision,
+            rootSequenceId: draft.definition.body.id };
+    }
+    if (action === "list_drafts")
+        return readAutomationDraftIndex(service, params.offset === undefined
+            ? 0 : params.offset);
+    if (action === "browse_catalog")
+        return readAutomationAuthoringCatalog(service, params);
+    if (action === "prepare_draft")
+        return readAutomationAuthoringPreparation(service, params);
+    const automationId = requiredText(params, "automationId");
+    if (isAutomationAuthoringInputAction(action))
+        return executeAutomationAuthoringInput(service, params);
+    if (action === "read_draft") {
+        const draft = await service.getDraft(automationId);
+        if (!draft)
+            throw new Error("automation_not_found");
+        return { draft, ...automationDraftPreparationReceipt(draft.definition) };
+    }
+    const isCatalogIndexRequest = action === "catalog" && params.projection === "index";
+    if (isCatalogIndexRequest)
+        return readAutomationAuthoringCatalogIndex(service, automationId, 0);
+    const hasUnsupportedCatalogProjection = action === "catalog" && params.projection !== undefined;
+    if (hasUnsupportedCatalogProjection)
+        throw new Error("automation_catalog_projection_invalid");
+    if (action === "catalog") {
+        const catalog = await service.catalog(automationId);
+        return { kind: "automation_authoring_catalog_v1", grantsPermissions: false,
+            catalogScope: automationAuthoringCatalogScope(automationId),
+            permissions: AUTOMATION_AUTHORING_REFERENCE.permissions,
+            operations: catalog.grantableOperations.map(({ fixedParams: _fixedParams, ...operation }) => operation),
+            grantedOperations: catalog.operations.map(({ toolName, operationId, contractVersion }) => ({ toolName, operationId, contractVersion })),
+            models: catalog.models,
+            savedAgents: catalog.savedAgents.map((agent) => ({
+                agentId: agent.id, revision: agent.revision, title: agent.title,
+                modelProfileId: agent.modelProfileId,
+            })) };
+    }
+    if (action === "validate_draft")
+        return { issues: await service.validate(automationId) };
+    if (action === "save_agent") {
+        const saved = await service.saveAgentFromDraft({
+            automationId,
+            nodeId: requiredText(params, "nodeId"),
+            expectedDraftRevision: requiredInteger(params, "expectedRevision", 1),
+            ...(params.agentId !== undefined ? { agentId: requiredText(params, "agentId") } : {}),
+            ...(params.expectedAgentRevision !== undefined
+                ? { expectedAgentRevision: requiredInteger(params, "expectedAgentRevision", 1) }
+                : {}),
+        });
+        return { agentId: saved.agentId, revision: saved.revision, title: saved.agent.title };
+    }
+    if (action === "set_details") {
+        const patch = supplied(params, ["title", "objective", "workingDirectory"]);
+        if (patch.workingDirectory === "")
+            patch.workingDirectory = null;
+        return mutate(service, params, { kind: "update_definition", patch });
+    }
+    if (action === "set_trigger_manual")
+        return mutate(service, params, { kind: "update_definition", patch: { trigger: { kind: "manual" } } });
+    if (action === "set_trigger_schedule")
+        return mutate(service, params, { kind: "update_definition", patch: {
+                trigger: { kind: "schedule", schedule: jsonObject(params, "scheduleJson") },
+            } });
+    if (action === "set_trigger_folder")
+        return mutate(service, params, { kind: "update_definition", patch: {
+                trigger: { kind: "folder",
+                    checkEveryMs: requiredInteger(params, "checkEveryMs", 1),
+                    minimumEligibleFiles: requiredInteger(params, "minimumEligibleFiles", 1) },
+            } });
+    if (action === "set_folder_source") {
+        const draft = await service.getDraft(automationId);
+        if (!draft)
+            throw new Error("automation_not_found");
+        return mutate(service, params, { kind: "update_definition", patch: {
+                source: {
+                    sourceId: draft.definition.source?.sourceId ?? "",
+                    location: { kind: "runtime_path", path: requiredText(params, "path") },
+                    mode: requiredText(params, "mode"),
+                    recursive: params.recursive,
+                    includeExisting: params.includeExisting,
+                    maxBatchFiles: requiredInteger(params, "maxBatchFiles", 1),
+                    includePatterns: params.includePatterns ?? [],
+                    excludePatterns: params.excludePatterns ?? [],
+                },
+            } });
+    }
+    if (action === "remove_folder_source")
+        return mutate(service, params, { kind: "update_definition", patch: { source: null } });
+    if (action === "set_run_inputs")
+        return mutate(service, params, { kind: "update_definition", patch: { inputs: jsonObject(params, "inputsJson") } });
+    if (action === "set_limits") {
+        const draft = await service.getDraft(automationId);
+        if (!draft)
+            throw new Error("automation_not_found");
+        const patch = supplied(params, ["maxConcurrentNodes", "maxModelCallsPerRun",
+            "maxToolCallsPerRun", "maxRunDurationMs", "maxRunsPerDay",
+            "maxStoredArtifactBytes", "stopReportDeadlineMs"]);
+        return mutate(service, params, { kind: "update_definition", patch: {
+                limits: { ...draft.definition.limits, ...patch },
+            } });
+    }
+    if (action === "add_agent")
+        return mutate(service, params, { kind: "add_node",
+            parentSequenceId: requiredText(params, "parentSequenceId"),
+            index: requiredInteger(params, "index"), nodeWithoutId: {
+                kind: "agent", title: params.title, onFailure: params.onFailure,
+                modelProfileId: params.modelProfileId, agentMode: params.agentMode,
+                roleInstructions: params.roleInstructions, prompt: params.prompt,
+                inputs: {}, tools: [], result: { kind: "text" },
+            } });
+    if (action === "add_saved_agent") {
+        const agentId = requiredText(params, "agentId");
+        const agentRevision = requiredInteger(params, "agentRevision", 1);
+        const saved = await service.getSavedAgent(agentId, agentRevision);
+        if (!saved)
+            throw new Error("automation_saved_agent_not_found");
+        const { id: _id, ...configuration } = saved.agent;
+        return mutate(service, params, { kind: "add_node",
+            parentSequenceId: requiredText(params, "parentSequenceId"),
+            index: requiredInteger(params, "index"), nodeWithoutId: {
+                ...configuration, savedAgentOrigin: { agentId, revision: agentRevision },
+            } });
+    }
+    if (action === "add_tool")
+        return mutate(service, params, { kind: "add_node",
+            parentSequenceId: requiredText(params, "parentSequenceId"),
+            index: requiredInteger(params, "index"), nodeWithoutId: {
+                kind: "tool", title: params.title, onFailure: params.onFailure,
+                operation: { toolName: params.toolName, operationId: params.operationId,
+                    contractVersion: params.contractVersion }, controls: {},
+            } });
+    const nodeId = requiredText(params, "nodeId");
+    if (action === "edit_agent")
+        return mutate(service, params, { kind: "update_node", nodeId,
+            patch: supplied(params, ["modelProfileId", "agentMode", "roleInstructions", "prompt"]) });
+    if (action === "set_step_policy")
+        return mutate(service, params, { kind: "update_node", nodeId,
+            patch: supplied(params, ["title", "onFailure"]) });
+    if (action === "set_agent_inputs")
+        return mutate(service, params, { kind: "update_node", nodeId,
+            patch: { inputs: jsonObject(params, "bindingsJson") } });
+    if (action === "set_agent_tools")
+        return mutate(service, params, { kind: "update_node", nodeId,
+            patch: { tools: jsonArray(params, "toolsJson") } });
+    if (action === "set_agent_result")
+        return mutate(service, params, { kind: "update_node", nodeId,
+            patch: { result: jsonObject(params, "resultJson") } });
+    if (action === "set_agent_acceptance")
+        return mutate(service, params, { kind: "update_node", nodeId,
+            patch: { acceptance: jsonArray(params, "acceptanceJson") } });
+    if (action === "set_tool_controls")
+        return mutate(service, params, { kind: "update_node", nodeId,
+            patch: { controls: jsonObject(params, "bindingsJson") } });
+    if (action === "set_tool_payload")
+        return mutate(service, params, { kind: "update_node", nodeId,
+            patch: { payload: jsonObject(params, "payloadJson") } });
+    if (action === "remove_step")
+        return mutate(service, params, { kind: "remove_node", nodeId });
+    if (action === "move_step")
+        return mutate(service, params, { kind: "move_node", nodeId,
+            parentSequenceId: requiredText(params, "parentSequenceId"),
+            index: requiredInteger(params, "index") });
+    if (action === "parallel_steps") {
+        if (!Array.isArray(params.nodeIds) || !params.nodeIds.every((id) => typeof id === "string"))
+            throw new Error("automation_graph_invalid");
+        return mutate(service, params, { kind: "wrap_parallel", nodeIds: params.nodeIds });
+    }
+    throw new Error("automation_action_unknown");
+}
+/** The caller injects the single environment service after tool registry construction. */
+export function createAutomationDraftToolModule(getService, ready) {
+    return {
+        definition: {
+            name: "automations",
+            eventPresentation: AUTOMATION_TOOL_EVENT_PRESENTATION,
+            description: "Inspect and make targeted edits to ABot Studio drafts. For a complete connected workflow or several related edits, prefer automation_builder create_automation_draft or apply_automation_draft_changes. Catalog discovery lists tools for the FUTURE workflow, not Studio editing commands; fetch operation detail only when needed. Successful edits return exact revision and newNodeIds for reuse; read_draft when state is unknown or after a revision conflict. Draft authoring only: the user grants permissions, publishes and runs automations.",
+            routingCapability: "semantic_mutation",
+            catalogGroups: ["automations"],
+            developmentRoles: ["auxiliary"],
+            controlsRefinement: "mechanical_when_complete",
+        },
+        normalInvocation: automationModelToolContract,
+        async implementation(params, context) {
+            try {
+                await ready();
+                context?.abortSignal?.throwIfAborted();
+                const result = await execute(getService(), params);
+                if (params.action === "read_draft") {
+                    const operation = automationModelToolContract.operations.find(({ operationId }) => operationId === "read_draft");
+                    return prepareAutomationDraftReceipt(result, { tool: "automations", operation, params, mutationEvidence: false });
+                }
+                const isDraftMutation = !["list_drafts", "read_draft", "catalog", "browse_catalog", "prepare_draft", "validate_draft"].includes(String(params.action));
+                return { ok: true, output: JSON.stringify(result), producedNewInformation: true,
+                    data: { mutationEvidence: isDraftMutation, currentStateEvidence: true } };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                const output = error instanceof AutomationDraftReceiptCapacityError ? JSON.stringify(error.details) : message;
+                return { ok: false, output, error: message, producedNewInformation: false };
+            }
+        },
+    };
+}

package/dist/src/runtime/capabilities/runtime-path-namespace.d.ts

@@ -0,0 +1,6 @@
+/** A relative component cannot normalize into a foreign drive namespace. */
+export declare function isRuntimePathNamespaceCompatible(value: string, platform?: NodeJS.Platform): boolean;
+/** Preserve a native Windows UNC root while normalizing scoped tool paths. */
+export declare function normalizeRuntimePathForScope(value: string, platform?: NodeJS.Platform): string;
+/** A different Windows drive or share produces an absolute relative result. */
+export declare function isRuntimePathWithinRoot(target: string, root: string, platform?: NodeJS.Platform): boolean;

package/dist/src/runtime/capabilities/runtime-path-namespace.js

@@ -0,0 +1,48 @@
+import { posix, win32 } from "node:path";
+function logicalSeparators(value) {
+    return value.replaceAll("\\", "/");
+}
+function hasDrivePrefix(value) {
+    return /^[A-Za-z]:/u.test(value);
+}
+function hasQualifiedDrive(value) {
+    return /^[A-Za-z]:\//u.test(value);
+}
+function hasQualifiedNetworkRoot(value) {
+    if (value.startsWith("//?/") || value.startsWith("//./"))
+        return false;
+    return /^\/\/[^/]+\/[^/]+(?:\/|$)/u.test(value);
+}
+function hasBackslashNetworkOrDeviceRoot(value) {
+    const prefix = value.slice(0, 2);
+    const networkRoot = /^[\\/]{2}$/u.test(prefix) && prefix.includes("\\");
+    return networkRoot || value.startsWith("\\??\\");
+}
+/** A relative component cannot normalize into a foreign drive namespace. */
+export function isRuntimePathNamespaceCompatible(value, platform = process.platform) {
+    const logical = logicalSeparators(value);
+    if (platform !== "win32" && hasBackslashNetworkOrDeviceRoot(value))
+        return false;
+    if (hasDrivePrefix(logical))
+        return platform === "win32" && hasQualifiedDrive(logical);
+    if (platform === "win32" && logical.startsWith("/"))
+        return hasQualifiedNetworkRoot(logical);
+    // Use the standard path grammar before checking a relative drive prefix.
+    return !hasDrivePrefix(posix.normalize(logical));
+}
+/** Preserve a native Windows UNC root while normalizing scoped tool paths. */
+export function normalizeRuntimePathForScope(value, platform = process.platform) {
+    if (platform === "win32" && win32.isAbsolute(value)) {
+        return logicalSeparators(win32.normalize(value));
+    }
+    return posix.normalize(logicalSeparators(value));
+}
+/** A different Windows drive or share produces an absolute relative result. */
+export function isRuntimePathWithinRoot(target, root, platform = process.platform) {
+    const paths = platform === "win32" ? win32 : posix;
+    const relative = paths.relative(root, target);
+    if (paths.isAbsolute(relative))
+        return false;
+    return (relative === "" ||
+        (relative !== ".." && !relative.startsWith(`..${paths.sep}`)));
+}