nexus-agentd 0.2.6 → 0.3.1

package/dist/session.d.ts

@@ -1,9 +1,32 @@
 import type { AgentDriver } from './drivers/index.js';
 import { SessionEventLog } from './events.js';
-import { RunStore, type RunListQuery } from './run-store.js';
+import { RunStore, type RunListQuery, type RunArtifactQuery } from './run-store.js';
+import { type AdminRetryReservationFactory, type AdminRunOperationResult, type AdminRunControls } from './session/admin-runs.js';
 import type { AcpSessionSink, AgentSessionRuntime, AgentSessionSink } from './session-contract.js';
 import type { AgentdAgentView, AgentdArtifact, AgentdConfig, AgentdEvent, AgentdEventType, AgentdInputAttachmentView, AgentdPendingRequest, AgentdPendingResponse, AgentdProtocol, AgentdSessionState, AgentdSessionView, AgentdTurnCompletionProof } from './types.js';
 import { type WorkspacePolicy } from './workspace.js';
+/** Optional durable sink for full artifact snapshots. */
+export interface SessionArtifactStore {
+    recordArtifacts(runId: string, artifacts: AgentdArtifact[]): unknown | Promise<unknown>;
+}
+export type SessionLifecycleEvent = {
+    type: 'session_created';
+    sessionId: string;
+    ownerKeyId: string;
+    agentId: string;
+} | {
+    type: 'run_updated';
+    sessionId: string;
+    runId: string;
+    ownerKeyId: string;
+    state: AgentdSessionState;
+} | {
+    type: 'session_closed';
+    sessionId: string;
+    ownerKeyId: string;
+    agentId: string;
+};
+export type SessionLifecycleListener = (event: SessionLifecycleEvent) => void;
 export declare class ManagedSession implements AgentSessionSink, AcpSessionSink {
     readonly agentId: string;
     readonly protocol: AgentdProtocol;
@@ -27,8 +50,11 @@ export declare class ManagedSession implements AgentSessionSink, AcpSessionSink
     private artifacts;
     private inputAttachments;
     private runtime?;
-    constructor(agentId: string, protocol: AgentdProtocol, workspace: string | undefined, ownerKeyId: string, maxEvents: number, maxOutputChars: number, agentName: string, runStore?: RunStore | undefined, instanceId?: string);
+    private readonly artifactStore?;
+    private readonly onRunUpdate?;
+    constructor(agentId: string, protocol: AgentdProtocol, workspace: string | undefined, ownerKeyId: string, maxEvents: number, maxOutputChars: number, agentName: string, runStore?: RunStore | undefined, instanceId?: string, artifactStore?: SessionArtifactStore, onRunUpdate?: (runId: string, state: AgentdSessionState) => void);
     attach(runtime: AgentSessionRuntime): void;
+    runtimeAvailable(): boolean;
     setProtocolSessionId(id: string): void;
     setAcpSessionId(id: string): void;
     setState(state: AgentdSessionState, error?: string): void;
@@ -43,7 +69,7 @@ export declare class ManagedSession implements AgentSessionSink, AcpSessionSink
     clearPending(): void;
     emit(type: AgentdEventType, data?: unknown): void;
     addInputAttachment(name: string, mediaType: string | undefined, bytes: Buffer): AgentdInputAttachmentView;
-    message(message: string, attachmentIds?: string[]): Promise<void>;
+    message(message: string, attachmentIds?: string[], retryOfRunId?: string): Promise<void>;
     resolvePending(response: AgentdPendingResponse, attachmentIds?: string[]): Promise<void>;
     cancel(): Promise<void>;
     dispose(): Promise<void>;
@@ -62,15 +88,21 @@ export declare class SessionManager {
     private sessions;
     private sessionLocks;
     private cleanupTimer?;
-    private readinessCache?;
-    constructor(config: AgentdConfig, workspacePolicy: WorkspacePolicy, drivers: Map<string, AgentDriver>, runStore?: RunStore | undefined);
+    private readonly readiness;
+    private readonly admission;
+    private readonly adminRuns;
+    private readonly artifactStore?;
+    private readonly lifecycleListeners;
+    constructor(config: AgentdConfig, workspacePolicy: WorkspacePolicy, drivers: Map<string, AgentDriver>, runStore?: RunStore | undefined, artifactStore?: SessionArtifactStore);
     reconfigure(config: AgentdConfig, workspacePolicy: WorkspacePolicy, drivers: Map<string, AgentDriver>): void;
     startCleanup(): void;
     listAgents(agentIds?: Set<string>, force?: boolean): Promise<AgentdAgentView[]>;
     create(agentId: string, workspaceInput: string | undefined, ownerKeyId: string): Promise<AgentdSessionView>;
+    private createReserved;
     get(id: string): AgentdSessionView;
     owns(id: string, keyId: string): boolean;
     count(): number;
+    subscribeLifecycle(listener: SessionLifecycleListener): () => boolean;
     listRuns(query?: RunListQuery): {
         runs: import("./types.js").AgentdRunView[];
         total: number;
@@ -81,7 +113,24 @@ export declare class SessionManager {
         };
     };
     getRun(id: string): import("./types.js").AgentdRunDetail;
-    message(id: string, message: string, attachmentIds?: string[]): Promise<AgentdSessionView>;
+    getRunOwnerKeyId(id: string): string | undefined;
+    deleteRun(id: string): import("./types.js").AgentdRunDetail | undefined;
+    ownsRun(id: string, keyId: string): boolean;
+    getRunArtifacts(id: string): import("./types.js").AgentdRunArtifactView[];
+    listArtifacts(query?: RunArtifactQuery): {
+        artifacts: import("./run-store.js").RunArtifactRow[];
+        total: number;
+    };
+    removeRunArtifact(runId: string, artifactId: string): Promise<boolean | undefined>;
+    getStorageMetrics(): ReturnType<RunStore['metrics']> | undefined;
+    readRunArtifact(runId: string, artifactId: string): Promise<import("./artifact-store.js").ArtifactReadResult | undefined>;
+    getRunArtifact(runId: string, artifactId: string): Promise<import("./artifact-store.js").ArtifactReadResult | undefined>;
+    getRunControls(id: string): AdminRunControls;
+    cancelRun(id: string): Promise<AdminRunOperationResult>;
+    respondRun(id: string, response: AgentdPendingResponse, attachmentIds?: string[]): Promise<AdminRunOperationResult>;
+    retryRun(id: string, reserveRetry?: AdminRetryReservationFactory): Promise<AdminRunOperationResult>;
+    retryOfRunId(id: string): string | undefined;
+    message(id: string, message: string, attachmentIds?: string[], retryOfRunId?: string): Promise<AgentdSessionView>;
     resolvePending(id: string, response: AgentdPendingResponse, attachmentIds?: string[]): Promise<AgentdSessionView>;
     addInputAttachment(id: string, name: string, mediaType: string | undefined, bytes: Buffer): AgentdInputAttachmentView;
     publishFile(id: string, paths: string[]): Promise<{
@@ -91,14 +140,23 @@ export declare class SessionManager {
     cancel(id: string): Promise<AgentdSessionView>;
     close(id: string): Promise<AgentdSessionView>;
     eventsAfter(id: string, after?: string): AgentdEvent[];
+    eventReplay(id: string, after?: string): {
+        earliestId: string;
+        latestId: string;
+        reset: {
+            reason: string;
+            requestedAfter: string | null;
+        } | undefined;
+        events: AgentdEvent[];
+    };
     subscribe(id: string, listener: (event: AgentdEvent) => void): () => boolean;
     shutdown(): Promise<void>;
     private withSessionLock;
     private require;
-    private ensureCapacity;
     private cleanup;
     private restartCleanup;
     private defaultWorkspace;
+    private notifyLifecycle;
 }
 export declare class SessionNotFoundError extends Error {
     readonly sessionId: string;

package/dist/session.js

@@ -2,13 +2,15 @@ import { randomUUID } from 'node:crypto';
 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;
@@ -36,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;
@@ -45,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();
@@ -277,7 +286,7 @@ export class ManagedSession {
         this.updatedAt = Date.now();
         return attachmentView(attachment);
     }
-    async message(message, attachmentIds = []) {
+    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);
@@ -305,7 +314,8 @@ 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) => {
@@ -403,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));
@@ -422,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();
     }
@@ -443,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}`);
         }
@@ -534,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, 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);
@@ -553,7 +616,14 @@ export class SessionManager {
                 console.error(JSON.stringify({ level: 'error', event: 'session_start_cleanup_failed', sessionId: session.id, message: errorMessage(cleanupError) }));
             }
             finally {
-                this.sessions.delete(session.id);
+                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)}`);
         }
