@abot-ai/runtime 1.0.0

package/dist/src/runtime/adapters/registered-tool-worker-capabilities/payload-rejection.js

@@ -0,0 +1,46 @@
+import { boundedSummary, requireCapabilityAdapterResult, } from "./result-observer.js";
+export const STEERING_SUPERSEDED_BEFORE_EXTERNAL_EXECUTION = "steering_superseded_before_external_execution";
+export const STEERING_SUPERSEDED_SUMMARY = "steering_superseded_before_external_execution: No external execution occurred because a newer active-request update superseded this capability invocation.";
+export function rejectPayloadLifecycle(params) {
+    const failed = params.executor.emitPayloadLifecycle({
+        ...params.lifecycle,
+        phase: "failed",
+        errorCode: params.code,
+    });
+    return failed.status === "rejected"
+        ? payloadRejection(failed.code, failed.message)
+        : (params.fallback ?? payloadRejection(params.code, params.message));
+}
+export function payloadRejection(sourceIssueCode, summary) {
+    return Object.freeze({
+        status: "rejected",
+        result: Object.freeze({
+            outcome: "failed",
+            observedEffect: "none",
+            summary: boundedSummary(summary),
+        }),
+        sourceIssueCode,
+        exactResult: requireCapabilityAdapterResult({
+            kind: "runtime_capability_rejection_v1",
+            authority: "runtime",
+            status: "rejected",
+            stage: "before_external_execution",
+            code: sourceIssueCode,
+            message: summary,
+        }),
+    });
+}
+export function executionFreshnessRejection(freshness) {
+    if (!freshness)
+        return undefined;
+    let current = false;
+    try {
+        current = freshness.isCurrent();
+    }
+    catch {
+        current = false;
+    }
+    return current
+        ? undefined
+        : payloadRejection(STEERING_SUPERSEDED_BEFORE_EXTERNAL_EXECUTION, STEERING_SUPERSEDED_SUMMARY);
+}

package/dist/src/runtime/adapters/registered-tool-worker-capabilities/payload-stages.d.ts

@@ -0,0 +1,32 @@
+import type { ToolExecutionSharedState } from "../../../capabilities/tool-types.js";
+import type { CapabilityAdapterResult } from "../../orchestration/capability-adapters/index.js";
+import type { WorkerCapabilityAdapterResult, WorkerCapabilityExecutionFreshness, WorkerCapabilityPayloadAuthor } from "../../orchestration/worker-capabilities/index.js";
+import type { RegisteredToolNormalInvocationExecutor, RegisteredToolNormalInvocationProjection } from "../registered-tool-normal-invocations.js";
+import { type RegisteredToolStagedPayloadPlan } from "../registered-tool-payload-plan.js";
+import { type RegisteredToolWorkerCapabilityProviderDiagnostic } from "../registered-tool-worker-capability-diagnostics.js";
+export type StagedOperationPayloadParams = Readonly<{
+    plan: RegisteredToolStagedPayloadPlan;
+    handle: RegisteredToolNormalInvocationProjection["handle"];
+    executor: RegisteredToolNormalInvocationExecutor;
+    sharedState: ToolExecutionSharedState;
+    payloadAuthor?: WorkerCapabilityPayloadAuthor;
+    call: Parameters<WorkerCapabilityPayloadAuthor["author"]>[0]["call"];
+    executionId: string;
+    descriptor: Parameters<WorkerCapabilityPayloadAuthor["author"]>[0]["descriptor"];
+    intent: string;
+    controls: Readonly<Record<string, unknown>>;
+    dependencyResults?: Parameters<WorkerCapabilityPayloadAuthor["author"]>[0]["dependencyResults"];
+    settledCapabilityResults: Parameters<WorkerCapabilityPayloadAuthor["author"]>[0]["settledCapabilityResults"];
+    diagnostic: RegisteredToolWorkerCapabilityProviderDiagnostic;
+    executionFreshness?: WorkerCapabilityExecutionFreshness;
+}>;
+export type StagedOperationPayloadResult = Readonly<{
+    status: "ready";
+    materializedParams: Readonly<Record<string, string>>;
+}> | Readonly<{
+    status: "rejected";
+    result: WorkerCapabilityAdapterResult;
+    sourceIssueCode: string;
+    exactResult: CapabilityAdapterResult;
+}>;
+export declare function prepareStagedOperationPayload(params: StagedOperationPayloadParams): Promise<StagedOperationPayloadResult>;

