@abot-ai/runtime 1.0.0 → 1.1.0

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

@@ -0,0 +1,44 @@
+import { ROLE_CAPABILITY_RESULT_REFERENCE_LIMIT_MAX, ROLE_CAPABILITY_RESULT_REFERENCE_TARGET_MAX_LENGTH, } from "../../role-calls/index.js";
+export function normalizeResultReferences(input) {
+    if (input === undefined)
+        return undefined;
+    if (!Array.isArray(input) ||
+        input.length > ROLE_CAPABILITY_RESULT_REFERENCE_LIMIT_MAX) {
+        return null;
+    }
+    const targets = new Set();
+    const references = [];
+    for (const candidate of input) {
+        const reference = normalizeToolTargetReference(candidate);
+        if (!reference)
+            return null;
+        if (targets.has(reference.target))
+            return null;
+        targets.add(reference.target);
+        references.push(reference);
+    }
+    return Object.freeze(references);
+}
+function normalizeToolTargetReference(candidate) {
+    if (typeof candidate !== "object" ||
+        candidate === null ||
+        Array.isArray(candidate)) {
+        return null;
+    }
+    const reference = candidate;
+    if (Object.keys(reference).length !== 2)
+        return null;
+    if (reference.kind !== "tool_target")
+        return null;
+    if (typeof reference.target !== "string")
+        return null;
+    if (reference.target.trim().length === 0)
+        return null;
+    if (reference.target.length > ROLE_CAPABILITY_RESULT_REFERENCE_TARGET_MAX_LENGTH) {
+        return null;
+    }
+    return Object.freeze({
+        kind: "tool_target",
+        target: reference.target.trim(),
+    });
+}

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

@@ -0,0 +1,12 @@
+import type { RoleCallFrame, RoleCallLedger, RoleCallLedgerHead } from "../../role-calls/index.js";
+import type { WorkerCapabilityDescriptor, WorkerSettledCapabilityResult } from "../contracts.js";
+import { type WorkerCapabilityDiagnosticContext } from "../diagnostics.js";
+import { type WorkerCapabilityScopeProjection } from "../scope.js";
+export declare function assertExecutionCapabilityScope(projection: WorkerCapabilityScopeProjection<unknown>, descriptor: WorkerCapabilityDescriptor, diagnostic: WorkerCapabilityDiagnosticContext): void;
+export declare function projectExecutionSettledCapabilityResults(params: {
+    ledger: RoleCallLedger;
+    head: RoleCallLedgerHead;
+    call: RoleCallFrame;
+    descriptors: readonly WorkerCapabilityDescriptor[];
+    diagnostic: WorkerCapabilityDiagnosticContext;
+}): readonly WorkerSettledCapabilityResult[];

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

@@ -0,0 +1,51 @@
+import { traceWorkerCapabilityContextProjected, traceWorkerCapabilityContextRejected, } from "../diagnostics.js";
+import { projectWorkerSettledCapabilityResults } from "../settled-results.js";
+import { assertWorkerCapabilityWithinScope, WorkerCapabilityScopeError, } from "../scope.js";
+export function assertExecutionCapabilityScope(projection, descriptor, diagnostic) {
+    try {
+        assertWorkerCapabilityWithinScope(projection, descriptor);
+    }
+    catch (error) {
+        const issueCode = error instanceof WorkerCapabilityScopeError
+            ? error.issueCode
+            : "capability_scope_validation_failed";
+        traceWorkerCapabilityContextRejected(diagnostic, descriptor, issueCode);
+        throw new Error(`worker_capability_rejected:${issueCode}`);
+    }
+}
+export function projectExecutionSettledCapabilityResults(params) {
+    let settledCapabilityResults;
+    try {
+        settledCapabilityResults = projectWorkerSettledCapabilityResults({
+            ledger: params.ledger,
+            head: params.head,
+            call: params.call,
+        });
+    }
+    catch (error) {
+        const issueCode = settledResultProjectionIssueCode(error);
+        for (const descriptor of params.descriptors) {
+            traceWorkerCapabilityContextRejected(params.diagnostic, descriptor, issueCode);
+        }
+        throw new Error(`worker_capability_context_rejected:${issueCode}`);
+    }
+    for (const descriptor of params.descriptors) {
+        traceWorkerCapabilityContextProjected(params.diagnostic, descriptor, settledCapabilityResults);
+    }
+    return settledCapabilityResults;
+}
+function settledResultProjectionIssueCode(error) {
+    if (!(error instanceof Error)) {
+        return "worker_settled_results_projection_failed";
+    }
+    if (error.message === "worker_settled_results_head_stale") {
+        return error.message;
+    }
+    if (error.message === "worker_settled_results_call_invalid") {
+        return error.message;
+    }
+    if (error.message === "worker_settled_results_execution_invalid") {
+        return error.message;
+    }
+    return "worker_settled_results_projection_failed";
+}

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

