@abot-ai/runtime 1.0.0 → 1.1.0

package/dist/src/runtime/steps/worker-decision/parser/capability-invocation-validation.js

@@ -0,0 +1,104 @@
+import { WORKER_CAPABILITY_AUTHORING_OBJECTIVE_MAX_LENGTH, WORKER_CAPABILITY_INTENT_MAX_LENGTH, } from "../contracts.js";
+import { partitionSelectedCapabilityControls, validateCapabilityExecutionControls, validateCapabilitySelectionControls, } from "./capability-controls-validation.js";
+import { validateBoundedWorkerDecisionText, validateExactWorkerDecisionKeys, } from "./decision-shape-validation.js";
+import { createWorkerDecisionIssue, hasObservationOnlyCapabilityMismatch, } from "./validation-contract.js";
+export function validateSingleCapabilityDecision(record, context, issues) {
+    if (hasMissingPendingCapabilityRefinement(context)) {
+        issues.push(createWorkerDecisionIssue("worker_capability_refinement_invalid", "decision.action"));
+    }
+    const invocation = parseCapabilityInvocation({
+        record,
+        path: "decision",
+        includesActionKey: true,
+        observationOnly: false,
+        executionRequiresPendingInvocation: true,
+        decisionPhase: context.decisionPhase,
+        availableCapabilities: context.availableCapabilities,
+        pendingInvocation: context.pendingCapabilitySelection,
+        pendingSlotId: undefined,
+    }, issues);
+    return {
+        acceptedControls: invocation.controls,
+        acceptedAuthoringObjective: invocation.authoringObjective,
+        acceptedSelectionControls: invocation.selectionControls,
+    };
+}
+function hasMissingPendingCapabilityRefinement(context) {
+    if (context.decisionPhase !== "capability_execution")
+        return false;
+    return context.pendingCapabilitySelection === undefined;
+}
+export function parseCapabilityInvocation(params, issues) {
+    const selectedCapability = resolveCapabilityInvocationDescriptor(params, issues);
+    if (params.decisionPhase === "capability_selection") {
+        validateBoundedWorkerDecisionText(params.record.intent, WORKER_CAPABILITY_INTENT_MAX_LENGTH, "worker_capability_intent_invalid", `${params.path}.intent`, issues);
+    }
+    const controlsPartition = partitionSelectedCapabilityControls(selectedCapability, `${params.path}.capabilityId`, issues);
+    validateExactWorkerDecisionKeys(params.record, expectedCapabilityInvocationKeys(params, controlsPartition?.selectionControlIds.length ?? 0, selectedCapability), issues, params.path);
+    const selectionControls = validateCapabilitySelectionControls(params, selectedCapability, controlsPartition, issues);
+    const controls = validateCapabilityExecutionControls(params, selectedCapability, controlsPartition, issues);
+    const authoringObjective = validateCapabilityAuthoringObjective(params, selectedCapability, issues);
+    return {
+        selectedCapability,
+        controlsPartition,
+        authoringObjective,
+        selectionControls,
+        controls,
+    };
+}
+function resolveCapabilityInvocationDescriptor(params, issues) {
+    if (params.pendingInvocation) {
+        return params.availableCapabilities.find((capability) => capability.capabilityId === params.pendingInvocation?.capabilityId);
+    }
+    if (executionRequiresPendingCapabilityInvocation(params))
+        return undefined;
+    if (typeof params.record.capabilityId !== "string") {
+        issues.push(createWorkerDecisionIssue("worker_capability_id_invalid", `${params.path}.capabilityId`));
+        return undefined;
+    }
+    const selectedCapability = params.availableCapabilities.find((capability) => capability.capabilityId === params.record.capabilityId);
+    if (!selectedCapability) {
+        issues.push(createWorkerDecisionIssue("worker_capability_unavailable", `${params.path}.capabilityId`));
+        return undefined;
+    }
+    if (hasObservationOnlyCapabilityMismatch(params, selectedCapability)) {
+        issues.push(createWorkerDecisionIssue("worker_capability_batch_effect_invalid", `${params.path}.capabilityId`));
+    }
+    return selectedCapability;
+}
+function executionRequiresPendingCapabilityInvocation(params) {
+    if (params.decisionPhase !== "capability_execution")
+        return false;
+    return params.executionRequiresPendingInvocation;
+}
+function expectedCapabilityInvocationKeys(params, selectionControlCount, selectedCapability) {
+    const keys = params.includesActionKey ? ["action"] : [];
+    if (params.decisionPhase === "capability_execution") {
+        keys.push("controls");
+        return keys;
+    }
+    keys.push("capabilityId", "intent");
+    if (selectedCapability?.requiresPayloadAuthoringObjective) {
+        keys.push("authoringObjective");
+    }
+    if (selectionControlCount > 0)
+        keys.push("selectionControls");
+    return keys;
+}
+function validateCapabilityAuthoringObjective(params, selectedCapability, issues) {
+    if (!selectedCapability?.requiresPayloadAuthoringObjective)
+        return undefined;
+    if (params.decisionPhase === "capability_execution") {
+        return params.pendingInvocation?.authoringObjective;
+    }
+    validateBoundedWorkerDecisionText(params.record.authoringObjective, WORKER_CAPABILITY_AUTHORING_OBJECTIVE_MAX_LENGTH, "worker_capability_authoring_objective_invalid", `${params.path}.authoringObjective`, issues);
+    const value = params.record.authoringObjective;
+    if (typeof value !== "string")
+        return undefined;
+    if (value.trim().length === 0)
+        return undefined;
+    if (value.length > WORKER_CAPABILITY_AUTHORING_OBJECTIVE_MAX_LENGTH) {
+        return undefined;
+    }
+    return value.trim();
+}

