@abot-ai/runtime 1.0.0

package/dist/src/runtime/orchestration/capability-adapters/descriptor.js

@@ -0,0 +1,54 @@
+import { isRoleCapabilityId } from "../role-calls/index.js";
+import { WORKER_CAPABILITY_SUMMARY_MAX_LENGTH, } from "../worker-capabilities/contracts.js";
+import { normalizeWorkerCapabilityControlsSchema } from "../worker-capabilities/controls.js";
+import { partitionWorkerCapabilityControlsSchema } from "../worker-capabilities/selection-controls.js";
+import { projectWorkerCapabilityScope } from "../worker-capabilities/scope.js";
+/**
+ * Contract projection only. Adapter construction and execution remain owned by
+ * the shared role-call capability binding.
+ */
+export function normalizeCapabilityDescriptor(descriptor) {
+    if (typeof descriptor !== "object" ||
+        descriptor === null ||
+        Array.isArray(descriptor) ||
+        !isRoleCapabilityId(descriptor.capabilityId)) {
+        return failure("descriptor_invalid");
+    }
+    if (typeof descriptor.summary !== "string" ||
+        descriptor.summary.trim().length === 0 ||
+        descriptor.summary.length > WORKER_CAPABILITY_SUMMARY_MAX_LENGTH) {
+        return failure("descriptor_summary_invalid");
+    }
+    const controls = normalizeWorkerCapabilityControlsSchema(descriptor.controls);
+    if (!controls.ok)
+        return failure(`descriptor_${controls.issueCode}`);
+    const partition = partitionWorkerCapabilityControlsSchema(controls.value, descriptor.selectionControlIds);
+    if (!partition.ok)
+        return failure(`descriptor_${partition.issueCode}`);
+    try {
+        projectWorkerCapabilityScope({
+            entries: [descriptor],
+            descriptorOf: (entry) => entry,
+        });
+    }
+    catch {
+        return failure("descriptor_scope_invalid");
+    }
+    return Object.freeze({
+        ok: true,
+        value: Object.freeze({
+            ...descriptor,
+            summary: descriptor.summary.trim(),
+            controls: controls.value,
+            ...(partition.value.selectionControlIds.length > 0
+                ? { selectionControlIds: partition.value.selectionControlIds }
+                : {}),
+            catalogGroups: Object.freeze([
+                ...(descriptor.catalogGroups ?? ["other"]),
+            ]),
+        }),
+    });
+}
+function failure(issueCode) {
+    return Object.freeze({ ok: false, issueCode });
+}

