@abot-ai/runtime 1.1.0 → 1.3.0

package/dist/src/runtime/session/session-attachment-deletion.js

@@ -0,0 +1,87 @@
+import { assertValidSessionId } from "../../sessions/record/rules.js";
+import { createSessionDeletionBoundary } from "./session-deletion-boundary.js";
+import { createSessionMutationQueue } from "./session-mutation-queue.js";
+// Adapter composition metadata. Each bound operation owns its deletion lifetime.
+const bindings = new WeakMap();
+function attachmentBindings(sessions) {
+    const existing = bindings.get(sessions);
+    if (existing)
+        return existing;
+    const bound = new WeakMap();
+    bindings.set(sessions, bound);
+    return bound;
+}
+/** The composed owner already finalizes attachments within its session transaction. */
+export function bindManagedSessionAttachmentDeletion(sessions, attachments) {
+    attachmentBindings(sessions).set(attachments, (id) => sessions.deleteSessionWithStats(id));
+}
+export async function deleteSessionWithAttachments(sessions, attachments, sessionId) {
+    assertValidSessionId(sessionId);
+    if (!attachments)
+        return sessions.deleteSessionWithStats(sessionId);
+    const bound = attachmentBindings(sessions);
+    const existing = bound.get(attachments);
+    if (existing)
+        return existing(sessionId);
+    const remove = createCompatibilitySessionDeletion(sessions, attachments);
+    bound.set(attachments, remove);
+    return remove(sessionId);
+}
+function createCompatibilitySessionDeletion(sessions, attachments) {
+    const enqueue = createSessionMutationQueue();
+    const pending = new Map();
+    return async (sessionId) => {
+        let current = pending.get(sessionId);
+        if (!current) {
+            current = {
+                deletion: createSessionDeletionBoundary(sessions, enqueue, (result) => deleteSessionAttachmentsIfSupported(attachments, result.sessionId)),
+                attempt: undefined,
+                callers: 0,
+                delivered: false,
+            };
+            pending.set(sessionId, current);
+        }
+        current.callers += 1;
+        try {
+            current.attempt ??= current.deletion.deleteSessionWithStats(sessionId);
+            const result = await current.attempt;
+            if (current.delivered) {
+                return {
+                    sessionId,
+                    deleted: false,
+                    deletedMessages: 0,
+                    deletedRequests: 0,
+                };
+            }
+            current.delivered = true;
+            return result;
+        }
+        finally {
+            current.callers -= 1;
+            // Concurrent callers share failure; only a later explicit call may retry.
+            if (current.callers === 0)
+                current.attempt = undefined;
+            // Raw stores may reuse IDs after successful deletion; retain only failed work.
+            if (canReleaseCompatibilityDeletion(current))
+                pending.delete(sessionId);
+        }
+    };
+}
+function canReleaseCompatibilityDeletion(state) {
+    return state.callers === 0 && state.delivered;
+}
+export async function deleteSessionAttachmentsIfSupported(attachments, sessionId) {
+    if (!attachments)
+        return;
+    try {
+        await attachments.deleteSessionAttachments(sessionId);
+    }
+    catch (error) {
+        if (isUnsupportedAttachmentOwner(error))
+            return;
+        throw error;
+    }
+}
+function isUnsupportedAttachmentOwner(error) {
+    return error instanceof Error && error.message === "attachment_owner_invalid";
+}

package/dist/src/runtime/session/session-deletion-boundary.d.ts

@@ -0,0 +1,10 @@
+import type { SessionDeleteResult } from "../../sessions/types.js";
+import type { SessionStore } from "../ports.js";
+import { type SessionDeletionFinalizer } from "./session-deletion-finalization.js";
+import type { SessionMutationQueue } from "./session-mutation-queue.js";
+/** Shared transaction for managed stores and compatibility deletion adapters. */
+export declare function createSessionDeletionBoundary(base: Pick<SessionStore, "deleteSessionWithStats">, enqueue: SessionMutationQueue, finalize?: SessionDeletionFinalizer): {
+    deleteSessionWithStats: (sessionId: string) => Promise<SessionDeleteResult>;
+    isDeleted: (sessionId: string) => boolean;
+    onDeleted: (listener: import("./session-deletion-cleanup.js").SessionDeletionListener) => () => void;
+};

