@myagentroam/agent 0.11.33 → 0.11.34

package/dist/runtime/wait.js

@@ -0,0 +1,82 @@
+import { AgentError } from '../error.js';
+export function createToolWaitInterrupt(pending) {
+    const listeners = new Set();
+    return {
+        pending,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        notify() {
+            for (const listener of listeners)
+                listener();
+        }
+    };
+}
+export function waitMetadata(waitOutcome) {
+    return { waitOutcome, ...(waitOutcome === 'interrupted' ? { reason: 'steer' } : {}) };
+}
+/** All exits release listeners; a ready result wins over steer and the deadline. */
+export function waitForToolCondition(input) {
+    input.signal?.throwIfAborted();
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let unsubscribe = () => { };
+        let unsubscribeInterrupt = () => { };
+        let cancelTimer = () => { };
+        const finish = (outcome, error) => {
+            if (settled)
+                return;
+            settled = true;
+            unsubscribe();
+            unsubscribeInterrupt();
+            cancelTimer();
+            input.signal?.removeEventListener('abort', abort);
+            if (error === undefined)
+                resolve(outcome);
+            else
+                reject(error);
+        };
+        const check = () => {
+            if (input.signal?.aborted)
+                abort();
+            else if (input.ready())
+                finish('ready');
+            else if (input.interrupt?.pending())
+                finish('interrupted');
+        };
+        const abort = () => finish('interrupted', input.signal?.reason ??
+            new AgentError('MAR_AGENT_EXECUTION_CANCELLED', 'Execution cancelled.'));
+        unsubscribe = input.subscribe(check);
+        unsubscribeInterrupt = input.interrupt?.subscribe(check) ?? (() => { });
+        cancelTimer = waitDeadline(input.waitMs, () => {
+            check();
+            finish('timeout');
+        });
+        input.signal?.addEventListener('abort', abort, { once: true });
+        check();
+    });
+}
+/** Explicit waits retain their deadline without overflowing the platform timer. */
+export function waitDeadline(waitMs, finish) {
+    if (waitMs <= 2_147_483_647) {
+        const timer = setTimeout(finish, waitMs);
+        return () => clearTimeout(timer);
+    }
+    const deadline = performance.now() + waitMs;
+    let timer;
+    const tick = () => {
+        const remaining = deadline - performance.now();
+        if (remaining <= 0)
+            finish();
+        else
+            arm(remaining);
+    };
+    const arm = (remaining) => {
+        timer = setTimeout(tick, Math.min(remaining, 2_147_483_647));
+    };
+    arm(waitMs);
+    return () => clearTimeout(timer);
+}

package/dist/sandbox/linux/bubblewrap-sandbox-executor.d.ts

@@ -1,5 +1,5 @@
 import { type ChildProcessWithoutNullStreams } from 'node:child_process';