package/dist/src/runtime/orchestration/capability-adapters/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Policy-neutral capability vocabulary over the single role-call capability
+ * implementation. This module deliberately contains no binding or execution
+ * engine; it only gives root contracts neutral names for shared contracts.
+ */
+export { WORKER_CAPABILITY_CONTROL_ARRAY_MAX_ITEMS as CAPABILITY_CONTROL_ARRAY_MAX_ITEMS, WORKER_CAPABILITY_CONTROL_COUNT_MAX as CAPABILITY_CONTROL_COUNT_MAX, WORKER_CAPABILITY_CONTROL_ENUM_MAX_VALUES as CAPABILITY_CONTROL_ENUM_MAX_VALUES, WORKER_CAPABILITY_CONTROL_ENUM_VALUE_MAX_LENGTH as CAPABILITY_CONTROL_ENUM_VALUE_MAX_LENGTH, WORKER_CAPABILITY_CONTROL_ID_MAX_LENGTH as CAPABILITY_CONTROL_ID_MAX_LENGTH, WORKER_CAPABILITY_CONTROL_STRING_MAX_LENGTH as CAPABILITY_CONTROL_STRING_MAX_LENGTH, WORKER_CAPABILITY_COUNT_MAX as CAPABILITY_COUNT_MAX, WORKER_CAPABILITY_ID_MAX_LENGTH as CAPABILITY_ID_MAX_LENGTH, WORKER_CAPABILITY_INTENT_MAX_LENGTH as CAPABILITY_INTENT_MAX_LENGTH, WORKER_CAPABILITY_SUMMARY_MAX_LENGTH as CAPABILITY_SUMMARY_MAX_LENGTH, EMPTY_WORKER_CAPABILITY_CONTROLS_SCHEMA as EMPTY_CAPABILITY_CONTROLS_SCHEMA, } from "../worker-capabilities/contracts.js";
+export type { WorkerCapabilityArrayControl as CapabilityArrayControl, WorkerCapabilityBooleanControl as CapabilityBooleanControl, WorkerCapabilityBoundedStringControl as CapabilityBoundedStringControl, WorkerCapabilityControl as CapabilityControl, WorkerCapabilityControls as CapabilityControls, WorkerCapabilityControlsSchema as CapabilityControlsSchema, WorkerCapabilityDescriptor as CapabilityDescriptor, WorkerCapabilityEffect as CapabilityDeclaredEffect, WorkerCapabilityEnumControl as CapabilityEnumControl, WorkerCapabilityNumberControl as CapabilityNumberControl, WorkerCapabilityScalarControl as CapabilityScalarControl, WorkerCapabilityUnboundedStringControl as CapabilityUnboundedStringControl, } from "../worker-capabilities/contracts.js";
+export { normalizeWorkerCapabilityControlsSchema as normalizeCapabilityControlsSchema, validateWorkerCapabilityControls as validateCapabilityControls, } from "../worker-capabilities/controls.js";
+export { materializeWorkerCapabilityControlsIfComplete as materializeCapabilityControlsIfComplete, mergeWorkerCapabilityControls as mergeCapabilityControls, normalizeWorkerCapabilitySelectionControlIds as normalizeCapabilitySelectionControlIds, partitionWorkerCapabilityControlsSchema as partitionCapabilityControlsSchema, validateWorkerCapabilityRemainingControls as validateCapabilityRemainingControls, validateWorkerCapabilitySelectionControls as validateCapabilitySelectionControls, } from "../worker-capabilities/selection-controls.js";
+export type { WorkerCapabilityControlsPartition as CapabilityControlsPartition, WorkerCapabilityControlsPartitionResult as CapabilityControlsPartitionResult, WorkerCapabilitySelectionControlIdsNormalization as CapabilitySelectionControlIdsNormalization, } from "../worker-capabilities/selection-controls.js";
+export { CAPABILITY_CATALOG_GROUP_COUNT_MAX, projectCapabilityCatalogGroups, projectCapabilityScope, type CapabilityCatalogGroup, } from "./scope.js";
+export { normalizeCapabilityDescriptor } from "./descriptor.js";
+export { CAPABILITY_ADAPTER_RESULT_SERIALIZED_MAX_BYTES, captureLegacyCapabilityAdapterResult, normalizeCapabilityAdapterResult, type CanonicalToolExecutionResult, type CapabilityAdapterResult, type CapabilityAdapterResultNormalization, type CapabilityJsonObject, type CapabilityJsonPrimitive, type CapabilityJsonValue, type CapabilityResultReference, type GenericCapabilityAdapterResult, type RegisteredToolCapabilityResult, type RuntimeCapabilityRejectionResult, } from "./result.js";
+export { EXECUTION_WORKING_DIRECTORY_MAX_LENGTH, EXECUTION_WORKING_DIRECTORY_PATTERN, normalizeExecutionWorkingDirectory, } from "./working-directory.js";

package/dist/src/runtime/orchestration/capability-adapters/index.js