package/dist/src/runtime/adapters/registered-tool-worker-capabilities/payload-stages.js

@@ -0,0 +1,303 @@
+import { materializeRegisteredToolPayloadStageResponseFormat, resolveRegisteredToolPayloadRelatedArtifactContexts, resolveRegisteredToolPayloadStageLiteralOutput, resolveRegisteredToolPayloadStageMinBytes, resolveRegisteredToolPayloadTargetContext, validateRegisteredToolPayloadStageTargetLineBounds, } from "../registered-tool-payload-plan.js";
+import { traceRegisteredToolWorkerCapabilityPayloadStageMaterialized, } from "../registered-tool-worker-capability-diagnostics.js";
+import { normalizePayloadAuthoringResult } from "./payload-authoring-result.js";
+import { executionFreshnessRejection, payloadRejection, rejectPayloadLifecycle, STEERING_SUPERSEDED_BEFORE_EXTERNAL_EXECUTION, STEERING_SUPERSEDED_SUMMARY, } from "./payload-rejection.js";
+export async function prepareStagedOperationPayload(params) {
+    return new PayloadStageRunner(params).run();
+}
+/** Owns the ordered payload-stage lifecycle for one capability execution. */
+class PayloadStageRunner {
+    params;
+    constructor(params) {
+        this.params = params;
+    }
+    async run() {
+        const payloadAuthor = this.params.payloadAuthor;
+        if (!payloadAuthor) {
+            return payloadRejection("operation_payload_author_unavailable", "The capability payload author is unavailable.");
+        }
+        const materialized = {};
+        for (const [stageOffset, stage] of this.params.plan.stages.entries()) {
+            const completed = await this.runStage({
+                stage,
+                stageOffset,
+                materialized,
+                payloadAuthor,
+            });
+            if (completed.status === "rejected") {
+                return completed;
+            }
+        }
+        return Object.freeze({
+            status: "ready",
+            materializedParams: Object.freeze({ ...materialized }),
+        });
+    }
+    async runStage(input) {
+        const started = this.startStage(input.stage, input.stageOffset);
+        if (started.status === "rejected") {
+            return started;
+        }
+        const stageInputs = await this.resolveStageInputs(input.stage, input.materialized, started.lifecycle);
+        if (stageInputs.status === "rejected") {
+            return stageInputs;
+        }
+        const validated = await this.authorStage(input.stage, started, stageInputs, input.payloadAuthor);
+        if (validated.status === "rejected") {
+            return validated;
+        }
+        return this.completeStage({
+            stage: input.stage,
+            started,
+            stageInputs,
+            body: validated.body,
+            materialized: input.materialized,
+        });
+    }
+    startStage(stage, stageOffset) {
+        const stageIndex = stageOffset + 1;
+        const stageCount = this.params.plan.stages.length;
+        const lifecycle = {
+            handle: this.params.handle,
+            controls: this.params.controls,
+            intent: this.params.intent,
+            payloadStage: stageIndex,
+            payloadStageCount: stageCount,
+            outputParam: stage.outputParam,
+        };
+        const started = this.params.executor.emitPayloadLifecycle({
+            ...lifecycle,
+            phase: "started",
+        });
+        return started.status === "rejected"
+            ? payloadRejection(started.code, started.message)
+            : Object.freeze({
+                status: "ready",
+                stageIndex,
+                stageCount,
+                lifecycle,
+            });
+    }
+    async resolveStageInputs(stage, materialized, lifecycle) {
+        const priorParams = selectMaterializedParams(stage, materialized);
+        if (!priorParams.ok) {
+            return rejectPayloadLifecycle({
+                executor: this.params.executor,
+                lifecycle,
+                code: "payload_stage_dependency_unavailable",
+                message: "A prior capability payload stage result is unavailable.",
+            });
+        }
+        const effectiveMinBytes = resolveRegisteredToolPayloadStageMinBytes({
+            stage,
+            ...(priorParams.value ? { materializedParams: priorParams.value } : {}),
+        });
+        if (effectiveMinBytes === undefined) {
+            return rejectPayloadLifecycle({
+                executor: this.params.executor,
+                lifecycle,
+                code: "payload_stage_min_bytes_unavailable",
+                message: "A prior capability payload stage result cannot resolve the payload byte minimum.",
+            });
+        }
+        let targetContext;
+        try {
+            targetContext = await resolveRegisteredToolPayloadTargetContext({
+                plan: this.params.plan,
+                stage,
+                controls: this.params.controls,
+                sharedState: this.params.sharedState,
+                ...(priorParams.value ? { materializedParams: priorParams.value } : {}),
+            });
+        }
+        catch {
+            targetContext = undefined;
+        }
+        if (stage.targetContext && !targetContext) {
+            return rejectPayloadLifecycle({
+                executor: this.params.executor,
+                lifecycle,
+                code: "payload_target_context_unavailable",
+                message: "The capability payload target context is unavailable.",
+            });
+        }
+        let responseFormat;
+        try {
+            responseFormat = materializeRegisteredToolPayloadStageResponseFormat({
+                stage,
+                ...(targetContext ? { targetContext } : {}),
+            });
+        }
+        catch {
+            return rejectPayloadLifecycle({
+                executor: this.params.executor,
+                lifecycle,
+                code: "payload_stage_target_line_bound_unavailable",
+                message: "The capability payload target line bound is unavailable.",
+            });
+        }
+        const literalResolution = resolveRegisteredToolPayloadStageLiteralOutput({
+            stage,
+            ...(priorParams.value ? { materializedParams: priorParams.value } : {}),
+        });
+        if (literalResolution.status === "invalid_dependency") {
+            return rejectPayloadLifecycle({
+                executor: this.params.executor,
+                lifecycle,
+                code: "payload_stage_literal_dependency_invalid",
+                message: "A prior capability payload stage result cannot resolve the declared literal output.",
+            });
+        }
+        return Object.freeze({
+            status: "ready",
+            materializedParams: priorParams.value,
+            effectiveMinBytes,
+            targetContext,
+            responseFormat,
+            literalResolution,
+        });
+    }
+    async authorStage(stage, started, stageInputs, payloadAuthor) {
+        let rawAuthored;
+        if (stageInputs.literalResolution.status === "matched") {
+            rawAuthored = Object.freeze({
+                status: "authored",
+                body: stageInputs.literalResolution.body,
+            });
+        }
+        else {
+            try {
+                const contextScope = stage.contextScope ?? "standard";
+                const relatedArtifactContexts = await resolveRegisteredToolPayloadRelatedArtifactContexts({
+                    contextScope,
+                    targetParam: this.params.plan.targetParam,
+                    controls: this.params.controls,
+                    sharedState: this.params.sharedState,
+                    settledCapabilityResults: this.params.settledCapabilityResults,
+                });
+                rawAuthored = await payloadAuthor.author({
+                    call: this.params.call,
+                    executionId: this.params.executionId,
+                    descriptor: this.params.descriptor,
+                    controls: this.params.controls,
+                    contextScope,
+                    ...(this.params.dependencyResults
+                        ? { dependencyResults: this.params.dependencyResults }
+                        : {}),
+                    settledCapabilityResults: this.params.settledCapabilityResults,
+                    ...(this.params.executionFreshness
+                        ? { requestSteering: this.params.executionFreshness.token }
+                        : {}),
+                    ...(relatedArtifactContexts.length > 0
+                        ? { relatedArtifactContexts }
+                        : {}),
+                    contract: {
+                        instructions: stage.instructions,
+                        minBytes: stageInputs.effectiveMinBytes,
+                        maxBytes: stage.maxBytes,
+                        ...(stageInputs.responseFormat
+                            ? { responseFormat: stageInputs.responseFormat }
+                            : {}),
+                    },
+                    stage: {
+                        index: started.stageIndex,
+                        count: started.stageCount,
+                        outputParam: stage.outputParam,
+                        ...(stage.contextScope ? { contextScope: stage.contextScope } : {}),
+                    },
+                    ...(stageInputs.materializedParams
+                        ? { materializedParams: stageInputs.materializedParams }
+                        : {}),
+                    ...(stageInputs.targetContext
+                        ? { targetContext: stageInputs.targetContext }
+                        : {}),
+                });
+            }
+            catch (error) {
+                if (error instanceof Error && error.name === "AbortError") {
+                    throw error;
+                }
+                return rejectPayloadLifecycle({
+                    executor: this.params.executor,
+                    lifecycle: started.lifecycle,
+                    code: "payload_author_failed",
+                    message: "The capability payload could not be prepared.",
+                });
+            }
+        }
+        return this.validateAuthoredStage(stage, stageInputs, rawAuthored, started.lifecycle);
+    }
+    validateAuthoredStage(stage, stageInputs, rawAuthored, lifecycle) {
+        const superseded = executionFreshnessRejection(this.params.executionFreshness);
+        if (superseded) {
+            return rejectPayloadLifecycle({
+                executor: this.params.executor,
+                lifecycle,
+                code: STEERING_SUPERSEDED_BEFORE_EXTERNAL_EXECUTION,
+                message: STEERING_SUPERSEDED_SUMMARY,
+                fallback: superseded,
+            });
+        }
+        const authored = normalizePayloadAuthoringResult(rawAuthored, stageInputs.literalResolution.status === "matched"
+            ? this.params.plan.payloadMinBytes
+            : stageInputs.effectiveMinBytes, stage.maxBytes, stageInputs.responseFormat);
+        if (authored.status === "failed") {
+            return rejectPayloadLifecycle({
+                executor: this.params.executor,
+                lifecycle,
+                code: authored.code,
+                message: "The capability payload could not be prepared.",
+            });
+        }
+        if (!validateRegisteredToolPayloadStageTargetLineBounds({
+            stage,
+            ...(stageInputs.targetContext
+                ? { targetContext: stageInputs.targetContext }
+                : {}),
+            body: authored.body,
+        })) {
+            return rejectPayloadLifecycle({
+                executor: this.params.executor,
+                lifecycle,
+                code: "payload_stage_target_line_bound_invalid",
+                message: "The capability payload selected a line outside the current target.",
+            });
+        }
+        return Object.freeze({ status: "ready", body: authored.body });
+    }
+    completeStage(input) {
+        if (input.stageInputs.literalResolution.status === "matched") {
+            traceRegisteredToolWorkerCapabilityPayloadStageMaterialized(this.params.diagnostic, this.params.descriptor.capabilityId, this.params.call, this.params.executionId, {
+                payloadStage: input.started.stageIndex,
+                payloadStageCount: input.started.stageCount,
+                source: "manifest_literal",
+                byteCount: Buffer.byteLength(input.body, "utf8"),
+            });
+        }
+        input.materialized[input.stage.outputParam] = input.body;
+        const completed = this.params.executor.emitPayloadLifecycle({
+            ...input.started.lifecycle,
+            phase: "completed",
+        });
+        return completed.status === "rejected"
+            ? payloadRejection(completed.code, completed.message)
+            : Object.freeze({ status: "completed" });
+    }
+}
+function selectMaterializedParams(stage, materialized) {
+    if (stage.includeMaterializedParams.length === 0) {
+        return Object.freeze({ ok: true });
+    }
+    const selected = {};
+    for (const name of stage.includeMaterializedParams) {
+        const value = materialized[name];
+        if (typeof value !== "string") {
+            return Object.freeze({ ok: false });
+        }
+        selected[name] = value;
+    }
+    return Object.freeze({
+        ok: true,
+        value: Object.freeze(selected),
+    });
+}

