@abot-ai/runtime 1.4.0 → 1.6.0

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

@@ -0,0 +1,158 @@
+import { TOOL_NORMAL_INVOCATION_IDENTIFIER_MAX_LENGTH } from "../../../capabilities/normal-invocation/contracts.js";
+import { AUTOMATION_AUTHORING_REFERENCE } from "../automation-builder/authoring-reference.js";
+// Percent-encoding expands one UTF-16 unit by at most nine characters.
+// Both canonical identifiers are bounded; preserve every safe integer version too.
+export const AUTOMATION_CATALOG_OPERATION_REF_MAX_LENGTH = 2 * TOOL_NORMAL_INVOCATION_IDENTIFIER_MAX_LENGTH * 9 + 2 + String(Number.MAX_SAFE_INTEGER).length;
+const PAGE_SIZE = 50;
+const LABEL_MAX_LENGTH = 160;
+function isCatalogIndexOffset(value) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value))
+        return false;
+    if (value < 0)
+        return false;
+    return value <= 2_147_483_647;
+}
+function catalogPage(items, offset) {
+    const page = items.slice(offset, offset + PAGE_SIZE);
+    const omittedCount = Math.max(0, items.length - offset - page.length);
+    return { items: page, offset, totalCount: items.length, omittedCount,
+        nextOffset: omittedCount > 0 ? offset + page.length : null };
+}
+function operationKey(operation) {
+    return JSON.stringify([operation.toolName, operation.operationId, operation.contractVersion]);
+}
+/** Opaque identity copied from discovery; consumers never synthesize or parse it. */
+export function automationCatalogOperationRef(operation) {
+    return `${encodeURIComponent(operation.toolName)}/${encodeURIComponent(operation.operationId)}@${operation.contractVersion}`;
+}
+function isCatalogReferenceName(value) {
+    if (typeof value !== "string")
+        return false;
+    if (value.length < 1 || value.length > 64)
+        return false;
+    return value.trim() === value && value.trim().length > 0;
+}
+function isCatalogAutomationId(value) {
+    if (typeof value !== "string")
+        return false;
+    if (value.trim().length === 0)
+        return false;
+    return value.length <= 128;
+}
+export function requireAutomationCatalogScope(params) {
+    if (params.automationId === undefined)
+        return "";
+    if (!isCatalogAutomationId(params.automationId))
+        throw new Error("automation_catalog_parameters_invalid");
+    return params.automationId;
+}
+/** Requested grant scope only; catalog reads do not establish draft existence. */
+export function automationAuthoringCatalogScope(automationId) {
+    return automationId
+        ? { kind: "automation", automationId }
+        : { kind: "pre_draft" };
+}
+function isCatalogContractVersion(value) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value))
+        return false;
+    if (value < 1)
+        return false;
+    return value <= 2_147_483_647;
+}
+function requireCatalogOperationReference(params) {
+    const { toolName, operationId, contractVersion } = params;
+    if (!isCatalogReferenceName(toolName))
+        throw new Error("automation_catalog_operation_reference_invalid");
+    if (!isCatalogReferenceName(operationId))
+        throw new Error("automation_catalog_operation_reference_invalid");
+    if (!isCatalogContractVersion(contractVersion))
+        throw new Error("automation_catalog_operation_reference_invalid");
+    return { toolName, operationId, contractVersion };
+}
+function hasCatalogOperationReferenceFields(params) {
+    return ["toolName", "operationId", "contractVersion"].some((key) => params[key] !== undefined);
+}
+/** Validate the view-specific flat API before reading the canonical catalog. */
+export async function readAutomationAuthoringCatalog(service, params) {
+    const automationId = requireAutomationCatalogScope(params);
+    const isIndexView = params.view === "index";
+    const hasUnexpectedIndexReference = isIndexView && hasCatalogOperationReferenceFields(params);
+    if (hasUnexpectedIndexReference)
+        throw new Error("automation_catalog_parameters_invalid");
+    if (isIndexView) {
+        return readAutomationAuthoringCatalogIndex(service, automationId, params.offset === undefined ? 0 : params.offset);
+    }
+    const isOperationView = params.view === "operation";
+    if (!isOperationView)
+        throw new Error("automation_catalog_view_invalid");
+    const hasUnexpectedOperationOffset = params.offset !== undefined;
+    if (hasUnexpectedOperationOffset)
+        throw new Error("automation_catalog_parameters_invalid");
+    const reference = requireCatalogOperationReference(params);
+    return readAutomationAuthoringCatalogOperation(service, automationId, reference.toolName, reference.operationId, reference.contractVersion);
+}
+/** A paged discovery view derived only from the configured automation catalog. */
+export async function readAutomationAuthoringCatalogIndex(service, automationId, offset) {
+    if (!isCatalogIndexOffset(offset))
+        throw new Error("automation_offset_invalid");
+    const catalog = await service.catalog(automationId);
+    return projectAutomationAuthoringCatalogIndex(catalog, offset, automationId);
+}
+/** Shared bounded projection; preparation reuses its already-read catalog snapshot. */
+export function projectAutomationAuthoringCatalogIndex(catalog, offset, automationId) {
+    const granted = new Set(catalog.operations.map(operationKey));
+    const operations = catalogPage([...catalog.grantableOperations]
+        .sort((left, right) => operationKey(left).localeCompare(operationKey(right)))
+        .map((operation) => ({
+        ref: automationCatalogOperationRef(operation),
+        toolName: operation.toolName, operationId: operation.operationId,
+        contractVersion: operation.contractVersion,
+        label: operation.label.slice(0, LABEL_MAX_LENGTH),
+        labelTruncated: operation.label.length > LABEL_MAX_LENGTH,
+        ...(operation.pluginName ? { pluginName: operation.pluginName } : {}),
+        catalogGroups: operation.catalogGroups, permissionMode: operation.permissionMode,
+        effect: operation.effect, granted: granted.has(operationKey(operation)),
+    })), offset);
+    const models = catalogPage([...catalog.models]
+        .sort((left, right) => left.id.localeCompare(right.id))
+        .map((model) => ({
+        id: model.id, label: model.label.slice(0, LABEL_MAX_LENGTH),
+        labelTruncated: model.label.length > LABEL_MAX_LENGTH,
+        ...(model.provider ? { provider: model.provider } : {}),
+    })), offset);
+    const savedAgents = catalogPage([...catalog.savedAgents]
+        .sort((left, right) => left.id.localeCompare(right.id))
+        .map((agent) => ({
+        agentId: agent.id, revision: agent.revision,
+        title: agent.title.slice(0, LABEL_MAX_LENGTH),
+        titleTruncated: agent.title.length > LABEL_MAX_LENGTH,
+        modelProfileId: agent.modelProfileId,
+    })), offset);
+    const totalCount = Math.max(operations.totalCount, models.totalCount, savedAgents.totalCount);
+    return {
+        kind: "automation_authoring_catalog_index_v1", grantsPermissions: false,
+        catalogScope: automationAuthoringCatalogScope(automationId),
+        permissions: AUTOMATION_AUTHORING_REFERENCE.permissions,
+        offset, pageSize: PAGE_SIZE,
+        // Every collection advances by the same page size; none can lose an intermediate page.
+        nextOffset: offset + PAGE_SIZE < totalCount ? offset + PAGE_SIZE : null,
+        operations, models, savedAgents,
+    };
+}
+/** Resolve an exact, current operation reference without granting or selecting it. */
+export async function readAutomationAuthoringCatalogOperation(service, automationId, toolName, operationId, contractVersion) {
+    const catalog = await service.catalog(automationId);
+    const matchesReference = (operation) => operation.toolName === toolName && operation.operationId === operationId &&
+        operation.contractVersion === contractVersion;
+    const selected = catalog.grantableOperations.find(matchesReference);
+    if (!selected)
+        throw new Error("automation_catalog_operation_not_found");
+    const { fixedParams: _fixedParams, ...operation } = selected;
+    return {
+        kind: "automation_authoring_catalog_operation_v1",
+        catalogScope: automationAuthoringCatalogScope(automationId),
+        permissions: AUTOMATION_AUTHORING_REFERENCE.permissions,
+        grantsPermissions: false, operation,
+        granted: catalog.operations.some(matchesReference),
+    };
+}