package/dist/src/runtime/steps/worker-decision/parser/decision-shape-validation.d.ts

@@ -0,0 +1,4 @@
+import type { WorkerDecisionValidationIssue } from "../contracts.js";
+export declare function readWorkerDecisionRecord(value: unknown): Record<string, unknown> | undefined;
+export declare function validateExactWorkerDecisionKeys(record: Record<string, unknown>, expectedKeys: readonly string[], issues: WorkerDecisionValidationIssue[], path?: string): void;
+export declare function validateBoundedWorkerDecisionText(value: unknown, maximumLength: number, code: string, path: string, issues: WorkerDecisionValidationIssue[]): void;

package/dist/src/runtime/steps/worker-decision/parser/decision-shape-validation.js

@@ -0,0 +1,28 @@
+import { createWorkerDecisionIssue } from "./validation-contract.js";
+export function readWorkerDecisionRecord(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+    return value;
+}
+export function validateExactWorkerDecisionKeys(record, expectedKeys, issues, path = "decision") {
+    const expected = new Set(expectedKeys);
+    const actual = Object.keys(record);
+    const hasExpectedKeyCount = actual.length === expected.size;
+    const containsOnlyExpectedKeys = actual.every((key) => expected.has(key));
+    if (hasExpectedKeyCount && containsOnlyExpectedKeys)
+        return;
+    issues.push(createWorkerDecisionIssue("worker_decision_shape_invalid", path));
+}
+export function validateBoundedWorkerDecisionText(value, maximumLength, code, path, issues) {
+    if (hasValidBoundedWorkerDecisionText(value, maximumLength))
+        return;
+    issues.push(createWorkerDecisionIssue(code, path));
+}
+function hasValidBoundedWorkerDecisionText(value, maximumLength) {
+    if (typeof value !== "string")
+        return false;
+    if (value.trim().length === 0)
+        return false;
+    return value.length <= maximumLength;
+}

package/dist/src/runtime/steps/worker-decision/parser/pending-capability-selection-validation.d.ts

@@ -0,0 +1,4 @@
+import type { DecisionValidationContext } from "./validation-contract.js";
+type PendingSelectionValidationOptions = Pick<DecisionValidationContext, "decisionPhase" | "pendingCapabilitySelection" | "pendingCapabilityBatchSelection" | "availableCapabilities" | "maxBatchCapabilityExecutions">;
+export declare function validatePendingSelectionOptions(options: PendingSelectionValidationOptions): void;
+export {};

package/dist/src/runtime/steps/worker-decision/parser/pending-capability-selection-validation.js

