@abot-ai/runtime 1.4.0 → 1.5.0

package/dist/src/runtime/orchestration/worker-capabilities/execution/approval-group.js

@@ -0,0 +1,171 @@
+import { restorePreparationRejection } from "./preparation-rejection.js";
+import { isDeepStrictEqual } from "node:util";
+import { settleAdmittedPreparedGroup } from "./settle-prepared.js";
+export async function resolvePreparedGroupApproval(params) {
+    if (!params.gate ||
+        !params.invocations.some((entry) => entry.prepared.approvalRequest))
+        return undefined;
+    params.invocations.forEach((entry, index) => entry.prepared.onAdmitted?.(params.executionIds[index]));
+    const entries = params.invocations.map(({ adapter, prepared, intent, authoringObjective }, index) => {
+        if ((!adapter.restore && !restorePreparationRejection(prepared.snapshot)) ||
+            prepared.snapshot === undefined ||
+            !prepared.actionFingerprint)
+            throw new Error("prepared_approval_snapshot_unavailable");
+        return {
+            executionId: params.executionIds[index],
+            capabilityId: adapter.descriptor.capabilityId,
+            declaredEffect: adapter.descriptor.effect,
+            intent,
+            ...(authoringObjective ? { authoringObjective } : {}),
+            controls: prepared.acceptedControls,
+            actionFingerprint: prepared.actionFingerprint,
+            snapshot: prepared.snapshot,
+            ...(prepared.approvalRequest
+                ? { approvalRequest: prepared.approvalRequest }
+                : {}),
+        };
+    });
+    const group = Object.freeze(structuredClone({
+        kind: "prepared_approval_group_v1",
+        requestId: params.requestId,
+        callId: params.call.callId,
+        invocationAttempt: params.call.activationCount,
+        batch: params.batch,
+        entries,
+        ...(params.executionFreshness
+            ? { executionFreshnessToken: params.executionFreshness.token }
+            : {}),
+    }));
+    if (!isDeepStrictEqual(group, JSON.parse(JSON.stringify(group))))
+        throw new Error("prepared_approval_snapshot_not_serializable");
+    const resolution = await params.gate.resolve(group);
+    if (resolution.kind === "awaiting_approval") {
+        validateDecisions(group, resolution.decisions ?? [], false);
+        return Object.freeze({
+            kind: "awaiting_approval",
+            group: Object.freeze({
+                ...group,
+                ...(resolution.decisions?.length
+                    ? { initialDecisions: resolution.decisions }
+                    : {}),
+            }),
+        });
+    }
+    applyDecisions(group, params.invocations, resolution.decisions);
+    return undefined;
+}
+/** Pure hydration. Call the returned execute only after durable decision-to-running commit. */
+export async function restoreCapabilityApprovalGroup(params) {
+    const head = params.ledger.current();
+    const group = params.group;
+    const call = head.state.calls.find((entry) => entry.callId === group.callId);
+    if (group.kind !== "prepared_approval_group_v1" ||
+        group.requestId !== head.state.requestId ||
+        !call ||
+        call.status !== "waiting_for_capability" ||
+        call.activationCount !== group.invocationAttempt ||
+        group.entries.length === 0 ||
+        (!group.batch && group.entries.length !== 1) ||
+        new Set(group.entries.map((entry) => entry.executionId)).size !==
+            group.entries.length)
+        throw new Error("prepared_approval_group_mismatch");
+    if (group.executionFreshnessToken !== undefined &&
+        !isDeepStrictEqual(group.executionFreshnessToken, params.executionFreshness?.token))
+        throw new Error("prepared_approval_freshness_mismatch");
+    const running = head.state.capabilityExecutions.filter((entry) => entry.status === "running");
+    if (running.length !== group.entries.length)
+        throw new Error("prepared_approval_group_mismatch");
+    const invocations = await Promise.all(group.entries.map(async (entry) => {
+        const admitted = running.find((value) => value.executionId === entry.executionId);
+        const adapter = params.adapters.find((value) => value.descriptor.capabilityId === entry.capabilityId);
+        if (!admitted ||
+            admitted.callId !== group.callId ||
+            admitted.invocationAttempt !== group.invocationAttempt ||
+            admitted.capabilityId !== entry.capabilityId ||
+            admitted.declaredEffect !== entry.declaredEffect ||
+            admitted.actionFingerprint !== entry.actionFingerprint ||
+            admitted.intent !== entry.intent ||
+            !isDeepStrictEqual(JSON.parse(admitted.controlsJson), entry.controls) ||
+            !adapter ||
+            adapter.descriptor.effect !== entry.declaredEffect)
+            throw new Error("prepared_approval_execution_mismatch");
+        const prepared = restorePreparationRejection(entry.snapshot) ??
+            (await adapter.restore?.({
+                context: params.context,
+                call,
+                intent: entry.intent,
+                controls: entry.controls,
+                ...(entry.authoringObjective
+                    ? { authoringObjective: entry.authoringObjective }
+                    : {}),
+                ...(params.executionFreshness
+                    ? { executionFreshness: params.executionFreshness }
+                    : {}),
+            }, entry.snapshot));
+        if (!prepared)
+            throw new Error("prepared_approval_restore_unavailable");
+        if (prepared.actionFingerprint !== entry.actionFingerprint ||
+            !isDeepStrictEqual(prepared.acceptedControls, entry.controls) ||
+            !isDeepStrictEqual(prepared.approvalRequest, entry.approvalRequest))
+            throw new Error("prepared_approval_restore_mismatch");
+        return {
+            adapter,
+            prepared,
+            intent: entry.intent,
+            controls: entry.controls,
+        };
+    }));
+    const diagnostic = {
+        requestId: group.requestId,
+        call,
+        capabilityIds: group.entries.map((entry) => entry.capabilityId),
+        scopeMode: call.workerCapabilityScope ? "catalog_groups" : "full",
+        scopeCatalogGroupIds: call.workerCapabilityScope?.catalogGroupIds ?? [],
+        knownCatalogGroupCount: 0,
+        fullCapabilityCount: params.adapters.length,
+        filteredCapabilityCount: params.adapters.length,
+    };
+    return Object.freeze({
+        async execute(decisions) {
+            applyDecisions(group, invocations, decisions);
+            return settleAdmittedPreparedGroup({
+                ledger: params.ledger,
+                expectedHead: head,
+                call,
+                invocations,
+                executionIds: group.entries.map((entry) => entry.executionId),
+                batch: group.batch,
+                diagnostic,
+            });
+        },
+    });
+}
+function validateDecisions(group, decisions, complete) {
+    const required = group.entries.filter((entry) => entry.approvalRequest);
+    if ((complete && decisions.length !== required.length) ||
+        new Set(decisions.map((entry) => entry.approvalId)).size !==
+            decisions.length)
+        throw new Error("prepared_approval_decisions_incomplete");
+    for (const decision of decisions) {
+        const entry = required.find((entry) => entry.approvalRequest.approvalId === decision.approvalId);
+        if (!entry ||
+            entry.actionFingerprint !== decision.actionFingerprint ||
+            typeof decision.decision?.approved !== "boolean")
+            throw new Error("prepared_approval_decision_mismatch");
+    }
+}
+function applyDecisions(group, invocations, decisions) {
+    validateDecisions(group, decisions, true);
+    invocations.forEach((invocation, index) => {
+        const approval = group.entries[index].approvalRequest;
+        if (!approval)
+            return;
+        if (!invocation.prepared.applyApprovalDecision)
+            throw new Error("prepared_approval_decision_unavailable");
+        invocation.prepared.applyApprovalDecision(decisions.find((decision) => decision.approvalId === approval.approvalId));
+    });
+}
+export async function resumeCapabilityApprovalGroup(params) {
+    const prepared = await restoreCapabilityApprovalGroup(params);
+    return prepared.execute(params.decisions);
+}