@@ -567,6 +637,10 @@ 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, stats: { active: 0, completed: 0, failed: 0 } };
     }
@@ -576,13 +650,63 @@ export class SessionManager {
             throw new RunNotFoundError(id);
         return run;
     }
-    async message(id, message, attachmentIds = []) {
+    getRunOwnerKeyId(id) {
+        const store = this.runStore;
+        return store?.getOwnerKeyId?.(id);
+    }
+    deleteRun(id) {
+        const store = this.runStore;
+        return store?.deleteRun?.(id);
+    }
+    ownsRun(id, keyId) {
+        return this.getRunOwnerKeyId(id) === keyId;
+    }
+    getRunArtifacts(id) {
+        return this.getRun(id).artifacts;
+    }
+    listArtifacts(query = {}) {
+        const store = this.runStore;
+        return store?.listArtifacts?.(query) || { artifacts: [], total: 0 };
+    }
+    async removeRunArtifact(runId, artifactId) {
+        const store = this.runStore;
+        return store?.removeArtifact?.(runId, artifactId);
+    }
+    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();
         });
     }
@@ -618,25 +742,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
@@ -666,22 +812,6 @@ 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) {
@@ -699,7 +829,14 @@ export class SessionManager {
                     console.error(JSON.stringify({ level: 'error', event: 'session_cleanup_failed', sessionId: id, message: errorMessage(error) }));
                 }
                 finally {
-                    this.sessions.delete(id);
+                    if (this.sessions.delete(id)) {
+                        this.notifyLifecycle({
+                            type: 'session_closed',
+                            sessionId: session.id,
+                            ownerKeyId: session.ownerKeyId,
+                            agentId: session.agentId
+                        });
+                    }
                 }
             });
         }
@@ -718,6 +855,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 = {
@@ -849,11 +1001,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';
 }

package/dist/sse-writer.d.ts

@@ -0,0 +1,7 @@
+import type { ServerResponse } from 'node:http';
+/** A false write already accepted the chunk. Queue later chunks until drain,
+ * with both a byte ceiling and a deadline independent of socket activity. */
+export declare function createSseWriter(response: ServerResponse, close: () => void, maxBytes?: number, drainMs?: number): {
+    write(chunk: string): boolean;
+    stop: () => void;
+};