@myagentroam/agent 0.11.33 → 0.11.34

package/dist/sdk/session-extension-prompt.js

@@ -0,0 +1,62 @@
+import { AgentError } from '../error.js';
+import { loadAgentInstructions } from '../runtime/context/instructions.js';
+/** Builds the Session prompt preview using the same capability and Skill boundaries as execution. */
+export function createSessionExtensionPrompt(ports) {
+    return async (facts, call) => {
+        call.signal.throwIfAborted();
+        const defaults = ports.execution();
+        const state = defaults ?? ports.models();
+        const modelId = facts.modelId ?? defaults?.modelId ?? ports.models().defaultModelId;
+        const instruction = defaults ? defaults.instruction : ports.instruction();
+        const model = state.models.get(modelId);
+        if (!model)
+            throw new AgentError('MAR_AGENT_MODEL_DISABLED', 'Selected model is unavailable.');
+        const mode = facts.mode ?? defaults?.mode ?? 'run';
+        const bindings = ports.capture(call);
+        if (!bindings)
+            throw new AgentError('MAR_AGENT_EXTENSION_PROMPT_UNAVAILABLE', 'Session prompt tool sources are unavailable.');
+        const definitions = [...bindings.values()]
+            .filter((binding) => binding.available?.(call) !== false)
+            .map((binding) => binding.definition)
+            .filter((tool) => !(ports.source === 'subagent' &&
+            (tool.agentScope === 'ROOT_ONLY' ||
+                tool.name.startsWith('agent_') ||
+                tool.name === 'question')) &&
+            !(tool.name === 'question' && mode !== 'plan') &&
+            !(tool.name === 'view_image' && !model.inputCapabilities.includes('IMAGE')) &&
+            !(['code_exec', 'code_exec_wait'].includes(tool.name) &&
+                (!model.codeMode || !ports.codeExecute)));
+        const byName = new Map(definitions.map((tool) => [tool.name, tool]));
+        const tools = facts.tools === undefined
+            ? definitions
+            : facts.tools.flatMap((name) => {
+                const tool = byName.get(name);
+                return tool ? [tool] : [];
+            });
+        const executionId = call.executionId ?? defaults?.executionId;
+        if (executionId === undefined &&
+            ports.host.listExecutionExtensions &&
+            !ports.host.listSessionSkills)
+            throw new AgentError('MAR_AGENT_EXTENSION_PROMPT_UNAVAILABLE', 'The Host does not provide an idle Session Skill catalog.');
+        const hostSkills = executionId !== undefined
+            ? ((await ports.host.listExecutionExtensions?.({
+                sessionId: ports.sessionId,
+                modelId,
+                executionId
+            }))?.skills ?? [])
+            : ((await ports.host.listSessionSkills?.({ sessionId: ports.sessionId, modelId })) ?? []);
+        call.signal.throwIfAborted();
+        const instructions = await loadAgentInstructions({
+            home: ports.home,
+            workspace: ports.workspace,
+            availableTools: new Set(tools.map((tool) => tool.name)),
+            hostSkills,
+            ...(ports.workspaceMapped() ? { workspaceDisplayPath: ports.displayWorkspace } : {})
+        });
+        call.signal.throwIfAborted();
+        return {
+            sections: ports.sections(tools, mode, model, instruction, instructions?.skillCatalog),
+            facts: { modelId, mode, tools: tools.map((tool) => tool.name) }
+        };
+    };
+}

package/dist/sdk/session-maintenance.d.ts

