@abot-ai/runtime 1.0.0

package/dist/src/runtime/orchestration/role-calls/reducer-primitives.js

@@ -0,0 +1,161 @@
+import { normalizeCapabilityAdapterResult, } from "../capability-adapters/result.js";
+import { ROLE_CAPABILITY_INVOCATION_CONTROLS_JSON_MAX_LENGTH, ROLE_CAPABILITY_RESULT_REFERENCE_LIMIT_MAX, ROLE_CAPABILITY_RESULT_REFERENCE_TARGET_MAX_LENGTH, } from "./contracts.js";
+export function commit(candidate, effect) {
+    return {
+        ok: true,
+        state: seal(candidate),
+        effect: Object.freeze(effect),
+    };
+}
+export function reject(state, code, issues) {
+    return {
+        ok: false,
+        state,
+        code,
+        ...(issues && issues.length > 0
+            ? { issues: Object.freeze([...issues]) }
+            : {}),
+    };
+}
+export function findCall(state, callId) {
+    return state.calls.find((call) => call.callId === callId);
+}
+export function exactKeys(value, requiredKeys, optionalKeys = []) {
+    const required = new Set(requiredKeys);
+    const allowed = new Set([...requiredKeys, ...optionalKeys]);
+    const actual = Object.keys(value);
+    return (requiredKeys.every((key) => actual.includes(key)) &&
+        actual.every((key) => allowed.has(key)) &&
+        actual.length >= required.size &&
+        actual.length <= allowed.size);
+}
+export function isExactJsonObjectString(value) {
+    if (typeof value !== "string" ||
+        value.length < 2 ||
+        value.length > ROLE_CAPABILITY_INVOCATION_CONTROLS_JSON_MAX_LENGTH) {
+        return false;
+    }
+    try {
+        const parsed = JSON.parse(value);
+        return isRecord(parsed) && JSON.stringify(parsed) === value;
+    }
+    catch {
+        return false;
+    }
+}
+export function isUniqueStringArray(value) {
+    return (Array.isArray(value) &&
+        value.every((entry) => typeof entry === "string" && entry.length > 0) &&
+        new Set(value).size === value.length);
+}
+export function sameStringArray(left, right) {
+    return (left.length === right.length &&
+        left.every((value, index) => value === right[index]));
+}
+export function areOwnedDependencyResults(state, caller, resultRefs, dependentCallIndex = state.calls.length) {
+    if (!isUniqueStringArray(resultRefs))
+        return false;
+    return resultRefs.every((resultRef) => {
+        const result = state.results.find((candidate) => candidate.resultRef === resultRef);
+        const producerIndex = state.calls.findIndex((candidate) => candidate.callId === result?.producerCallId);
+        const producer = state.calls[producerIndex];
+        return (result !== undefined &&
+            producer !== undefined &&
+            producerIndex >= 0 &&
+            producerIndex < dependentCallIndex &&
+            producer.parentCallId === caller.callId &&
+            caller.childCallIds.includes(producer.callId) &&
+            producer.status === "completed" &&
+            producer.resultRef === resultRef &&
+            producer.roleId === result.roleId);
+    });
+}
+export function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+export function parseOptionalCapabilityAdapterResult(input) {
+    if (input === undefined)
+        return undefined;
+    const normalized = normalizeCapabilityAdapterResult(input);
+    return normalized.ok ? normalized.value : null;
+}
+export function isExactResultValidForCall(_call, input) {
+    return normalizeCapabilityAdapterResult(input).ok;
+}
+export function parseCapabilityResultReferences(input) {
+    if (input === undefined)
+        return undefined;
+    if (!Array.isArray(input) ||
+        input.length > ROLE_CAPABILITY_RESULT_REFERENCE_LIMIT_MAX) {
+        return null;
+    }
+    const references = [];
+    const targets = new Set();
+    for (const candidate of input) {
+        if (!isRecord(candidate) ||
+            !exactKeys(candidate, ["kind", "target"]) ||
+            candidate.kind !== "tool_target" ||
+            !isBoundedText(candidate.target, ROLE_CAPABILITY_RESULT_REFERENCE_TARGET_MAX_LENGTH)) {
+            return null;
+        }
+        const target = candidate.target.trim();
+        if (targets.has(target))
+            return null;
+        targets.add(target);
+        references.push(Object.freeze({ kind: "tool_target", target }));
+    }
+    return Object.freeze(references);
+}
+export function isValidCapabilityResultReferences(input) {
+    return parseCapabilityResultReferences(input) !== null;
+}
+export function isBoundedText(value, maximumLength) {
+    return (typeof value === "string" &&
+        value.trim().length > 0 &&
+        value.length <= maximumLength);
+}
+export function isCanonicalTerminalText(value, maximumLength, mode) {
+    return (isBoundedText(value, maximumLength) &&
+        (mode === "exact" || value === value.trim()));
+}
+export function isOptionalBoundedText(value, maximumLength) {
+    return value === undefined || isBoundedText(value, maximumLength);
+}
+export function isRoleCapabilityDeclaredEffect(value) {
+    return value === "observation" || value === "mutation" || value === "mixed";
+}
+export function isRoleCapabilityObservedEffect(value) {
+    return (value === "none" ||
+        value === "observation" ||
+        value === "mutation" ||
+        value === "indeterminate");
+}
+export function isSettledObservedEffectCompatible(params) {
+    if (!isRoleCapabilityObservedEffect(params.observedEffect))
+        return false;
+    if (params.outcome === "succeeded") {
+        return params.declaredEffect === "mixed"
+            ? params.observedEffect === "observation" ||
+                params.observedEffect === "mutation"
+            : params.observedEffect === params.declaredEffect;
+    }
+    return (params.observedEffect === "none" ||
+        params.observedEffect === "indeterminate" ||
+        params.observedEffect === "observation" ||
+        (params.observedEffect === "mutation" &&
+            (params.declaredEffect === "mutation" ||
+                params.declaredEffect === "mixed")));
+}
+export function issue(code, path) {
+    return { code, path };
+}
+export function seal(value, seen = new WeakSet()) {
+    if (typeof value !== "object" || value === null || seen.has(value)) {
+        return value;
+    }
+    seen.add(value);
+    for (const child of Object.values(value)) {
+        seal(child, seen);
+    }
+    return Object.freeze(value);
+}