@@ -0,0 +1,25 @@
+import { type RoleCallDependencyResult, type RoleCallFrame } from "../../role-calls/index.js";
+import type { WorkerCapabilityAdapter, WorkerCapabilityControls, WorkerCapabilityExecutionFreshness, WorkerCapabilityPreparedExecution, WorkerSettledCapabilityResult } from "../contracts.js";
+export type PreparedBoundInvocation<TContext> = Readonly<{
+    adapter: WorkerCapabilityAdapter<TContext>;
+    intent: string;
+    authoringObjective?: string;
+    controls: WorkerCapabilityControls;
+    prepared: WorkerCapabilityPreparedExecution;
+}>;
+type BoundInvocationPreparationParams<TContext> = Readonly<{
+    context: TContext;
+    call: RoleCallFrame;
+    adapter: WorkerCapabilityAdapter<TContext>;
+    intent: string;
+    authoringObjective?: string;
+    controls: WorkerCapabilityControls;
+    preparationId: string;
+    settledCapabilityResults: readonly WorkerSettledCapabilityResult[];
+    dependencyResults?: readonly RoleCallDependencyResult[];
+    executionFreshness?: WorkerCapabilityExecutionFreshness;
+}>;
+export declare function prepareBoundInvocation<TContext>(params: BoundInvocationPreparationParams<TContext>): Promise<WorkerCapabilityPreparedExecution>;
+export declare function deduplicatePreparedInvocations<TContext>(invocations: readonly PreparedBoundInvocation<TContext>[]): readonly PreparedBoundInvocation<TContext>[];
+export declare function createPreparationId(call: RoleCallFrame, index: number): string;
+export {};

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

@@ -0,0 +1,111 @@
+import { isRoleOperationFingerprint, } from "../../role-calls/index.js";
+import { validateWorkerCapabilityAcceptedControls } from "../controls.js";
+import { createWorkerCapabilityDirectActionFingerprint } from "../preparation-fingerprint.js";
+import { createWorkerCapabilityPreparationFailureFingerprint } from "../preparation-fingerprint.js";
+export async function prepareBoundInvocation(params) {
+    const common = Object.freeze({
+        context: params.context,
+        call: params.call,
+        intent: params.intent,
+        ...(params.authoringObjective
+            ? { authoringObjective: params.authoringObjective }
+            : {}),
+        controls: params.controls,
+        settledCapabilityResults: params.settledCapabilityResults,
+        ...(params.dependencyResults
+            ? { dependencyResults: params.dependencyResults }
+            : {}),
+        ...(params.executionFreshness
+            ? { executionFreshness: params.executionFreshness }
+            : {}),
+    });
+    if (!params.adapter.prepare) {
+        return prepareDirectInvocation(params, common);
+    }
+    try {
+        const prepared = await params.adapter.prepare(Object.freeze({ ...common, preparationId: params.preparationId }));
+        if (!hasPreparedExecutionContract(prepared)) {
+            throw createAdapterPreparationContractError("prepared_execution_invalid");
+        }
+        if (!isRoleOperationFingerprint(prepared.actionFingerprint)) {
+            throw createAdapterPreparationContractError("prepared_action_fingerprint_invalid");
+        }
+        const acceptedControls = validateWorkerCapabilityAcceptedControls(prepared.acceptedControls);
+        if (!acceptedControls.ok) {
+            throw createAdapterPreparationContractError("prepared_accepted_controls_invalid");
+        }
+        return Object.freeze({
+            actionFingerprint: prepared.actionFingerprint,
+            acceptedControls: acceptedControls.value,
+            execute: prepared.execute,
+        });
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === "AbortError")
+            throw error;
+        return createPreparationFailureExecution(params, error);
+    }
+}
+function prepareDirectInvocation(params, common) {
+    const actionFingerprint = createWorkerCapabilityDirectActionFingerprint({
+        capabilityId: params.adapter.descriptor.capabilityId,
+        controls: params.controls,
+        ...(params.call.workingDirectory
+            ? { workingDirectory: params.call.workingDirectory }
+            : {}),
+    });
+    if (!actionFingerprint) {
+        return createPreparationFailureExecution(params, createAdapterPreparationContractError("direct_action_fingerprint_invalid"));
+    }
+    return Object.freeze({
+        actionFingerprint,
+        acceptedControls: params.controls,
+        execute: (executionId) => params.adapter.execute(Object.freeze({ ...common, executionId })),
+    });
+}
+export function deduplicatePreparedInvocations(invocations) {
+    const fingerprintsByCapability = new Map();
+    return Object.freeze(invocations.filter(({ adapter, prepared }) => {
+        const fingerprint = prepared.actionFingerprint;
+        if (!fingerprint)
+            return true;
+        const capabilityId = adapter.descriptor.capabilityId;
+        const fingerprints = fingerprintsByCapability.get(capabilityId) ?? new Set();
+        if (fingerprints.has(fingerprint))
+            return false;
+        fingerprints.add(fingerprint);
+        fingerprintsByCapability.set(capabilityId, fingerprints);
+        return true;
+    }));
+}
+export function createPreparationId(call, index) {
+    return `capability-preparation:${call.callId}:${call.activationCount}:${index + 1}`;
+}
+function hasPreparedExecutionContract(prepared) {
+    return (typeof prepared === "object" &&
+        prepared !== null &&
+        typeof prepared.execute === "function");
+}
+function createPreparationFailureExecution(params, error) {
+    const actionFingerprint = createWorkerCapabilityPreparationFailureFingerprint({
+        capabilityId: params.adapter.descriptor.capabilityId,
+        controls: params.controls,
+        ...(params.call.workingDirectory
+            ? { workingDirectory: params.call.workingDirectory }
+            : {}),
+        error,
+    });
+    return Object.freeze({
+        ...(actionFingerprint ? { actionFingerprint } : {}),
+        acceptedControls: params.controls,
+        execute: async () => {
+            throw error;
+        },
+    });
+}
+function createAdapterPreparationContractError(issueCode) {
+    return Object.assign(new Error(`worker_capability_adapter_preparation_contract_rejected:${issueCode}`), {
+        name: "WorkerCapabilityAdapterContractError",
+        issueCode,
+    });
+}

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