@@ -0,0 +1,25 @@
+import type { ExtensionManager } from '../extensions/manager.js';
+import type { AgentHost } from '../host/contracts.js';
+import type { SessionStore } from '../session/store/contracts.js';
+import type { SessionRegistry } from './session-registry.js';
+import type { SessionRuntime } from './session-runtime.js';
+/** Agent-level maintenance admission and tree cleanup, sharing the Agent writer owner. */
+export declare class SessionMaintenanceCoordinator {
+    #private;
+    private readonly store;
+    private readonly registry;
+    private readonly extensions;
+    private readonly host;
+    private readonly writerOwner;
+    private readonly disposed;
+    private readonly generation;
+    constructor(store: SessionStore, registry: SessionRegistry<SessionRuntime>, extensions: ExtensionManager, host: AgentHost, writerOwner: object, disposed: () => boolean, generation: () => number);
+    epoch(id: string): number;
+    canPublish(id: string, epoch: number): boolean;
+    assertAdmission(id?: string): void;
+    join(): Promise<void>;
+    clear(id: string): Promise<void>;
+    delete(id: string): Promise<void>;
+}
+/** Complete all independent stages, reporting the first authoritative failure. */
+export declare function completeAgentCleanup(steps: readonly (() => unknown | Promise<unknown>)[]): Promise<void>;

package/dist/sdk/session-maintenance.js