package/dist/src/runtime/orchestration/role-calls/reducer.d.ts

@@ -0,0 +1,9 @@
+import { type RoleCallPolicy, type RoleCallPolicyInput, type RoleCallState, type RoleCallTransitionResult, type RoleCallValidationIssue } from "./contracts.js";
+export { hasRoleCallCapabilityAuthority } from "./candidate-validation.js";
+export declare function createInitialRoleCallState(requestId: string): RoleCallState;
+export declare function applyRoleCallCommand(state: RoleCallState, commandInput: unknown, policy: RoleCallPolicy): RoleCallTransitionResult;
+export declare function validateRoleCallCandidate(params: {
+    state: RoleCallState;
+    policy: RoleCallPolicy;
+}): readonly RoleCallValidationIssue[];
+export declare function sealRoleCallPolicy(policy: RoleCallPolicyInput): RoleCallPolicy;

package/dist/src/runtime/orchestration/role-calls/reducer.js

@@ -0,0 +1,50 @@
+import { ROLE_CALL_LEDGER_CONTRACT_VERSION, SUPERVISOR_WORKER_V1_AUTHORITY_SNAPSHOT, } from "./contracts.js";
+import { validateRoleCallPolicy, validateRoleCallState, } from "./candidate-validation.js";
+import { decodeRoleCallCommand } from "./command-decoder.js";
+import { dispatchRoleCallCommand } from "./command-dispatch.js";
+import { reject, seal } from "./reducer-primitives.js";
+export { hasRoleCallCapabilityAuthority } from "./candidate-validation.js";
+export function createInitialRoleCallState(requestId) {
+    return seal({
+        contractVersion: ROLE_CALL_LEDGER_CONTRACT_VERSION,
+        requestId,
+        phase: "empty",
+        rootCallId: null,
+        activeCallId: null,
+        callSequence: 0,
+        resultSequence: 0,
+        capabilityExecutionSequence: 0,
+        calls: [],
+        results: [],
+        plans: [],
+        capabilityExecutions: [],
+        rootResponse: null,
+    });
+}
+export function applyRoleCallCommand(state, commandInput, policy) {
+    const policyIssues = validateRoleCallPolicy(policy);
+    if (policyIssues.length > 0) {
+        return reject(state, "invalid_policy", policyIssues);
+    }
+    const stateIssues = validateRoleCallState(state, policy);
+    if (stateIssues.length > 0) {
+        return reject(state, "invalid_current_state", stateIssues);
+    }
+    const command = decodeRoleCallCommand(commandInput);
+    if (!command.ok) {
+        return reject(state, command.code);
+    }
+    return dispatchRoleCallCommand(state, command.value, policy);
+}
+export function validateRoleCallCandidate(params) {
+    const policyIssues = validateRoleCallPolicy(params.policy);
+    return policyIssues.length > 0
+        ? policyIssues
+        : validateRoleCallState(params.state, params.policy);
+}
+export function sealRoleCallPolicy(policy) {
+    return seal(structuredClone({
+        ...policy,
+        authority: policy.authority ?? SUPERVISOR_WORKER_V1_AUTHORITY_SNAPSHOT,
+    }));
+}