@@ -0,0 +1,20 @@
+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";
+import type { PreparedBoundInvocation } from "./invocation-preparation.js";
+export declare function beginAndSettlePreparedSingle<TContext>(params: {
+    currentHead: RoleCallLedgerHead;
+    ledger: RoleCallLedger;
+    call: RoleCallFrame;
+    invocation: PreparedBoundInvocation<TContext>;
+    diagnostic: WorkerCapabilityDiagnosticContext;
+    executionFreshness?: WorkerCapabilityExecutionFreshness;
+}): Promise<WorkerCapabilityAttemptReference>;
+export declare function beginAndSettlePreparedBatch<TContext>(params: {
+    currentHead: RoleCallLedgerHead;
+    ledger: RoleCallLedger;
+    call: RoleCallFrame;
+    invocations: readonly PreparedBoundInvocation<TContext>[];
+    diagnostic: WorkerCapabilityDiagnosticContext;
+    executionFreshness?: WorkerCapabilityExecutionFreshness;
+}): Promise<WorkerCapabilityBatchAttemptReference>;

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

@@ -0,0 +1,142 @@
+import { requireRoleCallOperationSupervisionInterventionCommit, resolveRoleCallTransactions, } from "../../role-calls/index.js";
+import { traceWorkerCapabilityExecutionCompleted, traceWorkerCapabilityExecutionStarted, 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;
+    const admission = createExecutionAdmission(params.executionFreshness);
+    const begunResult = await transactions.beginCapabilityExecution({
+        expectedHead: params.currentHead,
+        callId: params.call.callId,
+        invocationAttempt: params.call.activationCount,
+        capabilityId: params.invocation.adapter.descriptor.capabilityId,
+        declaredEffect: params.invocation.adapter.descriptor.effect,
+        intent: params.invocation.intent,
+        controlsJson: JSON.stringify(params.invocation.prepared.acceptedControls),
+        ...(actionFingerprint ? { actionFingerprint } : {}),
+        ...(admission ? { admission } : {}),
+    });
+    if (!begunResult.ok) {
+        traceStateRejection(params.diagnostic, [params.invocation], "begin", begunResult.issueCode);
+        throw stateRejection("begin", begunResult.issueCode);
+    }
+    const begun = begunResult.commit;
+    if (begun.effect.type === "operation_supervision_intervened") {
+        return Object.freeze({
+            kind: "operation_supervision_intervened",
+            commit: requireRoleCallOperationSupervisionInterventionCommit(begun),
+        });
+    }
+    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 { result, outcomeFingerprint } = execution;
+    const settledResult = await transactions.settleCapabilityExecution({
+        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,
+    });
+    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) {
+    const transactions = resolveRoleCallTransactions(params.ledger);
+    const admission = createExecutionAdmission(params.executionFreshness);
+    const begunResult = await transactions.beginCapabilityBatch({
+        expectedHead: params.currentHead,
+        callId: params.call.callId,
+        invocationAttempt: params.call.activationCount,
+        entries: params.invocations.map(({ adapter, intent, prepared }) => ({
+            capabilityId: adapter.descriptor.capabilityId,
+            declaredEffect: "observation",
+            intent,
+            controlsJson: JSON.stringify(prepared.acceptedControls),
+            ...(prepared.actionFingerprint
+                ? { actionFingerprint: prepared.actionFingerprint }
+                : {}),
+        })),
+        ...(admission ? { admission } : {}),
+    });
+    if (!begunResult.ok) {
+        traceStateRejection(params.diagnostic, params.invocations, "begin", begunResult.issueCode);
+        throw stateRejection("begin", begunResult.issueCode);
+    }
+    const begun = begunResult.commit;
+    if (begun.effect.type === "operation_supervision_intervened") {
+        return Object.freeze({
+            kind: "operation_supervision_intervened",
+            commit: requireRoleCallOperationSupervisionInterventionCommit(begun),
+        });
+    }
+    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 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({
+        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]);
+    });
+    return Object.freeze({ executionIds: Object.freeze([...executionIds]) });
+}
+function createExecutionAdmission(executionFreshness) {
+    if (!executionFreshness)
+        return undefined;
+    return Object.freeze({
+        isCurrent: () => executionFreshness.isCurrent(),
+    });
+}
+function traceStateRejection(diagnostic, invocations, phase, issueCode, executionIds = []) {
+    invocations.forEach((invocation, index) => {
+        traceWorkerCapabilityStateRejected(diagnostic, invocation.adapter.descriptor, {
+            phase,
+            issueCode,
+            ...(executionIds[index] ? { executionId: executionIds[index] } : {}),
+        });
+    });
+}
+function stateRejection(phase, code) {
+    if (phase === "begin" && code === "operation_supervision_limit_exceeded") {
+        return new WorkerCapabilityOperationSupervisionLimitError();
+    }
+    return new Error(`worker_capability_${phase}_rejected:${code}`);
+}

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