@@ -0,0 +1,105 @@
+import { WORKER_CAPABILITY_AUTHORING_OBJECTIVE_MAX_LENGTH } from "../contracts.js";
+import { WORKER_CAPABILITY_INTENT_MAX_LENGTH } from "../contracts.js";
+import { partitionWorkerCapabilityControlsSchema, validateWorkerCapabilitySelectionControls, } from "../../../orchestration/worker-capabilities/index.js";
+export function validatePendingSelectionOptions(options) {
+    if (options.decisionPhase === "capability_selection") {
+        rejectUnexpectedPendingCapabilitySelection(options);
+        return;
+    }
+    if (!hasExactlyOnePendingCapabilitySelection(options)) {
+        throw new Error("worker_pending_capability_selection_invalid");
+    }
+    if (options.pendingCapabilitySelection) {
+        validatePendingSingleCapabilitySelection(options);
+        return;
+    }
+    if (!hasValidPendingCapabilityBatchSelection(options)) {
+        throw new Error("worker_pending_capability_batch_selection_invalid");
+    }
+}
+function rejectUnexpectedPendingCapabilitySelection(options) {
+    if (!hasUnexpectedPendingCapabilitySelection(options))
+        return;
+    throw new Error("worker_pending_capability_selection_unexpected");
+}
+function hasUnexpectedPendingCapabilitySelection(options) {
+    if (options.pendingCapabilitySelection !== undefined)
+        return true;
+    return options.pendingCapabilityBatchSelection !== undefined;
+}
+function hasExactlyOnePendingCapabilitySelection(options) {
+    const hasSingle = options.pendingCapabilitySelection !== undefined;
+    const hasBatch = options.pendingCapabilityBatchSelection !== undefined;
+    return hasSingle !== hasBatch;
+}
+function validatePendingSingleCapabilitySelection(options) {
+    const pending = options.pendingCapabilitySelection;
+    const descriptor = options.availableCapabilities.find(({ capabilityId }) => capabilityId === pending.capabilityId);
+    if (isValidPendingSingleSelection(pending, descriptor))
+        return;
+    throw new Error("worker_pending_capability_selection_invalid");
+}
+function isValidPendingSingleSelection(pending, descriptor) {
+    if (!descriptor)
+        return false;
+    if (!hasValidPendingCapabilityIntent(pending))
+        return false;
+    if (!hasExpectedPendingSelectionControls(pending, descriptor))
+        return false;
+    return hasExpectedPendingAuthoringObjective(pending, descriptor);
+}
+function hasValidPendingCapabilityBatchSelection(options) {
+    const pendingBatch = options.pendingCapabilityBatchSelection;
+    if (!Array.isArray(pendingBatch))
+        return false;
+    if (pendingBatch.length < 2)
+        return false;
+    if (!Number.isInteger(options.maxBatchCapabilityExecutions))
+        return false;
+    if (pendingBatch.length > options.maxBatchCapabilityExecutions)
+        return false;
+    return pendingBatch.every((pending) => isValidPendingObservationBatchItem(pending, options.availableCapabilities));
+}
+function isValidPendingObservationBatchItem(pending, availableCapabilities) {
+    const descriptor = availableCapabilities.find(({ capabilityId }) => capabilityId === pending.capabilityId);
+    if (!descriptor)
+        return false;
+    if (descriptor.effect !== "observation")
+        return false;
+    if (!hasValidPendingCapabilityIntent(pending))
+        return false;
+    if (!hasExpectedPendingSelectionControls(pending, descriptor))
+        return false;
+    return hasExpectedPendingAuthoringObjective(pending, descriptor);
+}
+function hasValidPendingCapabilityIntent(pending) {
+    if (pending.intent.trim() !== pending.intent)
+        return false;
+    if (pending.intent.length === 0)
+        return false;
+    return pending.intent.length <= WORKER_CAPABILITY_INTENT_MAX_LENGTH;
+}
+function hasExpectedPendingAuthoringObjective(pending, descriptor) {
+    const required = descriptor.requiresPayloadAuthoringObjective === true;
+    if (Object.hasOwn(pending, "authoringObjective") !== required)
+        return false;
+    if (!required)
+        return true;
+    const value = pending.authoringObjective;
+    if (typeof value !== "string")
+        return false;
+    if (value.trim() !== value)
+        return false;
+    if (value.length === 0)
+        return false;
+    return value.length <= WORKER_CAPABILITY_AUTHORING_OBJECTIVE_MAX_LENGTH;
+}
+function hasExpectedPendingSelectionControls(pending, descriptor) {
+    const partition = partitionWorkerCapabilityControlsSchema(descriptor.controls, descriptor.selectionControlIds);
+    if (!partition.ok)
+        return false;
+    const expected = partition.value.selectionControlIds.length > 0;
+    if (Object.hasOwn(pending, "selectionControls") !== expected)
+        return false;
+    return validateWorkerCapabilitySelectionControls(partition.value, pending.selectionControls ?? {}).ok;
+}

package/dist/src/runtime/steps/worker-decision/parser/validation-contract.d.ts