package/dist/src/runtime/orchestration/role-calls/transactions.d.ts

@@ -0,0 +1,5 @@
+import type { RoleCallLedger, RoleCallTransactions } from "./contracts.js";
+type RoleCallLedgerApply = RoleCallLedger["apply"];
+export declare function createRoleCallTransactions(apply: RoleCallLedgerApply): RoleCallTransactions;
+export declare function resolveRoleCallTransactions(ledger: RoleCallLedger): RoleCallTransactions;
+export {};

package/dist/src/runtime/orchestration/role-calls/transactions.js

@@ -0,0 +1,195 @@
+export function createRoleCallTransactions(apply) {
+    return Object.freeze({
+        async createRoot(input) {
+            return requireEffect(await apply({
+                expectedHead: input.expectedHead,
+                command: {
+                    authority: "runtime",
+                    type: "create_root",
+                },
+            }), "root_created", "root_create_transition_invalid", () => true);
+        },
+        async completeRootResponse(input) {
+            return requireEffect(await apply({
+                expectedHead: input.expectedHead,
+                command: {
+                    authority: "supervisor",
+                    type: "complete_root_response",
+                    callId: input.callId,
+                    response: input.response,
+                },
+            }), "root_response_committed", "root_response_transition_invalid", (effect) => effect.callId === input.callId);
+        },
+        async openChild(input) {
+            return requireEffect(await apply({
+                expectedHead: input.expectedHead,
+                command: createOpenChildCommand(input),
+            }), "child_opened", "child_open_transition_invalid", (effect) => effect.callerCallId === input.callerCallId);
+        },
+        async returnChild(input) {
+            return requireEffect(await apply({
+                expectedHead: input.expectedHead,
+                command: {
+                    authority: "runtime",
+                    type: "return_child",
+                    callerCallId: input.callerCallId,
+                    childCallId: input.childCallId,
+                    outcome: input.outcome,
+                    summary: input.summary,
+                },
+            }), "child_returned", "child_return_transition_invalid", (effect) => effect.callerCallId === input.callerCallId &&
+                effect.childCallId === input.childCallId);
+        },
+        async beginCapabilityExecution(input) {
+            return requireEffect(await apply({
+                expectedHead: input.expectedHead,
+                command: {
+                    authority: "active_role",
+                    type: "begin_capability_execution",
+                    callId: input.callId,
+                    invocationAttempt: input.invocationAttempt,
+                    capabilityId: input.capabilityId,
+                    declaredEffect: input.declaredEffect,
+                    intent: input.intent,
+                    controlsJson: input.controlsJson,
+                },
+            }), "capability_execution_begun", "commit_effect_invalid", (effect) => effect.callId === input.callId);
+        },
+        async settleCapabilityExecution(input) {
+            return requireEffect(await apply({
+                expectedHead: input.expectedHead,
+                command: createSettleCapabilityExecutionCommand(input),
+            }), "capability_execution_settled", "commit_effect_invalid", (effect) => effect.callId === input.callId &&
+                effect.executionId === input.executionId);
+        },
+        async beginCapabilityBatch(input) {
+            return requireEffect(await apply({
+                expectedHead: input.expectedHead,
+                command: {
+                    authority: "active_role",
+                    type: "begin_capability_batch",
+                    callId: input.callId,
+                    invocationAttempt: input.invocationAttempt,
+                    entries: input.entries,
+                },
+            }), "capability_batch_begun", "commit_effect_invalid", (effect) => effect.callId === input.callId &&
+                effect.executionIds.length === input.entries.length);
+        },
+        async settleCapabilityBatch(input) {
+            return requireEffect(await apply({
+                expectedHead: input.expectedHead,
+                command: {
+                    authority: "runtime",
+                    type: "settle_capability_batch",
+                    callId: input.callId,
+                    settlements: input.settlements,
+                },
+            }), "capability_batch_settled", "commit_effect_invalid", (effect) => effect.callId === input.callId &&
+                sameStrings(effect.executionIds, input.settlements.map(({ executionId }) => executionId)));
+        },
+        async updateCapabilityScope(input) {
+            return requireEffect(await apply({
+                expectedHead: input.expectedHead,
+                command: {
+                    authority: "active_role",
+                    type: "update_capability_scope",
+                    callId: input.callId,
+                    invocationAttempt: input.invocationAttempt,
+                    mode: input.mode,
+                    catalogGroupIds: input.catalogGroupIds,
+                },
+            }), "capability_scope_updated", "capability_scope_transition_invalid", (effect) => effect.callId === input.callId);
+        },
+        async establishWorkingDirectory(input) {
+            return requireEffect(await apply({
+                expectedHead: input.expectedHead,
+                command: {
+                    authority: "active_role",
+                    type: "establish_working_directory",
+                    callId: input.callId,
+                    invocationAttempt: input.invocationAttempt,
+                    workingDirectory: input.workingDirectory,
+                },
+            }), "working_directory_established", "working_directory_transition_invalid", (effect) => effect.callId === input.callId);
+        },
+        async reconsiderCapabilitySelection(input) {
+            return requireEffect(await apply({
+                expectedHead: input.expectedHead,
+                command: {
+                    authority: "active_role",
+                    type: "reconsider_capability_selection",
+                    callId: input.callId,
+                    invocationAttempt: input.invocationAttempt,
+                    steeringVersion: input.steeringVersion,
+                    selection: input.selection,
+                },
+            }), "capability_selection_reconsidered", "capability_selection_reconsideration_transition_invalid", (effect) => effect.callId === input.callId &&
+                effect.invocationAttempt === input.invocationAttempt);
+        },
+    });
+}
+export function resolveRoleCallTransactions(ledger) {
+    if (ledger.transactions) {
+        return ledger.transactions;
+    }
+    return createRoleCallTransactions((input) => ledger.apply(input));
+}
+function createOpenChildCommand(input) {
+    return {
+        authority: "active_role",
+        type: "open_child",
+        callerCallId: input.callerCallId,
+        roleId: input.roleId,
+        objective: input.objective,
+        dependencyResultRefs: input.dependencyResultRefs,
+        ...(input.workerCapabilityScope
+            ? { workerCapabilityScope: input.workerCapabilityScope }
+            : {}),
+        ...(input.workingDirectory !== undefined
+            ? { workingDirectory: input.workingDirectory }
+            : {}),
+        ...(input.plannerPlan ? { plannerPlan: input.plannerPlan } : {}),
+    };
+}
+function createSettleCapabilityExecutionCommand(input) {
+    return {
+        authority: "runtime",
+        type: "settle_capability_execution",
+        callId: input.callId,
+        executionId: input.executionId,
+        outcome: input.outcome,
+        observedEffect: input.observedEffect,
+        summary: input.summary,
+        exactResult: input.exactResult,
+        ...(input.referenceData ? { referenceData: input.referenceData } : {}),
+        ...(input.references ? { references: input.references } : {}),
+    };
+}
+function requireEffect(commit, effectType, invalidEffectIssueCode, validate) {
+    if (!commit.ok) {
+        return Object.freeze({
+            ok: false,
+            issueCode: commit.code,
+            commit,
+        });
+    }
+    if (commit.effect.type !== effectType) {
+        return invalidEffect(commit, invalidEffectIssueCode);
+    }
+    const typedCommit = commit;
+    if (!validate(typedCommit.effect)) {
+        return invalidEffect(commit, invalidEffectIssueCode);
+    }
+    return Object.freeze({ ok: true, commit: typedCommit });
+}
+function invalidEffect(commit, issueCode) {
+    return Object.freeze({
+        ok: false,
+        issueCode,
+        commit,
+    });
+}
+function sameStrings(left, right) {
+    return (left.length === right.length &&
+        left.every((value, index) => value === right[index]));
+}

