open-managed-agents 0.1.0

package/dist/src/control-plane/sessions/service.js

@@ -0,0 +1,733 @@
+import { createHash } from "node:crypto";
+import { log } from "../logging.js";
+import { EgressPolicyError, parseNetworkingConfig, } from "../egress/policy.js";
+import { ApiError, invalidRequest, notFound, rateLimited, toApiErrorBody } from "../errors.js";
+import { idempotencyCompletion, idempotencyConflictResponse, idempotencyMismatchError, reserveWindow, withIdempotencyReservationHeartbeat, } from "../request-idempotency.js";
+import { RuntimeUnsupportedSessionFileResourcesError } from "../events/types.js";
+import { newFileId, newSessionId, newSessionResourceId, newSessionSkillSnapshotId } from "../ids.js";
+import { parseCreateSession, parseAgentRef } from "./request.js";
+import { resolveBuiltinToolAccessForAgent } from "./pi/tool-permissions.js";
+import { normalizeSessionFileResources, } from "./resources.js";
+import { toManagedSession } from "./serialize.js";
+const MAX_SESSION_FILE_RESOURCES = 10;
+const MAX_SESSION_MOUNTED_BYTES = 50 * 1024 * 1024;
+const DEFAULT_PENDING_SNAPSHOT_CLEANUP_RETRY_DELAY_MS = 30_000;
+const DEFAULT_PENDING_SNAPSHOT_CLEANUP_MAX_ATTEMPTS = 5;
+export class DefaultSessionService {
+    store;
+    agents;
+    environments;
+    files;
+    maxActiveSessionsPerWorkspace;
+    egressCapability;
+    vaults;
+    skills;
+    maxFileResources;
+    maxMountedBytes;
+    runtime;
+    startupSnapshotDeleteSweep;
+    startupSnapshotCreateRollbackSweep;
+    startedAt = new Date().toISOString();
+    deleteSessionRows;
+    assertDeletable;
+    idempotencyLedger;
+    createSessionRowsWithIdempotency;
+    pendingSnapshotCleanupRetryDelayMs;
+    pendingSnapshotCleanupMaxAttempts;
+    onAdmissionRejected;
+    modelAvailability;
+    pendingSessionCreates = new Map();
+    pendingSnapshotDeleteRetryTimers = new Map();
+    pendingSnapshotCreateRollbackRetryTimers = new Map();
+    constructor(store, agents, environments, files, opts) {
+        this.store = store;
+        this.agents = agents;
+        this.environments = environments;
+        this.files = files;
+        if (opts.assertDeletable === undefined) {
+            throw new Error("DefaultSessionService requires assertDeletable for safe session deletion");
+        }
+        this.assertDeletable = opts.assertDeletable;
+        this.maxActiveSessionsPerWorkspace = opts.maxActiveSessionsPerWorkspace;
+        this.onAdmissionRejected = opts.onAdmissionRejected;
+        this.modelAvailability = opts.modelAvailability;
+        this.maxFileResources = opts.maxFileResources ?? MAX_SESSION_FILE_RESOURCES;
+        this.maxMountedBytes = opts.maxMountedBytes ?? MAX_SESSION_MOUNTED_BYTES;
+        this.egressCapability = opts.egressCapability;
+        this.vaults = opts.vaults;
+        this.skills = opts.skills;
+        this.runtime = opts.runtime;
+        this.deleteSessionRows = opts.deleteSessionRows;
+        this.idempotencyLedger = opts.idempotencyLedger;
+        this.createSessionRowsWithIdempotency = opts.createSessionRowsWithIdempotency;
+        if (this.idempotencyLedger && !this.createSessionRowsWithIdempotency) {
+            throw new Error("DefaultSessionService requires createSessionRowsWithIdempotency when idempotencyLedger is configured");
+        }
+        this.pendingSnapshotCleanupRetryDelayMs =
+            opts.pendingSnapshotCleanupRetryDelayMs ??
+                DEFAULT_PENDING_SNAPSHOT_CLEANUP_RETRY_DELAY_MS;
+        this.pendingSnapshotCleanupMaxAttempts =
+            opts.pendingSnapshotCleanupMaxAttempts ??
+                DEFAULT_PENDING_SNAPSHOT_CLEANUP_MAX_ATTEMPTS;
+        if (this.pendingSnapshotCleanupMaxAttempts < 1) {
+            throw invalidRequest("pendingSnapshotCleanupMaxAttempts must be at least 1");
+        }
+        this.startupSnapshotDeleteSweep = this.sweepPendingInternalSnapshotDeletes().catch((error) => {
+            log.warn("snapshot_delete_startup_sweep_failed", { error });
+        });
+        this.startupSnapshotCreateRollbackSweep =
+            this.sweepPendingInternalSnapshotCreateRollbacks({
+                createdBefore: this.startedAt,
+            }).catch((error) => {
+                log.warn("snapshot_create_rollback_startup_sweep_failed", { error });
+            });
+    }
+    async create(workspaceId, input) {
+        return this.createInternal(workspaceId, input);
+    }
+    async createIdempotent(workspaceId, input, idempotency, opts = {}) {
+        if (!this.idempotencyLedger) {
+            return { status: 200, body: await this.createInternal(workspaceId, input) };
+        }
+        const reservation = this.idempotencyLedger.reserveIdempotencyKey({
+            ...idempotency,
+            workspaceId,
+            ...reserveWindow(),
+        });
+        if (reservation.kind === "replay") {
+            return {
+                status: reservation.responseStatus,
+                body: reservation.responseBody,
+            };
+        }
+        if (reservation.kind === "fingerprint_mismatch") {
+            throw idempotencyMismatchError();
+        }
+        if (reservation.kind === "in_progress") {
+            return idempotencyConflictResponse(opts.requestId);
+        }
+        try {
+            const session = await this.createInternal(workspaceId, input, {
+                idempotency,
+            });
+            return { status: 200, body: session };
+        }
+        catch (error) {
+            if (shouldReleaseIdempotencyReservation(error)) {
+                this.idempotencyLedger.releaseIdempotencyReservation({
+                    ...idempotency,
+                    workspaceId,
+                });
+                throw unwrapIdempotentCreateError(error);
+            }
+            if (error instanceof ApiError && error.status < 500) {
+                const body = toApiErrorBody(error, opts.requestId);
+                this.idempotencyLedger.completeIdempotency(idempotencyCompletion(workspaceId, idempotency, {
+                    status: error.status,
+                    body,
+                }));
+                return { status: error.status, body };
+            }
+            throw error;
+        }
+    }
+    async createInternal(workspaceId, input, opts = {}) {
+        // 0113 D9: reserve before the async file-resource preparation below, not
+        // just before the row insert. Counting rows alone lets N concurrent
+        // creates with resources all pass the cap while none has inserted yet;
+        // the in-flight reservation closes that window and bounds the expensive
+        // prep itself.
+        const release = this.reserveSessionCreateSlot(workspaceId);
+        try {
+            return await this.createInternalReserved(workspaceId, input, opts);
+        }
+        finally {
+            release();
+        }
+    }
+    reserveSessionCreateSlot(workspaceId) {
+        const cap = this.maxActiveSessionsPerWorkspace;
+        if (cap === undefined)
+            return () => { };
+        const pending = this.pendingSessionCreates.get(workspaceId) ?? 0;
+        if (this.store.countActive(workspaceId) + pending >= cap) {
+            this.onAdmissionRejected?.();
+            throw rateLimited("Concurrent active session limit reached for this workspace; archive or delete sessions, or retry later");
+        }
+        this.pendingSessionCreates.set(workspaceId, pending + 1);
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            const current = this.pendingSessionCreates.get(workspaceId) ?? 1;
+            if (current <= 1)
+                this.pendingSessionCreates.delete(workspaceId);
+            else
+                this.pendingSessionCreates.set(workspaceId, current - 1);
+        };
+    }
+    // Fail-closed egress gate (plan 0117e-3, the slice's key safety property):
+    // every present networking shape is parsed before any file/skill/runtime
+    // preparation. Unsupported hosted networking and malformed legacy rows must
+    // not silently turn into a --network none session.
+    assertEgressHonorable(environment) {
+        let policy;
+        try {
+            policy = parseNetworkingConfig(environment.config);
+        }
+        catch (error) {
+            if (error instanceof EgressPolicyError) {
+                throw invalidRequest(`Environment ${environment.id} has an invalid networking config: ${error.message}`);
+            }
+            throw error;
+        }
+        if (policy === undefined)
+            return;
+        if (this.egressCapability?.canHonorNetworking !== true) {
+            throw invalidRequest(`Environment ${environment.id} grants network egress, but this deployment cannot honor it ` +
+                "(requires OMA_SANDBOX_PROVIDER=docker-local with OMA_ENABLE_EGRESS=true and OMA_EGRESS_SIDECAR_IMAGE)");
+        }
+        if (policy.credentials.length > 0 && !this.egressCapability.hasSecretsStore) {
+            throw invalidRequest(`Environment ${environment.id} grants credentials, but this deployment has no secrets store ` +
+                "(set OMA_MASTER_KEY or OMA_MASTER_KEY_FILE)");
+        }
+    }
+    requireActiveEnvironment(workspaceId, environmentId) {
+        const environment = this.environments.retrieveAny(workspaceId, environmentId);
+        if (!environment) {
+            throw invalidRequest(`Environment ${environmentId} not found`);
+        }
+        if (environment.archived_at !== null) {
+            throw invalidRequest(`Environment ${environmentId} is archived.`);
+        }
+        return environment;
+    }
+    async createInternalReserved(workspaceId, input, opts = {}) {
+        const req = parseCreateSession(input);
+        const agentRef = parseAgentRef(req.agent);
+        const owner = this.agents.retrieveAny(workspaceId, agentRef.id);
+        if (!owner) {
+            throw invalidRequest(`Agent ${agentRef.id} not found`);
+        }
+        if (owner.archived_at !== null) {
+            throw invalidRequest(`agent ${agentRef.id} is archived and cannot be used to create a session`);
+        }
+        const agent = agentRef.version === undefined
+            ? owner
+            : this.agents.retrieveVersion(workspaceId, agentRef.id, agentRef.version);
+        if (!agent) {
+            throw notFound(`agent.version: ${agentRef.version} not found`);
+        }
+        this.modelAvailability?.assertReady(agent.model);
+        if (agent.skills.length > 0) {
+            const read = resolveBuiltinToolAccessForAgent(agent, "read");
+            if (!read.enabled || read.permission === "deny") {
+                throw invalidRequest("Missing required tool: skills require the read tool to be usable (enabled and not always_deny) on the session's `agent_toolset`");
+            }
+            for (const attachment of agent.skills) {
+                const version = attachment.version ?? "latest";
+                if (!this.skills?.getVersion(workspaceId, attachment.skill_id, version)) {
+                    throw invalidRequest(`Could not resolve one or more skills: skill "${attachment.skill_id}" version "${version}" not found`);
+                }
+            }
+        }
+        const environment = this.requireActiveEnvironment(workspaceId, req.environment_id);
+        this.assertVaultsUsable(workspaceId, req.vault_ids ?? []);
+        this.assertEgressHonorable(environment);
+        const now = new Date().toISOString();
+        const sessionId = newSessionId();
+        let externalSideEffectsStarted = false;
+        const preparedFiles = await this.prepareFileResources(workspaceId, sessionId, req.resources ?? [], now, {
+            idempotency: opts.idempotency,
+            onExternalSideEffect: () => {
+                externalSideEffectsStarted = true;
+            },
+        });
+        const preparedSkills = await this.prepareSkillResources(workspaceId, sessionId, agent.skills, now, preparedFiles.totalBytes, {
+            idempotency: opts.idempotency,
+            onExternalSideEffect: () => { externalSideEffectsStarted = true; },
+        });
+        const resources = preparedFiles.resources;
+        const snapshots = [...preparedFiles.snapshots, ...preparedSkills.snapshots];
+        const mounts = [...preparedFiles.mounts, ...preparedSkills.mounts];
+        const row = {
+            id: sessionId,
+            workspace_id: workspaceId,
+            type: "session",
+            agent: {
+                type: "agent",
+                id: agent.id,
+                version: agent.version,
+            },
+            environment_id: environment.id,
+            vault_ids: req.vault_ids ?? [],
+            status: "idle",
+            title: req.title ?? null,
+            metadata: req.metadata ?? {},
+            created_at: now,
+            updated_at: now,
+            archived_at: null,
+            usage: null,
+            resources,
+        };
+        const sessionSnapshots = snapshots.map((snapshot) => ({
+            ...snapshot,
+            session_id: row.id,
+        }));
+        let runtimePrepared = false;
+        try {
+            if (mounts.length > 0 && this.runtime?.prepareSession) {
+                externalSideEffectsStarted = true;
+                await this.withIdempotencyHeartbeat(workspaceId, opts.idempotency, Promise.resolve(this.runtime.prepareSession(workspaceId, row.id, {
+                    fileMounts: mounts,
+                    skills: preparedSkills.skills.map(({ name, description }) => ({ name, description })),
+                    environmentId: row.environment_id,
+                    vaultIds: row.vault_ids,
+                    agent: row.agent,
+                })));
+                runtimePrepared = true;
+            }
+            // File and runtime preparation may await. Re-read immediately before the
+            // synchronous durable write so an archive/delete that completed while
+            // preparation was in flight cannot leave an orphaned session reference.
+            this.requireActiveEnvironment(workspaceId, row.environment_id);
+            const record = {
+                row,
+                snapshots: sessionSnapshots,
+                skillSnapshots: preparedSkills.skills.map((skill) => ({ ...skill, session_id: row.id })),
+            };
+            if (opts.idempotency && this.idempotencyLedger) {
+                const response = toManagedSession(row);
+                const completion = idempotencyCompletion(workspaceId, opts.idempotency, { status: 200, body: response }, { type: "session", id: row.id });
+                const created = this.createSessionRowsWithIdempotency(record, {
+                    complete: () => {
+                        this.idempotencyLedger?.completeIdempotencyInTransaction(completion);
+                    },
+                });
+                return toManagedSession(created);
+            }
+            return toManagedSession(this.store.create(record));
+        }
+        catch (error) {
+            if (runtimePrepared || mounts.length > 0) {
+                await this.closeRuntimeBestEffort(workspaceId, row.id);
+            }
+            await this.sweepPendingInternalSnapshotCreateRollbacks(workspaceId, row.id).catch((cleanupError) => {
+                log.warn("snapshot_create_rollback_sweep_failed", { error: cleanupError });
+            });
+            if (isUnsupportedFileResourceRuntime(error)) {
+                const unsupported = invalidRequest("Session file resources are not supported by the configured runtime.");
+                if (opts.idempotency) {
+                    throw new ReleaseIdempotencyReservationError(unsupported);
+                }
+                throw unsupported;
+            }
+            if (opts.idempotency && externalSideEffectsStarted) {
+                throw new ReleaseIdempotencyReservationError(error);
+            }
+            throw error;
+        }
+    }
+    assertVaultsUsable(workspaceId, vaultIds) {
+        if (vaultIds.length === 0)
+            return;
+        if (!this.vaults) {
+            throw invalidRequest("Vaults are not supported by this server.");
+        }
+        this.vaults.assertVaultsUsable(workspaceId, vaultIds);
+    }
+    retrieve(workspaceId, sessionId) {
+        const row = this.store.retrieveAny(workspaceId, sessionId);
+        if (!row) {
+            throw notFound(`Session ${sessionId} not found`);
+        }
+        return toManagedSession(row);
+    }
+    async delete(workspaceId, sessionId) {
+        // Domain-owned liveness invariant: reject deleting a running session before
+        // any row/file mutation, so no caller (route or internal) can tear down a
+        // live runtime. Synchronous, so it runs in the same tick as the row removal.
+        this.assertDeletable(workspaceId, sessionId);
+        const result = this.deleteSessionRows?.(workspaceId, sessionId) ??
+            this.deleteSessionRowsWithDefaultStore(workspaceId, sessionId);
+        if (!result) {
+            throw notFound(`Session ${sessionId} not found`);
+        }
+        // Load-bearing, not dead code. The delete-vs-live-indexing race is now closed
+        // by assertSessionDeletable (a running turn can't be deleted), but this sweep
+        // still covers process-restart / abandoned-turn recovery, where a session row
+        // can carry orphaned output/snapshot rows with no live task. Do not remove.
+        await this.sweepPendingInternalSnapshotDeletes(workspaceId, sessionId).catch((error) => {
+            log.warn("snapshot_delete_sweep_failed", { error });
+        });
+        await this.cleanupDeletedSessionOutputs(workspaceId, sessionId, result.deletedSessionOutputFiles);
+        return { id: result.row.id, type: "session_deleted" };
+    }
+    deleteSessionRowsWithDefaultStore(workspaceId, sessionId) {
+        const row = this.store.delete(workspaceId, sessionId);
+        return row ? { row } : undefined;
+    }
+    async cleanupDeletedSessionOutputs(workspaceId, sessionId, deletedFiles) {
+        try {
+            if (deletedFiles !== undefined && hasRecordObjectDelete(this.files)) {
+                await this.files.deleteObjectsForRecords(deletedFiles);
+                return;
+            }
+            await this.files?.deleteSessionOutputs(workspaceId, sessionId);
+        }
+        catch (error) {
+            log.warn("session_output_cleanup_failed", {
+                workspaceId,
+                sessionId,
+                error,
+            });
+        }
+    }
+    async sweepPendingInternalSnapshotDeletes(workspaceId, sessionId) {
+        await this.sweepPendingSnapshotCleanup({
+            workspaceId,
+            sessionId,
+            listWorkspaces: () => this.store.listPendingInternalSnapshotDeleteWorkspaces(),
+            getRows: (pendingWorkspaceId, pendingSessionId) => this.store.getPendingInternalSnapshotDeletes(pendingWorkspaceId, pendingSessionId),
+            clearRow: (rowWorkspaceId, rowSessionId, resourceId) => this.store.clearPendingInternalSnapshotDelete(rowWorkspaceId, rowSessionId, resourceId),
+            recordAttempt: (rowWorkspaceId, rowSessionId, resourceId, attemptedAt, error) => this.store.recordPendingInternalSnapshotDeleteAttempt(rowWorkspaceId, rowSessionId, resourceId, attemptedAt, error),
+            scheduleRetry: (rowWorkspaceId, rowSessionId) => this.schedulePendingSnapshotCleanupRetry({
+                workspaceId: rowWorkspaceId,
+                sessionId: rowSessionId,
+                timers: this.pendingSnapshotDeleteRetryTimers,
+                retryLabel: "delete",
+                sweep: () => this.sweepPendingInternalSnapshotDeletes(rowWorkspaceId, rowSessionId),
+            }),
+            retryLabel: "delete",
+        });
+    }
+    async drainStartupSnapshotSweepsForTest() {
+        await this.startupSnapshotDeleteSweep;
+        await this.startupSnapshotCreateRollbackSweep;
+    }
+    async sweepPendingInternalSnapshotCreateRollbacks(workspaceIdOrOpts, sessionId) {
+        const opts = typeof workspaceIdOrOpts === "object"
+            ? workspaceIdOrOpts
+            : { workspaceId: workspaceIdOrOpts, sessionId };
+        await this.sweepPendingSnapshotCleanup({
+            workspaceId: opts.workspaceId,
+            sessionId: opts.sessionId,
+            createdBefore: opts.createdBefore,
+            listWorkspaces: () => this.store.listPendingInternalSnapshotCreateRollbackWorkspaces(),
+            getRows: (pendingWorkspaceId, pendingSessionId) => this.store.getPendingInternalSnapshotCreateRollbacks(pendingWorkspaceId, pendingSessionId),
+            clearRow: (rowWorkspaceId, rowSessionId, resourceId) => this.store.clearPendingInternalSnapshotCreateRollback(rowWorkspaceId, rowSessionId, resourceId),
+            recordAttempt: (rowWorkspaceId, rowSessionId, resourceId, attemptedAt, error) => this.store.recordPendingInternalSnapshotCreateRollbackAttempt(rowWorkspaceId, rowSessionId, resourceId, attemptedAt, error),
+            scheduleRetry: (rowWorkspaceId, rowSessionId) => this.schedulePendingSnapshotCleanupRetry({
+                workspaceId: rowWorkspaceId,
+                sessionId: rowSessionId,
+                timers: this.pendingSnapshotCreateRollbackRetryTimers,
+                retryLabel: "create rollback",
+                sweep: () => this.sweepPendingInternalSnapshotCreateRollbacks({
+                    workspaceId: rowWorkspaceId,
+                    sessionId: rowSessionId,
+                }),
+            }),
+            retryLabel: "create rollback",
+        });
+    }
+    async sweepPendingSnapshotCleanup(opts) {
+        if (!this.files)
+            return;
+        const workspaces = opts.workspaceId === undefined ? opts.listWorkspaces() : [opts.workspaceId];
+        for (const pendingWorkspaceId of workspaces) {
+            const pending = opts.getRows(pendingWorkspaceId, opts.workspaceId === undefined ? undefined : opts.sessionId);
+            for (const row of pending) {
+                if (opts.createdBefore !== undefined && row.created_at >= opts.createdBefore) {
+                    continue;
+                }
+                if (row.attempt_count >= this.pendingSnapshotCleanupMaxAttempts) {
+                    continue;
+                }
+                try {
+                    await this.files.deleteInternalSnapshot(pendingWorkspaceId, row.snapshot_file_id);
+                    opts.clearRow(pendingWorkspaceId, row.session_id, row.resource_id);
+                }
+                catch (error) {
+                    const message = errorMessage(error);
+                    const attemptedAt = new Date().toISOString();
+                    const nextAttemptCount = row.attempt_count + 1;
+                    opts.recordAttempt(pendingWorkspaceId, row.session_id, row.resource_id, attemptedAt, message);
+                    const context = {
+                        workspaceId: pendingWorkspaceId,
+                        sessionId: row.session_id,
+                        resourceId: row.resource_id,
+                        snapshotFileId: row.snapshot_file_id,
+                        retryLabel: opts.retryLabel,
+                        attemptCount: nextAttemptCount,
+                        error: message,
+                    };
+                    if (nextAttemptCount >= this.pendingSnapshotCleanupMaxAttempts) {
+                        this.warnPendingSnapshotCleanupRetryCap(context);
+                        continue;
+                    }
+                    opts.scheduleRetry(pendingWorkspaceId, row.session_id);
+                }
+            }
+        }
+    }
+    schedulePendingSnapshotCleanupRetry(opts) {
+        const key = JSON.stringify([opts.workspaceId, opts.sessionId]);
+        if (opts.timers.has(key))
+            return;
+        const timer = setTimeout(() => {
+            opts.timers.delete(key);
+            void opts.sweep().catch((error) => {
+                log.warn("snapshot_cleanup_retry_failed", {
+                    retryLabel: opts.retryLabel,
+                    error,
+                });
+                this.schedulePendingSnapshotCleanupRetry(opts);
+            });
+        }, this.pendingSnapshotCleanupRetryDelayMs);
+        timer.unref?.();
+        opts.timers.set(key, timer);
+    }
+    warnPendingSnapshotCleanupRetryCap(context) {
+        log.warn("snapshot_cleanup_retry_cap_reached", {
+            retryLabel: context.retryLabel,
+            workspaceId: context.workspaceId,
+            sessionId: context.sessionId,
+            resourceId: context.resourceId,
+            snapshotFileId: context.snapshotFileId,
+            attemptCount: context.attemptCount,
+            maxAttempts: this.pendingSnapshotCleanupMaxAttempts,
+            error: context.error,
+        });
+    }
+    list(workspaceId, opts = {}) {
+        const page = this.store.list(workspaceId, opts);
+        return {
+            data: page.data.map(toManagedSession),
+            next_page: page.next_page,
+            prev_page: page.prev_page,
+        };
+    }
+    async prepareFileResources(workspaceId, sessionId, resources, now, opts = {}) {
+        if (resources.length === 0) {
+            return { resources: [], snapshots: [], mounts: [], totalBytes: 0 };
+        }
+        if (!this.files) {
+            throw invalidRequest("File resources are not supported by this server.");
+        }
+        if (resources.length > this.maxFileResources) {
+            throw invalidRequest(`Session file resources exceed the ${this.maxFileResources} file limit`);
+        }
+        const normalized = normalizeSessionFileResources(resources.map((resource) => ({
+            fileId: resource.file_id,
+            mountPath: resource.mount_path,
+        })));
+        const prepared = [];
+        let totalBytes = 0;
+        for (const resource of normalized) {
+            const source = await this.withIdempotencyHeartbeat(workspaceId, opts.idempotency, this.files.retrieveMetadata(workspaceId, resource.fileId));
+            if (!source) {
+                throw invalidRequest(`File ${resource.fileId} not found`);
+            }
+            const stream = await this.withIdempotencyHeartbeat(workspaceId, opts.idempotency, this.files.openBytes(workspaceId, resource.fileId));
+            if (!stream) {
+                throw invalidRequest(`File ${resource.fileId} not found`);
+            }
+            const bytes = await this.withIdempotencyHeartbeat(workspaceId, opts.idempotency, consumeBytes(stream));
+            const sha256 = sha256Hex(bytes);
+            if (sha256 !== source.sha256) {
+                throw invalidRequest(`File ${resource.fileId} failed integrity validation`);
+            }
+            totalBytes += bytes.byteLength;
+            if (totalBytes > this.maxMountedBytes) {
+                throw invalidRequest(`Session file resources exceed the ${limitLabel(this.maxMountedBytes)} mounted byte limit`);
+            }
+            prepared.push({
+                source,
+                bytes,
+                sha256,
+                resourceId: newSessionResourceId(),
+                mountPath: resource.mountPath,
+            });
+        }
+        const createdSnapshots = [];
+        try {
+            for (const item of prepared) {
+                const snapshotFileId = newFileId();
+                const rollbackRow = {
+                    workspace_id: workspaceId,
+                    session_id: sessionId,
+                    resource_id: item.resourceId,
+                    file_id: item.source.metadata.id,
+                    mount_path: item.mountPath,
+                    snapshot_file_id: snapshotFileId,
+                    sha256: item.sha256,
+                    size_bytes: item.bytes.byteLength,
+                    kind: "upload",
+                    skill_snapshot_id: null,
+                };
+                this.store.recordPendingInternalSnapshotCreateRollback(rollbackRow, now);
+                opts.onExternalSideEffect?.();
+                const snapshot = await this.withIdempotencyHeartbeat(workspaceId, opts.idempotency, this.files.createInternalSnapshot(workspaceId, {
+                    fileId: snapshotFileId,
+                    filename: item.source.metadata.filename,
+                    mimeType: item.source.metadata.mime_type,
+                    scopeId: item.resourceId,
+                    body: item.bytes,
+                }));
+                if (snapshot.metadata.id !== snapshotFileId) {
+                    throw new Error(`FileStorage returned internal snapshot id ${snapshot.metadata.id}; expected ${snapshotFileId}`);
+                }
+                createdSnapshots.push({
+                    workspace_id: workspaceId,
+                    resource_id: item.resourceId,
+                    file_id: item.source.metadata.id,
+                    mount_path: item.mountPath,
+                    snapshot_file_id: snapshot.metadata.id,
+                    sha256: snapshot.sha256,
+                    size_bytes: snapshot.metadata.size_bytes,
+                    kind: "upload",
+                    skill_snapshot_id: null,
+                });
+            }
+        }
+        catch (error) {
+            await this.sweepPendingInternalSnapshotCreateRollbacks(workspaceId, sessionId).catch((cleanupError) => {
+                log.warn("snapshot_create_rollback_sweep_failed", { error: cleanupError });
+            });
+            throw error;
+        }
+        return {
+            resources: prepared.map((item) => ({
+                id: item.resourceId,
+                type: "file",
+                file_id: item.source.metadata.id,
+                mount_path: item.mountPath,
+                created_at: now,
+                updated_at: now,
+            })),
+            snapshots: createdSnapshots,
+            mounts: createdSnapshots.map((snapshot, index) => ({
+                kind: "upload",
+                mountPath: snapshot.mount_path,
+                snapshotFileId: snapshot.snapshot_file_id,
+                sha256: snapshot.sha256,
+                sizeBytes: snapshot.size_bytes,
+                bytes: prepared[index].bytes,
+            })),
+            totalBytes,
+        };
+    }
+    async prepareSkillResources(workspaceId, sessionId, attachments, now, existingBytes, opts) {
+        if (attachments.length === 0)
+            return { skills: [], snapshots: [], mounts: [] };
+        if (!this.skills || !this.files)
+            throw invalidRequest("Skills are not supported by this server.");
+        const skills = [];
+        const snapshots = [];
+        const mounts = [];
+        let totalBytes = existingBytes;
+        try {
+            for (const attachment of attachments) {
+                const requested = attachment.version ?? "latest";
+                const version = this.skills.getVersion(workspaceId, attachment.skill_id, requested);
+                if (!version)
+                    throw invalidRequest(`Could not resolve one or more skills: skill "${attachment.skill_id}" version "${requested}" not found`);
+                const skillSnapshotId = newSessionSkillSnapshotId();
+                skills.push({ workspace_id: workspaceId, skill_snapshot_id: skillSnapshotId, skill_id: attachment.skill_id, version: version.version, name: version.name, description: version.description });
+                for (const file of this.skills.getVersionFiles(workspaceId, attachment.skill_id, version.version)) {
+                    const bytes = this.skills.openContent(workspaceId, attachment.skill_id, version.version, file.path);
+                    if (!bytes || sha256Hex(bytes) !== file.sha256)
+                        throw invalidRequest(`Skill ${attachment.skill_id} failed integrity validation`);
+                    totalBytes += bytes.byteLength;
+                    if (totalBytes > this.maxMountedBytes)
+                        throw invalidRequest(`Session resources exceed the ${limitLabel(this.maxMountedBytes)} mounted byte limit`);
+                    const resourceId = newSessionResourceId();
+                    const snapshotFileId = newFileId();
+                    const mountPath = `/workspace/skills/${file.path}`;
+                    const rollbackRow = { workspace_id: workspaceId, session_id: sessionId, resource_id: resourceId, file_id: `${attachment.skill_id}:${version.version}:${file.path}`, mount_path: mountPath, snapshot_file_id: snapshotFileId, sha256: file.sha256, size_bytes: bytes.byteLength, kind: "skill", skill_snapshot_id: skillSnapshotId };
+                    this.store.recordPendingInternalSnapshotCreateRollback(rollbackRow, now);
+                    opts.onExternalSideEffect?.();
+                    const snapshot = await this.withIdempotencyHeartbeat(workspaceId, opts.idempotency, this.files.createInternalSnapshot(workspaceId, { fileId: snapshotFileId, filename: file.path.split("/").at(-1) ?? "skill-file", mimeType: "application/octet-stream", scopeId: resourceId, body: bytes }));
+                    const row = { workspace_id: workspaceId, resource_id: resourceId, file_id: rollbackRow.file_id, mount_path: mountPath, snapshot_file_id: snapshot.metadata.id, sha256: snapshot.sha256, size_bytes: snapshot.metadata.size_bytes, kind: "skill", skill_snapshot_id: skillSnapshotId };
+                    snapshots.push(row);
+                    mounts.push({ kind: "skill", mountPath, snapshotFileId: row.snapshot_file_id, sha256: row.sha256, sizeBytes: row.size_bytes, bytes });
+                }
+            }
+            return { skills, snapshots, mounts };
+        }
+        catch (error) {
+            await this.sweepPendingInternalSnapshotCreateRollbacks(workspaceId, sessionId).catch((cleanupError) => log.warn("snapshot_create_rollback_sweep_failed", { error: cleanupError }));
+            throw error;
+        }
+    }
+    async closeRuntimeBestEffort(workspaceId, sessionId) {
+        try {
+            await this.runtime?.closeSession?.(workspaceId, sessionId);
+        }
+        catch {
+            // The row has not committed yet; snapshot cleanup below is the
+            // authoritative control-plane rollback path for this create.
+        }
+    }
+    async withIdempotencyHeartbeat(workspaceId, idempotency, operation) {
+        return withIdempotencyReservationHeartbeat(this.idempotencyLedger, idempotency === undefined ? undefined : { ...idempotency, workspaceId }, operation);
+    }
+}
+class ReleaseIdempotencyReservationError extends Error {
+    inner;
+    constructor(inner) {
+        super(errorMessage(inner));
+        this.inner = inner;
+        this.name = "ReleaseIdempotencyReservationError";
+    }
+}
+function shouldReleaseIdempotencyReservation(error) {
+    if (error instanceof ReleaseIdempotencyReservationError)
+        return true;
+    // 429 admission rejections are transient: completing the key would replay
+    // the 429 forever, even after capacity frees. Release so the same-key retry
+    // re-executes (0113 D9).
+    if (error instanceof ApiError && error.status === 429)
+        return true;
+    if (error instanceof ApiError && error.status < 500)
+        return false;
+    return true;
+}
+function unwrapIdempotentCreateError(error) {
+    return error instanceof ReleaseIdempotencyReservationError
+        ? error.inner
+        : error;
+}
+async function consumeBytes(stream) {
+    const chunks = [];
+    let totalLength = 0;
+    for await (const chunk of stream) {
+        chunks.push(chunk);
+        totalLength += chunk.byteLength;
+    }
+    const out = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return out;
+}
+function sha256Hex(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+function limitLabel(bytes) {
+    if (bytes % (1024 * 1024) === 0)
+        return `${bytes / (1024 * 1024)} MiB`;
+    return `${bytes} bytes`;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function hasRecordObjectDelete(files) {
+    return typeof files?.deleteObjectsForRecords === "function";
+}
+function isUnsupportedFileResourceRuntime(error) {
+    return error instanceof RuntimeUnsupportedSessionFileResourcesError;
+}