@@ -0,0 +1,12 @@
+/**
+ * Policy-neutral capability vocabulary over the single role-call capability
+ * implementation. This module deliberately contains no binding or execution
+ * engine; it only gives root contracts neutral names for shared contracts.
+ */
+export { WORKER_CAPABILITY_CONTROL_ARRAY_MAX_ITEMS as CAPABILITY_CONTROL_ARRAY_MAX_ITEMS, WORKER_CAPABILITY_CONTROL_COUNT_MAX as CAPABILITY_CONTROL_COUNT_MAX, WORKER_CAPABILITY_CONTROL_ENUM_MAX_VALUES as CAPABILITY_CONTROL_ENUM_MAX_VALUES, WORKER_CAPABILITY_CONTROL_ENUM_VALUE_MAX_LENGTH as CAPABILITY_CONTROL_ENUM_VALUE_MAX_LENGTH, WORKER_CAPABILITY_CONTROL_ID_MAX_LENGTH as CAPABILITY_CONTROL_ID_MAX_LENGTH, WORKER_CAPABILITY_CONTROL_STRING_MAX_LENGTH as CAPABILITY_CONTROL_STRING_MAX_LENGTH, WORKER_CAPABILITY_COUNT_MAX as CAPABILITY_COUNT_MAX, WORKER_CAPABILITY_ID_MAX_LENGTH as CAPABILITY_ID_MAX_LENGTH, WORKER_CAPABILITY_INTENT_MAX_LENGTH as CAPABILITY_INTENT_MAX_LENGTH, WORKER_CAPABILITY_SUMMARY_MAX_LENGTH as CAPABILITY_SUMMARY_MAX_LENGTH, EMPTY_WORKER_CAPABILITY_CONTROLS_SCHEMA as EMPTY_CAPABILITY_CONTROLS_SCHEMA, } from "../worker-capabilities/contracts.js";
+export { normalizeWorkerCapabilityControlsSchema as normalizeCapabilityControlsSchema, validateWorkerCapabilityControls as validateCapabilityControls, } from "../worker-capabilities/controls.js";
+export { materializeWorkerCapabilityControlsIfComplete as materializeCapabilityControlsIfComplete, mergeWorkerCapabilityControls as mergeCapabilityControls, normalizeWorkerCapabilitySelectionControlIds as normalizeCapabilitySelectionControlIds, partitionWorkerCapabilityControlsSchema as partitionCapabilityControlsSchema, validateWorkerCapabilityRemainingControls as validateCapabilityRemainingControls, validateWorkerCapabilitySelectionControls as validateCapabilitySelectionControls, } from "../worker-capabilities/selection-controls.js";
+export { CAPABILITY_CATALOG_GROUP_COUNT_MAX, projectCapabilityCatalogGroups, projectCapabilityScope, } from "./scope.js";
+export { normalizeCapabilityDescriptor } from "./descriptor.js";
+export { CAPABILITY_ADAPTER_RESULT_SERIALIZED_MAX_BYTES, captureLegacyCapabilityAdapterResult, normalizeCapabilityAdapterResult, } from "./result.js";
+export { EXECUTION_WORKING_DIRECTORY_MAX_LENGTH, EXECUTION_WORKING_DIRECTORY_PATTERN, normalizeExecutionWorkingDirectory, } from "./working-directory.js";

package/dist/src/runtime/orchestration/capability-adapters/result.d.ts

@@ -0,0 +1,74 @@
+export declare const CAPABILITY_ADAPTER_RESULT_SERIALIZED_MAX_BYTES: number;
+export type CapabilityJsonPrimitive = string | number | boolean | null;
+export type CapabilityJsonValue = CapabilityJsonPrimitive | readonly CapabilityJsonValue[] | CapabilityJsonObject;
+export interface CapabilityJsonObject {
+    readonly [key: string]: CapabilityJsonValue;
+}
+export type CapabilityResultReference = Readonly<{
+    kind: "tool_target";
+    target: string;
+}>;
+export type CanonicalToolExecutionResult = Readonly<{
+    ok: boolean;
+    tool: string;
+    output: string;
+    progress?: boolean;
+    producedNewInformation: boolean;
+    actions?: readonly Readonly<{
+        type: string;
+        target?: string;
+        details?: string;
+    }>[];
+    exitCode?: number;
+    stdout?: string;
+    stderr?: string;
+    data?: CapabilityJsonObject;
+    error?: string;
+    errorCode?: string;
+}>;
+export type RegisteredToolCapabilityResult = Readonly<{
+    kind: "registered_tool_execution_result_v1";
+    authority: "registered_plugin";
+    status: "executed";
+    /** Exact JSON-safe ToolExecutionResult returned by the registered plugin. */
+    result: CanonicalToolExecutionResult;
+    references?: readonly CapabilityResultReference[];
+}>;
+export type RuntimeCapabilityRejectionResult = Readonly<{
+    kind: "runtime_capability_rejection_v1";
+    authority: "runtime";
+    status: "rejected";
+    stage: "before_external_execution";
+    code: string;
+    message: string;
+    references?: readonly CapabilityResultReference[];
+}>;
+export type GenericCapabilityAdapterResult = Readonly<{
+    kind: "generic_capability_result_v1";
+    authority: "capability_adapter";
+    status: "executed";
+    ok: boolean;
+    /** Exact JSON-safe adapter-owned payload; runtime assigns no semantics. */
+    payload: CapabilityJsonValue;
+    references?: readonly CapabilityResultReference[];
+}>;
+export type CapabilityAdapterResult = RegisteredToolCapabilityResult | RuntimeCapabilityRejectionResult | GenericCapabilityAdapterResult;
+export type CapabilityAdapterResultNormalization = Readonly<{
+    ok: true;
+    value: CapabilityAdapterResult;
+}> | Readonly<{
+    ok: false;
+    code: "result_invalid" | "result_not_json_safe" | "result_too_large";
+}>;
+/**
+ * Captures one typed exact result without truncating or semantically rewriting
+ * plugin-authored content. Bounds come from the explicit envelope schema and
+ * the hard serialized-result producer limit.
+ */
+export declare function normalizeCapabilityAdapterResult(input: unknown): CapabilityAdapterResultNormalization;
+/**
+ * Compatibility bridge for custom adapters that still implement the legacy
+ * Worker result contract. The original adapter payload is captured exactly
+ * inside a generic envelope for every authorized principal.
+ */
+export declare function captureLegacyCapabilityAdapterResult(input: unknown): CapabilityAdapterResultNormalization;