package/dist/src/runtime/orchestration/role-calls/worker-capability-scope.d.ts

@@ -0,0 +1,4 @@
+import type { RoleCallWorkerCapabilityScope } from "./contracts.js";
+export declare const ROLE_CALL_WORKER_CAPABILITY_CATALOG_GROUP_LIMIT = 64;
+export declare function parseRoleCallWorkerCapabilityScope(input: unknown): RoleCallWorkerCapabilityScope | undefined;
+export declare function isRoleCallWorkerCapabilityScope(input: unknown): input is RoleCallWorkerCapabilityScope;

package/dist/src/runtime/orchestration/role-calls/worker-capability-scope.js

@@ -0,0 +1,28 @@
+import { isToolCatalogGroupId } from "../../../capabilities/tool-types.js";
+export const ROLE_CALL_WORKER_CAPABILITY_CATALOG_GROUP_LIMIT = 64;
+export function parseRoleCallWorkerCapabilityScope(input) {
+    if (!isRoleCallWorkerCapabilityScope(input))
+        return undefined;
+    return Object.freeze({
+        catalogGroupIds: Object.freeze([...input.catalogGroupIds]),
+    });
+}
+export function isRoleCallWorkerCapabilityScope(input) {
+    if (!isRecord(input) || !exactKeys(input, ["catalogGroupIds"])) {
+        return false;
+    }
+    const catalogGroupIds = input.catalogGroupIds;
+    return (Array.isArray(catalogGroupIds) &&
+        catalogGroupIds.length > 0 &&
+        catalogGroupIds.length <= ROLE_CALL_WORKER_CAPABILITY_CATALOG_GROUP_LIMIT &&
+        catalogGroupIds.every(isToolCatalogGroupId) &&
+        new Set(catalogGroupIds).size === catalogGroupIds.length);
+}
+function exactKeys(value, keys) {
+    const expected = new Set(keys);
+    const actual = Object.keys(value);
+    return (actual.length === expected.size && actual.every((key) => expected.has(key)));
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}