package/dist/src/runtime/capabilities/automations/authoring-input-contracts.d.ts

@@ -0,0 +1,140 @@
+/** Flat authoring conveniences project into the existing canonical draft mutation contract. */
+export declare const automationAuthoringInputOperations: readonly [{
+    readonly operationId: "bind_step_result";
+    readonly summary: "Bind one named agent input or tool control to an exact earlier step result, preserving other inputs. Select text or data explicitly; pointer is a JSON pointer for data only. Placement never passes outputs automatically. This does not set a tool payload; use set_tool_payload for that.";
+    readonly effect: "mutating";
+    readonly approval: "request_policy";
+    readonly fixedParams: {
+        readonly action: "bind_step_result";
+    };
+    readonly input: {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly inputName: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 64;
+            };
+            readonly sourceNodeId: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 128;
+            };
+            readonly select: {
+                readonly type: "string";
+                readonly enum: readonly ["text", "data"];
+            };
+            readonly pointer: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 512;
+            };
+            readonly automationId: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 128;
+            };
+            readonly expectedRevision: {
+                readonly type: "integer";
+                readonly minimum: 1;
+                readonly maximum: 2147483647;
+            };
+            readonly nodeId: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 128;
+            };
+        };
+        readonly required: readonly [...string[], "inputName", "sourceNodeId", "select"];
+    };
+}, {
+    readonly operationId: "set_step_literal";
+    readonly summary: "Set one named agent input or tool control to a literal while preserving other inputs. valueJson is only the raw JSON value (string, number, boolean, null, array or object), without a binding wrapper, bounded to 4096 UTF-8 bytes. The Runtime constructs the literal binding.";
+    readonly effect: "mutating";
+    readonly approval: "request_policy";
+    readonly fixedParams: {
+        readonly action: "set_step_literal";
+    };
+    readonly input: {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly inputName: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 64;
+            };
+            readonly valueJson: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 4096;
+            };
+            readonly automationId: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 128;
+            };
+            readonly expectedRevision: {
+                readonly type: "integer";
+                readonly minimum: 1;
+                readonly maximum: 2147483647;
+            };
+            readonly nodeId: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 128;
+            };
+        };
+        readonly required: readonly [...string[], "inputName", "valueJson"];
+    };
+}, {
+    readonly operationId: "select_agent_tool";
+    readonly summary: "Select one exact catalog operation for an agent and set usage to available or required. Updates the same exact reference without duplicating it, preserving other selections. Selection does not grant permission, publish or run the automation.";
+    readonly effect: "mutating";
+    readonly approval: "request_policy";
+    readonly fixedParams: {
+        readonly action: "select_agent_tool";
+    };
+    readonly input: {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly properties: {
+            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 usage: {
+                readonly type: "string";
+                readonly enum: readonly ["available", "required"];
+            };
+            readonly automationId: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 128;
+            };
+            readonly expectedRevision: {
+                readonly type: "integer";
+                readonly minimum: 1;
+                readonly maximum: 2147483647;
+            };
+            readonly nodeId: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 128;
+            };
+        };
+        readonly required: readonly [...string[], "toolName", "operationId", "contractVersion", "usage"];
+    };
+}];