package/dist/src/runtime/session/session-deletion-boundary.js

@@ -0,0 +1,39 @@
+import { assertValidSessionId } from "../../sessions/record/rules.js";
+import { createSessionDeletionCleanup } from "./session-deletion-cleanup.js";
+import { createSessionDeletionFinalization, } from "./session-deletion-finalization.js";
+import { createSessionDeletionReceipts } from "./session-deletion-receipts.js";
+/** Shared transaction for managed stores and compatibility deletion adapters. */
+export function createSessionDeletionBoundary(base, enqueue, finalize) {
+    const cleanup = createSessionDeletionCleanup();
+    const receipts = createSessionDeletionReceipts(base);
+    const finalization = finalize
+        ? createSessionDeletionFinalization(finalize)
+        : undefined;
+    if (finalization)
+        cleanup.onDeleted(finalization.finalizeDeletedSession);
+    async function deleteSessionWithStats(sessionId) {
+        assertValidSessionId(sessionId);
+        const settlePhysical = finalization?.prepare(sessionId);
+        let notification;
+        // Reserve before invoking listeners: synchronous reentry must queue behind us.
+        const result = enqueue(sessionId, async () => {
+            const [deletion] = await Promise.allSettled([receipts.remove(sessionId)]);
+            settlePhysical?.(deletion);
+            const [notified] = await notification;
+            if (deletion.status === "rejected")
+                throw deletion.reason;
+            if (notified.status === "rejected")
+                throw notified.reason;
+            receipts.acknowledge(sessionId);
+            return deletion.value;
+        });
+        // The queue is deferred; intent and cleanup are still installed synchronously.
+        notification = Promise.allSettled([cleanup.notify(sessionId)]);
+        return result;
+    }
+    return {
+        deleteSessionWithStats,
+        isDeleted: cleanup.isDeleted,
+        onDeleted: cleanup.onDeleted,
+    };
+}

package/dist/src/runtime/session/session-deletion-cleanup.d.ts

@@ -0,0 +1,7 @@
+export type SessionDeletionListener = (sessionId: string) => void | Promise<void>;
+/** Tombstones and original cleanup obligations last for this environment lifetime. */
+export declare function createSessionDeletionCleanup(): {
+    isDeleted: (sessionId: string) => boolean;
+    onDeleted: (listener: SessionDeletionListener) => () => void;
+    notify: (sessionId: string) => Promise<void>;
+};

package/dist/src/runtime/session/session-deletion-cleanup.js

