@abot-ai/runtime 1.2.0 → 1.3.0

package/dist/src/runtime/orchestration/role-calls/command-dispatch.js

@@ -1,11 +1,16 @@
 import { beginCapabilityBatch, settleCapabilityBatch, } from "./command-dispatch/capability-batch-transitions.js";
 import { beginCapabilityExecution, settleCapabilityExecution, } from "./command-dispatch/capability-execution-transitions.js";
 import { reconsiderCapabilitySelection } from "./command-dispatch/capability-selection-transition.js";
+import { beginMemoryRecall, settleMemoryRecall } from "./command-dispatch/memory-recall-transitions.js";
 import { establishWorkingDirectory, updateCapabilityScope, } from "./command-dispatch/call-scope-transitions.js";
 import { openChild, returnChild, } from "./command-dispatch/child-transitions.js";
 import { completeRootResponse, createRoot, } from "./command-dispatch/root-transitions.js";
 export function dispatchRoleCallCommand(state, command, policy, admittedHeadRevision) {
     switch (command.type) {
+        case "begin_memory_recall":
+            return beginMemoryRecall(state, command);
+        case "settle_memory_recall":
+            return settleMemoryRecall(state, command);
         case "create_root":
             return createRoot(state);
         case "complete_root_response":

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

@@ -5,8 +5,9 @@ import type { RoleOperationFingerprint, RoleOperationOutcomeFingerprint, RoleOpe
 import type { RoleCapabilitySelectionSupervisionStage, RoleCapabilitySelectionSupervisionState, RoleCapabilitySelectionSupervisionTrigger } from "./capability-selection-supervision.js";
 import type { RoleCapabilitySelectionReconsiderationCause } from "./reconsideration-cause.js";
 import type { RoleCallResultReceipt } from "./result-receipt.js";
-export declare const ROLE_CALL_LEDGER_CONTRACT_VERSION = 17;
-export declare const ROLE_CALL_LEDGER_HEAD_KIND: "runtime_role_call_ledger_v17";
+import type { RoleMemoryRecall, RoleMemoryRecallCommand, RoleMemoryRecallCommitEffect, RoleMemoryRecallTransactions } from "./memory-recall-contract.js";
+export declare const ROLE_CALL_LEDGER_CONTRACT_VERSION = 18;
+export declare const ROLE_CALL_LEDGER_HEAD_KIND: "runtime_role_call_ledger_v18";
 export declare const ROLE_CALL_OBJECTIVE_MAX_LENGTH = 8192;
 export declare const ROLE_CALL_RESULT_MAX_LENGTH = 8192;
 export declare const ROLE_CALL_RESPONSE_MAX_LENGTH = 65536;
@@ -53,7 +54,7 @@ export type RoleCallPolicyInput = Readonly<{
     authority?: ExecutionPolicyAuthoritySnapshot;
     limits: RoleCallPolicy["limits"];
 }>;
-export type RoleCallFrameStatus = "active" | "waiting_for_child" | "waiting_for_capability" | "completed";
+export type RoleCallFrameStatus = "active" | "waiting_for_child" | "waiting_for_capability" | "waiting_for_memory" | "completed";
 export type RoleCallWorkerCapabilityScope = Readonly<{
     catalogGroupIds: readonly string[];
 }>;
@@ -183,6 +184,7 @@ export type RoleCallState = Readonly<{
     results: readonly RoleCallResult[];
     plans: readonly RoleCallPlanState[];
     capabilityExecutions: readonly RoleCapabilityExecution[];
+    memoryRecalls: readonly RoleMemoryRecall[];
     operationSupervision: RoleOperationSupervisionState;
     capabilitySelectionSupervision: RoleCapabilitySelectionSupervisionState;
     rootResponse: string | null;
@@ -296,8 +298,8 @@ export type ReconsiderRoleCapabilitySelectionCommand = Readonly<{
     selection: RoleCapabilitySelectionProjection;
     cause: RoleCapabilitySelectionReconsiderationCause;
 }>;
-export type RoleCallLedgerCommand = CreateRootRoleCallCommand | CompleteRootResponseCommand | OpenChildRoleCallCommand | ReturnChildRoleCallCommand | BeginRoleCapabilityExecutionCommand | SettleRoleCapabilityExecutionCommand | BeginRoleCapabilityBatchCommand | SettleRoleCapabilityBatchCommand | UpdateRoleCapabilityScopeCommand | EstablishRoleCallWorkingDirectoryCommand | ReconsiderRoleCapabilitySelectionCommand;
-export type RoleCallCommitEffect = Readonly<{
+export type RoleCallLedgerCommand = RoleMemoryRecallCommand | CreateRootRoleCallCommand | CompleteRootResponseCommand | OpenChildRoleCallCommand | ReturnChildRoleCallCommand | BeginRoleCapabilityExecutionCommand | SettleRoleCapabilityExecutionCommand | BeginRoleCapabilityBatchCommand | SettleRoleCapabilityBatchCommand | UpdateRoleCapabilityScopeCommand | EstablishRoleCallWorkingDirectoryCommand | ReconsiderRoleCapabilitySelectionCommand;
+export type RoleCallCommitEffect = RoleMemoryRecallCommitEffect | Readonly<{
     type: "root_created";
     callId: string;
 }> | Readonly<{
@@ -364,7 +366,7 @@ export type RoleCallValidationIssue = Readonly<{
     code: string;
     path: string;
 }>;
-export type RoleCallTransitionRejectionCode = "invalid_current_state" | "invalid_policy" | "invalid_command" | "root_already_created" | "root_missing" | "caller_not_active" | "root_response_not_allowed" | "supervisor_child_forbidden" | "child_role_not_authorized" | "child_dependency_invalid" | "planner_plan_binding_invalid" | "planner_plan_already_declared" | "planner_plan_missing" | "planner_plan_item_unavailable" | "planner_plan_incomplete" | "depth_limit_exceeded" | "call_limit_exceeded" | "child_return_mismatch" | "capability_caller_invalid" | "capability_invocation_mismatch" | "capability_execution_limit_exceeded" | "capability_execution_mismatch" | "capability_scope_update_invalid" | "working_directory_establishment_invalid" | "capability_selection_reconsideration_invalid" | "capability_selection_supervision_limit_exceeded" | "operation_supervision_limit_exceeded" | "role_activation_limit_exceeded";
+export type RoleCallTransitionRejectionCode = "invalid_current_state" | "invalid_policy" | "invalid_command" | "root_already_created" | "root_missing" | "caller_not_active" | "root_response_not_allowed" | "supervisor_child_forbidden" | "child_role_not_authorized" | "child_dependency_invalid" | "planner_plan_binding_invalid" | "planner_plan_already_declared" | "planner_plan_missing" | "planner_plan_item_unavailable" | "planner_plan_incomplete" | "depth_limit_exceeded" | "call_limit_exceeded" | "child_return_mismatch" | "capability_caller_invalid" | "capability_invocation_mismatch" | "capability_execution_limit_exceeded" | "capability_execution_mismatch" | "capability_scope_update_invalid" | "working_directory_establishment_invalid" | "capability_selection_reconsideration_invalid" | "capability_selection_supervision_limit_exceeded" | "operation_supervision_limit_exceeded" | "memory_recall_caller_invalid" | "memory_recall_invocation_mismatch" | "memory_recall_settlement_mismatch" | "role_activation_limit_exceeded";
 export type RoleCallTransitionResult = Readonly<{
     ok: true;
     state: RoleCallState;
@@ -433,7 +435,7 @@ export type RoleCallTransactionFailure<TTransitionIssueCode extends string> = Re
     commit: RoleCallLedgerCommitResult;
 }>;
 export type RoleCallTransactionResult<TEffectType extends RoleCallCommitEffect["type"], TTransitionIssueCode extends string> = RoleCallTransactionSuccess<TEffectType> | RoleCallTransactionFailure<TTransitionIssueCode>;
-export type RoleCallTransactions = Readonly<{
+export type RoleCallTransactions = RoleMemoryRecallTransactions & Readonly<{
     createRoot(input: Readonly<{
         expectedHead: unknown;
     }>): Promise<RoleCallTransactionResult<"root_created", "root_create_transition_invalid">>;

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

@@ -1,5 +1,5 @@
-export const ROLE_CALL_LEDGER_CONTRACT_VERSION = 17;
-export const ROLE_CALL_LEDGER_HEAD_KIND = "runtime_role_call_ledger_v17";
+export const ROLE_CALL_LEDGER_CONTRACT_VERSION = 18;
+export const ROLE_CALL_LEDGER_HEAD_KIND = "runtime_role_call_ledger_v18";
 export const ROLE_CALL_OBJECTIVE_MAX_LENGTH = 8_192;
 export const ROLE_CALL_RESULT_MAX_LENGTH = 8_192;
 export const ROLE_CALL_RESPONSE_MAX_LENGTH = 65_536;

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

@@ -1,6 +1,7 @@
 import { traceDebug } from "../../observability/debug-logger.js";
 import { resolveRoleActivationBudget } from "./activation-budget.js";
 import { isSuccessfulObservedMutation } from "./operation-supervision.js";
+import { traceMemoryRecallCommit } from "./memory-recall-diagnostics.js";
 const ROLE_CALL_LOG_SCOPE = "runtime.role_calls";
 export function traceRoleCallCommit(params) {
     const state = params.head.state;
@@ -25,6 +26,8 @@ export function traceRoleCallCommit(params) {
         effectType: params.effect.type,
     });
     traceCapabilitySelectionSupervisionReset(params, common);
+    if (traceMemoryRecallCommit(params, common))
+        return;
     switch (params.effect.type) {
         case "root_created": {
             traceDebug(ROLE_CALL_LOG_SCOPE, "root.created", {

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

@@ -19,3 +19,4 @@ export * from "./reducer.js";
 export * from "./transactions.js";
 export * from "./worker-capability-scope.js";
 export * from "./working-directory.js";
+export * from "./memory-recall-contract.js";

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

@@ -19,3 +19,4 @@ export * from "./reducer.js";
 export * from "./transactions.js";
 export * from "./worker-capability-scope.js";
 export * from "./working-directory.js";
+export * from "./memory-recall-contract.js";

package/dist/src/runtime/orchestration/role-calls/memory-recall-contract.d.ts

@@ -0,0 +1,51 @@
+import type { LongTermMemoryRecord } from "../../long-term-memory/contracts.js";
+import type { RoleCallTransactionInput, RoleCallTransactionResult } from "./contracts.js";
+export declare const ROLE_MEMORY_RECALL_QUERY_MAX_LENGTH = 1024;
+export declare const ROLE_MEMORY_RECALL_RECORD_LIMIT_MAX = 6;
+export declare const ROLE_MEMORY_RECALL_RESULT_MAX_LENGTH = 6000;
+export declare const ROLE_MEMORY_RECALL_REASON_MAX_LENGTH = 256;
+export type RoleMemoryRecallResult = Readonly<{
+    outcome: "found" | "empty" | "unavailable" | "superseded";
+    records: readonly LongTermMemoryRecord[];
+    omittedRecordCount: number;
+    reason?: string;
+}>;
+export type RoleMemoryRecallIdentity = Readonly<{
+    callId: string;
+    invocationAttempt: number;
+    steeringVersion: number;
+}>;
+export type RoleMemoryRecall = RoleMemoryRecallIdentity & Readonly<{
+    recallId: string;
+    completedChildCount: number;
+    query: string;
+}> & (Readonly<{
+    status: "pending";
+    result?: undefined;
+}> | Readonly<{
+    status: "settled";
+    result: RoleMemoryRecallResult;
+}>);
+export type BeginRoleMemoryRecallCommand = RoleMemoryRecallIdentity & Readonly<{
+    authority: "active_role";
+    type: "begin_memory_recall";
+    query: string;
+}>;
+export type SettleRoleMemoryRecallCommand = RoleMemoryRecallIdentity & Readonly<{
+    authority: "runtime";
+    type: "settle_memory_recall";
+    recallId: string;
+    result: RoleMemoryRecallResult;
+}>;
+export type RoleMemoryRecallCommand = BeginRoleMemoryRecallCommand | SettleRoleMemoryRecallCommand;
+export type RoleMemoryRecallCommitEffect = RoleMemoryRecallIdentity & Readonly<{
+    recallId: string;
+}> & (Readonly<{
+    type: "memory_recall_begun";
+}> | Readonly<{
+    type: "memory_recall_settled";
+}>);
+export type RoleMemoryRecallTransactions = Readonly<{
+    beginMemoryRecall(input: RoleCallTransactionInput<BeginRoleMemoryRecallCommand>): Promise<RoleCallTransactionResult<"memory_recall_begun", "memory_recall_transition_invalid">>;
+    settleMemoryRecall(input: RoleCallTransactionInput<SettleRoleMemoryRecallCommand>): Promise<RoleCallTransactionResult<"memory_recall_settled", "memory_recall_transition_invalid">>;
+}>;

package/dist/src/runtime/orchestration/role-calls/memory-recall-contract.js

@@ -0,0 +1,4 @@
+export const ROLE_MEMORY_RECALL_QUERY_MAX_LENGTH = 1_024;
+export const ROLE_MEMORY_RECALL_RECORD_LIMIT_MAX = 6;
+export const ROLE_MEMORY_RECALL_RESULT_MAX_LENGTH = 6_000;
+export const ROLE_MEMORY_RECALL_REASON_MAX_LENGTH = 256;

package/dist/src/runtime/orchestration/role-calls/memory-recall-decoder.d.ts

@@ -0,0 +1,6 @@
+import type { DecodedRoleCallCommand } from "./command-decoder.js";
+import { type RoleMemoryRecallIdentity, type RoleMemoryRecallResult } from "./memory-recall-contract.js";
+export declare function decodeMemoryRecallCommand(input: Record<string, unknown>): DecodedRoleCallCommand;
+export declare function hasMemoryRecallIdentity(input: Record<string, unknown>): input is Record<string, unknown> & RoleMemoryRecallIdentity;
+export declare function isBoundedMemoryRecallQuery(input: unknown): input is string;
+export declare function normalizeRoleMemoryRecallResult(input: unknown): RoleMemoryRecallResult | undefined;

package/dist/src/runtime/orchestration/role-calls/memory-recall-decoder.js

@@ -0,0 +1,147 @@
+import { parseMemoryRecord } from "../../long-term-memory/repository-state.js";
+import { exactKeys, isRecord } from "../../validation/strict-record.js";
+import { ROLE_MEMORY_RECALL_QUERY_MAX_LENGTH, ROLE_MEMORY_RECALL_REASON_MAX_LENGTH, ROLE_MEMORY_RECALL_RECORD_LIMIT_MAX, ROLE_MEMORY_RECALL_RESULT_MAX_LENGTH, } from "./memory-recall-contract.js";
+export function decodeMemoryRecallCommand(input) {
+    const invalid = { ok: false, code: "invalid_command" };
+    if (!hasMemoryRecallIdentity(input))
+        return invalid;
+    if (input.type === "begin_memory_recall")
+        return decodeBeginMemoryRecall(input);
+    return decodeSettleMemoryRecall(input);
+}
+function decodeBeginMemoryRecall(input) {
+    const invalid = { ok: false, code: "invalid_command" };
+    if (input.authority !== "active_role")
+        return invalid;
+    if (!exactKeys(input, [
+        "authority",
+        "type",
+        "callId",
+        "invocationAttempt",
+        "steeringVersion",
+        "query",
+    ]))
+        return invalid;
+    if (!isBoundedMemoryRecallQuery(input.query))
+        return invalid;
+    return {
+        ok: true,
+        value: {
+            authority: "active_role",
+            type: "begin_memory_recall",
+            callId: input.callId,
+            invocationAttempt: input.invocationAttempt,
+            steeringVersion: input.steeringVersion,
+            query: input.query.trim(),
+        },
+    };
+}
+function decodeSettleMemoryRecall(input) {
+    const invalid = { ok: false, code: "invalid_command" };
+    if (input.type !== "settle_memory_recall")
+        return invalid;
+    if (input.authority !== "runtime")
+        return invalid;
+    if (!exactKeys(input, [
+        "authority",
+        "type",
+        "callId",
+        "invocationAttempt",
+        "steeringVersion",
+        "recallId",
+        "result",
+    ]))
+        return invalid;
+    if (typeof input.recallId !== "string")
+        return invalid;
+    const result = normalizeRoleMemoryRecallResult(input.result);
+    if (!result)
+        return invalid;
+    return {
+        ok: true,
+        value: {
+            authority: "runtime",
+            type: "settle_memory_recall",
+            callId: input.callId,
+            invocationAttempt: input.invocationAttempt,
+            steeringVersion: input.steeringVersion,
+            recallId: input.recallId,
+            result,
+        },
+    };
+}
+export function hasMemoryRecallIdentity(input) {
+    if (typeof input.callId !== "string" || input.callId.length === 0)
+        return false;
+    if (!Number.isSafeInteger(input.invocationAttempt))
+        return false;
+    if (input.invocationAttempt < 1)
+        return false;
+    if (!Number.isSafeInteger(input.steeringVersion))
+        return false;
+    return input.steeringVersion >= 0;
+}
+export function isBoundedMemoryRecallQuery(input) {
+    if (typeof input !== "string")
+        return false;
+    if (input.trim().length === 0)
+        return false;
+    return input.length <= ROLE_MEMORY_RECALL_QUERY_MAX_LENGTH;
+}
+export function normalizeRoleMemoryRecallResult(input) {
+    if (!isRecord(input))
+        return undefined;
+    if (!exactKeys(input, ["outcome", "records", "omittedRecordCount"], ["reason"]))
+        return undefined;
+    const outcome = input.outcome;
+    if (!isMemoryRecallOutcome(outcome))
+        return undefined;
+    if (!Array.isArray(input.records))
+        return undefined;
+    if (input.records.length > ROLE_MEMORY_RECALL_RECORD_LIMIT_MAX)
+        return undefined;
+    if (!Number.isSafeInteger(input.omittedRecordCount))
+        return undefined;
+    if (input.omittedRecordCount < 0)
+        return undefined;
+    if (!isMemoryRecallReason(input.reason))
+        return undefined;
+    if (!hasRecordsForMemoryRecallOutcome(outcome, input.records.length))
+        return undefined;
+    try {
+        if (JSON.stringify(input).length > ROLE_MEMORY_RECALL_RESULT_MAX_LENGTH)
+            return undefined;
+        const records = Object.freeze(input.records.map(parseMemoryRecord));
+        if (new Set(records.map((record) => record.id)).size !== records.length)
+            return undefined;
+        return Object.freeze({
+            outcome,
+            records,
+            omittedRecordCount: input.omittedRecordCount,
+            ...(input.reason !== undefined ? { reason: input.reason } : {}),
+        });
+    }
+    catch {
+        return undefined;
+    }
+}
+function isMemoryRecallOutcome(input) {
+    return (input === "found" ||
+        input === "empty" ||
+        input === "unavailable" ||
+        input === "superseded");
+}
+function isMemoryRecallReason(input) {
+    if (input === undefined)
+        return true;
+    if (typeof input !== "string")
+        return false;
+    if (input.trim().length === 0)
+        return false;
+    return input.length <= ROLE_MEMORY_RECALL_REASON_MAX_LENGTH;
+}
+function hasRecordsForMemoryRecallOutcome(outcome, count) {
+    if (outcome === "found")
+        return count > 0;
+    return count === 0;
+}

package/dist/src/runtime/orchestration/role-calls/memory-recall-diagnostics.d.ts

@@ -0,0 +1,5 @@
+import type { RoleCallCommitEffect, RoleCallLedgerHead } from "./contracts.js";
+export declare function traceMemoryRecallCommit(params: Readonly<{
+    head: RoleCallLedgerHead;
+    effect: RoleCallCommitEffect;
+}>, common: Readonly<Record<string, unknown>>): boolean;

package/dist/src/runtime/orchestration/role-calls/memory-recall-diagnostics.js

@@ -0,0 +1,27 @@
+import { traceDebug } from "../../observability/debug-logger.js";
+export function traceMemoryRecallCommit(params, common) {
+    const effect = params.effect;
+    if (!isMemoryRecallEffect(effect))
+        return false;
+    const recall = params.head.state.memoryRecalls.find((entry) => entry.recallId === effect.recallId);
+    const call = params.head.state.calls.find((entry) => entry.callId === effect.callId);
+    traceDebug("runtime.role_calls", effect.type === "memory_recall_begun"
+        ? "memory.recall_begun"
+        : "memory.recall_settled", {
+        ...common,
+        callId: effect.callId,
+        recallId: effect.recallId,
+        invocationAttempt: effect.invocationAttempt,
+        steeringVersion: effect.steeringVersion,
+        activationCount: call?.activationCount,
+        queryLength: recall?.query.length,
+        outcome: recall?.result?.outcome,
+        recordCount: recall?.result?.records.length,
+        omittedRecordCount: recall?.result?.omittedRecordCount,
+    });
+    return true;
+}
+function isMemoryRecallEffect(effect) {
+    return (effect.type === "memory_recall_begun" ||
+        effect.type === "memory_recall_settled");
+}

package/dist/src/runtime/orchestration/role-calls/memory-recall-state-validation.d.ts

@@ -0,0 +1,3 @@
+import type { RoleCallState, RoleCallValidationIssue } from "./contracts.js";
+export declare function validateRoleMemoryRecalls(state: RoleCallState): RoleCallValidationIssue[];
+export declare function hasSettledMemoryRecallActivationRange(state: RoleCallState, callId: string, fromActivation: number, toActivation: number): boolean;

package/dist/src/runtime/orchestration/role-calls/memory-recall-state-validation.js

@@ -0,0 +1,121 @@
+import { RUNTIME_ROOT_ROLE_ID } from "../roles.js";
+import { hasMemoryRecallIdentity, isBoundedMemoryRecallQuery, normalizeRoleMemoryRecallResult, } from "./memory-recall-decoder.js";
+import { exactKeys, isRecord } from "../../validation/strict-record.js";
+export function validateRoleMemoryRecalls(state) {
+    const invalid = [
+        { code: "invalid_role_memory_recalls", path: "state.memoryRecalls" },
+    ];
+    if (!Array.isArray(state.memoryRecalls))
+        return invalid;
+    const root = state.calls.find((call) => call.callId === state.rootCallId);
+    if (!root)
+        return state.memoryRecalls.length === 0 ? [] : invalid;
+    let previousAttempt = 0;
+    let previousSteeringVersion = 0;
+    let previousCompletedChildCount = 0;
+    let pendingCount = 0;
+    for (const [index, recall] of state.memoryRecalls.entries()) {
+        if (!isOrderedRootMemoryRecall(recall, root, index, previousAttempt, previousSteeringVersion, previousCompletedChildCount))
+            return invalid;
+        previousAttempt = recall.invocationAttempt;
+        previousSteeringVersion = recall.steeringVersion;
+        previousCompletedChildCount = recall.completedChildCount;
+        if (!isMemoryRecallSettlementBound(state, root, recall, index))
+            return invalid;
+        pendingCount += recall.status === "pending" ? 1 : 0;
+    }
+    if (hasUnboundMemoryWait(state, pendingCount))
+        return invalid;
+    return [];
+}
+function isOrderedRootMemoryRecall(recall, root, index, previousAttempt, previousSteeringVersion, previousCompletedChildCount) {
+    if (!isRecord(recall))
+        return false;
+    if (!hasMemoryRecallIdentity(recall))
+        return false;
+    if (!exactKeys(recall, [
+        "recallId",
+        "completedChildCount",
+        "callId",
+        "invocationAttempt",
+        "steeringVersion",
+        "query",
+        "status",
+    ], ["result"]))
+        return false;
+    if (recall.recallId !== `recall-${index + 1}`)
+        return false;
+    if (recall.callId !== root.callId)
+        return false;
+    if (root.roleId !== RUNTIME_ROOT_ROLE_ID)
+        return false;
+    if (root.parentCallId !== null)
+        return false;
+    if (recall.invocationAttempt <= previousAttempt)
+        return false;
+    if (recall.steeringVersion < previousSteeringVersion)
+        return false;
+    if (!hasOrderedMemoryRecallChildAnchor(recall.completedChildCount, root, previousCompletedChildCount))
+        return false;
+    if (!isBoundedMemoryRecallQuery(recall.query))
+        return false;
+    return recall.query === recall.query.trim();
+}
+function hasOrderedMemoryRecallChildAnchor(value, root, previousCompletedChildCount) {
+    if (typeof value !== "number")
+        return false;
+    if (!Number.isSafeInteger(value))
+        return false;
+    if (value < 0)
+        return false;
+    if (value < previousCompletedChildCount)
+        return false;
+    return value <= root.childCallIds.length;
+}
+function isMemoryRecallSettlementBound(state, root, recall, index) {
+    if (recall.status === "pending")
+        return isPendingMemoryRecallBound(state, root, recall, index);
+    if (recall.status !== "settled")
+        return false;
+    if (recall.invocationAttempt >= root.activationCount)
+        return false;
+    return normalizeRoleMemoryRecallResult(recall.result) !== undefined;
+}
+function isPendingMemoryRecallBound(state, root, recall, index) {
+    if (index !== state.memoryRecalls.length - 1)
+        return false;
+    if (recall.result !== undefined)
+        return false;
+    if (recall.invocationAttempt !== root.activationCount)
+        return false;
+    if (recall.completedChildCount !== root.childCallIds.length)
+        return false;
+    if (state.phase !== "running")
+        return false;
+    if (state.activeCallId !== root.callId)
+        return false;
+    return root.status === "waiting_for_memory";
+}
+export function hasSettledMemoryRecallActivationRange(state, callId, fromActivation, toActivation) {
+    if (toActivation < fromActivation)
+        return false;
+    const recalls = state.memoryRecalls.filter((recall) => isSettledMemoryRecallWithinRange(recall, callId, fromActivation, toActivation));
+    if (recalls.length !== toActivation - fromActivation)
+        return false;
+    return recalls.every((recall, index) => recall.invocationAttempt === fromActivation + index);
+}
+function isSettledMemoryRecallWithinRange(recall, callId, fromActivation, toActivation) {
+    if (recall.callId !== callId)
+        return false;
+    if (recall.status !== "settled")
+        return false;
+    if (recall.invocationAttempt < fromActivation)
+        return false;
+    return recall.invocationAttempt < toActivation;
+}
+function hasUnboundMemoryWait(state, pendingCount) {
+    const waitingCalls = state.calls.filter((call) => call.status === "waiting_for_memory");
+    if (waitingCalls.length !== pendingCount)
+        return true;
+    return waitingCalls.some((call) => call.callId !== state.rootCallId);
+}

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

@@ -0,0 +1,3 @@
+import type { RoleCallLedger } from "./contracts.js";
+import type { RoleMemoryRecallTransactions } from "./memory-recall-contract.js";
+export declare function createMemoryRecallTransactions(apply: RoleCallLedger["apply"]): RoleMemoryRecallTransactions;

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

@@ -0,0 +1,44 @@
+import { requireEffect } from "./transaction-effect.js";
+export function createMemoryRecallTransactions(apply) {
+    return Object.freeze({
+        async beginMemoryRecall(input) {
+            return requireEffect(await apply({
+                expectedHead: input.expectedHead,
+                command: {
+                    authority: "active_role",
+                    type: "begin_memory_recall",
+                    callId: input.callId,
+                    invocationAttempt: input.invocationAttempt,
+                    steeringVersion: input.steeringVersion,
+                    query: input.query,
+                },
+            }), "memory_recall_begun", "memory_recall_transition_invalid", (effect) => matchesMemoryRecallIdentity(effect, input));
+        },
+        async settleMemoryRecall(input) {
+            return requireEffect(await apply({
+                expectedHead: input.expectedHead,
+                command: {
+                    authority: "runtime",
+                    type: "settle_memory_recall",
+                    callId: input.callId,
+                    invocationAttempt: input.invocationAttempt,
+                    steeringVersion: input.steeringVersion,
+                    recallId: input.recallId,
+                    result: input.result,
+                },
+            }), "memory_recall_settled", "memory_recall_transition_invalid", (effect) => matchesMemoryRecallSettlement(effect, input));
+        },
+    });
+}
+function matchesMemoryRecallIdentity(effect, input) {
+    if (effect.callId !== input.callId)
+        return false;
+    if (effect.invocationAttempt !== input.invocationAttempt)
+        return false;
+    return effect.steeringVersion === input.steeringVersion;
+}
+function matchesMemoryRecallSettlement(effect, input) {
+    if (!matchesMemoryRecallIdentity(effect, input))
+        return false;
+    return effect.recallId === input.recallId;
+}

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

@@ -22,6 +22,7 @@ export function createInitialRoleCallState(requestId) {
         results: [],
         plans: [],
         capabilityExecutions: [],
+        memoryRecalls: [],
         operationSupervision: createInitialRoleOperationSupervisionState(),
         capabilitySelectionSupervision: createInitialRoleCapabilitySelectionSupervisionState(),
         rootResponse: null,

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

@@ -0,0 +1,5 @@
+import type { RoleCallCommitEffect, RoleCallLedgerCommit, RoleCallLedgerCommitResult, RoleCallTransactionResult } from "./contracts.js";
+export declare function requireEffect<TEffectType extends RoleCallCommitEffect["type"], TTransitionIssueCode extends string>(commit: RoleCallLedgerCommitResult, effectType: TEffectType, invalidEffectIssueCode: TTransitionIssueCode, validate: (effect: Extract<RoleCallCommitEffect, {
+    type: TEffectType;
+}>) => boolean): RoleCallTransactionResult<TEffectType, TTransitionIssueCode>;
+export declare function invalidEffect<TTransitionIssueCode extends string>(commit: RoleCallLedgerCommit, issueCode: TTransitionIssueCode): RoleCallTransactionResult<never, TTransitionIssueCode>;

package/dist/src/runtime/orchestration/role-calls/transaction-effect.js

@@ -0,0 +1,14 @@
+export 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 });
+}
+export function invalidEffect(commit, issueCode) {
+    return Object.freeze({ ok: false, issueCode, commit });
+}

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

@@ -1,5 +1,8 @@
+import { createMemoryRecallTransactions } from "./memory-recall-transactions.js";
+import { requireEffect, invalidEffect } from "./transaction-effect.js";
 export function createRoleCallTransactions(apply) {
     return Object.freeze({
+        ...createMemoryRecallTransactions(apply),
         async createRoot(input) {
             return requireEffect(await apply({
                 expectedHead: input.expectedHead,
@@ -223,30 +226,6 @@ function createSettleCapabilityExecutionCommand(input) {
         ...(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/plugins/manifest-validator.js

@@ -1,4 +1,5 @@
 import { isToolCatalogGroupId } from "../../capabilities/tool-types.js";
+import { parseEventResultMetadata } from "../../capabilities/tool-definition-validator/event-result-metadata.js";
 import { ABOT_RUNTIME_EXTENSION, ABOT_RUNTIME_EXTENSION_VERSION, AGENT_PLUGIN_MANIFEST_SCHEMA, } from "../../plugin-contract/manifest.js";
 const PLUGIN_NAME_PATTERN = /^(?!.*(?:--|\.\.))[a-z0-9][a-z0-9.-]{0,62}[a-z0-9]$|^[a-z0-9]$/u;
 const SECRET_ENV_PATTERN = /^[A-Z][A-Z0-9_]*$/u;
@@ -179,7 +180,8 @@ function parseEventPresentation(value, path) {
     if (value === undefined)
         return undefined;
     const presentation = expectRecord(value, path);
-    rejectUnknownKeys(presentation, ["metadata", "lifecycle"], path);
+    rejectUnknownKeys(presentation, ["metadata", "lifecycle", "resultMetadata"], path);
+    const resultMetadata = parseEventResultMetadata(presentation.resultMetadata, `${path}.resultMetadata`);
     const metadata = expectRecord(presentation.metadata, `${path}.metadata`);
     const lifecycle = presentation.lifecycle;
     if (lifecycle !== undefined && !isRecord(lifecycle)) {
@@ -232,6 +234,7 @@ function parseEventPresentation(value, path) {
                 },
             ];
         })),
+        ...(resultMetadata ? { resultMetadata } : {}),
         ...(parsedLifecycle && Object.keys(parsedLifecycle).length > 0
             ? { lifecycle: parsedLifecycle }
             : {}),