@@ -0,0 +1,205 @@
+import { AgentError } from '../error.js';
+import { closeModelAdapters } from './model-runtime.js';
+/** Agent-level maintenance admission and tree cleanup, sharing the Agent writer owner. */
+export class SessionMaintenanceCoordinator {
+    store;
+    registry;
+    extensions;
+    host;
+    writerOwner;
+    disposed;
+    generation;
+    #epochs = new Map();
+    #operations = new Map();
+    #treeAdmissions = new Map();
+    constructor(store, registry, extensions, host, writerOwner, disposed, generation) {
+        this.store = store;
+        this.registry = registry;
+        this.extensions = extensions;
+        this.host = host;
+        this.writerOwner = writerOwner;
+        this.disposed = disposed;
+        this.generation = generation;
+    }
+    epoch(id) {
+        return this.#epochs.get(id) ?? 0;
+    }
+    canPublish(id, epoch) {
+        return !this.disposed() && !this.#treeAdmissions.has(id) && this.epoch(id) === epoch;
+    }
+    assertAdmission(id) {
+        if (this.disposed())
+            throw new AgentError('MAR_AGENT_DISPOSED', 'Agent is disposed.');
+        if (id !== undefined && (this.#operations.has(id) || this.#treeAdmissions.has(id)))
+            throw new AgentError('MAR_AGENT_SESSION_CLOSING', 'Session is closing.');
+    }
+    async join() {
+        const results = await Promise.allSettled([...this.#operations.values()].map(({ pending }) => pending));
+        const failure = results.find((result) => result.status === 'rejected');
+        if (failure?.status === 'rejected')
+            throw failure.reason;
+    }
+    clear(id) {
+        return this.#track(id, 'clear', async () => {
+            if (this.registry.get(id)?.activeExecutionId !== undefined)
+                throw new AgentError('MAR_AGENT_EXECUTION_ACTIVE', 'A session cannot be cleared while an execution is active.');
+            const maintenance = await this.store.acquireSessionMaintenance(id, 'clear', this.writerOwner);
+            this.#invalidate([id]);
+            let failed = false;
+            try {
+                let runtime;
+                await completeAgentCleanup([
+                    () => this.registry.whenIdle([id]),
+                    () => {
+                        runtime = this.registry.get(id);
+                    },
+                    () => this.extensions.endSession(id, 'clear'),
+                    () => this.extensions.retireSession(id),
+                    () => this.extensions.clearSession(id),
+                    () => runtime?.retireInputs(),
+                    () => runtime?.disposeSubagents(),
+                    () => closeModelAdapters(runtime === undefined
+                        ? []
+                        : runtime
+                            .takeAdaptersForClose()
+                            .filter((adapter) => ![...this.registry].some(([otherId, other]) => otherId !== id && other.hasModelAdapter(adapter)))),
+                    () => runtime?.resetAfterClear(this.generation()),
+                    () => this.host.disposeSessionResources?.(id),
+                    () => this.store.clearSession(id, maintenance)
+                ]);
+            }
+            catch (error) {
+                failed = true;
+                throw error;
+            }
+            finally {
+                try {
+                    await maintenance.release();
+                }
+                catch (error) {
+                    if (!failed)
+                        throw error;
+                }
+            }
+        });
+    }
+    delete(id) {
+        return this.#track(id, 'delete', async () => {
+            const maintenance = await this.store.acquireSessionMaintenance(id, 'delete', this.writerOwner);
+            let failed = false;
+            const ids = maintenance.sessionIds;
+            for (const sessionId of ids)
+                this.#treeAdmissions.set(sessionId, (this.#treeAdmissions.get(sessionId) ?? 0) + 1);
+            try {
+                this.#invalidate(ids);
+                let runtimes = [];
+                await completeAgentCleanup([
+                    () => this.registry.whenIdle(ids),
+                    () => {
+                        runtimes = ids.flatMap((sessionId) => {
+                            const runtime = this.registry.get(sessionId);
+                            return runtime ? [runtime] : [];
+                        });
+                        for (const runtime of runtimes)
+                            runtime.cancelExecutions();
+                    },
+                    async () => {
+                        let failure;
+                        await Promise.all(ids.map(async (sessionId) => {
+                            try {
+                                await this.extensions.endSession(sessionId, 'other', false);
+                            }
+                            catch (error) {
+                                failure ??= { error };
+                            }
+                        }));
+                        if (failure)
+                            throw failure.error;
+                    },
+                    ...ids.map((sessionId) => () => this.extensions.retireSession(sessionId)),
+                    ...ids.map((sessionId) => () => this.extensions.clearSession(sessionId)),
+                    () => completeAgentCleanup(runtimes.map((runtime) => () => runtime.retireInputs())),
+                    () => completeAgentCleanup(runtimes.map((runtime) => () => runtime.disposeSubagents())),
+                    () => Promise.all(runtimes.map((runtime) => runtime.joinExecutions())),
+                    () => {
+                        for (const sessionId of ids) {
+                            const runtime = this.registry.get(sessionId);
+                            if (runtime)
+                                this.registry.unregister(sessionId, runtime);
+                        }
+                    },
+                    () => closeModelAdapters(runtimes
+                        .flatMap((runtime) => runtime.takeAdaptersForClose())
+                        .filter((adapter) => ![...this.registry.values()].some((other) => other.hasModelAdapter(adapter)))),
+                    ...ids.map((sessionId) => () => this.host.disposeSessionResources?.(sessionId)),
+                    () => this.store.delete(id, maintenance)
+                ]);
+            }
+            catch (error) {
+                failed = true;
+                throw error;
+            }
+            finally {
+                try {
+                    await maintenance.release();
+                }
+                catch (error) {
+                    if (!failed)
+                        throw error;
+                }
+                finally {
+                    for (const sessionId of ids) {
+                        const count = this.#treeAdmissions.get(sessionId);
+                        if (count === 1)
+                            this.#treeAdmissions.delete(sessionId);
+                        else
+                            this.#treeAdmissions.set(sessionId, count - 1);
+                    }
+                }
+            }
+        });
+    }
+    #invalidate(ids) {
+        for (const id of ids)
+            this.#epochs.set(id, this.epoch(id) + 1);
+    }
+    #track(id, kind, operation) {
+        if (this.disposed())
+            return Promise.reject(new AgentError('MAR_AGENT_DISPOSED', 'Agent is disposed.'));
+        const current = this.#operations.get(id);
+        if (current)
+            return current.kind === kind
+                ? current.pending
+                : Promise.reject(new AgentError('MAR_AGENT_SESSION_CLOSING', 'Session is closing.'));
+        if (this.#treeAdmissions.has(id))
+            return Promise.reject(new AgentError('MAR_AGENT_SESSION_CLOSING', 'Session is closing.'));
+        const completion = Promise.withResolvers();
+        const pending = completion.promise.finally(() => this.#operations.delete(id));
+        this.#operations.set(id, { kind, pending });
+        void pending.catch(() => undefined);
+        try {
+            completion.resolve(operation());
+        }
+        catch (error) {
+            completion.reject(error);
+        }
+        return pending;
+    }
+}
+/** Complete all independent stages, reporting the first authoritative failure. */
+export async function completeAgentCleanup(steps) {
+    let failed = false;
+    let failure;
+    for (const step of steps) {
+        try {
+            await step();
+        }
+        catch (error) {
+            if (!failed)
+                failure = error;
+            failed = true;
+        }
+    }
+    if (failed)
+        throw failure;
+}