@@ -0,0 +1,62 @@
+/** Tombstones and original cleanup obligations last for this environment lifetime. */
+export function createSessionDeletionCleanup() {
+    const listeners = new Set();
+    const deletedSessions = new Map();
+    function deletionState(sessionId) {
+        const existing = deletedSessions.get(sessionId);
+        if (existing)
+            return existing;
+        const state = { pending: new Set(listeners) };
+        deletedSessions.set(sessionId, state);
+        return state;
+    }
+    return {
+        isDeleted: (sessionId) => deletedSessions.has(sessionId),
+        onDeleted: (listener) => {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        notify: (sessionId) => {
+            // Install the tombstone before invoking any listener or yielding.
+            const state = deletionState(sessionId);
+            if (state.attempt)
+                return state.attempt;
+            if (state.pending.size === 0)
+                return Promise.resolve();
+            return startCleanupAttempt(sessionId, state);
+        },
+    };
+}
+function startCleanupAttempt(sessionId, state) {
+    let resolveAttempt;
+    let rejectAttempt;
+    const attempt = new Promise((resolve, reject) => {
+        resolveAttempt = resolve;
+        rejectAttempt = reject;
+    });
+    // Reentrant or concurrent deletion sees this same attempt immediately.
+    state.attempt = attempt;
+    void settleCleanupListeners(sessionId, state).then(() => {
+        state.attempt = undefined;
+        resolveAttempt();
+    }, (error) => {
+        state.attempt = undefined;
+        rejectAttempt(error);
+    });
+    return attempt;
+}
+async function settleCleanupListeners(sessionId, state) {
+    const outcomes = await Promise.allSettled([...state.pending].map(async (listener) => {
+        await listener(sessionId);
+        state.pending.delete(listener);
+    }));
+    // Keep only failed obligations, and wait for every listener before a retry.
+    const failure = outcomes.find(isFailedCleanup);
+    if (failure)
+        throw failure.reason;
+}
+function isFailedCleanup(outcome) {
+    return outcome.status === "rejected";
+}

package/dist/src/runtime/session/session-deletion-finalization.d.ts

@@ -0,0 +1,7 @@
+import type { SessionDeleteResult } from "../../sessions/types.js";
+export type SessionDeletionFinalizer = (result: SessionDeleteResult) => void | Promise<void>;
+/** Cleanup captures its physical-result promise before another call can replace it. */
+export declare function createSessionDeletionFinalization(finalize: SessionDeletionFinalizer): {
+    prepare(sessionId: string): (outcome: PromiseSettledResult<SessionDeleteResult>) => void;
+    finalizeDeletedSession(sessionId: string): Promise<void>;
+};

package/dist/src/runtime/session/session-deletion-finalization.js

@@ -0,0 +1,34 @@
+/** Cleanup captures its physical-result promise before another call can replace it. */
+export function createSessionDeletionFinalization(finalize) {
+    const physicalResults = new Map();
+    return {
+        prepare(sessionId) {
+            let resolve;
+            let reject;
+            const physical = new Promise((onResult, onError) => {
+                resolve = onResult;
+                reject = onError;
+            });
+            // Concurrent callers share cleanup, so some prepared results have no listener.
+            void physical.catch(() => undefined);
+            physicalResults.set(sessionId, physical);
+            return (outcome) => {
+                if (outcome.status === "fulfilled")
+                    resolve(outcome.value);
+                else
+                    reject(outcome.reason);
+                if (physicalResults.get(sessionId) === physical)
+                    physicalResults.delete(sessionId);
+            };
+        },
+        async finalizeDeletedSession(sessionId) {
+            const physical = physicalResults.get(sessionId);
+            if (!physical)
+                throw new Error("session_deletion_attempt_missing");
+            const result = await physical;
+            if (!result.deleted)
+                return;
+            await finalize(result);
+        },
+    };
+}

package/dist/src/runtime/session/session-deletion-receipts.d.ts

@@ -0,0 +1,7 @@
+import type { SessionDeleteResult } from "../../sessions/types.js";
+import type { SessionStore } from "../ports.js";
+/** Accessed only inside the owning lifecycle's per-session mutation queue. */
+export declare function createSessionDeletionReceipts(base: Pick<SessionStore, "deleteSessionWithStats">): {
+    remove(sessionId: string): Promise<SessionDeleteResult>;
+    acknowledge(sessionId: string): void;
+};

package/dist/src/runtime/session/session-deletion-receipts.js

@@ -0,0 +1,18 @@
+/** Accessed only inside the owning lifecycle's per-session mutation queue. */
+export function createSessionDeletionReceipts(base) {
+    const undelivered = new Map();
+    return {
+        async remove(sessionId) {
+            const existing = undelivered.get(sessionId);
+            if (existing)
+                return existing;
+            // Keep exact physical counts when later lifecycle cleanup rejects.
+            const receipt = { ...(await base.deleteSessionWithStats(sessionId)) };
+            undelivered.set(sessionId, receipt);
+            return receipt;
+        },
+        acknowledge(sessionId) {
+            undelivered.delete(sessionId);
+        },
+    };
+}

package/dist/src/runtime/session/session-lifecycle-store.d.ts

@@ -0,0 +1,21 @@
+import type { SessionStore } from "../ports.js";
+import type { SessionDeletionListener } from "./session-deletion-cleanup.js";
+import type { SessionDeletionFinalizer } from "./session-deletion-finalization.js";
+export type { SessionDeletionListener } from "./session-deletion-cleanup.js";
+export declare class SessionDeletedError extends Error {
+    readonly sessionId: string;
+    readonly code = "session_deleted";
+    constructor(sessionId: string);
+}
+export declare function isSessionDeletedError(error: unknown): error is SessionDeletedError;
+export type SessionLifecycleStore = Readonly<{
+    store: SessionStore;
+    isDeleted: (sessionId: string) => boolean;
+    onDeleted: (listener: SessionDeletionListener) => () => void;
+}>;
+/**
+ * Environment-owned deletion boundary. Every caller must use the wrapped store:
+ * an in-flight write finishes before deletion, while queued and later writes fail.
+ * Tombstones last for this application lifetime; deleted IDs cannot be reused.
+ */
+export declare function createSessionLifecycleStore(base: SessionStore, finalizeDeletion?: SessionDeletionFinalizer): SessionLifecycleStore;

package/dist/src/runtime/session/session-lifecycle-store.js

@@ -0,0 +1,72 @@
+import { createSessionDeletionBoundary } from "./session-deletion-boundary.js";
+import { createSessionMutationQueue } from "./session-mutation-queue.js";
+export class SessionDeletedError extends Error {
+    sessionId;
+    code = "session_deleted";
+    constructor(sessionId) {
+        super(`Session ${sessionId} has been deleted`);
+        this.sessionId = sessionId;
+        this.name = "SessionDeletedError";
+    }
+}
+export function isSessionDeletedError(error) {
+    return error instanceof SessionDeletedError;
+}
+/**
+ * Environment-owned deletion boundary. Every caller must use the wrapped store:
+ * an in-flight write finishes before deletion, while queued and later writes fail.
+ * Tombstones last for this application lifetime; deleted IDs cannot be reused.
+ */
+export function createSessionLifecycleStore(base, finalizeDeletion) {
+    const enqueueSessionMutation = createSessionMutationQueue();
+    const deletion = createSessionDeletionBoundary(base, enqueueSessionMutation, finalizeDeletion);
+    function assertSessionNotDeleted(sessionId) {
+        if (deletion.isDeleted(sessionId)) {
+            throw new SessionDeletedError(sessionId);
+        }
+    }
+    function wrapSessionMutation(operation) {
+        return async (...args) => {
+            assertSessionNotDeleted(args[0]);
+            return enqueueSessionMutation(args[0], async () => {
+                assertSessionNotDeleted(args[0]);
+                return operation.apply(base, args);
+            });
+        };
+    }
+    const store = {
+        getAllSessions: base.getAllSessions.bind(base),
+        listSessions: base.listSessions.bind(base),
+        getSessionById: base.getSessionById.bind(base),
+        getSessionSnapshot: base.getSessionSnapshot.bind(base),
+        getRequestReplayById: base.getRequestReplayById.bind(base),
+        getOrCreateSession: wrapSessionMutation(base.getOrCreateSession),
+        updateSessionTitle: wrapSessionMutation(base.updateSessionTitle),
+        appendMessage: wrapSessionMutation(base.appendMessage),
+        startRequestStream: wrapSessionMutation(base.startRequestStream),
+        appendRequestEvent: wrapSessionMutation(base.appendRequestEvent),
+        compareAndSwapSessionMemoryCheckpoint: wrapSessionMutation(base.compareAndSwapSessionMemoryCheckpoint),
+        resetSession: wrapSessionMutation(base.resetSession),
+        clearSessionMessages: wrapSessionMutation(base.clearSessionMessages),
+        deleteMessage: wrapSessionMutation(base.deleteMessage),
+        deleteMessageWithStats: wrapSessionMutation(base.deleteMessageWithStats),
+        deleteSession: async (sessionId) => (await deletion.deleteSessionWithStats(sessionId)).deleted,
+        deleteSessionWithStats: deletion.deleteSessionWithStats,
+        ...(base.updateSessionRuntimeMode
+            ? {
+                updateSessionRuntimeMode: wrapSessionMutation(base.updateSessionRuntimeMode),
+            }
+            : {}),
+        ...(base.appendContextEntry
+            ? { appendContextEntry: wrapSessionMutation(base.appendContextEntry) }
+            : {}),
+        ...(base.upsertArtifactPaths
+            ? { upsertArtifactPaths: wrapSessionMutation(base.upsertArtifactPaths) }
+            : {}),
+    };
+    return {
+        store,
+        isDeleted: deletion.isDeleted,
+        onDeleted: deletion.onDeleted,
+    };
+}

package/dist/src/runtime/session/session-mutation-queue.d.ts

@@ -0,0 +1,3 @@
+export type SessionMutationQueue = <T>(sessionId: string, operation: () => Promise<T>) => Promise<T>;
+/** One queue per store lifetime; unrelated sessions remain independent. */
+export declare function createSessionMutationQueue(): SessionMutationQueue;

package/dist/src/runtime/session/session-mutation-queue.js

@@ -0,0 +1,15 @@
+/** One queue per store lifetime; unrelated sessions remain independent. */
+export function createSessionMutationQueue() {
+    const queues = new Map();
+    return (sessionId, operation) => {
+        const predecessor = queues.get(sessionId) ?? Promise.resolve();
+        const result = predecessor.then(operation);
+        const settled = result.then(() => undefined, () => undefined);
+        queues.set(sessionId, settled);
+        void settled.then(() => {
+            if (queues.get(sessionId) === settled)
+                queues.delete(sessionId);
+        });
+        return result;
+    };
+}

package/dist/src/runtime/steps/execution-agent/capability-decision-parsing.d.ts

@@ -0,0 +1,16 @@
+import { type ExecutionAgentCapabilityInvocation, type ExecutionAgentDecisionValidationIssue } from "./contracts.js";
+import type { PreparedExecutionAgentCapability, PreparedExecutionAgentDecisionContract } from "./format.js";
+export declare function parseCapabilityCatalogGroupIds(value: unknown, offeredCatalogGroupIds: readonly string[], issues: ExecutionAgentDecisionValidationIssue[]): readonly string[] | undefined;
+export declare function parseCapabilityBatch(value: unknown, contract: PreparedExecutionAgentDecisionContract, issues: ExecutionAgentDecisionValidationIssue[]): readonly ExecutionAgentCapabilityInvocation[] | undefined;
+export declare function parseCapabilityInvocation(params: Readonly<{
+    value: unknown;
+    path: string;
+    capabilities: readonly PreparedExecutionAgentCapability[];
+    observationOnly: boolean;
+    includesAction: boolean;
+    issues: ExecutionAgentDecisionValidationIssue[];
+}>): Readonly<{
+    value?: ExecutionAgentCapabilityInvocation;
+    expectedKeys: readonly string[];
+}>;
+export declare function parseWorkingDirectory(record: Record<string, unknown>, contract: PreparedExecutionAgentDecisionContract, issues: ExecutionAgentDecisionValidationIssue[]): string | undefined;

package/dist/src/runtime/steps/execution-agent/capability-decision-parsing.js

@@ -0,0 +1,165 @@
+import { CAPABILITY_INTENT_MAX_LENGTH, materializeCapabilityControlsIfComplete, validateCapabilitySelectionControls, } from "../../orchestration/capability-adapters/index.js";
+import { normalizeExecutionWorkingDirectory } from "../../orchestration/capability-adapters/working-directory.js";
+import { executionCapabilityControlsIssue, normalizeGeneratedExecutionCapabilityControls, parseExecutionOperationObjective, requiresExecutionOperationObjective, } from "./capability-invocation-contract.js";
+import { EXECUTION_AGENT_CAPABILITY_SCOPE_GROUP_COUNT_MAX, } from "./contracts.js";
+import { asRecord, exactKeys, issue, validateBoundedText, } from "./decision-validation.js";
+export function parseCapabilityCatalogGroupIds(value, offeredCatalogGroupIds, issues) {
+    if (!Array.isArray(value) ||
+        value.length === 0 ||
+        value.length > EXECUTION_AGENT_CAPABILITY_SCOPE_GROUP_COUNT_MAX ||
+        new Set(value).size !== value.length ||
+        value.some((entry) => typeof entry !== "string")) {
+        issues.push(issue("execution_agent_capability_scope_invalid", "decision.catalogGroupIds", `catalogGroupIds must contain 1-${EXECUTION_AGENT_CAPABILITY_SCOPE_GROUP_COUNT_MAX} distinct offered group ids.`));
+        return undefined;
+    }
+    const catalogGroupIds = value;
+    if (catalogGroupIds.some((groupId) => !offeredCatalogGroupIds.includes(groupId))) {
+        issues.push(issue("execution_agent_capability_scope_group_unavailable", "decision.catalogGroupIds", "Every catalogGroupId must identify one group offered for this exact scope action."));
+        return undefined;
+    }
+    return Object.freeze([...catalogGroupIds]);
+}
+export function parseCapabilityBatch(value, contract, issues) {
+    if (!Array.isArray(value) ||
+        value.length < 2 ||
+        contract.maxBatchCapabilityExecutions < 2 ||
+        value.length > contract.maxBatchCapabilityExecutions) {
+        issues.push(issue("execution_agent_capability_batch_invalid", "decision.invocations", `Observation batch must contain 2-${contract.maxBatchCapabilityExecutions} invocations.`));
+        return undefined;
+    }
+    const accepted = [];
+    const issueCountBeforeInvocations = issues.length;
+    value.forEach((invocation, index) => {
+        const parsed = parseCapabilityInvocation({
+            value: invocation,
+            path: `decision.invocations.${index}`,
+            capabilities: contract.capabilities,
+            observationOnly: true,
+            includesAction: false,
+            issues,
+        });
+        if (parsed.value)
+            accepted.push(parsed.value);
+    });
+    const invocationValidationFailed = accepted.length !== value.length ||
+        issues.length !== issueCountBeforeInvocations;
+    if (invocationValidationFailed)
+        return undefined;
+    return Object.freeze(accepted);
+}
+export function parseCapabilityInvocation(params) {
+    const record = asRecord(params.value);
+    const baseExpectedKeys = [
+        ...(params.includesAction ? ["action"] : []),
+        "capabilityId",
+        "intent",
+    ];
+    if (!record) {
+        params.issues.push(issue("execution_agent_capability_invocation_invalid", params.path, "Capability invocation must be an object."));
+        return { expectedKeys: baseExpectedKeys };
+    }
+    let capability;
+    if (typeof record.capabilityId !== "string") {
+        params.issues.push(issue("execution_agent_capability_id_invalid", `${params.path}.capabilityId`, "capabilityId must identify one available capability."));
+    }
+    else {
+        capability = params.capabilities.find(({ capabilityId }) => capabilityId === record.capabilityId);
+        if (!capability) {
+            params.issues.push(issue("execution_agent_capability_unavailable", `${params.path}.capabilityId`, "capabilityId must identify one available capability."));
+        }
+        else if (params.observationOnly && capability.effect !== "observation") {
+            params.issues.push(issue("execution_agent_capability_batch_effect_invalid", `${params.path}.capabilityId`, "Only observation capabilities may be invoked in a batch."));
+        }
+    }
+    const expectedKeys = [
+        ...baseExpectedKeys,
+        ...(capability && requiresExecutionOperationObjective(capability.partition)
+            ? ["operationObjective"]
+            : []),
+        ...(capability?.partition.selectionControlIds.length
+            ? ["selectionControls"]
+            : []),
+    ];
+    if (!params.includesAction) {
+        exactKeys(record, expectedKeys, params.issues, params.path);
+    }
+    const intent = validateBoundedText({
+        value: record.intent,
+        maximumLength: CAPABILITY_INTENT_MAX_LENGTH,
+        code: "execution_agent_capability_intent_invalid",
+        path: `${params.path}.intent`,
+        label: "Capability intent",
+        issues: params.issues,
+    });
+    const operationObjective = parseExecutionOperationObjective({
+        value: record.operationObjective,
+        required: capability !== undefined &&
+            requiresExecutionOperationObjective(capability.partition),
+        path: `${params.path}.operationObjective`,
+        issues: params.issues,
+    });
+    let selectionControls;
+    let controls;
+    if (capability) {
+        const normalizedSelectionControls = capability.partition.selectionControlIds.length > 0
+            ? normalizeGeneratedExecutionCapabilityControls(record.selectionControls, capability.partition.selectionSchema)
+            : {};
+        const selection = validateCapabilitySelectionControls(capability.partition, normalizedSelectionControls);
+        if (!selection.ok) {
+            params.issues.push(executionCapabilityControlsIssue({
+                issueCode: selection.issueCode,
+                controlId: selection.controlId,
+                path: selection.controlId
+                    ? `${params.path}.selectionControls.${selection.controlId}`
+                    : `${params.path}.selectionControls`,
+            }));
+        }
+        else {
+            if (capability.partition.selectionControlIds.length > 0) {
+                selectionControls = selection.value;
+            }
+            const materialized = materializeCapabilityControlsIfComplete(capability.partition, selection.value);
+            if (materialized && !materialized.ok) {
+                params.issues.push(executionCapabilityControlsIssue({
+                    issueCode: materialized.issueCode,
+                    controlId: materialized.controlId,
+                    path: materialized.controlId
+                        ? `${params.path}.selectionControls.${materialized.controlId}`
+                        : `${params.path}.selectionControls`,
+                }));
+            }
+            else if (materialized?.ok) {
+                controls = materialized.value;
+            }
+        }
+    }
+    if (!capability ||
+        (params.observationOnly && capability.effect !== "observation") ||
+        intent === undefined ||
+        !operationObjective.ok) {
+        return { expectedKeys };
+    }
+    return {
+        expectedKeys,
+        value: Object.freeze({
+            capabilityId: capability.capabilityId,
+            intent,
+            ...(operationObjective.value
+                ? { operationObjective: operationObjective.value }
+                : {}),
+            ...(selectionControls ? { selectionControls } : {}),
+            ...(controls ? { controls } : {}),
+        }),
+    };
+}
+export function parseWorkingDirectory(record, contract, issues) {
+    if (!contract.includeWorkingDirectory)
+        return undefined;
+    if (record.workingDirectory === null)
+        return ".";
+    const normalized = normalizeExecutionWorkingDirectory(record.workingDirectory);
+    if (!normalized) {
+        issues.push(issue("execution_agent_working_directory_invalid", "decision.workingDirectory", "workingDirectory must be one safe agent-root-relative directory."));
+    }
+    return normalized;
+}

package/dist/src/runtime/steps/execution-agent/contracts.d.ts

@@ -1,3 +1,4 @@
+import type { MemoryRecallDecision } from "../memory-recall-decision.js";
 import type { RoleCapabilitySelectionProjection, RoleCapabilitySelectionReconsiderationCause } from "../../orchestration/role-calls/index.js";
 import { type CapabilityControls, type CapabilityDescriptor } from "../../orchestration/capability-adapters/index.js";
 export declare const EXECUTION_AGENT_DECISION_MODEL_STEP: "execution.decision";
@@ -58,7 +59,7 @@ export type ExecutionAgentInvokeAuditorDecision = Readonly<ExecutionAgentDecisio
     action: "invoke_auditor";
     criterionIds: readonly string[];
 }>;