package/dist/src/runtime/orchestration/role-calls/working-directory.d.ts

@@ -0,0 +1,16 @@
+export declare const ROLE_CALL_WORKING_DIRECTORY_MAX_LENGTH = 4096;
+export declare const ROLE_CALL_PORTABLE_WORKING_DIRECTORY_PATTERN = "^(?:\\.|[A-Za-z0-9._-]+(?:/[A-Za-z0-9._-]+)*)$";
+export type RoleCallWorkingDirectoryRoleId = "planner" | "worker";
+/** Only coordination and execution calls may own a canonical path base. */
+export declare function isRoleCallWorkingDirectoryRoleId(input: unknown): input is RoleCallWorkingDirectoryRoleId;
+/**
+ * Normalizes an agent-work-directory-relative role-call working directory.
+ * The canonical root is represented by `.` and traversal is never accepted.
+ */
+export declare function normalizeRoleCallWorkingDirectory(input: unknown): string | undefined;
+/**
+ * Strict portable form used when an active capability principal establishes
+ * its own immutable execution base. Existing delegated-call normalization is
+ * intentionally unchanged for compatibility.
+ */
+export declare function normalizeEstablishedRoleCallWorkingDirectory(input: unknown): string | undefined;

package/dist/src/runtime/orchestration/role-calls/working-directory.js