package/dist/src/runtime/adapters/registered-tool-worker-capabilities/result-evidence.d.ts

@@ -0,0 +1,21 @@
+import type { ToolActionSummary } from "../../../capabilities/tool-types.js";
+import { type RoleCapabilityResultReference } from "../../orchestration/role-calls/index.js";
+import { type CapabilityAdapterResult } from "../../orchestration/capability-adapters/index.js";
+import type { WorkerCapabilityAdapterResult } from "../../orchestration/worker-capabilities/index.js";
+import type { RegisteredToolNormalInvocationProjection, RegisteredToolNormalInvocationResult } from "../registered-tool-normal-invocations.js";
+export declare function summarizeCompletedMutation(completionActions: readonly ToolActionSummary[]): string;
+export declare function projectMutationGrounding(input: unknown, directRoot?: boolean): string | undefined;
+export declare function projectToolTargetReferences(completionActions: readonly ToolActionSummary[]): readonly Readonly<{
+    kind: "tool_target";
+    target: string;
+}>[];
+export declare function projectSelectedTargetReferences(projection: RegisteredToolNormalInvocationProjection, controls: Readonly<Record<string, unknown>>, directRootSelectionControlIds?: readonly string[]): readonly RoleCapabilityResultReference[];
+export declare function attachTargetReferences(result: WorkerCapabilityAdapterResult, selected: readonly RoleCapabilityResultReference[]): WorkerCapabilityAdapterResult;
+export declare function captureRegisteredToolResult(input: RegisteredToolNormalInvocationResult): CapabilityAdapterResult;
+export declare function requireCapabilityAdapterResult(input: unknown): CapabilityAdapterResult;
+export declare function validateToolExecutionResult(input: unknown): void;
+export declare function boundedSummary(input: string, directRoot?: boolean): string;
+export declare function projectObservationOutput(input: string, directRoot?: boolean): Readonly<{
+    summary: string;
+    referenceData?: string;
+}>;