-import type { LocalProcessExecutor, LocalProcessSpawnRequest } from '../../agent-core/host/local-process-executor.js';
+import type { LocalProcessExecutor, LocalProcessSpawnRequest } from '../../host/local-process-executor.js';
 import { type BubblewrapSandboxExecutorOptions } from './profile.js';
 /** Compiles one process request into the fixed Linux Bubblewrap policy. */
 export declare class BubblewrapSandboxExecutor implements LocalProcessExecutor {

package/dist/sandbox/linux/bubblewrap-sandbox-executor.js

@@ -4,8 +4,8 @@ import { lstat, mkdtemp, realpath, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { isAbsolute, join, posix, relative, resolve, sep } from 'node:path';
 import { promisify } from 'node:util';
-import { MarAgentError } from '../../agent-core/error.js';
-import { prepareLocalShellProcess } from '../../agent-core/host/local-shell.js';
+import { AgentError } from '../../error.js';
+import { prepareLocalShellProcess } from '../../host/local-shell.js';
 import { LINUX_BUBBLEWRAP_SANDBOX_POLICY_VERSION } from './profile.js';
 const execFileAsync = promisify(execFile);
 const DEFAULT_BUBBLEWRAP_PATH = '/usr/bin/bwrap';
@@ -89,7 +89,7 @@ export class BubblewrapSandboxExecutor {
         }
         catch (error) {
             await rm(launchDirectory, { recursive: true, force: true }).catch(() => undefined);
-            throw error instanceof MarAgentError ? error : policyInvalid(error);
+            throw error instanceof AgentError ? error : policyInvalid(error);
         }
         let argumentFd;
         let seccompFd;
@@ -308,7 +308,7 @@ async function validateBackend(path) {
             throw unavailable();
     }
     catch (error) {
-        if (error instanceof MarAgentError)
+        if (error instanceof AgentError)
             throw error;
         throw unavailable(error);
     }
@@ -326,7 +326,7 @@ async function secureDirectory(path) {
         return canonical;
     }
     catch (error) {
-        if (error instanceof MarAgentError)
+        if (error instanceof AgentError)
             throw error;
         throw policyInvalid(error);
     }
@@ -508,7 +508,7 @@ async function prepareNestedMountDestinations(mounts) {
                 throw policyInvalid();
         }
         catch (error) {
-            if (error instanceof MarAgentError)
+            if (error instanceof AgentError)
                 throw error;
             throw policyInvalid(error);
         }
@@ -641,8 +641,8 @@ function withinSandboxPath(parent, candidate) {
     return relation.length > 0 && relation !== '..' && !relation.startsWith('../');
 }
 function unavailable(_cause) {
-    return new MarAgentError('SANDBOX_UNAVAILABLE', 'Bubblewrap sandbox is unavailable.');
+    return new AgentError('SANDBOX_UNAVAILABLE', 'Bubblewrap sandbox is unavailable.');
 }
 function policyInvalid(_cause) {
-    return new MarAgentError('SANDBOX_POLICY_INVALID', 'Sandbox policy is invalid.');
+    return new AgentError('SANDBOX_POLICY_INVALID', 'Sandbox policy is invalid.');
 }

package/dist/sdk/agent.d.ts

@@ -0,0 +1,7 @@
+import { type AgentModelConfiguration } from '../model/configuration.js';
+import type { ModelAdapter } from '../model/contracts.js';
+import type { CreateAgentOptions, Agent } from './types.js';
+/** Validate models before Host negotiation and expose only built-in protocol adapters. */
+export declare function createAgent(options: CreateAgentOptions): Promise<Agent>;
+/** Package-internal seam for deterministic adapter tests; not a package export. */
+export declare function createAgentWithAdapter(options: CreateAgentOptions, adapterFactory?: (configuration: AgentModelConfiguration) => ModelAdapter): Promise<Agent>;

package/dist/sdk/agent.js

@@ -0,0 +1,321 @@
+import { addModelCredentialProviders, resolveAgentModels } from './model-runtime.js';
+import { createSessionOpener } from './session.js';
+import { SessionRuntime } from './session-runtime.js';
+import { SessionRegistry } from './session-registry.js';
+import { SessionMaintenanceCoordinator, completeAgentCleanup } from './session-maintenance.js';
+import { AgentError } from '../error.js';
+import { ExtensionManager } from '../extensions/manager.js';
+import { extensionToolRuntime } from './extension-tool-runtime.js';
+import { ExtensionStore } from '../extensions/store.js';
+import { createExtensionModels } from './extension-models.js';
+import { negotiateHost } from '../host/contracts.js';
+import { toolCallers } from '../tools/callers.js';
+import { AnthropicMessagesAdapter } from '../model/anthropic-messages.js';
+import { OpenAiResponsesAdapter } from '../model/openai-responses.js';
+import { JsonlSessionStore } from '../session/store/jsonl/jsonl-store.js';
+/** Validate models before Host negotiation and expose only built-in protocol adapters. */
+export async function createAgent(options) {
+    if (Object.hasOwn(options, 'adapterFactory'))
+        throw new AgentError('MAR_AGENT_MODEL_CONFIG_INVALID', 'Custom model adapters are not supported.');
+    return createAgentWithAdapter(options);
+}
+/** Package-internal seam for deterministic adapter tests; not a package export. */
+export async function createAgentWithAdapter(options, adapterFactory) {
+    const resolvedModels = resolveAgentModels(options.models);
+    let { models, defaultModelId } = resolvedModels;
+    let modelGeneration = 0;
+    const { credentialProviders } = resolvedModels;
+    let retainedExtensionProviders;
+    const description = negotiateHost(await options.host.describe());
+    if (description.mode !== options.mode)
+        throw new AgentError('MAR_AGENT_HOST_INCOMPATIBLE', 'Host mode does not match Agent mode.');
+    if (options.sessionStore === null)
+        throw new AgentError('MAR_AGENT_SESSION_STORE_INVALID', 'Session store must not be null.');
+    const ownsStore = options.sessionStore === undefined;
+    const store = options.sessionStore ?? (await JsonlSessionStore.open(description.homeDirectory));
+    // The same adapter can be borrowed concurrently by Execution and Extension operations.
+    const activeExecutionAdapters = new Map();
+    const activeAdapterReferences = {
+        add(adapter) {
+            activeExecutionAdapters.set(adapter, (activeExecutionAdapters.get(adapter) ?? 0) + 1);
+        },
+        delete(adapter) {
+            const references = activeExecutionAdapters.get(adapter);
+            if (references === undefined)
+                return;
+            if (references === 1)
+                activeExecutionAdapters.delete(adapter);
+            else
+                activeExecutionAdapters.set(adapter, references - 1);
+        }
+    };
+    const sessionRuntimes = new SessionRegistry();
+    const sessionWriterOwner = {};
+    let disposed = false;
+    let disposal;
+    let maintenanceCoordinator;
+    const assertSessionAdmission = (sessionId) => maintenanceCoordinator.assertAdmission(sessionId);
+    let reconfiguration;
+    const createAdapter = (modelId, configuredModels = models) => {
+        const configuration = configuredModels.get(modelId);
+        if (!configuration)
+            throw new AgentError('MAR_AGENT_MODEL_DISABLED', 'Selected model is unavailable.');
+        return (adapterFactory?.(configuration) ??
+            (configuration.protocol === 'OPENAI_RESPONSES'
+                ? new OpenAiResponsesAdapter(configuration)
+                : new AnthropicMessagesAdapter(configuration)));
+    };
+    const activeSessionIds = () => new Set([...sessionRuntimes].flatMap(([id, runtime]) => runtime.activeExecutionId === undefined ? [] : [id]));
+    const extensions = new ExtensionManager({
+        toolRuntime: extensionToolRuntime,
+        store: (directory, run) => new ExtensionStore(directory).bind(run),
+        ...(options.host.extensionPorts === undefined
+            ? {}
+            : { hostPorts: options.host.extensionPorts }),
+        extensions: options.extensions ?? [],
+        capabilities: [
+            'tools',
+            'prompts',
+            'commands',
+            'clock',
+            'services',
+            'hooks',
+            'observability',
+            'models',
+            'data.state',
+            'data.checkpoint',
+            'data.store',
+            'session',
+            'agents',
+            'settings',
+            ...(options.host.extensionPorts?.environment ? ['environment'] : []),
+            ...(options.host.extensionPorts?.files ? ['files'] : []),
+            ...(options.host.extensionPorts?.network ? ['network'] : []),
+            ...(options.host.extensionPorts?.mcp ? ['mcp'] : []),
+            ...(options.host.extensionPorts?.processes ? ['processes'] : [])
+        ],
+        models: createExtensionModels(() => ({ models, defaultModelId }), createAdapter, activeAdapterReferences, (snapshot, call) => {
+            const runtime = sessionRuntimes.get(call.sessionId);
+            if (!runtime)
+                throw new AgentError('MAR_AGENT_MODEL_SNAPSHOT_INVALID', 'Request snapshot is unavailable.');
+            return runtime.resolveRequest(snapshot);
+        }, options.host.modelUsage === undefined
+            ? undefined
+            : (usage, call) => options.host.modelUsage({
+                ...usage,
+                sessionId: call.sessionId,
+                ...(call.executionId === undefined ? {} : { executionId: call.executionId }),
+                purpose: 'other',
+                agentRole: sessionRuntimes.get(call.sessionId)?.sourceType === 'subagent' ? 'subagent' : 'root'
+            })),
+        sessionBackend: (id) => sessionRuntimes.get(id)?.sessionBackend,
+        agentsBackend: (id) => sessionRuntimes.get(id)?.agentsBackend,
+        scheduleTool: (id) => (definition, run) => {
+            const schedule = sessionRuntimes.get(id)?.scheduleTool;
+            if (!schedule)
+                throw new AgentError('MAR_AGENT_TOOL_NOT_AVAILABLE', 'Session tool scheduler is unavailable.');
+            return schedule(definition, run);
+        },
+        baseTools: (id, context) => {
+            const execution = sessionRuntimes.get(id)?.execution?.toolSources;
+            if (context?.executionId && execution?.executionId === context.executionId)
+                return execution.bindings;
+            return (options.host.extensionPorts?.tools?.catalog(id, context?.executionId) ?? []).map((source) => ({
+                definition: {
+                    ...source.definition,
+                    allowedCallers: [
+                        ...toolCallers({
+                            ...source.definition,
+                            allowedCallers: source.definition.allowedCallers ??
+                                (source.mcp ? ['direct', 'programmatic'] : ['direct'])
+                        })
+                    ]
+                },
+                source: source.source,
+                ...(source.mcp === undefined ? {} : { mcp: source.mcp }),
+                ...(source.available === undefined ? {} : { available: source.available.bind(source) }),
+                invoke: source.execute.bind(source)
+            }));
+        },
+        allowTool: (id, name, definition) => {
+            const runtime = sessionRuntimes.get(id);
+            return !(runtime?.sourceType === 'subagent' && definition?.agentScope === 'ROOT_ONLY');
+        },
+        checkpoint: {
+            read: async (extensionId, key, call) => {
+                call.signal.throwIfAborted();
+                return store.readExtensionCheckpoint(call.sessionId, extensionId, key);
+            },
+            write: (extensionId, key, value, expectedRevision, call) => store.writeExtensionCheckpoint(call.sessionId, extensionId, key, value, expectedRevision, {
+                owner: sessionWriterOwner,
+                signal: call.signal,
+                ...(call.executionId ? { executionId: call.executionId } : {}),
+                ...(call.turnId ? { turnId: call.turnId } : {})
+            })
+        },
+        busyExcept: (sessionId) => [...activeSessionIds()].some((id) => id !== sessionId)
+    });
+    const activeAdaptersExcept = (sessionId) => {
+        const activeAdapters = new Set(activeExecutionAdapters.keys());
+        for (const [candidateSessionId, runtime] of sessionRuntimes)
+            if (candidateSessionId !== sessionId && activeSessionIds().has(candidateSessionId))
+                runtime.collectActiveModelAdapters(activeAdapters);
+        return activeAdapters;
+    };
+    const settings = {
+        ...(options.workspaceMapping === undefined
+            ? {}
+            : { workspaceMapping: options.workspaceMapping }),
+        ...(options.systemInstruction === undefined
+            ? {}
+            : { systemInstruction: options.systemInstruction })
+    };
+    maintenanceCoordinator = new SessionMaintenanceCoordinator(store, sessionRuntimes, extensions, options.host, sessionWriterOwner, () => disposed, () => modelGeneration);
+    const openSession = createSessionOpener({
+        host: options.host,
+        description,
+        settings,
+        store,
+        extensions,
+        agentResources: {
+            activeExecutionAdapters: activeAdapterReferences,
+            sessionRuntimes,
+            sessionWriterOwner
+        },
+        hasCustomAdapters: adapterFactory !== undefined,
+        modelState: () => ({ models, defaultModelId, generation: modelGeneration }),
+        createAdapter,
+        activeAdaptersExcept,
+        openEpoch: (sessionId) => maintenanceCoordinator.epoch(sessionId),
+        canPublishSession: (sessionId, epoch) => maintenanceCoordinator.canPublish(sessionId, epoch),
+        assertSessionAdmission,
+        assertCanStart: (sessionId) => {
+            assertSessionAdmission(sessionId);
+            if (reconfiguration)
+                throw new AgentError('MAR_AGENT_EXECUTION_ACTIVE', 'Models are being reconfigured for the next execution.');
+        }
+    });
+    return {
+        extensionDiagnostics: () => extensions.diagnostics(),
+        createSession: async (input) => {
+            assertSessionAdmission();
+            return sessionRuntimes.trackOpen(undefined, async () => openSession((await store.createSession(input)).id, input.workspace));
+        },
+        openSession: (id) => openSession(id),
+        listSessions: async (input) => {
+            assertSessionAdmission();
+            return store.list(input);
+        },
+        getSession: async (id) => {
+            assertSessionAdmission();
+            return store.getSession(id);
+        },
+        setSessionTitle: async (id, title, input) => {
+            assertSessionAdmission();
+            return store.updateTitle(id, title, { ...input, automatic: input?.automatic ?? false }, sessionWriterOwner);
+        },
+        clearSession: (id) => maintenanceCoordinator.clear(id),
+        setSystemInstruction: (systemInstruction) => {
+            if (disposed)
+                throw new AgentError('MAR_AGENT_DISPOSED', 'Agent is disposed.');
+            if (systemInstruction === undefined)
+                delete settings.systemInstruction;
+            else
+                settings.systemInstruction = systemInstruction;
+        },
+        reconfigureModels: async (input) => {
+            if (disposed)
+                throw new AgentError('MAR_AGENT_DISPOSED', 'Agent is disposed.');
+            if (reconfiguration)
+                throw new AgentError('MAR_AGENT_EXECUTION_ACTIVE', 'Models are already being reconfigured for the next execution.');
+            const next = resolveAgentModels(input.models, input.defaultModelId);
+            const activeSessions = activeSessionIds();
+            if ([...activeSessions].some((sessionId) => sessionRuntimes.get(sessionId)?.sourceType !== 'subagent'))
+                throw new AgentError('MAR_AGENT_EXECUTION_ACTIVE', 'Models cannot be reconfigured while a main execution is active.');
+            const activeAdapters = new Set(activeExecutionAdapters.keys());
+            for (const [sessionId, runtime] of sessionRuntimes)
+                if (activeSessions.has(sessionId))
+                    runtime.collectActiveModelAdapters(activeAdapters);
+            const inactiveRuntimes = [...sessionRuntimes].flatMap(([sessionId, runtime]) => activeSessions.has(sessionId) ? [] : [runtime]);
+            const completion = Promise.withResolvers();
+            reconfiguration = completion.promise;
+            void completion.promise.catch(() => undefined);
+            let interruptedByDisposal = false;
+            try {
+                const commitSessionGeneration = await SessionRuntime.stageModelReconfiguration(inactiveRuntimes, next.models, activeAdapters, () => {
+                    if (disposed) {
+                        interruptedByDisposal = true;
+                        throw new AgentError('MAR_AGENT_DISPOSED', 'Agent is disposed.');
+                    }
+                });
+                // The final admission check and all committed state changes share one synchronous turn.
+                commitSessionGeneration(modelGeneration + 1);
+                if (extensions.hasReferences() || activeSessions.size > 0) {
+                    if (!retainedExtensionProviders ||
+                        retainedExtensionProviders.revision !== extensions.revision) {
+                        const providers = new Set();
+                        for (const configuration of models.values())
+                            addModelCredentialProviders(providers, configuration);
+                        // A pending composition retains its original providers, not every intermediate catalog.
+                        retainedExtensionProviders = { revision: extensions.revision, providers };
+                    }
+                }
+                else {
+                    retainedExtensionProviders = undefined;
+                }
+                models = next.models;
+                defaultModelId = next.defaultModelId;
+                modelGeneration++;
+                for (const provider of next.credentialProviders)
+                    credentialProviders.add(provider);
+                const liveProviders = new Set(next.credentialProviders);
+                for (const provider of retainedExtensionProviders?.providers ?? [])
+                    liveProviders.add(provider);
+                for (const adapter of activeExecutionAdapters.keys())
+                    addModelCredentialProviders(liveProviders, adapter.configuration);
+                for (const runtime of sessionRuntimes.values())
+                    runtime.collectModelCredentialProviders(liveProviders);
+                const obsoleteProviders = [...credentialProviders].filter((provider) => !liveProviders.has(provider));
+                const providerCloseResults = await Promise.allSettled(obsoleteProviders.map(async (provider) => provider.close()));
+                for (const [index, result] of providerCloseResults.entries())
+                    if (result.status === 'fulfilled')
+                        credentialProviders.delete(obsoleteProviders[index]);
+            }
+            catch (error) {
+                if (!interruptedByDisposal)
+                    completion.reject(error);
+                throw error;
+            }
+            finally {
+                completion.resolve();
+                if (reconfiguration === completion.promise)
+                    reconfiguration = undefined;
+            }
+        },
+        deleteSession: (id) => maintenanceCoordinator.delete(id),
+        dispose: () => {
+            if (disposal)
+                return disposal;
+            disposed = true;
+            for (const runtime of sessionRuntimes.values())
+                runtime.cancelExecutions();
+            // Explicit end observers finish in a separate lifecycle frame before Session retirement.
+            const runtimes = [...sessionRuntimes.values()];
+            const pendingReconfiguration = reconfiguration;
+            disposal = completeAgentCleanup([
+                () => sessionRuntimes.whenIdle(),
+                () => maintenanceCoordinator.join(),
+                () => extensions.dispose(),
+                ...runtimes.map((runtime) => () => runtime.retireInputs()),
+                ...runtimes.map((runtime) => () => runtime.disposeSubagents()),
+                () => Promise.all(runtimes.map((runtime) => runtime.joinExecutions())),
+                () => pendingReconfiguration,
+                () => SessionRuntime.closeModelAdapters(runtimes),
+                () => completeAgentCleanup([...credentialProviders].map((provider) => () => provider.close())),
+                () => options.host.dispose(),
+                () => (ownsStore ? store.close() : undefined)
+            ]);
+            return disposal;
+        }
+    };
+}

package/dist/sdk/execution-code-mode.d.ts

@@ -0,0 +1,18 @@
+import type { SessionStore } from '../session/store/contracts.js';
+import type { ClientToolDefinition } from '../tools/contracts.js';
+import type { RoundToolScope } from '../tools/execution.js';
+import type { ExecutionResult } from './types.js';
+/** Retains the Session and its Extension scope while a code cell outlives the caller. */
+export declare function createExecutionCodeModeContext(input: {
+    readonly store: Pick<SessionStore, 'readCodeModeState' | 'retainSessionLease' | 'append' | 'commitCodeModeState'>;
+    readonly sessionId: string;
+    readonly executionId: string;
+    readonly turnId: string;
+    readonly writerOwner: object;
+    readonly supportsImages: boolean;
+    readonly tools: readonly ClientToolDefinition[];
+    permissionStop(callId: string): ExecutionResult['permissionStop'];
+    assertLive(): void;
+    pin(): () => void;
+    cleanupFailed(): void;
+}): NonNullable<RoundToolScope['codeModeContext']>;

package/dist/sdk/execution-code-mode.js

@@ -0,0 +1,51 @@
+import { allowsToolCaller } from '../tools/callers.js';
+/** Retains the Session and its Extension scope while a code cell outlives the caller. */
+export function createExecutionCodeModeContext(input) {
+    return async (call) => {
+        const stateSnapshot = call.name === 'code_exec' ? await input.store.readCodeModeState(input.sessionId) : [];
+        return {
+            retainSession: async () => {
+                input.assertLive();
+                const release = await input.store.retainSessionLease(input.sessionId, input.writerOwner);
+                let unpin;
+                try {
+                    unpin = input.pin();
+                }
+                catch (error) {
+                    try {
+                        await release();
+                    }
+                    catch {
+                        input.cleanupFailed();
+                    }
+                    throw error;
+                }
+                return async () => {
+                    try {
+                        await release();
+                    }
+                    finally {
+                        unpin();
+                    }
+                };
+            },
+            onSettled: async (result) => {
+                await input.store.append(input.sessionId, {
+                    type: 'code.cell.completed',
+                    payload: { ...result, callId: call.callId },
+                    executionId: input.executionId,
+                    turnId: input.turnId
+                });
+            },
+            supportsImages: input.supportsImages,
+            permissionStop: () => input.permissionStop(call.callId),
+            tools: input.tools.filter((tool) => allowsToolCaller(tool, 'programmatic')),
+            state: stateSnapshot,
+            commitState: (mutations) => input.store.commitCodeModeState(input.sessionId, mutations, {
+                executionId: input.executionId,
+                turnId: input.turnId,
+                expectedState: stateSnapshot
+            })
+        };
+    };
+}

package/dist/sdk/execution-compact-commit.d.ts

@@ -0,0 +1,23 @@
+import type { SessionModelMessage } from '../session/model-request.js';
+import type { SessionRecord } from '../session/record-contract.js';
+import type { SessionStore, SessionStoreCompactInput } from '../session/store/contracts.js';
+import type { ResourceInputProjection } from './resource-input.js';
+/** Commits one validated snapshot and records its fact before fallible live projection. */
+export declare function commitExecutionCompaction(input: {
+    readonly store: Pick<SessionStore, 'compact'>;
+    readonly sessionId: string;
+    readonly signal: AbortSignal;
+    readonly prefix: readonly SessionModelMessage[];
+    readonly messages: readonly SessionModelMessage[];
+    readonly generation: string | undefined;
+    readonly messageSources: WeakMap<SessionModelMessage, SessionRecord>;
+    draft(): Omit<SessionStoreCompactInput, 'retainedModelContext' | 'inlineMediaState'>;
+    readonly checkpoint: ResourceInputProjection['checkpoint'];
+    readonly withProjection: <T>(action: () => Promise<T>) => Promise<T>;
+    readonly currentGeneration: () => string | undefined;
+    readonly recordCommit: (recordId: string) => void;
+    readonly replace: (retained: SessionModelMessage[]) => void;
+}): Promise<{
+    record: SessionRecord;
+    retained: SessionModelMessage[];
+}>;

package/dist/sdk/execution-compact-commit.js

@@ -0,0 +1,41 @@
+import { AgentError } from '../error.js';
+/** Commits one validated snapshot and records its fact before fallible live projection. */
+export async function commitExecutionCompaction(input) {
+    return input.withProjection(async () => {
+        input.signal.throwIfAborted();
+        if (input.currentGeneration() !== input.generation ||
+            input.prefix.some((message, index) => input.messages[index] !== message))
+            throw new AgentError('MAR_AGENT_COMPACT_STALE', 'The compaction prefix has changed.');
+        const retained = input.messages
+            .slice(input.prefix.length)
+            .filter((message) => message.contextKind !== 'private' || message.role === 'provider');
+        const retainedModelContext = retained.map((message) => {
+            const source = input.messageSources.get(message);
+            const saved = source?.type === 'model.context' && source.payload.inputRef
+                ? source.payload
+                : source?.type === 'compact.completed'
+                    ? (source.payload
+                        .retainedModelContext ?? []).find((item) => item.inputRef === message.metadata?.recordId)
+                    : undefined;
+            return saved
+                ? {
+                    ...saved,
+                    ...(message.metadata ? { metadata: message.metadata } : {})
+                }
+                : {
+                    ...message,
+                    ...(message.images?.length
+                        ? { images: message.images.map(({ dataBase64: _bytes, ...image }) => image) }
+                        : {})
+                };
+        });
+        const record = await input.store.compact(input.sessionId, {
+            ...input.draft(),
+            inlineMediaState: input.checkpoint(retained),
+            retainedModelContext
+        }, { signal: input.signal });
+        input.recordCommit(record.recordId);
+        input.replace(retained);
+        return { record, retained };
+    });
+}

package/dist/sdk/execution-compact-extension.d.ts

@@ -0,0 +1,12 @@
+import { type ExtensionCompactContext, type ExtensionCompactResult } from '../extensions/compaction.js';
+import type { SessionModelMessage } from '../session/model-request.js';
+import type { CompactionOperation } from '../runtime/compaction/operation.js';
+import type { ModelRequestUsage } from '../model/usage-observer.js';
+/** Bounds Extension diagnostics and validates its candidate before native fallback. */
+export declare function createExecutionCompactExtension(ports: {
+    readonly contextWindowTokens: number;
+    readonly maxOutputTokens: number;
+    hasInterceptor(): boolean;
+    invoke(context: Omit<ExtensionCompactContext, 'operationId'>, signal: AbortSignal): Promise<ExtensionCompactResult | undefined>;
+    reportUsage?: (usage: ModelRequestUsage) => void | Promise<void>;
+}): (history: readonly SessionModelMessage[], reason: "manual" | "automatic", focus: string | undefined, compaction: CompactionOperation) => Promise<ExtensionCompactResult | undefined>;