@@ -0,0 +1,50 @@
+import type { WorkerControlDecision, WorkerDecisionPhase, WorkerDecisionValidationIssue } from "../contracts.js";
+import type { WorkerCapabilityControls, WorkerCapabilityControlsPartition, WorkerCapabilityDescriptor } from "../../../orchestration/worker-capabilities/index.js";
+export type WorkerDecisionAction = WorkerControlDecision["action"];
+export type PendingCapabilityInvocation = Readonly<{
+    capabilityId: string;
+    intent: string;
+    authoringObjective?: string;
+    selectionControls?: WorkerCapabilityControls;
+}>;
+export type AcceptedCapabilityInvocation = Readonly<{
+    capabilityId: string;
+    intent: string;
+    authoringObjective?: string;
+    selectionControls?: WorkerCapabilityControls;
+    controls?: WorkerCapabilityControls;
+}>;
+export type DecisionValidationContext = Readonly<{
+    decisionPhase: WorkerDecisionPhase;
+    allowedActions: readonly WorkerDecisionAction[];
+    pendingCapabilitySelection?: PendingCapabilityInvocation;
+    pendingCapabilityBatchSelection?: readonly PendingCapabilityInvocation[];
+    availableCapabilities: readonly WorkerCapabilityDescriptor[];
+    maxBatchCapabilityExecutions: number;
+}>;
+export type ActionValidation = Readonly<{
+    acceptedControls?: WorkerCapabilityControls;
+    acceptedAuthoringObjective?: string;
+    acceptedSelectionControls?: WorkerCapabilityControls;
+    acceptedBatchInvocations?: readonly AcceptedCapabilityInvocation[];
+}>;
+export type CapabilityInvocationValidation = Readonly<{
+    selectedCapability?: WorkerCapabilityDescriptor;
+    controlsPartition?: WorkerCapabilityControlsPartition;
+    authoringObjective?: string;
+    selectionControls?: WorkerCapabilityControls;
+    controls?: WorkerCapabilityControls;
+}>;
+export type CapabilityInvocationValidationInput = Readonly<{
+    record: Record<string, unknown>;
+    path: string;
+    includesActionKey: boolean;
+    observationOnly: boolean;
+    executionRequiresPendingInvocation: boolean;
+    decisionPhase: WorkerDecisionPhase;
+    availableCapabilities: readonly WorkerCapabilityDescriptor[];
+    pendingInvocation: PendingCapabilityInvocation | undefined;
+    pendingSlotId: string | undefined;
+}>;
+export declare function hasObservationOnlyCapabilityMismatch(params: Pick<CapabilityInvocationValidationInput, "observationOnly">, selectedCapability: WorkerCapabilityDescriptor): boolean;
+export declare function createWorkerDecisionIssue(code: string, path: string, message?: string): WorkerDecisionValidationIssue;

package/dist/src/runtime/steps/worker-decision/parser/validation-contract.js

@@ -0,0 +1,19 @@
+import { WORKER_DECISION_ACTIONS } from "../contracts.js";
+export function hasObservationOnlyCapabilityMismatch(params, selectedCapability) {
+    if (!params.observationOnly)
+        return false;
+    return selectedCapability.effect !== "observation";
+}
+export function createWorkerDecisionIssue(code, path, message) {
+    return {
+        code,
+        path,
+        message: message ?? defaultWorkerDecisionIssueMessage(code),
+    };
+}
+function defaultWorkerDecisionIssueMessage(code) {
+    if (code === "worker_action_invalid") {
+        return `Action must be one of: ${WORKER_DECISION_ACTIONS.join(", ")}.`;
+    }
+    return `Worker decision failed ${code}.`;
+}

package/dist/src/runtime/steps/worker-decision/parser.d.ts

@@ -1,17 +1,21 @@
 import { type WorkerDecisionPhase, type WorkerDecisionDiagnosticContext, type WorkerDecisionParseResult } from "./contracts.js";
-import { type WorkerCapabilityControls, type WorkerCapabilityDescriptor } from "../../orchestration/worker-capabilities/index.js";
+import type { WorkerCapabilityControls, WorkerCapabilityDescriptor } from "../../orchestration/worker-capabilities/index.js";
+import type { WorkerDecisionAction } from "./parser/validation-contract.js";
 export declare function parseWorkerDecisionOutput(text: string, diagnostic?: WorkerDecisionDiagnosticContext, options?: Readonly<{
     availableCapabilities?: readonly WorkerCapabilityDescriptor[];
     maxBatchCapabilityExecutions?: number;
     decisionPhase?: WorkerDecisionPhase;
+    allowedActions?: readonly WorkerDecisionAction[];
     pendingCapabilitySelection?: Readonly<{
         capabilityId: string;
         intent: string;
+        authoringObjective?: string;
         selectionControls?: WorkerCapabilityControls;
     }>;
     pendingCapabilityBatchSelection?: readonly Readonly<{
         capabilityId: string;
         intent: string;
+        authoringObjective?: string;
         selectionControls?: WorkerCapabilityControls;
     }>[];
 }>): WorkerDecisionParseResult;