@@ -0,0 +1,51 @@
+export const ROLE_CALL_WORKING_DIRECTORY_MAX_LENGTH = 4_096;
+export const ROLE_CALL_PORTABLE_WORKING_DIRECTORY_PATTERN = "^(?:\\.|[A-Za-z0-9._-]+(?:/[A-Za-z0-9._-]+)*)$";
+const PORTABLE_DIRECTORY_SEGMENT = /^[A-Za-z0-9._-]+$/u;
+/** Only coordination and execution calls may own a canonical path base. */
+export function isRoleCallWorkingDirectoryRoleId(input) {
+    return input === "planner" || input === "worker";
+}
+/**
+ * Normalizes an agent-work-directory-relative role-call working directory.
+ * The canonical root is represented by `.` and traversal is never accepted.
+ */
+export function normalizeRoleCallWorkingDirectory(input) {
+    if (typeof input !== "string" ||
+        input.length === 0 ||
+        input.length > ROLE_CALL_WORKING_DIRECTORY_MAX_LENGTH) {
+        return undefined;
+    }
+    const trimmed = input.trim();
+    if (trimmed.length === 0 || trimmed.includes("\0"))
+        return undefined;
+    const slashNormalized = trimmed.replace(/\\/g, "/");
+    const withoutLeadingCurrentDirectory = slashNormalized.replace(/^(?:\.\/)+/, "");
+    if (withoutLeadingCurrentDirectory.startsWith("/") ||
+        /^[A-Za-z]:/.test(withoutLeadingCurrentDirectory)) {
+        return undefined;
+    }
+    const rawSegments = slashNormalized.split("/");
+    if (rawSegments.some((segment) => segment === ".."))
+        return undefined;
+    const segments = rawSegments.filter((segment) => segment.length > 0 && segment !== ".");
+    const normalized = segments.length === 0 ? "." : segments.join("/");
+    return normalized.length <= ROLE_CALL_WORKING_DIRECTORY_MAX_LENGTH
+        ? normalized
+        : undefined;
+}
+/**
+ * Strict portable form used when an active capability principal establishes
+ * its own immutable execution base. Existing delegated-call normalization is
+ * intentionally unchanged for compatibility.
+ */
+export function normalizeEstablishedRoleCallWorkingDirectory(input) {
+    const normalized = normalizeRoleCallWorkingDirectory(input);
+    if (!normalized)
+        return undefined;
+    return normalized === "." ||
+        normalized
+            .split("/")
+            .every((segment) => PORTABLE_DIRECTORY_SEGMENT.test(segment))
+        ? normalized
+        : undefined;
+}

package/dist/src/runtime/orchestration/role-executors/activation/loop.d.ts

@@ -0,0 +1,21 @@
+import type { RoleExecutionResult, RoleExecutor, RoleExecutorRegistry } from "../contracts.js";
+type RoleExecutionInput<TContext, TValue> = Parameters<RoleExecutorRegistry<TContext, TValue>["execute"]>[0];
+export declare class RoleActivationLoop<TContext, TValue> {
+    private readonly params;
+    private expectedCall;
+    private continuationReference;
+    constructor(params: Readonly<{
+        input: RoleExecutionInput<TContext, TValue>;
+        registeredRoleIds: RoleExecutorRegistry<TContext, TValue>["roleIds"];
+        executorByRoleId: ReadonlyMap<RoleExecutor<TContext, TValue>["roleId"], RoleExecutor<TContext, TValue>>;
+        invokeChild: RoleExecutorRegistry<TContext, TValue>["invokeChild"];
+    }>);
+    run(): Promise<RoleExecutionResult<TValue>>;
+    private resolveInitialActivation;
+    private requireCurrentActivation;
+    private runActivation;
+    private completeTerminal;
+    private continueThroughChild;
+    private continueThroughCapability;
+}
+export {};