nexus-agentd 0.2.5 → 0.3.0

package/dist/session.js

@@ -1,13 +1,16 @@
 import { randomUUID } from 'node:crypto';
-import { open, realpath } from 'node:fs/promises';
-import { basename, extname, isAbsolute, relative, resolve, sep } from 'node:path';
+import { realpath } from 'node:fs/promises';
+import { extname } from 'node:path';
 import { AcpProcessRuntime } from './acp/runtime.js';
-import { A2AClientRuntime, probeA2AAgent } from './a2a/runtime.js';
+import { A2AClientRuntime } from './a2a/runtime.js';
 import { SessionEventLog } from './events.js';
+import { AdminRunManager } from './session/admin-runs.js';
+import { SessionAdmission } from './session/admission.js';
+import { SessionReadiness } from './session/readiness.js';
+import { ContainedReadError, readContainedFile } from './workspace.js';
 const MAX_SESSION_ARTIFACTS = 64;
 const MAX_ARTIFACT_BASE64_CHARS = 16 * 1024 * 1024;
 const MAX_SESSION_BASE64_CHARS = 32 * 1024 * 1024;
-const READINESS_CACHE_MS = 20_000;
 const MAX_INPUT_ATTACHMENTS = 16;
 const MAX_INPUT_ATTACHMENT_BYTES = 16 * 1024 * 1024;
 const MAX_SESSION_INPUT_BYTES = 32 * 1024 * 1024;
