@myagentroam/agent 0.11.33 → 0.11.35

package/dist/sdk/session-runtime.js

@@ -0,0 +1,205 @@
+import { AgentError } from '../error.js';
+import { ExtensionRequestSnapshots } from '../extensions/model-request.js';
+import { latestContextualWorldStateGeneration, parsePersistedContextualWorldState } from '../runtime/context/world-state.js';
+import { TodoStore } from '../tools/agent/todo.js';
+import { createSessionToolScheduler } from '../tools/scheduler.js';
+import { SessionModelAdapters } from './session-model-adapters.js';
+export class SessionRuntime {
+    storedSession;
+    #executionContext;
+    #todo;
+    scheduleTool = createSessionToolScheduler();
+    #modelAdapters;
+    #contextualWorldState;
+    #subagents;
+    #subagentsOpening;
+    #inputs;
+    #requestSnapshots;
+    #recordProjection;
+    #sessionBackend;
+    #agentsBackend;
+    #executions = new Map();
+    #activeExecutionId;
+    constructor(storedSession, generation, createAdapter, hasCustomAdapters) {
+        this.storedSession = storedSession;
+        this.#modelAdapters = new SessionModelAdapters(generation, createAdapter, hasCustomAdapters);
+    }
+    adapter(modelId, models) {
+        return this.#modelAdapters.getOrCreate(modelId, models);
+    }
+    refreshAdapters(generation, retained) {
+        return this.#modelAdapters.refresh(generation, retained);
+    }
+    static stageModelReconfiguration(sessions, models, active, assertOpen) {
+        return SessionModelAdapters.stageReconfiguration(sessions.map((session) => session.#modelAdapters), models, active, assertOpen);
+    }
+    collectActiveModelAdapters(target) {
+        this.#modelAdapters.collectActiveReferences(target);
+    }
+    collectModelCredentialProviders(target) {
+        this.#modelAdapters.collectCredentialProviders(target);
+    }
+    hasModelAdapter(adapter) {
+        return this.#modelAdapters.hasReference(adapter);
+    }
+    takeAdaptersForClose() {
+        return this.#modelAdapters.drain();
+    }
+    static closeModelAdapters(sessions) {
+        return SessionModelAdapters.closeSessions(sessions.map((session) => session.#modelAdapters));
+    }
+    retireInputs() {
+        return this.#inputs?.retire();
+    }
+    getOrCreateInputs(create) {
+        return (this.#inputs ??= create());
+    }
+    disposeSubagents() {
+        return this.#subagents?.dispose();
+    }
+    get subagents() {
+        return this.#subagents;
+    }
+    async ensureSubagents(open) {
+        if (this.#subagents)
+            return this.#subagents;
+        const pending = (this.#subagentsOpening ??= open());
+        try {
+            return (this.#subagents = await pending);
+        }
+        finally {
+            if (this.#subagentsOpening === pending)
+                this.#subagentsOpening = undefined;
+        }
+    }
+    resetAfterClear(generation) {
+        this.#modelAdapters.setGeneration(generation);
+        this.#todo = undefined;
+        this.#subagents = undefined;
+        this.#subagentsOpening = undefined;
+        this.#contextualWorldState = undefined;
+        this.#inputs = undefined;
+        this.#requestSnapshots = undefined;
+    }
+    recordRequest(modelId, request) {
+        return (this.#requestSnapshots ??= new ExtensionRequestSnapshots()).record(modelId, request);
+    }
+    completeRequest(snapshot) {
+        this.#requestSnapshots?.complete(snapshot);
+    }
+    captureRequest(input) {
+        return this.#requestSnapshots?.capture(input);
+    }
+    resolveRequest(snapshot) {
+        if (!this.#requestSnapshots)
+            throw new AgentError('MAR_AGENT_MODEL_SNAPSHOT_INVALID', 'Request snapshot is unavailable.');
+        return this.#requestSnapshots.resolve(snapshot);
+    }
+    async withRecordProjection(action) {
+        const pending = (this.#recordProjection ?? Promise.resolve())
+            .catch(() => undefined)
+            .then(action);
+        this.#recordProjection = pending;
+        try {
+            return await pending;
+        }
+        finally {
+            if (this.#recordProjection === pending)
+                this.#recordProjection = undefined;
+        }
+    }
+    async joinRecordProjection() {
+        await this.#recordProjection?.catch(() => undefined);
+    }
+    get sourceType() {
+        return this.storedSession.source.type;
+    }
+    restoreTodo(snapshot, retained) {
+        if (!retained)
+            this.#todo = TodoStore.restore(snapshot);
+        return (this.#todo ??= TodoStore.restore(snapshot));
+    }
+    async restoreExecutionState(store, writerOwner) {
+        const sessionId = this.storedSession.id;
+        const state = await store.readExecutionState(sessionId);
+        const todo = this.restoreTodo(state.todo, store.hasRetainedSessionLease(sessionId, writerOwner));
+        const generation = latestContextualWorldStateGeneration(state.contextRecords);
+        const persisted = parsePersistedContextualWorldState(await store.readContextualWorldState(sessionId));
+        const world = this.#contextualWorldState?.generation === generation &&
+            this.#contextualWorldState !== undefined
+            ? this.#contextualWorldState
+            : persisted?.generation === generation && persisted !== undefined
+                ? persisted
+                : {
+                    generation,
+                    initialized: false,
+                    instructionSnapshot: undefined,
+                    resourceSnapshot: undefined,
+                    entries: []
+                };
+        this.#contextualWorldState = world;
+        return { todo, contextRecords: state.contextRecords, generation, world };
+    }
+    get sessionBackend() {
+        return this.#sessionBackend;
+    }
+    ensureSessionBackend(create) {
+        this.#sessionBackend ??= create();
+    }
+    get agentsBackend() {
+        return this.#agentsBackend;
+    }
+    ensureAgentsBackend(create) {
+        this.#agentsBackend ??= create();
+    }
+    get execution() {
+        return this.#executionContext;
+    }
+    bindExecutionContext(context) {
+        this.#executionContext = context;
+    }
+    unbindExecutionContext(context) {
+        if (this.#executionContext === context)
+            this.#executionContext = undefined;
+    }
+    get contextualWorldState() {
+        return this.#contextualWorldState;
+    }
+    updateContextualWorldState(state) {
+        this.#contextualWorldState = state;
+    }
+    get activeExecutionId() {
+        return this.#activeExecutionId;
+    }
+    assertCanExecute() {
+        if (this.#activeExecutionId !== undefined)
+            throw new AgentError('MAR_AGENT_EXECUTION_ACTIVE', 'Session already has an active execution.');
+    }
+    registerExecution(execution) {
+        this.assertCanExecute();
+        this.#executions.set(execution.executionId, execution);
+        this.#activeExecutionId = execution.executionId;
+    }
+    deactivateExecution(execution) {
+        if (this.#executions.get(execution.executionId) === execution &&
+            this.#activeExecutionId === execution.executionId)
+            this.#activeExecutionId = undefined;
+    }
+    unregisterExecution(execution) {
+        if (this.#executions.get(execution.executionId) === execution)
+            this.#executions.delete(execution.executionId);
+    }
+    cancelExecution(executionId) {
+        this.#executions.get(executionId)?.cancel();
+    }
+    cancelExecutions() {
+        for (const execution of this.#executions.values())
+            execution.cancel();
+    }
+    joinExecutions() {
+        return Promise.allSettled([...this.#executions.values()].flatMap((execution) => {
+            const result = execution.join();
+            return result === undefined ? [] : [result];
+        }));
+    }
+}

package/dist/sdk/session.d.ts

@@ -0,0 +1,3 @@
+import type { InternalAgentSession, SessionServices } from './session-composition.js';
+/** SDK Session orchestration owns warm resources; Runtime owns only the model/tool loop. */
+export declare function createSessionOpener(services: SessionServices): (id: string, workspace?: string) => Promise<InternalAgentSession>;

package/dist/sdk/session.js

@@ -0,0 +1,313 @@
+import { createExtensionSessionLaunch, extensionInputSource } from './extension-session-launch.js';
+import { createSessionExecutionFactory } from './session-execution-factory.js';
+import { createSessionExtensionMessages } from './session-extension-messages.js';
+import { createSessionExtensionPrompt } from './session-extension-prompt.js';
+import { createSubagentBackend } from './subagent-backend.js';
+import { AgentError } from '../error.js';
+import { SessionInputCoordinator, recordSessionInputCommit } from '../extensions/session-input.js';
+import { buildSystemPromptSections } from '../prompts/index.js';
+import { childSubagentInstruction } from '../prompts/subagent.js';
+import { DEFAULT_COMPACTION_FOCUS } from '../runtime/compaction/history.js';
+import { restoreEnvironmentState } from '../runtime/context/environment.js';
+import { SubagentSessionController } from '../subagent/session-controller.js';
+import { allowsDirectTool } from '../tools/callers.js';
+import { createExtensionAgentsBackend } from './extension-agents.js';
+import { createExtensionSessionBackend } from './extension-session.js';
+import { createSessionOpen } from './session-open.js';
+function restoreSubagentOrigin(origin) {
+    return { ...origin.correlation, signal: origin.signal };
+}
+/** SDK Session orchestration owns warm resources; Runtime owns only the model/tool loop. */
+export function createSessionOpener(services) {
+    const { host, description, settings, store, createAdapter, activeAdaptersExcept } = services;
+    const { activeExecutionAdapters, sessionRuntimes, sessionWriterOwner } = services.agentResources;
+    const openSession = createSessionOpen({
+        registry: sessionRuntimes,
+        getSession: (id) => store.getSession(id),
+        generation: () => services.modelState().generation,
+        createAdapter,
+        hasCustomAdapters: services.hasCustomAdapters,
+        openSubagents: (id, workspace) => SubagentSessionController.open({
+            parentSessionId: id,
+            rootSessionId: id,
+            backend: createSubagentBackend(store, workspace)
+        }),
+        assertAdmission: services.assertSessionAdmission,
+        epoch: services.openEpoch,
+        canPublish: services.canPublishSession,
+        createHandle: (id, runtime, stored, workspace) => createSessionHandle(id, runtime, stored, workspace)
+    });
+    const createSessionHandle = (sessionId, sessionRuntime, storedSession, workspace) => {
+        const storedWorkspace = storedSession.workspace;
+        const sessionSource = storedSession.source;
+        const logicalWorkspace = settings.workspaceMapping?.logicalPath ?? workspace ?? storedWorkspace ?? '';
+        const instructionWorkspace = settings.workspaceMapping?.physicalPath ?? workspace ?? storedWorkspace ?? '';
+        const currentEnvironment = {
+            platform: description.platform,
+            ...(description.architecture ? { architecture: description.architecture } : {}),
+            ...(description.shell ? { shell: description.shell } : {}),
+            ...(description.guaranteedCommands
+                ? { guaranteedCommands: description.guaranteedCommands }
+                : {}),
+            workspace: logicalWorkspace
+        };
+        if (!restoreEnvironmentState({ version: 1, state: currentEnvironment }))
+            throw new AgentError('MAR_AGENT_HOST_INCOMPATIBLE', 'Host environment facts are invalid or exceed the context limit.');
+        const buildSessionPromptSections = (availableTools, promptMode, selectedModel, executionSystemInstruction, skillCatalog) => buildSystemPromptSections({
+            mode: promptMode,
+            platform: description.platform,
+            ...(description.architecture ? { architecture: description.architecture } : {}),
+            ...(description.shell ? { shell: description.shell } : {}),
+            ...(description.guaranteedCommands
+                ? { guaranteedCommands: description.guaranteedCommands }
+                : {}),
+            workspace: logicalWorkspace,
+            tools: availableTools
+                .filter((tool) => !tool.name.startsWith('mcp__'))
+                .map((tool) => tool.name),
+            directTools: availableTools
+                .filter((tool) => !tool.name.startsWith('mcp__') &&
+                allowsDirectTool(tool, availableTools.some((candidate) => candidate.name === 'code_exec')))
+                .map((tool) => tool.name),
+            extension: executionSystemInstruction
+        }).concat([
+            { id: 'core:skill-catalog', text: skillCatalog || null },
+            {
+                id: 'core:child-instructions',
+                text: sessionSource.type === 'subagent' ? childSubagentInstruction || null : null
+            }
+        ]);
+        const sessionAdapter = (modelId, configuredModels) => {
+            return sessionRuntime.adapter(modelId, configuredModels);
+        };
+        const refreshSessionAdapters = async (generation) => {
+            const retainedByActiveSessions = activeAdaptersExcept(sessionId);
+            await sessionRuntime.refreshAdapters(generation, retainedByActiveSessions);
+        };
+        const sessionInputs = () => sessionRuntime.getOrCreateInputs(() => new SessionInputCoordinator((receipt) => services.extensions.session(sessionId)?.diagnose({
+            code: receipt.errorCode ?? 'MAR_AGENT_SESSION_INPUT_FAILED',
+            operationId: receipt.operationId,
+            sessionId
+        })));
+        // Only physical record commits and projection replacement enter this lane, never Hooks.
+        const withRecordProjection = (action) => sessionRuntime.withRecordProjection(action);
+        const appendExtensionMessage = async (entry, request, call) => {
+            call.signal.throwIfAborted();
+            const release = await store.acquireSessionWriteLease(sessionId, sessionWriterOwner);
+            try {
+                return await withRecordProjection(async () => {
+                    call.signal.throwIfAborted();
+                    const message = projectAppendedModelMessage(request.input);
+                    const record = await store.append(sessionId, {
+                        type: message ? 'model.context' : 'session.notice',
+                        payload: {
+                            ...(message ?? {
+                                content: request.input.content,
+                                textBlocks: request.input.textBlocks
+                            }),
+                            source: extensionInputSource(call, request.input.attribution)
+                        },
+                        ...(call.executionId ? { executionId: call.executionId } : {}),
+                        ...(call.turnId ? { turnId: call.turnId } : {})
+                    }, { signal: call.signal });
+                    const result = {
+                        changed: true,
+                        modelChanged: !!message,
+                        recordId: record.recordId,
+                        ...(call.executionId ? { executionId: call.executionId } : {})
+                    };
+                    recordSessionInputCommit(entry, result);
+                    if (message)
+                        sessionRuntime.execution?.appendedMessages?.append(record.recordId, message);
+                    return result;
+                });
+            }
+            finally {
+                await release();
+            }
+        };
+        const execution = createSessionExecutionFactory({
+            assertCanStart: services.assertCanStart,
+            extensions: services.extensions,
+            baseTools: services.extensions.options.baseTools,
+            hasCustomAdapters: services.hasCustomAdapters,
+            modelState: services.modelState,
+            host,
+            store,
+            description,
+            settings,
+            sessionWriterOwner,
+            activeExecutionAdapters,
+            sessionId,
+            sessionRuntime,
+            sessionSource,
+            logicalWorkspace,
+            instructionWorkspace,
+            currentEnvironment,
+            buildSessionPromptSections,
+            sessionAdapter,
+            refreshSessionAdapters,
+            sessionInputs,
+            withRecordProjection,
+            appendExtensionMessage,
+            startSubagentTurn: async (id, input) => (await openSession(id)).startSubagentTurn(input)
+        });
+        sessionRuntime.ensureSessionBackend(() => createExtensionSessionBackend({
+            describe: async (call) => {
+                call.signal.throwIfAborted();
+                const defaults = sessionRuntime.execution;
+                const state = defaults ?? services.modelState();
+                const modelId = defaults?.modelId ?? services.modelState().defaultModelId;
+                const current = await store.getSession(sessionId);
+                const userTurns = await store.userTurnCount(sessionId);
+                call.signal.throwIfAborted();
+                const model = state.models.get(modelId);
+                if (!model)
+                    throw new AgentError('MAR_AGENT_MODEL_DISABLED', 'Selected model is unavailable.');
+                return {
+                    sessionId,
+                    ...(logicalWorkspace ? { cwd: logicalWorkspace, root: logicalWorkspace } : {}),
+                    modelId,
+                    modelName: model.name,
+                    startedAt: Date.parse(current.createdAt),
+                    source: structuredClone(sessionSource),
+                    userTurns
+                };
+            },
+            composePrompt: createSessionExtensionPrompt({
+                sessionId,
+                source: sessionSource.type,
+                home: description.homeDirectory,
+                workspace: instructionWorkspace,
+                displayWorkspace: logicalWorkspace,
+                codeExecute: description.capabilities.includes('code.execute'),
+                host,
+                execution: () => sessionRuntime.execution,
+                models: () => services.modelState(),
+                instruction: () => settings.systemInstruction,
+                workspaceMapped: () => settings.workspaceMapping !== undefined,
+                capture: (call) => services.extensions.session(sessionId)?.capture(call),
+                sections: buildSessionPromptSections
+            }),
+            captureRequest: async (call, input) => {
+                call.signal.throwIfAborted();
+                return sessionRuntime.captureRequest(input);
+            },
+            sessionId,
+            coordinator: sessionInputs,
+            activeExecutionId: () => sessionRuntime.activeExecutionId,
+            append: appendExtensionMessage,
+            messages: createSessionExtensionMessages({
+                sessionId,
+                store,
+                agents: () => sessionRuntime.agentsBackend,
+                runtime: (id) => sessionRuntimes.get(id),
+                models: () => services.modelState()
+            }),
+            launch: createExtensionSessionLaunch(sessionSource.type, execution),
+            diagnose: (code, operationId) => services.extensions.session(sessionId)?.diagnose({ code, operationId, sessionId })
+        }));
+        if (sessionSource.type === 'user')
+            sessionRuntime.ensureAgentsBackend(() => createExtensionAgentsBackend({
+                existingController: () => sessionRuntime.subagents,
+                controller: async () => {
+                    // Access to managed children is not a new Execution admission for their parent.
+                    services.assertCanStart();
+                    if (sessionRuntime.subagents === undefined)
+                        await openSession(sessionId);
+                    if (!sessionRuntime.subagents)
+                        throw new AgentError('MAR_AGENT_SUBAGENT_FAILED', 'Session task controller is unavailable.');
+                    return sessionRuntime.subagents;
+                },
+                parent: (controller, call) => {
+                    const current = call.executionId === undefined
+                        ? undefined
+                        : controller.parentExecution(call.executionId);
+                    if (call.executionId !== undefined && !current)
+                        throw new AgentError('MAR_AGENT_SUBAGENT_FAILED', 'Parent Execution source is unavailable.');
+                    const state = services.modelState();
+                    const selected = state.models.get(state.defaultModelId);
+                    return {
+                        ...(current ?? {
+                            modelId: selected.id,
+                            reasoningEffort: selected.defaultReasoningEffort,
+                            models: state.models,
+                            emitTerminal: async () => { },
+                            startTurn: async (turn) => {
+                                const child = await openSession(turn.sessionId);
+                                return child.startSubagentTurn({
+                                    prompt: turn.prompt,
+                                    modelId: turn.modelId,
+                                    reasoningEffort: turn.reasoningEffort,
+                                    role: turn.role,
+                                    initialMailbox: turn.initialMailbox,
+                                    turnId: turn.turnId,
+                                    ...(turn.origin === undefined
+                                        ? {}
+                                        : { origin: restoreSubagentOrigin(turn.origin) }),
+                                    ...(turn.delivery === undefined ? {} : { delivery: turn.delivery })
+                                });
+                            }
+                        }),
+                        operationId: call.operationId,
+                        origin: { signal: call.signal, correlation: call },
+                        signal: call.signal,
+                        ...(call.ownerInstanceId === undefined
+                            ? {}
+                            : { ownerInstanceId: call.ownerInstanceId }),
+                        ...(call.extensionId === undefined ? {} : { extensionId: call.extensionId })
+                    };
+                }
+            }));
+        return {
+            id: sessionId,
+            run: (input) => execution('run', input),
+            plan: (input) => execution('plan', input),
+            steer: (input) => sessionRuntime.execution?.steer?.(input) ?? Promise.resolve({ status: 'notAccepted' }),
+            compact: (input = {}) => {
+                const requests = sessionRuntime.execution?.compactRequests;
+                if (requests) {
+                    services.assertSessionAdmission(sessionId);
+                    return requests.request(input);
+                }
+                return execution('compact', {
+                    prompt: input.prompt ?? DEFAULT_COMPACTION_FOCUS,
+                    ...input
+                });
+            },
+            cancel: async (executionId) => sessionRuntime.cancelExecution(executionId),
+            startSubagentTurn: (turn) => execution(turn.role === 'explore' ? 'plan' : 'run', {
+                prompt: turn.prompt,
+                modelId: turn.modelId,
+                reasoningEffort: turn.reasoningEffort,
+                ...(turn.permissionMode === undefined ? {} : { permissionMode: turn.permissionMode })
+            }, {
+                publishHostEvents: false,
+                ...(turn.origin === undefined ? {} : { signal: turn.origin.signal }),
+                inputSource: turn.origin === undefined ? 'parent_agent' : 'extension',
+                ...(turn.origin === undefined
+                    ? {}
+                    : { extensionSource: extensionInputSource(turn.origin) }),
+                initialMailbox: turn.initialMailbox,
+                turnId: turn.turnId,
+                ...(turn.mcpExecutionScopeId === undefined
+                    ? {}
+                    : { mcpExecutionScopeId: turn.mcpExecutionScopeId }),
+                ...(turn.delivery ? { delivery: turn.delivery } : {})
+            })
+        };
+    };
+    return openSession;
+}
+function projectAppendedModelMessage(input) {
+    if (input.visibility === 'transcript')
+        return undefined;
+    return {
+        role: 'user',
+        contextKind: 'contextual',
+        content: input.content,
+        ...(input.textBlocks === undefined
+            ? {}
+            : { textBlocks: input.textBlocks.map((block) => ({ text: block.text })) })
+    };
+}

package/dist/sdk/subagent-backend.d.ts

@@ -0,0 +1,3 @@
+import type { SessionStore } from '../session/store/contracts.js';
+import type { SubagentSessionControllerBackend } from '../subagent/session-controller.js';
+export declare function createSubagentBackend(store: Pick<SessionStore, 'createSession' | 'delete' | 'listSubagentChildren' | 'getSession' | 'read'>, workspace: string): SubagentSessionControllerBackend;

package/dist/sdk/subagent-backend.js

@@ -0,0 +1,49 @@
+import { AgentError } from '../error.js';
+export function createSubagentBackend(store, workspace) {
+    return {
+        createSession: async (input) => {
+            const session = await store.createSession({
+                workspace,
+                title: input.title,
+                source: input.source
+            });
+            return { id: session.id };
+        },
+        deleteSession: async (sessionId) => {
+            await store.delete(sessionId);
+        },
+        listChildren: async (parentSessionId) => {
+            const sessions = await store.listSubagentChildren(parentSessionId);
+            return sessions.map((session) => ({
+                id: session.id,
+                createdAt: session.createdAt,
+                lastActivityAt: session.lastActivityAt,
+                source: session.source
+            }));
+        },
+        loadChild: async (parentSessionId, childSessionId) => {
+            try {
+                const session = await store.getSession(childSessionId);
+                if (session.source.type !== 'subagent' ||
+                    session.source.parentSessionId !== parentSessionId)
+                    return undefined;
+                return {
+                    id: session.id,
+                    createdAt: session.createdAt,
+                    lastActivityAt: session.lastActivityAt,
+                    source: session.source,
+                    records: await store.read(session.id)
+                };
+            }
+            catch (error) {
+                if (error instanceof AgentError && error.code === 'MAR_AGENT_SESSION_NOT_FOUND') {
+                    // A history read failure is not proof that the child was deleted.
+                    const children = await store.listSubagentChildren(parentSessionId);
+                    if (!children.some((child) => child.id === childSessionId))
+                        return undefined;
+                }
+                throw error;
+            }
+        }
+    };
+}

package/dist/sdk/types.d.ts

@@ -0,0 +1,80 @@
+import type { AgentHost } from '../host/contracts.js';
+import type { ExtensionSource, AgentExtension } from '../extensions/contracts.js';
+import type { AgentModelConfiguration } from '../model/configuration.js';
+import type { RunInput } from '../runtime/contracts.js';
+import type { CompactInput, ExecutionHandle } from '../runtime/execution-handle.js';
+import type { AgentSessionPage, AgentSessionSummary } from '../session/catalog.js';
+import type { SessionListInput, SessionSource, SessionTitleUpdateInput } from '../session/types.js';
+export interface CreateSessionInput {
+    workspace: string;
+    title?: string;
+}
+export type { SessionTitleUpdateInput } from '../session/types.js';
+export type { HostExecutionExtensions, HostSessionResourceSnapshot, HostSkill, AgentHost } from '../host/contracts.js';
+export type { ExecutionMode, ExecutionResult, AgentImageMetadata, RunInput, RunInputImage } from '../runtime/contracts.js';
+export type { AgentEvent, AgentEventBase } from '../runtime/events.js';
+export type { CompactInput, ExecutionHandle } from '../runtime/execution-handle.js';
+export type { CodeCellEventData, ExecOutputSnapshot, AgentToolArtifact, AgentToolImageArtifact, McpCatalogTool, McpToolCallContext, McpToolCatalog, McpToolCatalogContext, ToolCall, ToolExecutionContext, ToolExecutionResult } from '../tools/contracts.js';
+export interface SteerInput {
+    readonly expectedExecutionId: string;
+    readonly prompt: string;
+    readonly modelText?: string;
+    readonly clientMessageId: string;
+    readonly images?: RunInput['images'];
+}
+export type SteerResult = {
+    readonly status: 'accepted';
+    readonly entry: Extract<import('../session/catalog.js').AgentSessionHistoryEntry, {
+        kind: 'user';
+    }>;
+} | {
+    readonly status: 'handled';
+} | {
+    readonly status: 'notAccepted';
+};
+/** A persisted Session permits one active main execution at a time. */
+export interface AgentSession {
+    readonly id: string;
+    run(input: RunInput): ExecutionHandle;
+    plan(input: RunInput): ExecutionHandle;
+    steer(input: SteerInput): Promise<SteerResult>;
+    compact(input?: CompactInput): ExecutionHandle;
+    cancel(executionId: string): Promise<void>;
+}
+export interface Agent {
+    extensionDiagnostics(): readonly import('../extensions/contracts.js').ExtensionDiagnostic[];
+    createSession(input: CreateSessionInput): Promise<AgentSession>;
+    openSession(sessionId: string): Promise<AgentSession>;
+    listSessions(input?: SessionListInput): Promise<AgentSessionPage>;
+    getSession(sessionId: string): Promise<AgentSessionSummary & {
+        automaticTitlePending: boolean;
+    }>;
+    setSessionTitle(sessionId: string, title: string, input?: SessionTitleUpdateInput): Promise<boolean>;
+    clearSession(sessionId: string): Promise<void>;
+    /** Updates future execution snapshots only; undefined clears the Host instruction extension. */
+    setSystemInstruction(systemInstruction?: string): void;
+    /** Rebinds future main executions only; running subagents keep their captured model providers. */
+    reconfigureModels(input: {
+        readonly models: readonly AgentModelConfiguration[];
+        readonly defaultModelId?: string;
+    }): Promise<void>;
+    deleteSession(sessionId: string): Promise<void>;
+    /** Joins executions/reconfiguration, closes owned resources, and releases borrowed Store leases. */
+    dispose(): Promise<void>;
+}
+export interface CreateAgentOptions {
+    /** Ready-to-use borrowed Store. The caller closes it after all Agent/Catalog users finish. */
+    sessionStore?: import('../session/store/contracts.js').SessionStore;
+    mode: 'normal' | 'node';
+    host: AgentHost;
+    models: readonly AgentModelConfiguration[];
+    defaultModelId?: string;
+    systemInstruction?: string;
+    workspaceMapping?: {
+        readonly logicalPath: string;
+        readonly physicalPath: string;
+    };
+    /** Trusted extensions or an extension source to compose into this Agent. */
+    extensions?: readonly AgentExtension[] | ExtensionSource;
+}
+export type { AgentSessionSummary, SessionListInput, SessionSource };

package/dist/sdk/types.js

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