-export type ExecutionAgentDecision = ExecutionAgentOpenCapabilityScopeDecision | ExecutionAgentExtendCapabilityScopeDecision | ExecutionAgentRespondDecision | ExecutionAgentBlockedDecision | ExecutionAgentInvokeCapabilityDecision | ExecutionAgentInvokeCapabilitiesDecision | ExecutionAgentInvokePlannerDecision | ExecutionAgentInvokeAuditorDecision;
+export type ExecutionAgentDecision = MemoryRecallDecision | ExecutionAgentOpenCapabilityScopeDecision | ExecutionAgentExtendCapabilityScopeDecision | ExecutionAgentRespondDecision | ExecutionAgentBlockedDecision | ExecutionAgentInvokeCapabilityDecision | ExecutionAgentInvokeCapabilitiesDecision | ExecutionAgentInvokePlannerDecision | ExecutionAgentInvokeAuditorDecision;
 /** Runtime-only transition emitted when controls refinement exhausts validation. */
 export type ExecutionAgentReconsiderCapabilitySelectionDecision = Readonly<{
     action: "reconsider_capability_selection";
@@ -94,6 +95,7 @@ export type ExecutionAgentDecisionContractOptions = Readonly<{
     includeAcknowledgement?: boolean;
     includeTitle?: boolean;
     allowRespond?: boolean;
+    allowMemoryRecall?: boolean;
     allowPlanner?: boolean;
     allowAuditor?: boolean;
     availableAuditCriterionIds?: readonly string[];

package/dist/src/runtime/steps/execution-agent/decision-parsing.d.ts

@@ -0,0 +1,2 @@
+import { type ExecutionAgentDecisionContractOptions, type ExecutionAgentDecisionParseResult } from "./contracts.js";
+export declare function parseExecutionAgentDecisionOutput(text: string, options?: ExecutionAgentDecisionContractOptions): ExecutionAgentDecisionParseResult;