@abot-ai/runtime 1.0.0

package/dist/src/runtime/request/root-execution-kernel.js

@@ -0,0 +1,472 @@
+import { projectRequestToolResults } from "../context/request-tool-results.js";
+import { emitRuntimeStatus } from "../events/runtime-status.js";
+import { resolveRoleCallTransactions, } from "../orchestration/role-calls/index.js";
+import { RUNTIME_ROOT_ROLE_ID } from "../orchestration/roles.js";
+import { createRoleCapabilityBinding, projectWorkerCapabilityCatalogGroups, } from "../orchestration/worker-capabilities/index.js";
+import { projectRequestSteeringSnapshot, resolveRequestSteeringInbox, } from "./request-steering.js";
+import { traceSupervisorRootAcknowledgementPublished, traceSupervisorRootActivationFailed, traceSupervisorRootActivationStarted, traceSupervisorRootObservationHandoffBound, traceSupervisorRootInvocationSuperseded, traceSupervisorRootResponseSuperseded, } from "./supervisor-root-execution-diagnostics.js";
+const CONTINUE_ROOT_EXECUTION = Object.freeze({
+    kind: "continue",
+});
+export async function runRootExecutionKernel(params) {
+    return new RootExecutionSession(params).run();
+}
+class RootExecutionSession {
+    request;
+    ledger;
+    transactions;
+    policy;
+    diagnostic;
+    requestSteering;
+    resume;
+    observationHandoff;
+    availableWorkerCapabilityCatalog;
+    acknowledgementPublished = false;
+    titlePublished = false;
+    constructor(params) {
+        this.request = params.request;
+        this.ledger = params.ledger;
+        this.transactions = resolveRoleCallTransactions(params.ledger);
+        this.policy = params.request.executionPolicy;
+        this.diagnostic = Object.freeze({
+            requestId: params.request.requestId,
+            allowedRoleIds: this.policy.roleExecutors.roleIds,
+        });
+        this.requestSteering = resolveRequestSteeringInbox(params.request.requestSteering);
+    }
+    async run() {
+        // Every non-terminal decision consumes a ledger-bounded child call.
+        for (;;) {
+            const control = await this.runActivation();
+            if (control.kind === "complete") {
+                return control.result;
+            }
+        }
+    }
+    async runActivation() {
+        const attempt = {
+            failureStage: "project_activation",
+        };
+        try {
+            const activation = this.resolveActivation(attempt);
+            const decisionActivation = await this.decide(activation, attempt);
+            if (!(await this.publishImmediatePresentation(decisionActivation, attempt))) {
+                return CONTINUE_ROOT_EXECUTION;
+            }
+            return await this.executeDecision(decisionActivation, attempt);
+        }
+        catch (error) {
+            traceSupervisorRootActivationFailed({
+                diagnostic: this.diagnostic,
+                failureStage: attempt.failureStage,
+                error,
+                ...(attempt.head ? { head: attempt.head } : {}),
+                ...(attempt.call ? { call: attempt.call } : {}),
+                ...(this.resume ? { resume: this.resume } : {}),
+            });
+            throw error;
+        }
+    }
+    resolveActivation(attempt) {
+        const head = this.ledger.current();
+        attempt.head = head;
+        const callIdentity = this.policy.rootContract.projectCallIdentity(head);
+        const call = requireRootCallFrame({ head, callId: callIdentity.callId });
+        attempt.call = call;
+        traceSupervisorRootActivationStarted({
+            diagnostic: this.diagnostic,
+            head,
+            call,
+            ...(this.resume ? { resume: this.resume } : {}),
+        });
+        if (this.resume) {
+            emitSupervisorResumeStatus(this.request);
+        }
+        return Object.freeze({ head, call, callIdentity });
+    }
+    async decide(activation, attempt) {
+        attempt.failureStage = "project_worker_catalog";
+        this.availableWorkerCapabilityCatalog ??=
+            this.policy.authority.capabilityAuthorities.includes("root") ||
+                (this.policy.roleExecutors.roleIds.includes("worker") &&
+                    this.policy.authority.capabilityAuthorities.includes("worker"))
+                ? projectWorkerCapabilityCatalogGroups(this.request.workerCapabilities.provider.getDescriptors())
+                : Object.freeze([]);
+        attempt.failureStage = "decide";
+        const decisionToolResults = projectRequestToolResults({
+            ledger: this.ledger,
+            head: activation.head,
+            modelStep: this.policy.rootContract.decisionModelStep,
+            callId: activation.call.callId,
+        });
+        const decisionOutcome = await this.policy.rootContract.decide(this.request, {
+            head: activation.head,
+            callFrame: activation.call,
+            call: activation.callIdentity,
+            toolResults: decisionToolResults,
+            includeAcknowledgement: this.resume === undefined && !this.acknowledgementPublished,
+            includeTitle: this.resume === undefined &&
+                !this.titlePublished &&
+                this.request.shouldGenerateSessionTitle,
+            allowedRoleIds: this.policy.roleExecutors.roleIds,
+            availableWorkerCapabilityCatalog: this.availableWorkerCapabilityCatalog,
+            ...(this.resume ? { resume: this.resume } : {}),
+        });
+        const requiresFreshPresentation = this.policy.rootContract.deferRespondPresentation === true;
+        return Object.freeze({
+            ...activation,
+            decision: decisionOutcome.decision,
+            decisionSteeringVersion: decisionOutcome.steeringVersion,
+            requiresFreshPresentation,
+            deferPresentation: requiresFreshPresentation &&
+                (decisionOutcome.decision.action === "respond" ||
+                    decisionOutcome.decision.action === "blocked"),
+        });
+    }
+    async publishImmediatePresentation(activation, attempt) {
+        const { decision } = activation;
+        if (activation.deferPresentation) {
+            return true;
+        }
+        if (decision.title !== undefined) {
+            if (activation.requiresFreshPresentation &&
+                !this.isInvocationCurrent(activation.decisionSteeringVersion)) {
+                return false;
+            }
+            attempt.failureStage = "publish_title";
+            await this.request.onSessionTitle(decision.title);
+            this.titlePublished = true;
+        }
+        if (decision.acknowledgement !== undefined) {
+            if (activation.requiresFreshPresentation &&
+                !this.isInvocationCurrent(activation.decisionSteeringVersion)) {
+                return false;
+            }
+            attempt.failureStage = "publish_acknowledgement";
+            this.request.onAcknowledgement(decision.acknowledgement);
+            this.acknowledgementPublished = true;
+            traceSupervisorRootAcknowledgementPublished({
+                diagnostic: this.diagnostic,
+                head: activation.head,
+                call: activation.call,
+                acknowledgementLength: decision.acknowledgement.length,
+            });
+        }
+        return true;
+    }
+    async executeDecision(activation, attempt) {
+        const { decision } = activation;
+        if (decision.action === "invoke_role") {
+            return this.invokeRole(activation, decision, attempt);
+        }
+        if (decision.action === "reconsider_capability_selection") {
+            return this.reconsiderCapabilitySelection(activation, decision, attempt);
+        }
+        if (decision.action === "update_capability_scope") {
+            return this.updateCapabilityScope(activation, decision, attempt);
+        }
+        if (decision.action === "invoke_capability" ||
+            decision.action === "invoke_capabilities") {
+            return this.invokeCapabilities(activation, decision, attempt);
+        }
+        return this.completeResponse(activation, decision, attempt);
+    }
+    async invokeRole(activation, decision, attempt) {
+        if (!this.isInvocationCurrent(activation.decisionSteeringVersion)) {
+            return CONTINUE_ROOT_EXECUTION;
+        }
+        attempt.failureStage = "invoke_child";
+        const child = await this.policy.roleExecutors.invokeChild({
+            requestId: this.request.requestId,
+            context: this.request,
+            callerCall: activation.call,
+            ledger: this.ledger,
+            expectedHead: activation.head,
+            roleId: decision.roleId,
+            objective: decision.objective,
+            ...(decision.roleId === "planner" || decision.roleId === "worker"
+                ? { workingDirectory: decision.workingDirectory }
+                : {}),
+            ...(decision.roleId === "worker" && decision.workerCapabilityScope
+                ? { workerCapabilityScope: decision.workerCapabilityScope }
+                : {}),
+            turnCount: activation.call.activationCount,
+        });
+        attempt.failureStage = "project_resume";
+        this.resume = this.policy.rootContract.projectResume(this.ledger, child.returnCommit);
+        if (child.execution.value?.finalObservation) {
+            attempt.failureStage = "bind_observation";
+            this.observationHandoff = bindSupervisorObservationHandoff({
+                diagnostic: this.diagnostic,
+                returnCommit: child.returnCommit,
+                resume: this.resume,
+                finalObservation: child.execution.value.finalObservation,
+                replaced: this.observationHandoff !== undefined,
+            });
+        }
+        return CONTINUE_ROOT_EXECUTION;
+    }
+    async reconsiderCapabilitySelection(activation, decision, attempt) {
+        if (!this.isInvocationCurrent(activation.decisionSteeringVersion)) {
+            return CONTINUE_ROOT_EXECUTION;
+        }
+        attempt.failureStage = "apply_root_transition";
+        const reconsidered = await this.transactions.reconsiderCapabilitySelection({
+            expectedHead: activation.head,
+            callId: activation.call.callId,
+            invocationAttempt: activation.call.activationCount,
+            steeringVersion: activation.decisionSteeringVersion,
+            selection: decision.selection,
+        });
+        if (!reconsidered.ok) {
+            throw new Error(`role_call_ledger_rejected:${reconsidered.issueCode}`);
+        }
+        return CONTINUE_ROOT_EXECUTION;
+    }
+    async updateCapabilityScope(activation, decision, attempt) {
+        if (!this.isInvocationCurrent(activation.decisionSteeringVersion)) {
+            return CONTINUE_ROOT_EXECUTION;
+        }
+        attempt.failureStage = "invoke_child";
+        const updated = await this.transactions.updateCapabilityScope({
+            expectedHead: activation.head,
+            callId: activation.call.callId,
+            invocationAttempt: activation.call.activationCount,
+            mode: decision.mode,
+            catalogGroupIds: decision.catalogGroupIds,
+        });
+        if (!updated.ok) {
+            throw new Error(`role_call_ledger_rejected:${updated.issueCode}`);
+        }
+        return CONTINUE_ROOT_EXECUTION;
+    }
+    async invokeCapabilities(activation, decision, attempt) {
+        if (!this.isInvocationCurrent(activation.decisionSteeringVersion)) {
+            return CONTINUE_ROOT_EXECUTION;
+        }
+        attempt.failureStage = "invoke_child";
+        let head = activation.head;
+        let call = activation.call;
+        if (decision.workingDirectory !== undefined) {
+            const established = await this.transactions.establishWorkingDirectory({
+                expectedHead: head,
+                callId: call.callId,
+                invocationAttempt: call.activationCount,
+                workingDirectory: decision.workingDirectory,
+            });
+            if (!established.ok) {
+                throw new Error(`role_call_ledger_rejected:${established.issueCode}`);
+            }
+            head = established.commit.head;
+            attempt.head = head;
+            call = requireRootCallFrame({ head, callId: call.callId });
+            attempt.call = call;
+        }
+        const binding = createRoleCapabilityBinding({
+            requestId: this.request.requestId,
+            context: this.request.workerCapabilities.executionContext,
+            call,
+            ledger: this.ledger,
+            adapters: this.request.workerCapabilities.provider.getAdapters(),
+            ...(this.policy.authority.capabilityAuthorities.includes("root")
+                ? {
+                    executionFreshness: createRootExecutionFreshness({
+                        requestSteering: this.requestSteering,
+                        steeringVersion: activation.decisionSteeringVersion,
+                    }),
+                }
+                : {}),
+        });
+        if (decision.action === "invoke_capability") {
+            await binding.execute({
+                capabilityId: decision.capabilityId,
+                intent: decision.intent,
+                controls: decision.controls,
+            });
+        }
+        else {
+            await binding.executeBatch({ invocations: decision.invocations });
+        }
+        this.resume = undefined;
+        return CONTINUE_ROOT_EXECUTION;
+    }
+    async completeResponse(activation, decision, attempt) {
+        if (!this.isResponseCurrent(activation.decisionSteeringVersion, "before_response")) {
+            return CONTINUE_ROOT_EXECUTION;
+        }
+        attempt.failureStage = "project_observation";
+        const finalObservation = this.observationHandoff
+            ? projectSupervisorFinalObservation(this.observationHandoff, this.resume)
+            : undefined;
+        attempt.failureStage = "compose_response";
+        const response = decision.action === "blocked"
+            ? decision.response
+            : await this.policy.rootContract.authorResponse(this.request, {
+                head: activation.head,
+                callFrame: activation.call,
+                steeringVersion: activation.decisionSteeringVersion,
+                call: activation.callIdentity,
+                toolResults: projectRequestToolResults({
+                    ledger: this.ledger,
+                    head: activation.head,
+                    modelStep: this.policy.rootContract.responseModelStep,
+                    callId: activation.call.callId,
+                }),
+                ...(this.resume ? { resume: this.resume } : {}),
+            });
+        if (!this.isResponseCurrent(activation.decisionSteeringVersion, "after_response")) {
+            return CONTINUE_ROOT_EXECUTION;
+        }
+        attempt.failureStage = "seal_response";
+        this.request.abortSignal.throwIfAborted();
+        if (!this.requestSteering.seal(activation.decisionSteeringVersion)) {
+            this.traceResponseSuperseded(activation.decisionSteeringVersion, "seal");
+            return CONTINUE_ROOT_EXECUTION;
+        }
+        await this.publishDeferredPresentation(activation, attempt);
+        attempt.failureStage = "commit_response";
+        const output = await commitSupervisorResponse({
+            transactions: this.transactions,
+            expectedHead: activation.head,
+            callId: activation.call.callId,
+            response,
+        });
+        return Object.freeze({
+            kind: "complete",
+            result: Object.freeze({
+                output,
+                ...(this.policy.authority.terminalTextMode === "exact"
+                    ? { outputTextMode: "exact" }
+                    : {}),
+                ...(finalObservation ? { finalObservation } : {}),
+            }),
+        });
+    }
+    async publishDeferredPresentation(activation, attempt) {
+        if (!activation.deferPresentation) {
+            return;
+        }
+        if (activation.decision.title !== undefined) {
+            attempt.failureStage = "publish_title";
+            await this.request.onSessionTitle(activation.decision.title);
+            this.titlePublished = true;
+        }
+        if (activation.decision.acknowledgement !== undefined) {
+            attempt.failureStage = "publish_acknowledgement";
+            this.request.onAcknowledgement(activation.decision.acknowledgement);
+            this.acknowledgementPublished = true;
+            traceSupervisorRootAcknowledgementPublished({
+                diagnostic: this.diagnostic,
+                head: activation.head,
+                call: activation.call,
+                acknowledgementLength: activation.decision.acknowledgement.length,
+            });
+        }
+    }
+    isInvocationCurrent(decisionSteeringVersion) {
+        if (this.requestSteering.isCurrent(decisionSteeringVersion)) {
+            return true;
+        }
+        traceSupervisorRootInvocationSuperseded({
+            diagnostic: this.diagnostic,
+            decisionSteeringVersion,
+            currentSteeringVersion: this.requestSteering.snapshot().version,
+        });
+        return false;
+    }
+    isResponseCurrent(decisionSteeringVersion, phase) {
+        if (this.requestSteering.isCurrent(decisionSteeringVersion)) {
+            return true;
+        }
+        this.traceResponseSuperseded(decisionSteeringVersion, phase);
+        return false;
+    }
+    traceResponseSuperseded(decisionSteeringVersion, phase) {
+        traceSupervisorRootResponseSuperseded({
+            diagnostic: this.diagnostic,
+            decisionSteeringVersion,
+            currentSteeringVersion: this.requestSteering.snapshot().version,
+            phase,
+        });
+    }
+}
+function createRootExecutionFreshness(params) {
+    const snapshot = projectRequestSteeringSnapshot(params.requestSteering, params.steeringVersion);
+    return Object.freeze({
+        token: Object.freeze({
+            kind: "request_steering_v1",
+            version: snapshot.version,
+            updates: Object.freeze(snapshot.updates.map(({ sequence, text }) => Object.freeze({ sequence, text }))),
+        }),
+        isCurrent: () => params.requestSteering.isCurrent(snapshot.version),
+    });
+}
+function bindSupervisorObservationHandoff(params) {
+    const { callerCallId, childCallId, resultRef } = params.returnCommit.effect;
+    if (params.resume.callerCallId !== callerCallId ||
+        params.resume.returnedChildCallId !== childCallId ||
+        params.resume.returnedResultRef !== resultRef ||
+        !params.resume.completedChildren.some((child) => child.callerCallId === callerCallId &&
+            child.childCallId === childCallId &&
+            child.resultRef === resultRef)) {
+        throw new Error("supervisor_observation_handoff_source_invalid");
+    }
+    const handoff = Object.freeze({
+        callerCallId,
+        childCallId,
+        resultRef,
+        finalObservation: params.finalObservation,
+    });
+    traceSupervisorRootObservationHandoffBound({
+        diagnostic: params.diagnostic,
+        callerCallId,
+        childCallId,
+        resultRef,
+        replaced: params.replaced,
+        observationContentLength: params.finalObservation.observationContent.length,
+    });
+    return handoff;
+}
+function projectSupervisorFinalObservation(handoff, resume) {
+    if (resume?.callerCallId !== handoff.callerCallId ||
+        !resume.completedChildren.some((child) => child.callerCallId === handoff.callerCallId &&
+            child.childCallId === handoff.childCallId &&
+            child.resultRef === handoff.resultRef)) {
+        throw new Error("supervisor_observation_handoff_source_invalid");
+    }
+    return handoff.finalObservation;
+}
+function emitSupervisorResumeStatus(request) {
+    emitRuntimeStatus(request, {
+        stage: "supervisor",
+        phase: "resuming",
+        message: "Processing the delegated result...",
+    });
+}
+function requireRootCallFrame(params) {
+    const call = params.head.state.calls.find((candidate) => candidate.callId === params.callId);
+    if (!call ||
+        call.callId !== params.head.state.rootCallId ||
+        call.parentCallId !== null ||
+        call.roleId !== RUNTIME_ROOT_ROLE_ID ||
+        call.depth !== 0 ||
+        call.status !== "active") {
+        throw new Error("supervisor_call_frame_missing");
+    }
+    return call;
+}
+async function commitSupervisorResponse(params) {
+    const committed = await params.transactions.completeRootResponse({
+        expectedHead: params.expectedHead,
+        callId: params.callId,
+        response: params.response,
+    });
+    if (!committed.ok) {
+        throw new Error(`role_call_ledger_rejected:${committed.issueCode}`);
+    }
+    const output = committed.commit.head.state.rootResponse;
+    if (!output) {
+        throw new Error("supervisor_root_response_missing");
+    }
+    return output;
+}