package/dist/sdk/session-model-adapters.d.ts

@@ -0,0 +1,28 @@
+import type { ModelAdapter } from '../model/contracts.js';
+import type { ModelCredentialProvider } from '../model/configuration.js';
+import { type ResolvedModelConfiguration } from './model-runtime.js';
+/** Session-owned cache; Agent coordinates references shared across Sessions. */
+export declare class SessionModelAdapters {
+    #private;
+    readonly createAdapter: (modelId: string, models: ReadonlyMap<string, ResolvedModelConfiguration>) => ModelAdapter;
+    readonly hasCustomAdapters: boolean;
+    constructor(generation: number, createAdapter: (modelId: string, models: ReadonlyMap<string, ResolvedModelConfiguration>) => ModelAdapter, hasCustomAdapters: boolean);
+    getOrCreate(modelId: string, models: ReadonlyMap<string, ResolvedModelConfiguration>): ModelAdapter;
+    snapshot(): readonly ModelAdapter[];
+    collectActiveReferences(target: Set<ModelAdapter>): void;
+    collectCredentialProviders(target: Set<ModelCredentialProvider>): void;
+    hasReference(adapter: ModelAdapter): boolean;
+    static closeSessions(sessions: readonly SessionModelAdapters[]): Promise<void>;
+    /** Stage one coordinated transition; each cache owns its own retirement and generation. */
+    static stageReconfiguration(sessions: readonly SessionModelAdapters[], models: ReadonlyMap<string, ResolvedModelConfiguration>, active: ReadonlySet<ModelAdapter>, assertOpen: () => void): Promise<(generation: number) => void>;
+    refresh(generation: number, retainedByActive: ReadonlySet<ModelAdapter>): Promise<void>;
+    prepareReconfigure(models: ReadonlyMap<string, ResolvedModelConfiguration>, activeAdapters: ReadonlySet<ModelAdapter>): readonly {
+        readonly adapter: ModelAdapter;
+        readonly commit: () => void;
+    }[];
+    /** Remove unretained references; the caller deduplicates and closes across Sessions. */
+    retire(retained: ReadonlySet<ModelAdapter>): readonly ModelAdapter[];
+    setGeneration(generation: number): void;
+    /** Transfer close responsibility once, so shared references can be closed as a group. */
+    drain(): readonly ModelAdapter[];
+}

package/dist/sdk/session-model-adapters.js