package/dist/src/runtime/orchestration/worker-capabilities/execution/invocation-preparation.js

@@ -1,3 +1,4 @@
+import { preparationRejectionSnapshot } from "./preparation-rejection.js";
 import { isRoleOperationFingerprint, } from "../../role-calls/index.js";
 import { validateWorkerCapabilityAcceptedControls } from "../controls.js";
 import { createWorkerCapabilityDirectActionFingerprint } from "../preparation-fingerprint.js";
@@ -41,6 +42,16 @@ export async function prepareBoundInvocation(params) {
             actionFingerprint: prepared.actionFingerprint,
             acceptedControls: acceptedControls.value,
             execute: prepared.execute,
+            ...(prepared.snapshot !== undefined
+                ? { snapshot: prepared.snapshot }
+                : {}),
+            ...(prepared.onAdmitted ? { onAdmitted: prepared.onAdmitted } : {}),
+            ...(prepared.approvalRequest
+                ? { approvalRequest: prepared.approvalRequest }
+                : {}),
+            ...(prepared.applyApprovalDecision
+                ? { applyApprovalDecision: prepared.applyApprovalDecision }
+                : {}),
         });
     }
     catch (error) {
@@ -101,6 +112,7 @@ function createPreparationFailureExecution(params, error) {
     return Object.freeze({
         ...(actionFingerprint ? { actionFingerprint } : {}),
         acceptedControls: params.controls,
+        snapshot: preparationRejectionSnapshot(actionFingerprint, params.controls, error),
         execute: async () => {
             throw error;
         },

package/dist/src/runtime/orchestration/worker-capabilities/execution/ledger-transaction.d.ts

@@ -1,3 +1,4 @@
+import type { CapabilityApprovalGate } from "../approval-contracts.js";
 import { type RoleCallFrame, type RoleCallLedger, type RoleCallLedgerHead } from "../../role-calls/index.js";
 import type { WorkerCapabilityAttemptReference, WorkerCapabilityBatchAttemptReference, WorkerCapabilityExecutionFreshness } from "../contracts.js";
 import { type WorkerCapabilityDiagnosticContext } from "../diagnostics.js";
@@ -9,6 +10,7 @@ export declare function beginAndSettlePreparedSingle<TContext>(params: {
     invocation: PreparedBoundInvocation<TContext>;
     diagnostic: WorkerCapabilityDiagnosticContext;
     executionFreshness?: WorkerCapabilityExecutionFreshness;
+    approvalGate?: CapabilityApprovalGate;
 }): Promise<WorkerCapabilityAttemptReference>;
 export declare function beginAndSettlePreparedBatch<TContext>(params: {
     currentHead: RoleCallLedgerHead;
@@ -17,4 +19,5 @@ export declare function beginAndSettlePreparedBatch<TContext>(params: {
     invocations: readonly PreparedBoundInvocation<TContext>[];
     diagnostic: WorkerCapabilityDiagnosticContext;
     executionFreshness?: WorkerCapabilityExecutionFreshness;
+    approvalGate?: CapabilityApprovalGate;
 }): Promise<WorkerCapabilityBatchAttemptReference>;

package/dist/src/runtime/orchestration/worker-capabilities/execution/ledger-transaction.js

@@ -1,7 +1,8 @@
+import { resolvePreparedGroupApproval } from "./approval-group.js";
+import { settleAdmittedPreparedGroup } from "./settle-prepared.js";
 import { requireRoleCallOperationSupervisionInterventionCommit, resolveRoleCallTransactions, } from "../../role-calls/index.js";
-import { traceWorkerCapabilityExecutionCompleted, traceWorkerCapabilityExecutionStarted, traceWorkerCapabilityStateRejected, } from "../diagnostics.js";
+import { traceWorkerCapabilityStateRejected, } from "../diagnostics.js";
 import { WorkerCapabilityOperationSupervisionLimitError } from "../errors.js";
-import { executePreparedAndNormalizeAdapter } from "./adapter-execution.js";
 export async function beginAndSettlePreparedSingle(params) {
     const transactions = resolveRoleCallTransactions(params.ledger);
     const actionFingerprint = params.invocation.prepared.actionFingerprint;
@@ -29,31 +30,26 @@ export async function beginAndSettlePreparedSingle(params) {
         });
     }
     const executionId = begun.effect.executionId;
-    traceWorkerCapabilityExecutionStarted(params.diagnostic, params.invocation.adapter.descriptor, executionId, params.invocation.intent.length, Object.keys(params.invocation.prepared.acceptedControls).length);
-    const execution = await executePreparedAndNormalizeAdapter({
-        prepared: params.invocation.prepared,
-        descriptor: params.invocation.adapter.descriptor,
-        diagnostic: params.diagnostic,
-        executionId,
+    const wait = await resolvePreparedGroupApproval({
+        gate: params.approvalGate,
+        requestId: params.diagnostic.requestId,
+        call: params.call,
+        invocations: [params.invocation],
+        executionIds: [executionId],
+        batch: false,
+        executionFreshness: params.executionFreshness,
     });
-    const { result, outcomeFingerprint } = execution;
-    const settledResult = await transactions.settleCapabilityExecution({
+    if (wait)
+        return wait;
+    await settleAdmittedPreparedGroup({
+        ledger: params.ledger,
         expectedHead: begun.head,
-        callId: params.call.callId,
-        executionId,
-        outcome: result.outcome,
-        ...(outcomeFingerprint ? { outcomeFingerprint } : {}),
-        observedEffect: result.observedEffect,
-        summary: result.summary,
-        ...(result.referenceData ? { referenceData: result.referenceData } : {}),
-        ...(result.references ? { references: result.references } : {}),
-        exactResult: result.exactResult,
+        call: params.call,
+        invocations: [params.invocation],
+        executionIds: [executionId],
+        batch: false,
+        diagnostic: params.diagnostic,
     });
-    if (!settledResult.ok) {
-        traceStateRejection(params.diagnostic, [params.invocation], "settle", settledResult.issueCode, [executionId]);
-        throw stateRejection("settle", settledResult.issueCode);
-    }
-    traceWorkerCapabilityExecutionCompleted(params.diagnostic, params.invocation.adapter.descriptor, result, executionId);
     return Object.freeze({ executionId });
 }
 export async function beginAndSettlePreparedBatch(params) {
@@ -86,37 +82,26 @@ export async function beginAndSettlePreparedBatch(params) {
         });
     }
     const executionIds = begun.effect.executionIds;
-    params.invocations.forEach((invocation, index) => {
-        traceWorkerCapabilityExecutionStarted(params.diagnostic, invocation.adapter.descriptor, executionIds[index], invocation.intent.length, Object.keys(invocation.prepared.acceptedControls).length);
+    const wait = await resolvePreparedGroupApproval({
+        gate: params.approvalGate,
+        requestId: params.diagnostic.requestId,
+        call: params.call,
+        invocations: params.invocations,
+        executionIds,
+        batch: true,
+        executionFreshness: params.executionFreshness,
     });
-    const executions = await Promise.all(params.invocations.map((invocation, index) => executePreparedAndNormalizeAdapter({
-        prepared: invocation.prepared,
-        descriptor: invocation.adapter.descriptor,
-        diagnostic: params.diagnostic,
-        executionId: executionIds[index],
-    })));
-    const settledResult = await transactions.settleCapabilityBatch({
+    if (wait)
+        return wait;
+    return settleAdmittedPreparedGroup({
+        ledger: params.ledger,
         expectedHead: begun.head,
-        callId: params.call.callId,
-        settlements: executions.map(({ result, outcomeFingerprint }, index) => ({
-            executionId: executionIds[index],
-            outcome: result.outcome,
-            ...(outcomeFingerprint ? { outcomeFingerprint } : {}),
-            observedEffect: result.observedEffect,
-            summary: result.summary,
-            ...(result.referenceData ? { referenceData: result.referenceData } : {}),
-            ...(result.references ? { references: result.references } : {}),
-            exactResult: result.exactResult,
-        })),
-    });
-    if (!settledResult.ok) {
-        traceStateRejection(params.diagnostic, params.invocations, "settle", settledResult.issueCode, executionIds);
-        throw stateRejection("settle", settledResult.issueCode);
-    }
-    params.invocations.forEach((invocation, index) => {
-        traceWorkerCapabilityExecutionCompleted(params.diagnostic, invocation.adapter.descriptor, executions[index].result, executionIds[index]);
+        call: params.call,
+        invocations: params.invocations,
+        executionIds,
+        batch: true,
+        diagnostic: params.diagnostic,
     });
-    return Object.freeze({ executionIds: Object.freeze([...executionIds]) });
 }
 function createExecutionAdmission(executionFreshness) {
     if (!executionFreshness)

package/dist/src/runtime/orchestration/worker-capabilities/execution/preparation-rejection.d.ts

@@ -0,0 +1,66 @@
+import type { WorkerCapabilityPreparedExecution, WorkerCapabilityControls } from "../contracts.js";
+export declare function preparationRejectionSnapshot(actionFingerprint: string | undefined, controls: WorkerCapabilityControls, error: unknown): {
+    kind: string;
+    actionFingerprint: string | undefined;
+    acceptedControls: Readonly<Record<string, unknown>>;
+    result: {
+        failureOutcomeFingerprint: string | null;
+        outcome: "succeeded";
+        observedEffect: import("../../role-calls/contracts.js").RoleCapabilityEffect;
+        summary: string;
+        referenceData?: string;
+        references?: readonly import("../../role-calls/contracts.js").RoleCapabilityResultReference[];
+        exactResult: Readonly<{
+            kind: "registered_tool_execution_result_v1";
+            authority: "registered_plugin";
+            status: "executed";
+            result: import("../../capability-adapters/result.js").CanonicalToolExecutionResult;
+            references?: readonly import("../../capability-adapters/result.js").CapabilityResultReference[];
+        }> | Readonly<{
+            kind: "runtime_capability_rejection_v1";
+            authority: "runtime";
+            status: "rejected";
+            stage: "before_external_execution";
+            code: string;
+            message: string;
+            references?: readonly import("../../capability-adapters/result.js").CapabilityResultReference[];
+        }> | Readonly<{
+            kind: "generic_capability_result_v1";
+            authority: "capability_adapter";
+            status: "executed";
+            ok: boolean;
+            payload: import("../../capability-adapters/result.js").CapabilityJsonValue;
+            references?: readonly import("../../capability-adapters/result.js").CapabilityResultReference[];
+        }>;
+    } | {
+        failureOutcomeFingerprint: string | null;
+        outcome: "failed";
+        observedEffect: import("../contracts.js").WorkerCapabilityObservedEffect;
+        summary: string;
+        referenceData?: string;
+        references?: readonly import("../../role-calls/contracts.js").RoleCapabilityResultReference[];
+        exactResult: Readonly<{
+            kind: "registered_tool_execution_result_v1";
+            authority: "registered_plugin";
+            status: "executed";
+            result: import("../../capability-adapters/result.js").CanonicalToolExecutionResult;
+            references?: readonly import("../../capability-adapters/result.js").CapabilityResultReference[];
+        }> | Readonly<{
+            kind: "runtime_capability_rejection_v1";
+            authority: "runtime";
+            status: "rejected";
+            stage: "before_external_execution";
+            code: string;
+            message: string;
+            references?: readonly import("../../capability-adapters/result.js").CapabilityResultReference[];
+        }> | Readonly<{
+            kind: "generic_capability_result_v1";
+            authority: "capability_adapter";
+            status: "executed";
+            ok: boolean;
+            payload: import("../../capability-adapters/result.js").CapabilityJsonValue;
+            references?: readonly import("../../capability-adapters/result.js").CapabilityResultReference[];
+        }>;
+    };
+};
+export declare function restorePreparationRejection(snapshot: unknown): WorkerCapabilityPreparedExecution | undefined;

package/dist/src/runtime/orchestration/worker-capabilities/execution/preparation-rejection.js

@@ -0,0 +1,37 @@
+import { createTechnicalExecutionFailureResult, normalizeCompletedAdapterExecution, } from "./adapter-result-normalization.js";
+import { createWorkerCapabilityExecutionErrorOutcomeFingerprint } from "../outcome-fingerprint.js";
+export function preparationRejectionSnapshot(actionFingerprint, controls, error) {
+    return {
+        kind: "capability_preparation_rejection_v1",
+        actionFingerprint,
+        acceptedControls: controls,
+        result: {
+            ...createTechnicalExecutionFailureResult(error),
+            failureOutcomeFingerprint: createWorkerCapabilityExecutionErrorOutcomeFingerprint(error) ?? null,
+        },
+    };
+}
+export function restorePreparationRejection(snapshot) {
+    if (!snapshot ||
+        typeof snapshot !== "object" ||
+        !("kind" in snapshot) ||
+        snapshot.kind !== "capability_preparation_rejection_v1")
+        return undefined;
+    const value = snapshot;
+    if (typeof value.actionFingerprint !== "string" ||
+        !value.acceptedControls ||
+        typeof value.acceptedControls !== "object")
+        throw new Error("capability_preparation_snapshot_invalid");
+    const result = structuredClone(value.result);
+    const checked = normalizeCompletedAdapterExecution(result, "mixed");
+    if (!checked.ok ||
+        checked.execution.result.outcome !== "failed" ||
+        checked.execution.result.observedEffect !== "none")
+        throw new Error("capability_preparation_snapshot_invalid");
+    return {
+        actionFingerprint: value.actionFingerprint,
+        acceptedControls: value.acceptedControls,
+        snapshot: structuredClone(snapshot),
+        execute: async () => result,
+    };
+}

package/dist/src/runtime/orchestration/worker-capabilities/execution/settle-prepared.d.ts

@@ -0,0 +1,15 @@
+import { type RoleCallLedger, type RoleCallLedgerHead, type RoleCallFrame } from "../../role-calls/index.js";
+import { type WorkerCapabilityDiagnosticContext } from "../diagnostics.js";
+import type { PreparedBoundInvocation } from "./invocation-preparation.js";
+/** Shared dispatch and settlement for freshly admitted and restored exact actions. */
+export declare function settleAdmittedPreparedGroup<TContext>(params: {
+    ledger: RoleCallLedger;
+    expectedHead: RoleCallLedgerHead;
+    call: RoleCallFrame;
+    invocations: readonly PreparedBoundInvocation<TContext>[];
+    executionIds: readonly string[];
+    batch: boolean;
+    diagnostic: WorkerCapabilityDiagnosticContext;
+}): Promise<Readonly<{
+    executionIds: readonly string[];
+}>>;

package/dist/src/runtime/orchestration/worker-capabilities/execution/settle-prepared.js

@@ -0,0 +1,43 @@
+import { resolveRoleCallTransactions, } from "../../role-calls/index.js";
+import { traceWorkerCapabilityExecutionStarted, traceWorkerCapabilityExecutionCompleted, } from "../diagnostics.js";
+import { executePreparedAndNormalizeAdapter } from "./adapter-execution.js";
+/** Shared dispatch and settlement for freshly admitted and restored exact actions. */
+export async function settleAdmittedPreparedGroup(params) {
+    params.invocations.forEach((invocation, index) => {
+        traceWorkerCapabilityExecutionStarted(params.diagnostic, invocation.adapter.descriptor, params.executionIds[index], invocation.intent.length, Object.keys(invocation.prepared.acceptedControls).length);
+    });
+    const executions = await Promise.all(params.invocations.map((invocation, index) => executePreparedAndNormalizeAdapter({
+        prepared: invocation.prepared,
+        descriptor: invocation.adapter.descriptor,
+        diagnostic: params.diagnostic,
+        executionId: params.executionIds[index],
+    })));
+    const settlements = executions.map(({ result, outcomeFingerprint }, index) => ({
+        executionId: params.executionIds[index],
+        outcome: result.outcome,
+        ...(outcomeFingerprint ? { outcomeFingerprint } : {}),
+        observedEffect: result.observedEffect,
+        summary: result.summary,
+        ...(result.referenceData ? { referenceData: result.referenceData } : {}),
+        ...(result.references ? { references: result.references } : {}),
+        exactResult: result.exactResult,
+    }));
+    const transactions = resolveRoleCallTransactions(params.ledger);
+    const settled = params.batch
+        ? await transactions.settleCapabilityBatch({
+            expectedHead: params.expectedHead,
+            callId: params.call.callId,
+            settlements,
+        })
+        : await transactions.settleCapabilityExecution({
+            expectedHead: params.expectedHead,
+            callId: params.call.callId,
+            ...settlements[0],
+        });
+    if (!settled.ok)
+        throw new Error("worker_capability_settle_rejected:" + settled.issueCode);
+    params.invocations.forEach((invocation, index) => traceWorkerCapabilityExecutionCompleted(params.diagnostic, invocation.adapter.descriptor, executions[index].result, params.executionIds[index]));
+    return Object.freeze({
+        executionIds: Object.freeze([...params.executionIds]),
+    });
+}

package/dist/src/runtime/orchestration/worker-capabilities/execution.d.ts

@@ -1,3 +1,4 @@
+import type { CapabilityApprovalGate } from "./approval-contracts.js";
 import type { RoleCallDependencyResult, RoleCallFrame, RoleCallLedger, RoleCallLedgerHead } from "../role-calls/index.js";
 import type { WorkerCapabilityAdapter, WorkerCapabilityAttemptReference, WorkerCapabilityBatchAttemptReference, WorkerCapabilityControls, WorkerCapabilityExecutionFreshness } from "./contracts.js";
 import type { WorkerCapabilityDiagnosticContext } from "./diagnostics.js";
@@ -15,6 +16,7 @@ export declare function executeBoundWorkerCapability<TContext>(params: {
     capabilityScope: WorkerCapabilityScopeProjection<unknown>;
     dependencyResults?: readonly RoleCallDependencyResult[];
     executionFreshness?: WorkerCapabilityExecutionFreshness;
+    approvalGate?: CapabilityApprovalGate;
 }): Promise<WorkerCapabilityAttemptReference>;
 export declare function executeBoundWorkerCapabilityBatch<TContext>(params: {
     context: TContext;
@@ -31,4 +33,5 @@ export declare function executeBoundWorkerCapabilityBatch<TContext>(params: {
     capabilityScope: WorkerCapabilityScopeProjection<unknown>;
     dependencyResults?: readonly RoleCallDependencyResult[];
     executionFreshness?: WorkerCapabilityExecutionFreshness;
+    approvalGate?: CapabilityApprovalGate;
 }): Promise<WorkerCapabilityBatchAttemptReference>;

package/dist/src/runtime/orchestration/worker-capabilities/execution.js

@@ -45,6 +45,7 @@ export async function executeBoundWorkerCapability(params) {
             prepared,
         }),
         diagnostic: params.diagnostic,
+        ...(params.approvalGate ? { approvalGate: params.approvalGate } : {}),
         ...(params.executionFreshness
             ? { executionFreshness: params.executionFreshness }
             : {}),
@@ -101,6 +102,7 @@ export async function executeBoundWorkerCapabilityBatch(params) {
         call: params.call,
         invocations: uniqueInvocations,
         diagnostic: params.diagnostic,
+        ...(params.approvalGate ? { approvalGate: params.approvalGate } : {}),
         ...(params.executionFreshness
             ? { executionFreshness: params.executionFreshness }
             : {}),
@@ -130,6 +132,7 @@ async function settleCollapsedPreparedBatch(params) {
         call: params.call,
         invocation: params.invocations[0],
         diagnostic: params.diagnostic,
+        ...(params.approvalGate ? { approvalGate: params.approvalGate } : {}),
         ...(params.executionFreshness
             ? { executionFreshness: params.executionFreshness }
             : {}),
@@ -137,7 +140,7 @@ async function settleCollapsedPreparedBatch(params) {
     return projectSingleAttemptAsBatch(result);
 }
 function projectSingleAttemptAsBatch(result) {
-    if ("commit" in result)
+    if ("commit" in result || "kind" in result)
         return result;
     return Object.freeze({
         executionIds: Object.freeze([result.executionId]),

package/dist/src/runtime/orchestration/worker-capabilities/index.d.ts

@@ -2,6 +2,7 @@ export * from "./batch-selection.js";
 export * from "./binding.js";
 export * from "./controls.js";
 export * from "./contracts.js";
+export * from "./approval-contracts.js";
 export * from "./assignment-provenance.js";
 export * from "./errors.js";
 export * from "./outcome-fingerprint.js";
@@ -11,3 +12,4 @@ export { isWorkerCapabilityPayloadSourceProvenanceValid, projectWorkerPayloadPla
 export * from "./scope.js";
 export * from "./selection-controls.js";
 export * from "./settled-results.js";
+export { resumeCapabilityApprovalGroup, restoreCapabilityApprovalGroup, } from "./execution/approval-group.js";

package/dist/src/runtime/orchestration/worker-capabilities/index.js

@@ -2,6 +2,7 @@ export * from "./batch-selection.js";
 export * from "./binding.js";
 export * from "./controls.js";
 export * from "./contracts.js";
+export * from "./approval-contracts.js";
 export * from "./assignment-provenance.js";
 export * from "./errors.js";
 export * from "./outcome-fingerprint.js";
@@ -11,3 +12,4 @@ export { isWorkerCapabilityPayloadSourceProvenanceValid, projectWorkerPayloadPla
 export * from "./scope.js";
 export * from "./selection-controls.js";
 export * from "./settled-results.js";
+export { resumeCapabilityApprovalGroup, restoreCapabilityApprovalGroup, } from "./execution/approval-group.js";

package/dist/src/runtime/orchestration/worker-capabilities/payload-author.js

@@ -1,4 +1,4 @@
-import { isRoleCapabilityId, ROLE_CAPABILITY_REFERENCE_DATA_MAX_LENGTH, ROLE_CAPABILITY_RESULT_REFERENCE_LIMIT_MAX, ROLE_CAPABILITY_RESULT_REFERENCE_TARGET_MAX_LENGTH, ROLE_CAPABILITY_EXECUTION_LIMIT_MAX, ROLE_CALL_RESULT_MAX_LENGTH, } from "../role-calls/index.js";
+import { isRoleCapabilityId, isRoleCallResultText, ROLE_CAPABILITY_REFERENCE_DATA_MAX_LENGTH, ROLE_CAPABILITY_RESULT_REFERENCE_LIMIT_MAX, ROLE_CAPABILITY_RESULT_REFERENCE_TARGET_MAX_LENGTH, ROLE_CAPABILITY_EXECUTION_LIMIT_MAX, ROLE_CALL_RESULT_MAX_LENGTH, } from "../role-calls/index.js";
 import { normalizeCapabilityAdapterResult } from "../capability-adapters/result.js";
 import { traceWorkerCapabilityPayloadCompleted, traceWorkerCapabilityPayloadFailed, traceWorkerCapabilityPayloadStarted, } from "./payload-diagnostics.js";
 import { WORKER_CAPABILITY_RAW_PAYLOAD_MODEL_STEP, WORKER_CAPABILITY_RELATED_ARTIFACT_CONTEXT_MAX_CHARS, WORKER_CAPABILITY_RELATED_ARTIFACT_CONTEXT_MAX_COUNT, WorkerCapabilityPayloadBudgetExceededError, WorkerCapabilityPayloadValidationError, } from "./payload-contracts.js";
@@ -256,9 +256,7 @@ function validDependencyResults(results, call) {
             candidate.producerCallId.length > 0 &&
             isRuntimeDelegateRoleId(candidate.roleId) &&
             (candidate.outcome === "completed" || candidate.outcome === "failed") &&
-            typeof candidate.summary === "string" &&
-            candidate.summary.trim().length > 0 &&
-            candidate.summary.length <= ROLE_CALL_RESULT_MAX_LENGTH &&
+            isRoleCallResultText(candidate.summary) &&
             (semanticCheckpoints === undefined ||
                 (Array.isArray(semanticCheckpoints) &&
                     semanticCheckpoints.length > 0 &&

package/dist/src/runtime/passive-learning/active-batches.d.ts

@@ -0,0 +1,11 @@
+import { processLearningBatch } from "./process-batch.js";
+/** Owns cancellation and settlement for admitted learning batches, not scheduling. */
+export declare class LearningActiveBatches {
+    private readonly active;
+    get size(): number;
+    has(id: string): boolean;
+    dispatch(options: Omit<Parameters<typeof processLearningBatch>[0], "signal">, settled: () => void): void;
+    settle(): Promise<void>;
+    abort(reason: string): void;
+    excludeApplications(exclusions: readonly string[]): Promise<void>;
+}

package/dist/src/runtime/passive-learning/active-batches.js

@@ -0,0 +1,29 @@
+import { processLearningBatch } from "./process-batch.js";
+import { isLearningApplicationExcluded } from "./application-policy.js";
+/** Owns cancellation and settlement for admitted learning batches, not scheduling. */
+export class LearningActiveBatches {
+    active = new Map();
+    get size() { return this.active.size; }
+    has(id) { return this.active.has(id); }
+    dispatch(options, settled) {
+        const abort = new AbortController();
+        const promise = processLearningBatch({ ...options, signal: abort.signal }).finally(() => {
+            this.active.delete(options.batch.id);
+            settled();
+        });
+        this.active.set(options.batch.id, { abort, promise, apps: options.batch.observations.map((item) => item.source.app) });
+    }
+    async settle() {
+        await Promise.allSettled([...this.active.values()].map(({ promise }) => promise));
+    }
+    abort(reason) {
+        for (const work of this.active.values())
+            work.abort.abort(new Error(reason));
+    }
+    async excludeApplications(exclusions) {
+        const affected = [...this.active.values()].filter((work) => work.apps.some((app) => isLearningApplicationExcluded(app, exclusions)));
+        for (const work of affected)
+            work.abort.abort(new Error("learning_application_processing_excluded"));
+        await Promise.allSettled(affected.map((work) => work.promise));
+    }
+}

package/dist/src/runtime/passive-learning/activity-permissions.d.ts

@@ -0,0 +1,7 @@
+import type { PassiveLearningPreferences } from "./contracts.js";
+type ActivityControls = Pick<PassiveLearningPreferences, "activityPermissions" | "enabled" | "processingPaused" | "proactiveEnabled">;
+/** Old API clients retain their existing switches until authorization is explicitly saved. */
+export declare function normalizeLearningActivityControls(input: Partial<PassiveLearningPreferences>, previous: PassiveLearningPreferences): ActivityControls;
+/** Authorizing an activity validates its model without starting a review or invoking a model. */
+export declare function validateLearningActivityModels(previous: PassiveLearningPreferences, next: PassiveLearningPreferences, validateProfile: (profile: string) => void): void;
+export {};