package/dist/src/runtime/request/runner.d.ts

@@ -0,0 +1,6 @@
+import type { RequestRunnerResult } from "./result.js";
+import { type RequestArtifactPathPersistence } from "./session-artifact-path-persistence.js";
+import { type RequestExecutionScope } from "./execution-scope.js";
+export declare function runRequestRunner(request: RequestExecutionScope, options?: Readonly<{
+    persistArtifactPaths?: RequestArtifactPathPersistence;
+}>): Promise<RequestRunnerResult>;

package/dist/src/runtime/request/runner.js

@@ -0,0 +1,81 @@
+import { createRoleCallLedger, ROLE_CALL_OBJECTIVE_MAX_LENGTH, ROLE_CALL_RESPONSE_MAX_LENGTH, ROLE_CALL_RESULT_MAX_LENGTH, resolveRoleCallTransactions, } from "../orchestration/role-calls/index.js";
+import { traceDebug } from "../observability/debug-logger.js";
+import { attachRequestPlannerRoleCallEvents } from "./role-call-planner-events.js";
+import { runRootExecutionKernel } from "./root-execution-kernel.js";
+import { persistSettledSessionArtifactPaths, } from "./session-artifact-path-persistence.js";
+const INITIAL_ROLE_CALL_LIMITS = Object.freeze({
+    limits: Object.freeze({
+        maxDepth: 12,
+        maxCalls: 48,
+        maxCapabilityExecutions: 96,
+        maxObjectiveChars: ROLE_CALL_OBJECTIVE_MAX_LENGTH,
+        maxResultChars: ROLE_CALL_RESULT_MAX_LENGTH,
+        maxResponseChars: ROLE_CALL_RESPONSE_MAX_LENGTH,
+    }),
+});
+export async function runRequestRunner(request, options = {}) {
+    const executionPolicy = request.executionPolicy;
+    if (request.executionPolicySelection?.policy !== undefined &&
+        executionPolicy.authority.id !== request.executionPolicySelection.policy) {
+        throw new Error("execution_policy_selection_mismatch");
+    }
+    traceDebug("runtime.request", "request.execution_policy.selected", {
+        requestId: request.requestId,
+        policyId: executionPolicy.authority.id,
+        policyVersion: executionPolicy.authority.version,
+        source: request.executionPolicySelection?.source ?? "default",
+        ...(request.executionPolicySelection?.primaryProfileId
+            ? {
+                primaryProfileId: request.executionPolicySelection.primaryProfileId,
+            }
+            : {}),
+    });
+    const ledger = createRoleCallLedger({
+        requestId: request.requestId,
+        policy: Object.freeze({
+            authority: executionPolicy.authority,
+            limits: INITIAL_ROLE_CALL_LIMITS.limits,
+        }),
+    });
+    attachRequestPlannerRoleCallEvents({
+        ledger,
+        onEvent: request.onEvent,
+    });
+    let result;
+    try {
+        const created = await resolveRoleCallTransactions(ledger).createRoot({
+            expectedHead: ledger.current(),
+        });
+        if (!created.ok) {
+            throw new Error(`role_call_ledger_rejected:${created.issueCode}`);
+        }
+        result = await runRootExecutionKernel({
+            request,
+            ledger,
+        });
+    }
+    catch (error) {
+        await persistSettledSessionArtifactPaths({
+            head: ledger.current(),
+            sessionId: request.sessionId,
+            trigger: "root_failed",
+            ...(options.persistArtifactPaths
+                ? { persistArtifactPaths: options.persistArtifactPaths }
+                : {}),
+        });
+        throw error;
+    }
+    await persistSettledSessionArtifactPaths({
+        head: ledger.current(),
+        sessionId: request.sessionId,
+        trigger: "root_succeeded",
+        ...(options.persistArtifactPaths
+            ? { persistArtifactPaths: options.persistArtifactPaths }
+            : {}),
+    });
+    return deliverAnswer(request, result);
+}
+function deliverAnswer(request, result) {
+    request.onAnswerToken(result.output);
+    return result;
+}