@@ -0,0 +1,96 @@
+import { addModelCredentialProviders, closeModelAdapters } from './model-runtime.js';
+/** Session-owned cache; Agent coordinates references shared across Sessions. */
+export class SessionModelAdapters {
+    createAdapter;
+    hasCustomAdapters;
+    #adapters = new Map();
+    #generation;
+    constructor(generation, createAdapter, hasCustomAdapters) {
+        this.createAdapter = createAdapter;
+        this.hasCustomAdapters = hasCustomAdapters;
+        this.#generation = generation;
+    }
+    getOrCreate(modelId, models) {
+        const existing = this.#adapters.get(modelId);
+        if (existing !== undefined)
+            return existing;
+        const adapter = this.createAdapter(modelId, models);
+        // Stateless custom adapters belong to the individual Execution instead.
+        if (!this.hasCustomAdapters || adapter.createTurnSession !== undefined)
+            this.#adapters.set(modelId, adapter);
+        return adapter;
+    }
+    snapshot() {
+        return [...this.#adapters.values()];
+    }
+    collectActiveReferences(target) {
+        for (const adapter of this.#adapters.values())
+            target.add(adapter);
+    }
+    collectCredentialProviders(target) {
+        for (const adapter of this.#adapters.values())
+            addModelCredentialProviders(target, adapter.configuration);
+    }
+    hasReference(adapter) {
+        return [...this.#adapters.values()].includes(adapter);
+    }
+    static closeSessions(sessions) {
+        return closeModelAdapters(sessions.flatMap((session) => session.drain()));
+    }
+    /** Stage one coordinated transition; each cache owns its own retirement and generation. */
+    static async stageReconfiguration(sessions, models, active, assertOpen) {
+        const commits = new Map();
+        for (const session of sessions)
+            for (const { adapter, commit } of session.prepareReconfigure(models, active))
+                commits.set(adapter, commit);
+        const retained = new Set(commits.keys());
+        const retired = new Set(sessions.flatMap((session) => session.retire(retained)));
+        await closeModelAdapters([...retired].filter((adapter) => !active.has(adapter)));
+        return (generation) => {
+            assertOpen();
+            for (const commit of commits.values())
+                commit();
+            for (const session of sessions)
+                session.setGeneration(generation);
+        };
+    }
+    async refresh(generation, retainedByActive) {
+        if (this.#generation === generation)
+            return;
+        await closeModelAdapters(this.snapshot().filter((adapter) => !retainedByActive.has(adapter)));
+        this.#adapters.clear();
+        this.#generation = generation;
+    }
+    prepareReconfigure(models, activeAdapters) {
+        const plans = [];
+        for (const [modelId, adapter] of this.#adapters) {
+            if (activeAdapters.has(adapter))
+                continue;
+            const configuration = models.get(modelId);
+            const commit = configuration === undefined ? undefined : adapter.prepareReconfigure?.(configuration);
+            if (commit !== undefined)
+                plans.push({ adapter, commit });
+        }
+        return plans;
+    }
+    /** Remove unretained references; the caller deduplicates and closes across Sessions. */
+    retire(retained) {
+        const removed = [];
+        for (const [modelId, adapter] of this.#adapters) {
+            if (!retained.has(adapter)) {
+                removed.push(adapter);
+                this.#adapters.delete(modelId);
+            }
+        }
+        return removed;
+    }
+    setGeneration(generation) {
+        this.#generation = generation;
+    }
+    /** Transfer close responsibility once, so shared references can be closed as a group. */
+    drain() {
+        const adapters = this.snapshot();
+        this.#adapters.clear();
+        return adapters;
+    }
+}

package/dist/sdk/session-open.d.ts

@@ -0,0 +1,22 @@
+import type { ModelAdapter } from '../model/contracts.js';
+import type { SessionStore } from '../session/store/contracts.js';
+import type { SubagentSessionController } from '../subagent/session-controller.js';
+import type { ResolvedModelConfiguration } from './model-runtime.js';
+import { type SessionRegistry } from './session-registry.js';
+import { SessionRuntime } from './session-runtime.js';
+type StoredSession = Awaited<ReturnType<SessionStore['getSession']>>;
+interface SessionOpenPorts<Handle> {
+    readonly registry: SessionRegistry<SessionRuntime>;
+    readonly getSession: (id: string) => Promise<StoredSession>;
+    readonly generation: () => number;
+    readonly createAdapter: (id: string, models: ReadonlyMap<string, ResolvedModelConfiguration>) => ModelAdapter;
+    readonly hasCustomAdapters: boolean;
+    readonly openSubagents: (id: string, workspace: string) => Promise<SubagentSessionController>;
+    readonly assertAdmission: (id: string) => void;
+    readonly epoch: (id: string) => number;
+    readonly canPublish: (id: string, epoch: number) => boolean;
+    readonly createHandle: (id: string, runtime: SessionRuntime, stored: StoredSession, workspace?: string) => Handle;
+}
+/** The open flow owns unpublished candidates; the registry owns only identity and barriers. */
+export declare function createSessionOpen<Handle>(ports: SessionOpenPorts<Handle>): (id: string, workspace?: string) => Promise<Handle>;
+export {};

package/dist/sdk/session-open.js

@@ -0,0 +1,44 @@
+import { AgentError } from '../error.js';
+import { SessionOpenCleanupError } from './session-registry.js';
+import { SessionRuntime } from './session-runtime.js';
+/** The open flow owns unpublished candidates; the registry owns only identity and barriers. */
+export function createSessionOpen(ports) {
+    return async (id, workspace) => {
+        ports.assertAdmission(id);
+        const epoch = ports.epoch(id);
+        return ports.registry.trackOpen(id, async () => {
+            const runtime = await ports.registry.getOrCreate(id, epoch, () => ports.canPublish(id, epoch), async (publish) => {
+                const stored = await ports.getSession(id);
+                const candidate = new SessionRuntime(stored, ports.generation(), ports.createAdapter, ports.hasCustomAdapters);
+                try {
+                    if (stored.source.type === 'user')
+                        await candidate.ensureSubagents(() => ports.openSubagents(id, stored.workspace));
+                    ports.createHandle(id, candidate, stored, workspace);
+                    if (!publish(candidate))
+                        throw new AgentError('MAR_AGENT_SESSION_CLOSING', 'Session is closing.');
+                    return candidate;
+                }
+                catch (error) {
+                    try {
+                        await candidate.disposeSubagents();
+                    }
+                    catch (cleanupError) {
+                        throw new SessionOpenCleanupError(cleanupError);
+                    }
+                    throw error;
+                }
+            });
+            ports.assertAdmission(id);
+            const stored = await ports.getSession(id);
+            ports.assertAdmission(id);
+            if (!ports.canPublish(id, epoch))
+                throw new AgentError('MAR_AGENT_SESSION_CLOSING', 'Session is closing.');
+            if (stored.source.type === 'user' && runtime.subagents === undefined) {
+                await runtime.ensureSubagents(() => ports.openSubagents(id, stored.workspace));
+                if (!ports.canPublish(id, epoch))
+                    throw new AgentError('MAR_AGENT_SESSION_CLOSING', 'Session is closing.');
+            }
+            return ports.createHandle(id, runtime, stored, workspace);
+        });
+    };
+}

package/dist/sdk/session-registry.d.ts

@@ -0,0 +1,17 @@
+/** An identity index and completion barrier; the open flow owns candidate resources. */
+export declare class SessionRegistry<Runtime extends object> {
+    private readonly runtimes;
+    private readonly pending;
+    private readonly opens;
+    get(sessionId: string): Runtime | undefined;
+    values(): IterableIterator<Runtime>;
+    [Symbol.iterator](): IterableIterator<[string, Runtime]>;
+    trackOpen<T>(sessionId: string | undefined, open: () => Promise<T>): Promise<T>;
+    getOrCreate(sessionId: string, epoch: number, canPublish: () => boolean, initialize: (publish: (runtime: Runtime) => boolean) => Promise<Runtime>): Promise<Runtime>;
+    unregister(sessionId: string, runtime: Runtime): void;
+    whenIdle(sessionIds?: readonly string[]): Promise<void>;
+}
+/** Marks candidate cleanup failures without treating normal invalidation as cleanup failure. */
+export declare class SessionOpenCleanupError extends Error {
+    constructor(cause: unknown);
+}

package/dist/sdk/session-registry.js

@@ -0,0 +1,83 @@
+/** An identity index and completion barrier; the open flow owns candidate resources. */
+export class SessionRegistry {
+    runtimes = new Map();
+    pending = new Map();
+    opens = new Map();
+    get(sessionId) {
+        return this.runtimes.get(sessionId);
+    }
+    values() {
+        return this.runtimes.values();
+    }
+    [Symbol.iterator]() {
+        return this.runtimes[Symbol.iterator]();
+    }
+    trackOpen(sessionId, open) {
+        let opens = this.opens.get(sessionId);
+        if (!opens) {
+            opens = new Set();
+            this.opens.set(sessionId, opens);
+        }
+        const group = opens;
+        const pending = Promise.resolve().then(open);
+        group.add(pending);
+        const remove = () => {
+            group.delete(pending);
+            if (group.size === 0 && this.opens.get(sessionId) === group)
+                this.opens.delete(sessionId);
+        };
+        void pending.then(remove, remove);
+        return pending;
+    }
+    getOrCreate(sessionId, epoch, canPublish, initialize) {
+        const existingPending = this.pending.get(sessionId)?.get(epoch);
+        if (existingPending)
+            return existingPending;
+        const existing = this.runtimes.get(sessionId);
+        if (existing)
+            return Promise.resolve(existing);
+        let byEpoch = this.pending.get(sessionId);
+        if (!byEpoch) {
+            byEpoch = new Map();
+            this.pending.set(sessionId, byEpoch);
+        }
+        const epochs = byEpoch;
+        const pending = Promise.resolve().then(() => initialize((runtime) => {
+            if (!canPublish() || this.runtimes.has(sessionId))
+                return false;
+            this.runtimes.set(sessionId, runtime);
+            return true;
+        }));
+        epochs.set(epoch, pending);
+        const removePending = () => {
+            if (epochs.get(epoch) !== pending)
+                return;
+            epochs.delete(epoch);
+            if (epochs.size === 0 && this.pending.get(sessionId) === epochs)
+                this.pending.delete(sessionId);
+        };
+        void pending.then(removePending, removePending);
+        return pending;
+    }
+    unregister(sessionId, runtime) {
+        if (this.runtimes.get(sessionId) === runtime)
+            this.runtimes.delete(sessionId);
+    }
+    async whenIdle(sessionIds) {
+        const selected = sessionIds === undefined ? undefined : new Set(sessionIds);
+        const pending = [...this.opens].flatMap(([sessionId, opens]) => selected === undefined || (sessionId !== undefined && selected.has(sessionId))
+            ? [...opens]
+            : []);
+        pending.push(...[...this.pending].flatMap(([sessionId, epochs]) => selected === undefined || selected.has(sessionId) ? [...epochs.values()] : []));
+        const results = await Promise.allSettled(pending);
+        const failedCleanup = results.find((result) => result.status === 'rejected' && result.reason instanceof SessionOpenCleanupError);
+        if (failedCleanup?.status === 'rejected')
+            throw failedCleanup.reason.cause;
+    }
+}
+/** Marks candidate cleanup failures without treating normal invalidation as cleanup failure. */
+export class SessionOpenCleanupError extends Error {
+    constructor(cause) {
+        super('Session open candidate cleanup failed.', { cause });
+    }
+}

package/dist/sdk/session-runtime.d.ts

@@ -0,0 +1,72 @@
+import { ExtensionRequestSnapshots, type ExtensionRequestSnapshot } from '../extensions/model-request.js';
+import type { ExtensionSessionBackend, SessionInputCoordinator } from '../extensions/session-input.js';
+import type { ExtensionAgentsBackend } from '../extensions/agents.js';
+import type { ModelAdapter } from '../model/contracts.js';
+import type { ModelCredentialProvider } from '../model/configuration.js';
+import type { SessionModelRequest as ModelRequest } from '../session/model-request.js';
+import type { SessionStore } from '../session/store/contracts.js';
+import { type ContextualWorldState } from '../runtime/context/world-state.js';
+import type { SubagentSessionController } from '../subagent/session-controller.js';
+import { TodoStore } from '../tools/agent/todo.js';
+import type { ExecutionResult } from './types.js';
+import type { ResolvedModelConfiguration } from './model-runtime.js';
+import type { SessionExecution, SessionExecutionContext } from './session-execution.js';
+export declare class SessionRuntime {
+    #private;
+    readonly storedSession: Awaited<ReturnType<SessionStore['getSession']>>;
+    readonly scheduleTool: <T>(definition: import("../host.js").ClientToolDefinition | undefined, run: () => Promise<T>) => Promise<T>;
+    constructor(storedSession: Awaited<ReturnType<SessionStore['getSession']>>, generation: number, createAdapter: (modelId: string, models: ReadonlyMap<string, ResolvedModelConfiguration>) => ModelAdapter, hasCustomAdapters: boolean);
+    adapter(modelId: string, models: ReadonlyMap<string, ResolvedModelConfiguration>): ModelAdapter;
+    refreshAdapters(generation: number, retained: ReadonlySet<ModelAdapter>): Promise<void>;
+    static stageModelReconfiguration(sessions: readonly SessionRuntime[], models: ReadonlyMap<string, ResolvedModelConfiguration>, active: ReadonlySet<ModelAdapter>, assertOpen: () => void): Promise<(generation: number) => void>;
+    collectActiveModelAdapters(target: Set<ModelAdapter>): void;
+    collectModelCredentialProviders(target: Set<ModelCredentialProvider>): void;
+    hasModelAdapter(adapter: ModelAdapter): boolean;
+    takeAdaptersForClose(): readonly ModelAdapter[];
+    static closeModelAdapters(sessions: readonly SessionRuntime[]): Promise<void>;
+    retireInputs(): Promise<unknown> | undefined;
+    getOrCreateInputs(create: () => SessionInputCoordinator): SessionInputCoordinator;
+    disposeSubagents(): Promise<unknown> | undefined;
+    get subagents(): SubagentSessionController | undefined;
+    ensureSubagents(open: () => Promise<SubagentSessionController>): Promise<SubagentSessionController>;
+    resetAfterClear(generation: number): void;
+    recordRequest(modelId: string, request: ModelRequest): ExtensionRequestSnapshot;
+    completeRequest(snapshot: ExtensionRequestSnapshot): void;
+    captureRequest(input: Parameters<ExtensionRequestSnapshots['capture']>[0]): ExtensionRequestSnapshot | undefined;
+    resolveRequest(snapshot: ExtensionRequestSnapshot): {
+        modelId: string;
+        request: ModelRequest;
+        view: import("../extensions/model-request.js").ExtensionModelRequest;
+    };
+    withRecordProjection<T>(action: () => Promise<T>): Promise<T>;
+    joinRecordProjection(): Promise<void>;
+    get sourceType(): 'user' | 'subagent';
+    restoreTodo(snapshot: Parameters<typeof TodoStore.restore>[0], retained: boolean): TodoStore;
+    restoreExecutionState(store: Pick<SessionStore, 'readExecutionState' | 'readContextualWorldState' | 'hasRetainedSessionLease'>, writerOwner: object): Promise<{
+        todo: TodoStore;
+        contextRecords: import("../session/record-contract.js").SessionRecord[];
+        generation: string | undefined;
+        world: ContextualWorldState;
+    }>;
+    get sessionBackend(): (ExtensionSessionBackend & {
+        kick(): void;
+    }) | undefined;
+    ensureSessionBackend(create: () => ExtensionSessionBackend & {
+        kick(): void;
+    }): void;
+    get agentsBackend(): ExtensionAgentsBackend | undefined;
+    ensureAgentsBackend(create: () => ExtensionAgentsBackend): void;
+    get execution(): SessionExecutionContext | undefined;
+    bindExecutionContext(context: SessionExecutionContext): void;
+    unbindExecutionContext(context: SessionExecutionContext): void;
+    get contextualWorldState(): ContextualWorldState | undefined;
+    updateContextualWorldState(state: ContextualWorldState): void;
+    get activeExecutionId(): string | undefined;
+    assertCanExecute(): void;
+    registerExecution(execution: SessionExecution): void;
+    deactivateExecution(execution: SessionExecution): void;
+    unregisterExecution(execution: SessionExecution): void;
+    cancelExecution(executionId: string): void;
+    cancelExecutions(): void;
+    joinExecutions(): Promise<PromiseSettledResult<ExecutionResult>[]>;
+}