@@ -35,7 +38,9 @@ export class ManagedSession {
     artifacts = [];
     inputAttachments = new Map();
     runtime;
-    constructor(agentId, protocol, workspace, ownerKeyId, maxEvents, maxOutputChars, agentName, runStore, instanceId = randomUUID()) {
+    artifactStore;
+    onRunUpdate;
+    constructor(agentId, protocol, workspace, ownerKeyId, maxEvents, maxOutputChars, agentName, runStore, instanceId = randomUUID(), artifactStore, onRunUpdate) {
         this.agentId = agentId;
         this.protocol = protocol;
         this.workspace = workspace;
@@ -44,12 +49,17 @@ export class ManagedSession {
         this.agentName = agentName;
         this.runStore = runStore;
         this.instanceId = instanceId;
+        this.artifactStore = artifactStore || runStore;
+        this.onRunUpdate = onRunUpdate;
         this.events = new SessionEventLog(this.id, maxEvents);
         this.events.append('session_state', { state: this.state, protocol });
     }
     attach(runtime) {
         this.runtime = runtime;
     }
+    runtimeAvailable() {
+        return Boolean(this.runtime && this.runtime.isAvailable?.() !== false);
+    }
     setProtocolSessionId(id) {
         this.protocolSessionId = id;
         this.updatedAt = Date.now();
@@ -193,40 +203,21 @@ export class ManagedSession {
         return artifacts;
     }
     async publishSingleFile(requestedPath) {
-        let handle;
         try {
             const workspaceRoot = await realpath(this.workspace);
-            const unresolved = resolve(workspaceRoot, requestedPath);
-            const target = await realpath(unresolved);
-            assertWorkspacePath(workspaceRoot, target);
-            handle = await open(target, 'r');
-            // Resolve again after opening so a swapped symlink cannot silently
-            // redirect a publish request outside the configured workspace.
-            const verifiedTarget = await realpath(unresolved);
-            assertWorkspacePath(workspaceRoot, verifiedTarget);
-            if (verifiedTarget !== target) {
-                throw new SessionRequestError(409, 'Published file changed while it was being opened');
-            }
-            const stats = await handle.stat();
-            if (!stats.isFile()) {
-                throw new SessionRequestError(400, 'Only regular files can be published');
-            }
-            if (stats.size > MAX_PUBLISHED_FILE_BYTES) {
-                throw new SessionRequestError(413, `Published file exceeds the ${MAX_PUBLISHED_FILE_BYTES} byte limit`);
-            }
-            const bytes = await handle.readFile();
-            const filename = basename(verifiedTarget);
-            const workspacePath = relative(workspaceRoot, verifiedTarget).split(sep).join('/');
+            const file = await readContainedFile([workspaceRoot], requestedPath, {
+                maxBytes: MAX_PUBLISHED_FILE_BYTES
+            });
             const artifact = {
                 id: `published:${randomUUID()}`,
-                name: filename,
-                filename,
-                mediaType: mediaTypeForPath(filename),
-                bytesBase64: bytes.toString('base64'),
+                name: file.filename,
+                filename: file.filename,
+                mediaType: mediaTypeForPath(file.filename),
+                bytesBase64: file.bytes.toString('base64'),
                 metadata: {
                     source: 'workspace_publish',
-                    path: workspacePath,
-                    size: bytes.length
+                    path: file.relative,
+                    size: file.size
                 }
             };
             this.addArtifact(artifact);
@@ -236,6 +227,8 @@ export class ManagedSession {
         catch (error) {
             if (error instanceof SessionRequestError)
                 throw error;
+            if (error instanceof ContainedReadError)
+                throw publishFailure(error);
             const code = error?.code;
             if (code === 'ENOENT') {
                 throw new SessionRequestError(404, 'Published file was not found');
@@ -245,9 +238,6 @@ export class ManagedSession {
             }
             throw error;
         }
-        finally {
-            await handle?.close();
-        }
     }
     setPending(request) {
         this.completion = undefined;
@@ -296,8 +286,8 @@ export class ManagedSession {
         this.updatedAt = Date.now();
         return attachmentView(attachment);
     }
-    async message(message, attachmentIds = []) {
-        if (!this.runtime)
+    async message(message, attachmentIds = [], retryOfRunId) {
+        if (!this.runtime || this.runtime.isAvailable?.() === false)
             throw new SessionRequestError(409, 'Agent runtime is unavailable');
         const attachments = this.inputAttachmentsFor(attachmentIds);
         if (this.pendingRequest) {
@@ -324,15 +314,17 @@ export class ManagedSession {
             protocolSessionId: this.protocolSessionId,
             ownerKeyId: this.ownerKeyId,
             task: message,
-            inputAttachmentCount: attachments.length
+            inputAttachmentCount: attachments.length,
+            ...(retryOfRunId ? { retryOfRunId } : {})
         }).id;
+        this.setState('running');
         void this.runtime.prompt(message, attachments).catch((error) => {
             if (this.state !== 'canceled')
                 this.setState('failed', errorMessage(error));
         });
     }
     async resolvePending(response, attachmentIds = []) {
-        if (!this.runtime) {
+        if (!this.runtime || this.runtime.isAvailable?.() === false) {
             throw new SessionRequestError(409, 'Agent runtime is unavailable');
         }
         const pending = this.pendingRequest;
@@ -349,11 +341,31 @@ export class ManagedSession {
         await this.runtime.respondPending(response, attachments);
     }
     async cancel() {
-        await this.runtime?.cancel();
+        const runtime = this.runtime;
+        this.runtime = undefined;
+        this.clearPending();
+        this.setState('canceled');
+        try {
+            await runtime?.cancel();
+        }
+        finally {
+            try {
+                await runtime?.dispose();
+            }
+            finally {
+                this.inputAttachments.clear();
+            }
+        }
     }
     async dispose() {
-        await this.runtime?.dispose();
-        this.inputAttachments.clear();
+        const runtime = this.runtime;
+        this.runtime = undefined;
+        try {
+            await runtime?.dispose();
+        }
+        finally {
+            this.inputAttachments.clear();
+        }
     }
     snapshot() {
         return {
@@ -401,6 +413,34 @@ export class ManagedSession {
             updatedAt: this.updatedAt,
             ...patch
         });
+        if (patch.artifacts && this.artifactStore?.recordArtifacts) {
+            const runId = this.currentRunId;
+            const artifacts = structuredClone(this.artifacts);
+            void Promise.resolve()
+                .then(() => this.artifactStore.recordArtifacts(runId, artifacts))
+                .catch((error) => {
+                console.error(JSON.stringify({
+                    level: 'error',
+                    event: 'artifact_snapshot_record_failed',
+                    runId,
+                    message: errorMessage(error)
+                }));
+            });
+        }
+        try {
+            this.onRunUpdate?.(this.currentRunId, this.state);
+        }
+        catch (error) {
+            // Lifecycle observers (for example quota accounting) must never
+            // turn a successful agent event into a failed protocol turn.
+            console.error(JSON.stringify({
+                level: 'error',
+                event: 'session_lifecycle_observer_failed',
+                sessionId: this.id,
+                runId: this.currentRunId,
+                message: errorMessage(error)
+            }));
+        }
     }
     inputAttachmentsFor(ids) {
         const unique = Array.from(new Set(ids));
@@ -420,18 +460,83 @@ export class SessionManager {
     sessions = new Map();
     sessionLocks = new Map();
     cleanupTimer;
-    readinessCache;
-    constructor(config, workspacePolicy, drivers, runStore) {
+    readiness;
+    admission;
+    adminRuns;
+    artifactStore;
+    lifecycleListeners = new Set();
+    constructor(config, workspacePolicy, drivers, runStore, artifactStore) {
         this.config = config;
         this.workspacePolicy = workspacePolicy;
         this.drivers = drivers;
         this.runStore = runStore;
+        this.artifactStore = artifactStore || runStore;
+        this.readiness = new SessionReadiness(config, drivers, {
+            requestError: (status, message) => new SessionRequestError(status, message)
+        });
+        this.admission = new SessionAdmission({
+            maxSessions: () => this.config.maxSessions || 64,
+            sessionCount: () => this.sessions.size,
+            sessions: () => this.sessions.values(),
+            isCurrent: (session) => this.sessions.get(session.id) === session,
+            withSessionLock: (id, operation) => this.withSessionLock(id, operation),
+            removeSession: (id) => {
+                const session = this.sessions.get(id);
+                if (!session || !this.sessions.delete(id))
+                    return;
+                this.notifyLifecycle({
+                    type: 'session_closed',
+                    sessionId: session.id,
+                    ownerKeyId: session.ownerKeyId,
+                    agentId: session.agentId
+                });
+            },
+            requestError: (status, message) => new SessionRequestError(status, message)
+        });
+        this.adminRuns = new AdminRunManager({
+            getRun: (runId) => this.getRun(runId),
+            getSession: (sessionId) => this.sessions.get(sessionId),
+            getAgent: (agentId) => this.config.agents[agentId],
+            getOwnerKeyId: (runId) => this.getRunOwnerKeyId(runId),
+            withSessionLock: (sessionId, operation) => this.withSessionLock(sessionId, operation),
+            startRetry: async (run, ownerKeyId, reservation) => {
+                const created = await this.create(run.agentId, run.workspace, ownerKeyId);
+                try {
+                    reservation?.bind(created.id);
+                    await this.message(created.id, run.task, [], run.id);
+                    const snapshot = this.get(created.id);
+                    if (!snapshot.runId) {
+                        throw new SessionRequestError(502, 'Retried task did not create a run record');
+                    }
+                    return { runId: snapshot.runId, sessionId: created.id };
+                }
+                catch (error) {
+                    try {
+                        await this.close(created.id);
+                    }
+                    catch (cleanupError) {
+                        console.error(JSON.stringify({
+                            level: 'error',
+                            event: 'retry_session_cleanup_failed',
+                            sessionId: created.id,
+                            message: errorMessage(cleanupError)
+                        }));
+                    }
+                    throw error;
+                }
+            },
+            markRetryOf: (newRunId, oldRunId) => {
+                const store = this.runStore;
+                return store?.setRetryOfRunId?.(newRunId, oldRunId);
+            },
+            requestError: (status, message) => new SessionRequestError(status, message)
+        });
     }
     reconfigure(config, workspacePolicy, drivers) {
         this.config = config;
         this.workspacePolicy = workspacePolicy;
         this.drivers = drivers;
-        this.readinessCache = undefined;
+        this.readiness.reconfigure(config, drivers);
         if (this.cleanupTimer)
             this.restartCleanup();
     }
@@ -441,81 +546,25 @@ export class SessionManager {
         this.restartCleanup();
     }
     async listAgents(agentIds, force = false) {
-        const now = Date.now();
-        if (!force && this.readinessCache && this.readinessCache.expiresAt > now) {
-            return filterAgents(this.readinessCache.agents, agentIds);
-        }
-        const agents = await Promise.all(Object.entries(this.config.agents).map(async ([id, config]) => {
-            if (config.protocol === 'a2a')
-                return probeA2AAgent(id, config);
-            if (config.enabled === false) {
-                return {
-                    id,
-                    name: config.name || id,
-                    description: config.description,
-                    protocol: 'acp',
-                    driver: config.driver,
-                    ready: false,
-                    enabled: false,
-                    workspace: this.defaultWorkspace(id),
-                    error: 'Agent is disabled',
-                    checkedAt: Date.now()
-                };
-            }
-            const driver = this.drivers.get(id);
-            if (!driver) {
-                return {
-                    id,
-                    name: config.name || id,
-                    description: config.description,
-                    protocol: 'acp',
-                    driver: config.driver,
-                    ready: false,
-                    enabled: true,
-                    workspace: this.defaultWorkspace(id),
-                    error: 'ACP driver is unavailable',
-                    checkedAt: Date.now()
-                };
-            }
-            const startedAt = Date.now();
-            try {
-                const probe = await driver.probe();
-                return {
-                    ...probe,
-                    protocol: 'acp',
-                    driver: config.driver,
-                    enabled: true,
-                    workspace: this.defaultWorkspace(id),
-                    checkedAt: Date.now(),
-                    responseMs: Date.now() - startedAt
-                };
-            }
-            catch (error) {
-                return {
-                    id,
-                    name: config.name || id,
-                    description: config.description,
-                    protocol: 'acp',
-                    driver: config.driver,
-                    ready: false,
-                    enabled: true,
-                    workspace: this.defaultWorkspace(id),
-                    error: errorMessage(error),
-                    checkedAt: Date.now(),
-                    responseMs: Date.now() - startedAt
-                };
-            }
-        }));
-        agents.sort((left, right) => left.name.localeCompare(right.name));
-        this.readinessCache = {
-            expiresAt: Date.now() + READINESS_CACHE_MS,
-            agents: structuredClone(agents)
-        };
-        return filterAgents(agents, agentIds);
+        return this.readiness.listAgents(agentIds, force);
     }
     async create(agentId, workspaceInput, ownerKeyId) {
-        await this.ensureCapacity();
-        const config = this.config.agents[agentId];
+        if (!Object.hasOwn(this.config.agents, agentId) || this.config.agents[agentId].enabled === false) {
+            throw new SessionRequestError(404, `Configured agent not found: ${agentId}`);
+        }
+        let release = () => undefined;
+        await this.withSessionLock('admission', async () => {
+            release = await this.admission.reserve();
+        });
+        try {
+            return await this.createReserved(agentId, workspaceInput, ownerKeyId, release);
+        }
+        finally {
+            release();
+        }
+    }
+    async createReserved(agentId, workspaceInput, ownerKeyId, release) {
+        const config = Object.hasOwn(this.config.agents, agentId) ? this.config.agents[agentId] : undefined;
         if (!config || config.enabled === false) {
             throw new SessionRequestError(404, `Configured agent not found: ${agentId}`);
         }
@@ -532,11 +581,27 @@ export class SessionManager {
             }
             workspace = await this.workspacePolicy.resolve(requestedWorkspace);
         }
-        const session = new ManagedSession(agentId, config.protocol === 'a2a' ? 'a2a' : 'acp', workspace, ownerKeyId, this.config.maxEventsPerSession, this.config.maxOutputChars, config.name || agentId, this.runStore, this.instanceId);
+        if (this.admission.isClosing()) {
+            throw new SessionRequestError(503, 'Gateway is shutting down');
+        }
+        const session = new ManagedSession(agentId, config.protocol === 'a2a' ? 'a2a' : 'acp', workspace, ownerKeyId, this.config.maxEventsPerSession, this.config.maxOutputChars, config.name || agentId, this.runStore, this.instanceId, this.artifactStore, (runId, state) => this.notifyLifecycle({
+            type: 'run_updated',
+            sessionId: session.id,
+            runId,
+            ownerKeyId: session.ownerKeyId,
+            state
+        }));
         const runtime = config.protocol === 'a2a'
             ? new A2AClientRuntime(config, session, this.config.promptTimeoutMs || 30 * 60_000)
-            : new AcpProcessRuntime(driver, session, this.config.maxOutputChars, this.config.promptTimeoutMs || 30 * 60_000);
+            : new AcpProcessRuntime(driver, session, this.config.maxOutputChars, this.config.promptTimeoutMs || 30 * 60_000, this.workspacePolicy.listRoots());
         this.sessions.set(session.id, session);
+        this.notifyLifecycle({
+            type: 'session_created',
+            sessionId: session.id,
+            ownerKeyId: session.ownerKeyId,
+            agentId: session.agentId
+        });
+        release();
         session.attach(runtime);
         try {
             await runtime.start(workspace);
@@ -544,8 +609,22 @@ export class SessionManager {
         }
         catch (error) {
             session.setState('failed', errorMessage(error));
-            await session.dispose();
-            this.sessions.delete(session.id);
+            try {
+                await session.dispose();
+            }
+            catch (cleanupError) {
+                console.error(JSON.stringify({ level: 'error', event: 'session_start_cleanup_failed', sessionId: session.id, message: errorMessage(cleanupError) }));
+            }
+            finally {
+                if (this.sessions.delete(session.id)) {
+                    this.notifyLifecycle({
+                        type: 'session_closed',
+                        sessionId: session.id,
+                        ownerKeyId: session.ownerKeyId,
+                        agentId: session.agentId
+                    });
+                }
+            }
             throw new SessionRequestError(502, `Agent failed to start: ${errorMessage(error)}`);
         }
     }
@@ -558,8 +637,12 @@ export class SessionManager {
     count() {
         return this.sessions.size;
     }
+    subscribeLifecycle(listener) {
+        this.lifecycleListeners.add(listener);
+        return () => this.lifecycleListeners.delete(listener);
+    }
     listRuns(query = {}) {
-        return this.runStore?.list(query) || { runs: [], total: 0 };
+        return this.runStore?.list(query) || { runs: [], total: 0, stats: { active: 0, completed: 0, failed: 0 } };
     }
     getRun(id) {
         const run = this.runStore?.get(id);
@@ -567,13 +650,51 @@ export class SessionManager {
             throw new RunNotFoundError(id);
         return run;
     }
-    async message(id, message, attachmentIds = []) {
+    getRunOwnerKeyId(id) {
+        const store = this.runStore;
+        return store?.getOwnerKeyId?.(id);
+    }
+    ownsRun(id, keyId) {
+        return this.getRunOwnerKeyId(id) === keyId;
+    }
+    getRunArtifacts(id) {
+        return this.getRun(id).artifacts;
+    }
+    getStorageMetrics() {
+        return this.runStore?.metrics();
+    }
+    async readRunArtifact(runId, artifactId) {
+        // Read through RunStore so the artifact directory remains the only
+        // place that knows how payload filenames are derived and validated.
+        this.getRun(runId);
+        const store = this.runStore;
+        return store?.readArtifact?.(runId, artifactId);
+    }
+    getRunArtifact(runId, artifactId) {
+        return this.readRunArtifact(runId, artifactId);
+    }
+    getRunControls(id) {
+        return this.adminRuns.getRunControls(id);
+    }
+    async cancelRun(id) {
+        return this.adminRuns.cancelRun(id);
+    }
+    async respondRun(id, response, attachmentIds = []) {
+        return this.adminRuns.respondRun(id, response, attachmentIds);
+    }
+    async retryRun(id, reserveRetry) {
+        return this.adminRuns.retryRun(id, reserveRetry);
+    }
+    retryOfRunId(id) {
+        return this.adminRuns.retryOfRunId(id);
+    }
+    async message(id, message, attachmentIds = [], retryOfRunId) {
         const text = String(message || '');
         if (!text.trim())
             throw new SessionRequestError(400, 'message is required');
         return this.withSessionLock(id, async () => {
             const session = this.require(id);
-            await session.message(text, attachmentIds);
+            await session.message(text, attachmentIds, retryOfRunId);
             return session.snapshot();
         });
     }
@@ -609,25 +730,47 @@ export class SessionManager {
                 await session.cancel();
             const snapshot = session.snapshot();
             await session.dispose();
-            this.sessions.delete(id);
+            if (this.sessions.delete(id)) {
+                this.notifyLifecycle({
+                    type: 'session_closed',
+                    sessionId: session.id,
+                    ownerKeyId: session.ownerKeyId,
+                    agentId: session.agentId
+                });
+            }
             return snapshot;
         });
     }
     eventsAfter(id, after) {
         return this.require(id).events.after(after);
     }
+    eventReplay(id, after) {
+        return this.require(id).events.replay(after);
+    }
     subscribe(id, listener) {
         return this.require(id).events.subscribe(listener);
     }
     async shutdown() {
+        this.admission.markClosing();
         if (this.cleanupTimer)
             clearInterval(this.cleanupTimer);
         this.cleanupTimer = undefined;
-        await Promise.allSettled(Array.from(this.sessions.values()).map(async (session) => {
+        const results = await Promise.allSettled(Array.from(this.sessions.values()).map(async (session) => {
             session.interruptForShutdown();
             await session.dispose();
         }));
+        for (const session of this.sessions.values()) {
+            this.notifyLifecycle({
+                type: 'session_closed',
+                sessionId: session.id,
+                ownerKeyId: session.ownerKeyId,
+                agentId: session.agentId
+            });
+        }
         this.sessions.clear();
+        const failures = results.filter((result) => result.status === 'rejected');
+        if (failures.length)
+            throw new AggregateError(failures.map((result) => result.reason), 'Failed to dispose one or more Agent sessions');
     }
     async withSessionLock(id, operation) {
         // Serialise mutating operations per session so that concurrent
@@ -657,38 +800,41 @@ export class SessionManager {
             throw new SessionNotFoundError(id);
         return session;
     }
-    async ensureCapacity() {
-        const limit = this.config.maxSessions || 64;
-        if (this.sessions.size < limit)
-            return;
-        const terminal = Array.from(this.sessions.values())
-            .filter((session) => isTerminal(session.state))
-            .sort((left, right) => left.updatedAt - right.updatedAt);
-        while (this.sessions.size >= limit && terminal.length) {
-            const session = terminal.shift();
-            await session.dispose();
-            this.sessions.delete(session.id);
-        }
-        if (this.sessions.size >= limit) {
-            throw new SessionRequestError(429, 'Session capacity has been reached');
-        }
-    }
     async cleanup() {
         const cutoff = Date.now() - this.config.sessionTtlMs;
         for (const [id, session] of this.sessions) {
             if (session.updatedAt > cutoff)
                 continue;
-            if (!isTerminal(session.state)) {
-                session.setState('failed', 'Session expired after exceeding its lifetime');
-            }
-            await session.dispose();
-            this.sessions.delete(id);
+            await this.withSessionLock(id, async () => {
+                if (this.sessions.get(id) !== session || session.updatedAt > cutoff)
+                    return;
+                if (!isTerminal(session.state))
+                    session.setState('failed', 'Session expired after exceeding its lifetime');
+                try {
+                    await session.dispose();
+                }
+                catch (error) {
+                    console.error(JSON.stringify({ level: 'error', event: 'session_cleanup_failed', sessionId: id, message: errorMessage(error) }));
+                }
+                finally {
+                    if (this.sessions.delete(id)) {
+                        this.notifyLifecycle({
+                            type: 'session_closed',
+                            sessionId: session.id,
+                            ownerKeyId: session.ownerKeyId,
+                            agentId: session.agentId
+                        });
+                    }
+                }
+            });
         }
     }
     restartCleanup() {
         if (this.cleanupTimer)
             clearInterval(this.cleanupTimer);
-        this.cleanupTimer = setInterval(() => void this.cleanup(), this.config.cleanupIntervalMs || 60_000);
+        this.cleanupTimer = setInterval(() => void this.cleanup().catch((error) => {
+            console.error(JSON.stringify({ level: 'error', event: 'session_cleanup_failed', message: errorMessage(error) }));
+        }), this.config.cleanupIntervalMs || 60_000);
         this.cleanupTimer.unref?.();
     }
     defaultWorkspace(agentId) {
@@ -697,6 +843,21 @@ export class SessionManager {
             return '';
         return config?.workspace || this.config.workspaceRoots[0] || '';
     }
+    notifyLifecycle(event) {
+        for (const listener of this.lifecycleListeners) {
+            try {
+                listener(structuredClone(event));
+            }
+            catch (error) {
+                console.error(JSON.stringify({
+                    level: 'error',
+                    event: 'session_lifecycle_listener_failed',
+                    type: event.type,
+                    message: errorMessage(error)
+                }));
+            }
+        }
+    }
 }
 function progressForState(state, error) {
     const phases = {
@@ -746,10 +907,16 @@ function runArtifact(artifact) {
         metadata: artifact.metadata ? structuredClone(artifact.metadata) : undefined
     };
 }
-function assertWorkspacePath(workspaceRoot, target) {
-    const child = relative(workspaceRoot, target);
-    if (child === '..' || child.startsWith(`..${sep}`) || isAbsolute(child)) {
-        throw new SessionRequestError(403, 'Published files must stay inside the session workspace');
+function publishFailure(error) {
+    switch (error.failure) {
+        case 'swapped':
+            return new SessionRequestError(409, 'Published file changed while it was being opened');
+        case 'not-a-file':
+            return new SessionRequestError(400, 'Only regular files can be published');
+        case 'too-large':
+            return new SessionRequestError(413, `Published file exceeds the ${MAX_PUBLISHED_FILE_BYTES} byte limit`);
+        case 'outside':
+            return new SessionRequestError(403, 'Published files must stay inside the session workspace');
     }
 }
 function mediaTypeForPath(path) {
@@ -822,11 +989,6 @@ export class RunNotFoundError extends Error {
         this.runId = runId;
     }
 }
-function filterAgents(agents, ids) {
-    return agents
-        .filter((agent) => !ids || ids.has(agent.id))
-        .map((agent) => structuredClone(agent));
-}
 function isTerminal(state) {
     return state === 'completed' || state === 'failed' || state === 'canceled';
 }