package/dist/src/runtime/adapters/registered-tool-worker-capabilities/result-evidence.js

@@ -0,0 +1,151 @@
+import { ROLE_CAPABILITY_REFERENCE_DATA_MAX_LENGTH, ROLE_CAPABILITY_RESULT_REFERENCE_LIMIT_MAX, ROLE_CAPABILITY_RESULT_REFERENCE_TARGET_MAX_LENGTH, ROLE_CALL_RESULT_MAX_LENGTH, } from "../../orchestration/role-calls/index.js";
+import { normalizeCapabilityAdapterResult, } from "../../orchestration/capability-adapters/index.js";
+import { executionProtocolError } from "./errors.js";
+import { isPlainRecord, nonEmpty } from "./values.js";
+const MUTATION_GROUNDING_MAX_LENGTH = 32_768;
+export function summarizeCompletedMutation(completionActions) {
+    if (completionActions.length === 0) {
+        return boundedSummary("The mutation capability reported a completed change.");
+    }
+    return boundedSummary([
+        "The mutation capability completed these logical effects:",
+        ...completionActions.map((action) => action.target
+            ? `- ${action.type}: ${action.target}`
+            : `- ${action.type}`),
+    ].join("\n"));
+}
+export function projectMutationGrounding(input, directRoot = false) {
+    const normalized = nonEmpty(input);
+    if (!normalized)
+        return undefined;
+    if (directRoot && normalized.length > MUTATION_GROUNDING_MAX_LENGTH) {
+        return undefined;
+    }
+    return normalized.length <= MUTATION_GROUNDING_MAX_LENGTH
+        ? normalized
+        : `${normalized.slice(0, MUTATION_GROUNDING_MAX_LENGTH - 1)}…`;
+}
+export function projectToolTargetReferences(completionActions) {
+    return projectTargetReferences(completionActions.map(({ target }) => target));
+}
+export function projectSelectedTargetReferences(projection, controls, directRootSelectionControlIds) {
+    const targetParam = projection.stagedPayloadPlan?.targetParam ??
+        projection.payloadContextPlan?.targetParam;
+    const targetParams = targetParam
+        ? [targetParam]
+        : (directRootSelectionControlIds ?? []);
+    return projectTargetReferences(targetParams.map((param) => controls[param]));
+}
+export function attachTargetReferences(result, selected) {
+    if (selected.length === 0)
+        return result;
+    const references = projectTargetReferences([
+        ...selected.map(({ target }) => target),
+        ...(result.references ?? []).map(({ target }) => target),
+    ]);
+    return Object.freeze({
+        ...result,
+        references,
+        ...(result.exactResult
+            ? {
+                exactResult: requireCapabilityAdapterResult({
+                    ...result.exactResult,
+                    references: projectTargetReferences([
+                        ...selected.map(({ target }) => target),
+                        ...(result.exactResult.references ?? []).map(({ target }) => target),
+                    ]),
+                }),
+            }
+            : {}),
+    });
+}
+export function captureRegisteredToolResult(input) {
+    if (input.status === "rejected") {
+        return requireCapabilityAdapterResult({
+            kind: "runtime_capability_rejection_v1",
+            authority: "runtime",
+            status: "rejected",
+            stage: "before_external_execution",
+            code: input.code,
+            message: input.message,
+        });
+    }
+    const references = projectToolTargetReferences(input.completionActions);
+    return requireCapabilityAdapterResult({
+        kind: "registered_tool_execution_result_v1",
+        authority: "registered_plugin",
+        status: "executed",
+        result: input.result,
+        ...(references.length > 0 ? { references } : {}),
+    });
+}
+export function requireCapabilityAdapterResult(input) {
+    const normalized = normalizeCapabilityAdapterResult(input);
+    if (!normalized.ok) {
+        throw executionProtocolError(`canonical_result_${normalized.code}`);
+    }
+    return normalized.value;
+}
+function projectTargetReferences(values) {
+    const targets = new Set();
+    const references = [];
+    for (const value of values) {
+        const target = typeof value === "string" ? value.trim() : "";
+        if (!target ||
+            target.length > ROLE_CAPABILITY_RESULT_REFERENCE_TARGET_MAX_LENGTH ||
+            targets.has(target)) {
+            continue;
+        }
+        targets.add(target);
+        references.push(Object.freeze({ kind: "tool_target", target }));
+        if (references.length >= ROLE_CAPABILITY_RESULT_REFERENCE_LIMIT_MAX)
+            break;
+    }
+    return Object.freeze(references);
+}
+export function validateToolExecutionResult(input) {
+    if (!isPlainRecord(input) ||
+        typeof input.ok !== "boolean" ||
+        !nonEmpty(input.tool) ||
+        typeof input.output !== "string" ||
+        typeof input.producedNewInformation !== "boolean" ||
+        (input.data !== undefined && !isPlainRecord(input.data)) ||
+        (isPlainRecord(input.data) &&
+            input.data.currentStateEvidence !== undefined &&
+            typeof input.data.currentStateEvidence !== "boolean") ||
+        (isPlainRecord(input.data) &&
+            input.data.mutationEvidence !== undefined &&
+            typeof input.data.mutationEvidence !== "boolean") ||
+        (isPlainRecord(input.data) &&
+            input.data.stateAlreadySatisfied !== undefined &&
+            typeof input.data.stateAlreadySatisfied !== "boolean")) {
+        throw executionProtocolError("tool_result_invalid");
+    }
+}
+export function boundedSummary(input, directRoot = false) {
+    const normalized = input.trim();
+    if (normalized.length > ROLE_CALL_RESULT_MAX_LENGTH) {
+        return directRoot
+            ? "The capability result is available in the canonical direct execution result."
+            : "The capability result is available in the canonical execution result.";
+    }
+    return normalized;
+}
+export function projectObservationOutput(input, directRoot = false) {
+    const normalized = input.trim();
+    if (normalized.length <= ROLE_CALL_RESULT_MAX_LENGTH) {
+        return Object.freeze({ summary: normalized });
+    }
+    if (directRoot ||
+        normalized.length > ROLE_CAPABILITY_REFERENCE_DATA_MAX_LENGTH) {
+        return Object.freeze({
+            summary: directRoot
+                ? "The capability result is available in the canonical direct execution result."
+                : "The capability result is available in the canonical execution result.",
+        });
+    }
+    return Object.freeze({
+        summary: `The observation completed successfully with ${normalized.length} characters of result data; its producing Worker received the complete result.`,
+        referenceData: normalized,
+    });
+}

package/dist/src/runtime/adapters/registered-tool-worker-capabilities/result-observer.d.ts

@@ -0,0 +1,8 @@
+import type { WorkerCapabilityAdapterResult } from "../../orchestration/worker-capabilities/index.js";
+import type { RegisteredToolNormalInvocationResult } from "../registered-tool-normal-invocations.js";
+type ObservedExternalResult = Readonly<{
+    result: WorkerCapabilityAdapterResult;
+    sourceIssueCode?: string;
+}>;
+export declare function observeExternalResult(input: RegisteredToolNormalInvocationResult, expectedEffect: "read_only" | "mutating" | "mixed", directRoot: boolean): ObservedExternalResult;
+export { attachTargetReferences, boundedSummary, projectSelectedTargetReferences, requireCapabilityAdapterResult, } from "./result-evidence.js";