@@ -1,38 +1,34 @@
-import { type RoleCallFrame, type RoleCallLedger, type RoleCallLedgerHead, type RoleCallDependencyResult } from "../role-calls/index.js";
-import type { WorkerCapabilityAdapter, WorkerCapabilityBatchExecutionReference, WorkerCapabilityExecutionReference, WorkerCapabilityExecutionFreshness, WorkerCapabilityControls, WorkerCapabilityDescriptor } from "./contracts.js";
-import { type WorkerCapabilityDiagnosticContext } from "./diagnostics.js";
-import { type WorkerCapabilityScopeProjection } from "./scope.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";
+import type { WorkerCapabilityScopeProjection } from "./scope.js";
 export declare function executeBoundWorkerCapability<TContext>(params: {
     context: TContext;
     call: RoleCallFrame;
     currentHead: RoleCallLedgerHead;
     ledger: RoleCallLedger;
-    adapter: Readonly<{
-        descriptor: WorkerCapabilityDescriptor;
-        execute: WorkerCapabilityAdapter<TContext>["execute"];
-    }>;
+    adapter: WorkerCapabilityAdapter<TContext>;
     intent: string;
+    authoringObjective?: string;
     controls: WorkerCapabilityControls;
     diagnostic: WorkerCapabilityDiagnosticContext;
     capabilityScope: WorkerCapabilityScopeProjection<unknown>;
     dependencyResults?: readonly RoleCallDependencyResult[];
     executionFreshness?: WorkerCapabilityExecutionFreshness;
-}): Promise<WorkerCapabilityExecutionReference>;
+}): Promise<WorkerCapabilityAttemptReference>;
 export declare function executeBoundWorkerCapabilityBatch<TContext>(params: {
     context: TContext;
     call: RoleCallFrame;
     currentHead: RoleCallLedgerHead;
     ledger: RoleCallLedger;
     invocations: readonly Readonly<{
-        adapter: Readonly<{
-            descriptor: WorkerCapabilityDescriptor;
-            execute: WorkerCapabilityAdapter<TContext>["execute"];
-        }>;
+        adapter: WorkerCapabilityAdapter<TContext>;
         intent: string;
+        authoringObjective?: string;
         controls: WorkerCapabilityControls;
     }>[];
     diagnostic: WorkerCapabilityDiagnosticContext;
     capabilityScope: WorkerCapabilityScopeProjection<unknown>;
     dependencyResults?: readonly RoleCallDependencyResult[];
     executionFreshness?: WorkerCapabilityExecutionFreshness;
-}): Promise<WorkerCapabilityBatchExecutionReference>;
+}): Promise<WorkerCapabilityBatchAttemptReference>;