package/dist/src/runtime/capabilities/automations/authoring-input-contracts.js

@@ -0,0 +1,36 @@
+const id = { type: "string", minLength: 1, maxLength: 128 };
+const name = { type: "string", minLength: 1, maxLength: 64 };
+const positiveInteger = { type: "integer", minimum: 1, maximum: 2_147_483_647 };
+const node = { automationId: id, expectedRevision: positiveInteger, nodeId: id };
+const requiredNode = ["automationId", "expectedRevision", "nodeId"];
+/** Flat authoring conveniences project into the existing canonical draft mutation contract. */
+export const automationAuthoringInputOperations = [
+    {
+        operationId: "bind_step_result",
+        summary: "Bind one named agent input or tool control to an exact earlier step result, preserving other inputs. Select text or data explicitly; pointer is a JSON pointer for data only. Placement never passes outputs automatically. This does not set a tool payload; use set_tool_payload for that.",
+        effect: "mutating", approval: "request_policy", fixedParams: { action: "bind_step_result" },
+        input: { type: "object", additionalProperties: false,
+            properties: { ...node, inputName: name, sourceNodeId: id,
+                select: { type: "string", enum: ["text", "data"] },
+                pointer: { type: "string", minLength: 1, maxLength: 512 } },
+            required: [...requiredNode, "inputName", "sourceNodeId", "select"] },
+    },
+    {
+        operationId: "set_step_literal",
+        summary: "Set one named agent input or tool control to a literal while preserving other inputs. valueJson is only the raw JSON value (string, number, boolean, null, array or object), without a binding wrapper, bounded to 4096 UTF-8 bytes. The Runtime constructs the literal binding.",
+        effect: "mutating", approval: "request_policy", fixedParams: { action: "set_step_literal" },
+        input: { type: "object", additionalProperties: false,
+            properties: { ...node, inputName: name,
+                valueJson: { type: "string", minLength: 1, maxLength: 4_096 } },
+            required: [...requiredNode, "inputName", "valueJson"] },
+    },
+    {
+        operationId: "select_agent_tool",
+        summary: "Select one exact catalog operation for an agent and set usage to available or required. Updates the same exact reference without duplicating it, preserving other selections. Selection does not grant permission, publish or run the automation.",
+        effect: "mutating", approval: "request_policy", fixedParams: { action: "select_agent_tool" },
+        input: { type: "object", additionalProperties: false,
+            properties: { ...node, toolName: name, operationId: name, contractVersion: positiveInteger,
+                usage: { type: "string", enum: ["available", "required"] } },
+            required: [...requiredNode, "toolName", "operationId", "contractVersion", "usage"] },
+    },
+];

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

@@ -0,0 +1,9 @@
+import type { AutomationService } from "../../automations/service.js";
+export declare function isAutomationAuthoringInputAction(action: string): boolean;
+/** The parser and revision-checked draft service remain the sole mutation authority. */
+export declare function executeAutomationAuthoringInput(service: AutomationService, params: Record<string, unknown>): Promise<{
+    automationId: string;
+    revision: number;
+    newNodeIds: readonly string[];
+    sourceId?: string;
+}>;

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

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

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

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

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

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