package/dist/src/runtime/orchestration/capability-adapters/result.js

@@ -0,0 +1,307 @@
+import { ROLE_CAPABILITY_RESULT_REFERENCE_LIMIT_MAX, ROLE_CAPABILITY_RESULT_REFERENCE_TARGET_MAX_LENGTH, } from "../role-calls/contracts.js";
+export const CAPABILITY_ADAPTER_RESULT_SERIALIZED_MAX_BYTES = 256 * 1024;
+/**
+ * Captures one typed exact result without truncating or semantically rewriting
+ * plugin-authored content. Bounds come from the explicit envelope schema and
+ * the hard serialized-result producer limit.
+ */
+export function normalizeCapabilityAdapterResult(input) {
+    try {
+        const normalized = normalizeCanonicalResult(input);
+        return normalized
+            ? acceptBoundedResult(normalized)
+            : invalid("result_invalid");
+    }
+    catch {
+        return invalid("result_not_json_safe");
+    }
+}
+/**
+ * Compatibility bridge for custom adapters that still implement the legacy
+ * Worker result contract. The original adapter payload is captured exactly
+ * inside a generic envelope for every authorized principal.
+ */
+export function captureLegacyCapabilityAdapterResult(input) {
+    try {
+        return captureLegacyCapabilityAdapterResultUnsafe(input);
+    }
+    catch {
+        return invalid("result_not_json_safe");
+    }
+}
+function captureLegacyCapabilityAdapterResultUnsafe(input) {
+    if (!isPlainRecord(input) ||
+        !hasExactKeys(input, ["outcome", "observedEffect", "summary"], ["referenceData", "references", "exactResult"]) ||
+        (input.outcome !== "succeeded" && input.outcome !== "failed") ||
+        (input.observedEffect !== "none" &&
+            input.observedEffect !== "observation" &&
+            input.observedEffect !== "mutation" &&
+            input.observedEffect !== "indeterminate") ||
+        typeof input.summary !== "string" ||
+        (input.referenceData !== undefined &&
+            typeof input.referenceData !== "string")) {
+        return invalid("result_invalid");
+    }
+    const references = normalizeReferences(input.references);
+    const payload = captureJsonValue({
+        outcome: input.outcome,
+        observedEffect: input.observedEffect,
+        summary: input.summary,
+        ...(input.referenceData === undefined
+            ? {}
+            : { referenceData: input.referenceData }),
+    });
+    if (references === null || payload === undefined) {
+        return invalid("result_not_json_safe");
+    }
+    return acceptBoundedResult(Object.freeze({
+        kind: "generic_capability_result_v1",
+        authority: "capability_adapter",
+        status: "executed",
+        ok: input.outcome === "succeeded",
+        payload,
+        ...(references ? { references } : {}),
+    }));
+}
+function normalizeCanonicalResult(input) {
+    if (!isPlainRecord(input))
+        return undefined;
+    switch (input.kind) {
+        case "registered_tool_execution_result_v1":
+            return normalizeRegisteredToolResult(input);
+        case "runtime_capability_rejection_v1":
+            return normalizeRuntimeRejection(input);
+        case "generic_capability_result_v1":
+            return normalizeGenericResult(input);
+        default:
+            return undefined;
+    }
+}
+function normalizeRegisteredToolResult(input) {
+    if (!hasExactKeys(input, ["kind", "authority", "status", "result"], ["references"]) ||
+        input.authority !== "registered_plugin" ||
+        input.status !== "executed") {
+        return undefined;
+    }
+    const result = captureToolExecutionResult(input.result);
+    const references = normalizeReferences(input.references);
+    if (!result || references === null)
+        return undefined;
+    return Object.freeze({
+        kind: "registered_tool_execution_result_v1",
+        authority: "registered_plugin",
+        status: "executed",
+        result,
+        ...(references ? { references } : {}),
+    });
+}
+function normalizeRuntimeRejection(input) {
+    if (!hasExactKeys(input, ["kind", "authority", "status", "stage", "code", "message"], ["references"]) ||
+        input.authority !== "runtime" ||
+        input.status !== "rejected" ||
+        input.stage !== "before_external_execution" ||
+        typeof input.code !== "string" ||
+        input.code.trim().length === 0 ||
+        typeof input.message !== "string" ||
+        input.message.trim().length === 0) {
+        return undefined;
+    }
+    const references = normalizeReferences(input.references);
+    if (references === null)
+        return undefined;
+    return Object.freeze({
+        kind: "runtime_capability_rejection_v1",
+        authority: "runtime",
+        status: "rejected",
+        stage: "before_external_execution",
+        code: input.code,
+        message: input.message,
+        ...(references ? { references } : {}),
+    });
+}
+function normalizeGenericResult(input) {
+    if (!hasExactKeys(input, ["kind", "authority", "status", "ok", "payload"], ["references"]) ||
+        input.authority !== "capability_adapter" ||
+        input.status !== "executed" ||
+        typeof input.ok !== "boolean") {
+        return undefined;
+    }
+    const payload = captureJsonValue(input.payload);
+    const references = normalizeReferences(input.references);
+    if (payload === undefined || references === null)
+        return undefined;
+    return Object.freeze({
+        kind: "generic_capability_result_v1",
+        authority: "capability_adapter",
+        status: "executed",
+        ok: input.ok,
+        payload,
+        ...(references ? { references } : {}),
+    });
+}
+function captureToolExecutionResult(input) {
+    if (!isPlainRecord(input) ||
+        !hasExactKeys(input, ["ok", "tool", "output", "producedNewInformation"], [
+            "progress",
+            "actions",
+            "exitCode",
+            "stdout",
+            "stderr",
+            "data",
+            "error",
+            "errorCode",
+        ]) ||
+        typeof input.ok !== "boolean" ||
+        typeof input.tool !== "string" ||
+        input.tool.trim().length === 0 ||
+        typeof input.output !== "string" ||
+        typeof input.producedNewInformation !== "boolean" ||
+        (input.progress !== undefined && typeof input.progress !== "boolean") ||
+        (input.exitCode !== undefined &&
+            (typeof input.exitCode !== "number" ||
+                !Number.isFinite(input.exitCode))) ||
+        (input.stdout !== undefined && typeof input.stdout !== "string") ||
+        (input.stderr !== undefined && typeof input.stderr !== "string") ||
+        (input.error !== undefined && typeof input.error !== "string") ||
+        (input.errorCode !== undefined && typeof input.errorCode !== "string") ||
+        !validActions(input.actions) ||
+        !validToolData(input.data)) {
+        return undefined;
+    }
+    const captured = captureJsonValue(input);
+    return isPlainRecord(captured)
+        ? captured
+        : undefined;
+}
+function validActions(input) {
+    return (input === undefined ||
+        (Array.isArray(input) &&
+            input.every((entry) => isPlainRecord(entry) &&
+                hasExactKeys(entry, ["type"], ["target", "details"]) &&
+                typeof entry.type === "string" &&
+                (entry.target === undefined || typeof entry.target === "string") &&
+                (entry.details === undefined || typeof entry.details === "string"))));
+}
+function validToolData(input) {
+    if (input === undefined)
+        return true;
+    if (!isPlainRecord(input))
+        return false;
+    const booleanFields = [
+        "hasData",
+        "mutationEvidence",
+        "currentStateEvidence",
+        "stateAlreadySatisfied",
+    ];
+    return !(booleanFields.some((field) => input[field] !== undefined && typeof input[field] !== "boolean") ||
+        (input.itemCount !== undefined &&
+            (typeof input.itemCount !== "number" ||
+                !Number.isFinite(input.itemCount))) ||
+        (input.mutationGrounding !== undefined &&
+            typeof input.mutationGrounding !== "string") ||
+        (input.observationMeta !== undefined &&
+            !isPlainRecord(input.observationMeta)) ||
+        (input.eventMeta !== undefined && !isPlainRecord(input.eventMeta)) ||
+        captureJsonValue(input) === undefined);
+}
+function normalizeReferences(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) {
+        if (!isPlainRecord(candidate) ||
+            !hasExactKeys(candidate, ["kind", "target"]) ||
+            candidate.kind !== "tool_target" ||
+            typeof candidate.target !== "string" ||
+            candidate.target.trim().length === 0 ||
+            candidate.target.length >
+                ROLE_CAPABILITY_RESULT_REFERENCE_TARGET_MAX_LENGTH ||
+            targets.has(candidate.target)) {
+            return null;
+        }
+        targets.add(candidate.target);
+        references.push(Object.freeze({ kind: "tool_target", target: candidate.target }));
+    }
+    return Object.freeze(references);
+}
+function captureJsonValue(input, seen = new WeakSet()) {
+    if (input === null ||
+        typeof input === "string" ||
+        typeof input === "boolean") {
+        return input;
+    }
+    if (typeof input === "number") {
+        return Number.isFinite(input) ? input : undefined;
+    }
+    if (typeof input !== "object" || seen.has(input))
+        return undefined;
+    seen.add(input);
+    try {
+        if (Array.isArray(input)) {
+            const values = [];
+            for (let index = 0; index < input.length; index += 1) {
+                const descriptor = Object.getOwnPropertyDescriptor(input, index);
+                if (!descriptor || !("value" in descriptor))
+                    return undefined;
+                const value = captureJsonValue(descriptor.value, seen);
+                if (value === undefined)
+                    return undefined;
+                values.push(value);
+            }
+            return Object.freeze(values);
+        }
+        if (!isPlainRecord(input) || !hasOnlyEnumerableDataProperties(input)) {
+            return undefined;
+        }
+        const entries = [];
+        for (const key of Object.keys(input)) {
+            const value = captureJsonValue(input[key], seen);
+            if (value === undefined)
+                return undefined;
+            entries.push([key, value]);
+        }
+        return Object.freeze(Object.fromEntries(entries));
+    }
+    finally {
+        seen.delete(input);
+    }
+}
+function hasOnlyEnumerableDataProperties(input) {
+    return Reflect.ownKeys(input).every((key) => {
+        if (typeof key !== "string")
+            return false;
+        const descriptor = Object.getOwnPropertyDescriptor(input, key);
+        return descriptor?.enumerable === true && "value" in descriptor;
+    });
+}
+function isPlainRecord(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function hasExactKeys(input, required, optional = []) {
+    const allowed = new Set([...required, ...optional]);
+    const keys = Object.keys(input);
+    return (required.every((key) => Object.hasOwn(input, key)) &&
+        keys.every((key) => allowed.has(key)));
+}
+function invalid(code) {
+    return Object.freeze({ ok: false, code });
+}
+function acceptBoundedResult(value) {
+    const serialized = JSON.stringify(value);
+    if (serialized === undefined)
+        return invalid("result_not_json_safe");
+    if (Buffer.byteLength(serialized, "utf8") >
+        CAPABILITY_ADAPTER_RESULT_SERIALIZED_MAX_BYTES) {
+        return invalid("result_too_large");
+    }
+    return Object.freeze({ ok: true, value });
+}

package/dist/src/runtime/orchestration/capability-adapters/scope.d.ts

@@ -0,0 +1,17 @@
+import type { ToolCatalogGroup } from "../../../capabilities/tool-types.js";
+import type { WorkerCapabilityDescriptor, WorkerCapabilityEffect } from "../worker-capabilities/contracts.js";
+import { type WorkerCapabilityScopeProjection } from "../worker-capabilities/scope.js";
+export declare const CAPABILITY_CATALOG_GROUP_COUNT_MAX = 64;
+export type CapabilityCatalogGroup = Readonly<{
+    groupId: ToolCatalogGroup;
+    description: string;
+    memberCount: number;
+    effects: readonly WorkerCapabilityEffect[];
+}>;
+/** Builds routing text mechanically from every exact group member. */
+export declare function projectCapabilityCatalogGroups(descriptors: readonly WorkerCapabilityDescriptor[]): readonly CapabilityCatalogGroup[];
+export declare function projectCapabilityScope<T>(params: Readonly<{
+    entries: readonly T[];
+    scope?: unknown;
+    descriptorOf(entry: T): WorkerCapabilityDescriptor;
+}>): WorkerCapabilityScopeProjection<T>;

package/dist/src/runtime/orchestration/capability-adapters/scope.js

@@ -0,0 +1,51 @@
+import { projectWorkerCapabilityScope, } from "../worker-capabilities/scope.js";
+export const CAPABILITY_CATALOG_GROUP_COUNT_MAX = 64;
+const EFFECT_ORDER = Object.freeze([
+    "observation",
+    "mutation",
+    "mixed",
+]);
+/** Builds routing text mechanically from every exact group member. */
+export function projectCapabilityCatalogGroups(descriptors) {
+    const normalized = projectWorkerCapabilityScope({
+        entries: descriptors,
+        descriptorOf: (entry) => entry,
+    });
+    const groups = new Map();
+    for (const descriptor of normalized.entries) {
+        for (const groupId of descriptor.catalogGroups ?? ["other"]) {
+            const group = groups.get(groupId) ?? {
+                members: [],
+                effects: new Set(),
+            };
+            group.members.push({
+                capabilityId: descriptor.capabilityId,
+                summary: descriptor.summary,
+            });
+            group.effects.add(descriptor.effect);
+            groups.set(groupId, group);
+        }
+    }
+    if (groups.size > CAPABILITY_CATALOG_GROUP_COUNT_MAX) {
+        throw new TypeError("capability_scope_rejected:catalog_group_limit");
+    }
+    return Object.freeze([...groups.entries()]
+        .sort(([left], [right]) => compareAscii(left, right))
+        .map(([groupId, group]) => {
+        const members = [...group.members].sort((left, right) => compareAscii(left.capabilityId, right.capabilityId));
+        return Object.freeze({
+            groupId,
+            description: members
+                .map(({ capabilityId, summary }) => `${capabilityId}: ${summary}`)
+                .join("\n"),
+            memberCount: members.length,
+            effects: Object.freeze(EFFECT_ORDER.filter((effect) => group.effects.has(effect))),
+        });
+    }));
+}
+export function projectCapabilityScope(params) {
+    return projectWorkerCapabilityScope(params);
+}
+function compareAscii(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}

package/dist/src/runtime/orchestration/capability-adapters/working-directory.d.ts

@@ -0,0 +1,4 @@
+export declare const EXECUTION_WORKING_DIRECTORY_MAX_LENGTH = 4096;
+export declare const EXECUTION_WORKING_DIRECTORY_PATTERN = "^(?:\\.|[A-Za-z0-9._-]+(?:/[A-Za-z0-9._-]+)*)$";
+/** Normalizes one portable agent-work-directory-relative execution base. */
+export declare function normalizeExecutionWorkingDirectory(input: unknown): string | undefined;

package/dist/src/runtime/orchestration/capability-adapters/working-directory.js

@@ -0,0 +1,7 @@
+import { normalizeEstablishedRoleCallWorkingDirectory, ROLE_CALL_PORTABLE_WORKING_DIRECTORY_PATTERN, ROLE_CALL_WORKING_DIRECTORY_MAX_LENGTH, } from "../role-calls/index.js";
+export const EXECUTION_WORKING_DIRECTORY_MAX_LENGTH = ROLE_CALL_WORKING_DIRECTORY_MAX_LENGTH;
+export const EXECUTION_WORKING_DIRECTORY_PATTERN = ROLE_CALL_PORTABLE_WORKING_DIRECTORY_PATTERN;
+/** Normalizes one portable agent-work-directory-relative execution base. */
+export function normalizeExecutionWorkingDirectory(input) {
+    return normalizeEstablishedRoleCallWorkingDirectory(input);
+}

package/dist/src/runtime/orchestration/final-response/finalization.d.ts

@@ -0,0 +1,15 @@
+import type { SessionMessageGrounding, SessionMessageObservationMeta, SessionThinkingTraceEntry } from "../../../sessions/types.js";
+import type { AgentMode } from "../../../shared/types.js";
+import type { EventSink, SessionStore } from "../../ports.js";
+export declare function finalizeResponse(params: {
+    events: EventSink;
+    sessionStore?: Pick<SessionStore, "appendMessage">;
+    sessionId: string;
+    requestId: string;
+    agentMode: AgentMode;
+    output: string;
+    grounding?: SessionMessageGrounding;
+    observationMeta?: SessionMessageObservationMeta;
+    observationContent?: string;
+    thinkingTrace?: SessionThinkingTraceEntry[];
+}): Promise<void>;

package/dist/src/runtime/orchestration/final-response/finalization.js

@@ -0,0 +1,18 @@
+import { defaultRuntimeSessionStore } from "../../adapters/default-session-adapters.js";
+export async function finalizeResponse(params) {
+    const sessionStore = params.sessionStore ?? defaultRuntimeSessionStore;
+    await sessionStore.appendMessage(params.sessionId, "assistant", params.output, {
+        lastAgentMode: params.agentMode,
+        requestId: params.requestId,
+        ...(params.grounding ? { grounding: params.grounding } : {}),
+        ...(params.observationMeta
+            ? { observationMeta: params.observationMeta }
+            : {}),
+        ...(params.observationContent
+            ? { observationContent: params.observationContent }
+            : {}),
+        ...(params.thinkingTrace ? { thinkingTrace: params.thinkingTrace } : {}),
+    });
+    params.events.event("thinking.completed");
+    params.events.completed(params.output);
+}

package/dist/src/runtime/orchestration/lifecycle/request-lifecycle.d.ts

@@ -0,0 +1,37 @@
+export type RequestLifecycleAbortReason = "request_timeout" | "request_inactivity_timeout";
+export type MeaningfulProgressKind = "accepted_tool_execution" | "valid_decision" | "valid_final_output";
+export type RequestLifecycleState = {
+    stage?: string;
+    phase?: string;
+    message?: string;
+    reason?: string;
+    attempt?: number;
+    toolIteration?: number;
+    decisionAttemptCount?: number;
+};
+export declare function getRequestTimeoutMs(): number;
+export declare function getRequestInactivityTimeoutMs(): number;
+export declare class RequestLifecycle {
+    readonly abortController: AbortController;
+    private readonly requestId;
+    private readonly startedAtMs;
+    private readonly requestTimeoutMs;
+    private readonly inactivityTimeoutMs;
+    private requestTimeoutHandle;
+    private inactivityTimeoutHandle;
+    private abortReason;
+    private state;
+    constructor(params: {
+        requestId: string;
+        requestTimeoutMs?: number;
+        inactivityTimeoutMs?: number;
+    });
+    get signal(): AbortSignal;
+    get timedOutReason(): RequestLifecycleAbortReason | null;
+    markProgress(kind: MeaningfulProgressKind): void;
+    updateState(state: RequestLifecycleState): void;
+    dispose(): void;
+    private resetInactivityTimer;
+    private abort;
+}
+export declare function buildLifecycleDegradedOutput(reason: RequestLifecycleAbortReason): string;