package/dist/src/runtime/request/session-artifact-path-persistence.d.ts

@@ -0,0 +1,11 @@
+import type { SessionArtifactPath, SessionArtifactPathInput } from "../../sessions/types.js";
+import type { RoleCallLedgerHead } from "../orchestration/role-calls/index.js";
+export type RequestArtifactPathPersistence = (inputs: readonly SessionArtifactPathInput[]) => Promise<void>;
+export declare function collectSettledSessionArtifactPathInputs(head: RoleCallLedgerHead): readonly SessionArtifactPathInput[];
+export declare function snapshotSessionArtifactPathTargets(artifactPaths: readonly SessionArtifactPath[] | undefined): readonly string[];
+export declare function persistSettledSessionArtifactPaths(params: {
+    head: RoleCallLedgerHead;
+    sessionId: string;
+    trigger: "root_succeeded" | "root_failed";
+    persistArtifactPaths?: RequestArtifactPathPersistence;
+}): Promise<void>;

package/dist/src/runtime/request/session-artifact-path-persistence.js

@@ -0,0 +1,78 @@
+import { MAX_SESSION_ARTIFACT_PATHS, MAX_SESSION_ARTIFACT_PATH_TARGET_LENGTH, } from "../../sessions/artifact-paths.js";
+import { traceDebug } from "../observability/debug-logger.js";
+import { classifyRuntimeErrorType } from "../observability/error-type.js";
+const LOG_SCOPE = "runtime.session_artifact_paths";
+export function collectSettledSessionArtifactPathInputs(head) {
+    const byTarget = new Map();
+    for (const execution of head.state.capabilityExecutions) {
+        if (execution.status !== "settled" ||
+            execution.outcome !== "succeeded" ||
+            !execution.references) {
+            continue;
+        }
+        for (const reference of execution.references) {
+            if (reference.kind !== "tool_target") {
+                continue;
+            }
+            const input = Object.freeze({
+                target: reference.target,
+                sourceRequestId: head.state.requestId,
+                sourceExecutionId: execution.executionId,
+            });
+            // Keep unique inputs ordered by their final successful occurrence so the
+            // session store can refresh recency deterministically.
+            byTarget.delete(reference.target);
+            byTarget.set(reference.target, input);
+        }
+    }
+    return Object.freeze([...byTarget.values()]);
+}
+export function snapshotSessionArtifactPathTargets(artifactPaths) {
+    if (!Array.isArray(artifactPaths) || artifactPaths.length === 0) {
+        return Object.freeze([]);
+    }
+    const targets = [];
+    const seen = new Set();
+    for (let index = artifactPaths.length - 1; index >= 0 && targets.length < MAX_SESSION_ARTIFACT_PATHS; index -= 1) {
+        const target = artifactPaths[index]?.target;
+        if (typeof target !== "string" ||
+            target.trim().length === 0 ||
+            target.length > MAX_SESSION_ARTIFACT_PATH_TARGET_LENGTH ||
+            seen.has(target)) {
+            continue;
+        }
+        seen.add(target);
+        targets.push(target);
+    }
+    return Object.freeze(targets);
+}
+export async function persistSettledSessionArtifactPaths(params) {
+    const inputs = collectSettledSessionArtifactPathInputs(params.head);
+    if (inputs.length === 0) {
+        return;
+    }
+    const diagnostic = {
+        requestId: params.head.state.requestId,
+        sessionId: params.sessionId,
+        trigger: params.trigger,
+        pathCount: inputs.length,
+        sourceExecutionCount: new Set(inputs.map(({ sourceExecutionId }) => sourceExecutionId)).size,
+    };
+    if (!params.persistArtifactPaths) {
+        traceDebug(LOG_SCOPE, "persistence.skipped", {
+            ...diagnostic,
+            reason: "store_method_unavailable",
+        });
+        return;
+    }
+    try {
+        await params.persistArtifactPaths(inputs);
+        traceDebug(LOG_SCOPE, "persistence.completed", diagnostic);
+    }
+    catch (error) {
+        traceDebug(LOG_SCOPE, "persistence.failed", {
+            ...diagnostic,
+            errorType: classifyRuntimeErrorType(error),
+        });
+    }
+}

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

@@ -0,0 +1,2 @@
+import type { SessionStore } from "../ports.js";
+export type RequestSessionStore = Pick<SessionStore, "appendMessage" | "appendContextEntry" | "appendRequestEvent" | "compareAndSwapSessionMemoryCheckpoint" | "getOrCreateSession" | "startRequestStream" | "upsertArtifactPaths" | "updateSessionTitle">;

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

@@ -0,0 +1 @@
+export {};