@myagentroam/agent 0.11.32 → 0.11.34

package/dist/extensions/session-tools.js

@@ -0,0 +1,208 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
+import { AgentError } from '../error.js';
+import { ExtensionResourceScope } from './resources.js';
+import { ExtensionTools } from './tools.js';
+/** One Session's tool catalog, references, attempt lineage, and invocation frames. */
+export class ExtensionSessionTools {
+    toolRuntime;
+    operations;
+    hooks;
+    baseTools;
+    allowTool;
+    scheduleTool;
+    assertLive;
+    isRetired;
+    constructor(toolRuntime, operations, hooks, baseTools, allowTool, scheduleTool, assertLive, isRetired) {
+        this.toolRuntime = toolRuntime;
+        this.operations = operations;
+        this.hooks = hooks;
+        this.baseTools = baseTools;
+        this.allowTool = allowTool;
+        this.scheduleTool = scheduleTool;
+        this.assertLive = assertLive;
+        this.isRetired = isRetired;
+    }
+    #toolRefs = new WeakMap();
+    tools = new ExtensionTools((binding, stage) => Object.freeze({
+        ...binding,
+        invoke: (input, call) => this.toolAttempt(input, call, stage, async () => {
+            this.assertToolAvailable(binding, call);
+            this.toolRuntime.currentPermissions(call)?.assertDispatch();
+            const invoke = () => {
+                this.assertToolAvailable(binding, call);
+                return binding.invoke(input, call);
+            };
+            const schedule = this.toolFrame?.schedule ?? this.scheduleTool;
+            return binding.definition.name === 'code_exec' ||
+                binding.definition.name === 'code_exec_wait'
+                ? invoke()
+                : schedule(binding.definition, invoke);
+        }, binding.source)
+    }), (call, callback) => this.operations.callback(call, callback), (definition) => this.toolRuntime.validateCallers(definition));
+    #attempt = new AsyncLocalStorage();
+    #toolFrame = new AsyncLocalStorage();
+    get toolFrame() {
+        const frame = this.#toolFrame.getStore();
+        return frame?.active ? frame : undefined;
+    }
+    withTools(bindings, schedule, run) {
+        this.assertLive();
+        const frame = { bindings, schedule, active: true };
+        return this.#toolFrame.run(frame, () => {
+            try {
+                const result = run();
+                if (result instanceof Promise)
+                    return result.finally(() => {
+                        frame.active = false;
+                    });
+                frame.active = false;
+                return result;
+            }
+            catch (error) {
+                frame.active = false;
+                throw error;
+            }
+        });
+    }
+    independent(run) {
+        return this.#toolFrame.run(undefined, () => this.#attempt.run(undefined, run));
+    }
+    isMcp(ref) {
+        return this.#toolRefs.get(ref)?.mcp !== undefined;
+    }
+    bind(scope, extensionId, run, current) {
+        return {
+            register: (spec) => this.tools.register(scope, extensionId, spec),
+            catalog: () => Object.freeze([...this.capture(current()).values()].map((binding) => this.toolRef(binding))),
+            check: (call) => run(async (context) => this.check(call, context)),
+            invoke: (call) => run((context) => this.invoke(call, context, this.invocationSnapshot(call, context)))
+        };
+    }
+    toolRef(binding) {
+        const ref = Object.freeze({
+            definition: binding.definition,
+            source: binding.source,
+            ...(binding.mcp === undefined ? {} : { mcp: binding.mcp })
+        });
+        this.#toolRefs.set(ref, binding);
+        return ref;
+    }
+    capture(context, includeStaged = false, base) {
+        this.assertLive();
+        if (!base && !includeStaged && this.toolFrame)
+            return this.toolFrame.bindings;
+        const tools = this.tools.capture(base ?? this.baseTools(context), includeStaged || ExtensionResourceScope.initializing);
+        return new Map([...tools].filter(([name, binding]) => this.allowTool(name, binding.definition)));
+    }
+    async invoke(call, context, snapshot = this.capture(context)) {
+        this.assertLive();
+        const permissionPolicy = this.toolRuntime.currentPermissions(context);
+        if (permissionPolicy?.mode === 'auto') {
+            const original = snapshot.get(call.name);
+            if (!original)
+                throw new AgentError('MAR_AGENT_TOOL_NOT_AVAILABLE', 'Tool source is unavailable.');
+            this.assertToolAvailable(original, context);
+            call = permissionPolicy.prepare(call, context, original.definition);
+            call = await permissionPolicy.authorize(call, context);
+        }
+        else if (call.permission !== undefined && call.permission !== null)
+            throw new AgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Framework permission metadata requires an Auto execution.');
+        const effective = Object.freeze({
+            ...context,
+            ...(call.callId === undefined ? {} : { toolCallId: call.callId })
+        });
+        return this.operations.continue(effective, () => this.toolAttempt(call, effective, 'result', () => this.hooks.invoke('tool.invoke', call, effective, async (target, effective) => {
+            const binding = snapshot.get(target.name);
+            if (!binding)
+                throw new AgentError('MAR_AGENT_TOOL_NOT_AVAILABLE', 'Tool source is unavailable.');
+            this.assertToolAvailable(binding, effective);
+            permissionPolicy?.assertDispatch();
+            return binding.invoke({
+                ...target,
+                arguments: this.toolRuntime.normalizeInput(target.arguments, binding.definition.inputSchema)
+            }, effective);
+        })));
+    }
+    assertToolAvailable(binding, call) {
+        this.assertLive();
+        call.signal.throwIfAborted();
+        if (!this.allowTool(binding.definition.name, binding.definition) ||
+            binding.available?.(call) === false)
+            throw new AgentError('MAR_AGENT_TOOL_NOT_AVAILABLE', 'Tool source is unavailable.');
+        if (call.entry !== 'native-api' && !binding.definition.allowedCallers?.includes(call.entry))
+            throw new AgentError('MAR_AGENT_TOOL_NOT_AVAILABLE', 'Tool caller is unavailable.');
+    }
+    toolAttempt(input, call, stage, invoke, source) {
+        const parent = this.#attempt.getStore();
+        const frame = { id: randomUUID(), active: true };
+        const attempt = Object.freeze({
+            attemptId: frame.id,
+            ...(parent?.active ? { parentAttemptId: parent.id } : {}),
+            name: input.name,
+            ...(input.callId === undefined ? {} : { callId: input.callId }),
+            stage,
+            ...(source === undefined ? {} : { source })
+        });
+        return this.#attempt.run(frame, async () => {
+            try {
+                let result;
+                try {
+                    result = this.toolRuntime.validateResult(await invoke());
+                }
+                catch (error) {
+                    const cancelled = call.signal.aborted ||
+                        (error instanceof AgentError && error.code === 'MAR_AGENT_CANCELLED');
+                    let errorCode = cancelled ? 'MAR_AGENT_CANCELLED' : 'MAR_AGENT_TOOL_FAILED';
+                    try {
+                        if (error instanceof AgentError)
+                            errorCode = error.code;
+                        else if (error &&
+                            typeof error === 'object' &&
+                            'code' in error &&
+                            typeof error.code === 'string')
+                            errorCode = error.code.slice(0, 80);
+                    }
+                    catch {
+                        /* A diagnostic getter must not replace the real failure. */
+                    }
+                    await this.hooks.emit(stage === 'result' ? 'tool.failed' : 'tool.attempt.failed', { ...attempt, status: cancelled ? 'cancelled' : 'failed', errorCode }, call, true);
+                    throw error;
+                }
+                await this.hooks.emit(stage === 'result' ? 'tool.completed' : 'tool.attempt.completed', { ...attempt, result }, call);
+                return result;
+            }
+            finally {
+                frame.active = false;
+            }
+        });
+    }
+    check(call, context) {
+        let binding;
+        try {
+            binding = this.invocationSnapshot(call, context).get(call.name);
+        }
+        catch {
+            return { available: false, code: 'MAR_AGENT_TOOL_NOT_AVAILABLE' };
+        }
+        const available = !this.isRetired() &&
+            binding !== undefined &&
+            this.allowTool(call.name, binding.definition) &&
+            binding.available?.(context) !== false &&
+            (context.entry === 'native-api' ||
+                binding.definition.allowedCallers?.includes(context.entry) === true);
+        return {
+            available,
+            ...(available ? { source: binding.source } : { code: 'MAR_AGENT_TOOL_NOT_AVAILABLE' })
+        };
+    }
+    invocationSnapshot(call, context) {
+        const snapshot = this.capture(context);
+        if (!call.ref)
+            return snapshot;
+        const binding = this.#toolRefs.get(call.ref);
+        if (!binding || binding.definition.name !== call.name)
+            throw new AgentError('MAR_AGENT_TOOL_NOT_AVAILABLE', 'Tool reference is unavailable.');
+        return new Map([...snapshot, [call.name, binding]]);
+    }
+}

package/dist/extensions/session.d.ts

@@ -0,0 +1,60 @@
+import type { ToolCall, ToolExecutionResult } from '../tools/contracts.js';
+import type { ExtensionToolRuntime } from './tool-runtime.js';
+import type { ExtensionDomainFacts, ExtensionDomainOperations, ExtensionDiagnostic, AgentExtension, SessionExtensionContext, ExtensionCapabilitySnapshot } from './contracts.js';
+import { ExtensionHooks } from './hooks.js';
+import type { ExtensionPromptComposition } from './prompt-composition.js';
+import type { ExtensionModelEvent } from './model-stream.js';
+import { ExtensionMcp } from './mcp.js';
+import { type ExtensionAgentsBackend, type ExtensionAgentAction } from './agents.js';
+import type { AgentHostExtensionPorts } from './host-ports.js';
+import { ExtensionOperations, type ExtensionOperationContext } from './operation.js';
+import { ExtensionResourceScope } from './resources.js';
+import { ExtensionServices } from './services.js';
+import type { ExtensionToolBinding } from './tools.js';
+import { type ExtensionModelsBackend } from './models.js';
+import { type ExtensionCheckpointBackend, type ExtensionStoreBackend } from './data.js';
+import type { ExtensionSessionBackend } from './session-input.js';
+/** Session-local definitions and facades; SDK supplies real Host sources for each operation. */
+export declare class ExtensionSession {
+    #private;
+    readonly toolRuntime: ExtensionToolRuntime;
+    readonly id: string;
+    readonly epoch: number;
+    readonly operations: ExtensionOperations;
+    readonly capabilities: ExtensionCapabilitySnapshot;
+    readonly diagnose: (diagnostic: ExtensionDiagnostic) => void;
+    readonly baseTools: (context?: ExtensionOperationContext) => readonly ExtensionToolBinding[];
+    readonly models?: ExtensionModelsBackend | undefined;
+    readonly checkpoint?: ExtensionCheckpointBackend | undefined;
+    readonly sessionBackend?: ExtensionSessionBackend | undefined;
+    readonly hostPorts?: AgentHostExtensionPorts | undefined;
+    readonly agentsBackend?: ExtensionAgentsBackend | undefined;
+    readonly allowTool: (name: string, definition?: ExtensionToolBinding['definition']) => boolean;
+    readonly scheduleTool: <T>(definition: ExtensionToolBinding['definition'], run: () => Promise<T>) => Promise<T>;
+    readonly store?: ExtensionStoreBackend | undefined;
+    isEnding: boolean;
+    readonly mcp: ExtensionMcp;
+    readonly hooks: ExtensionHooks<ExtensionDomainOperations, ExtensionDomainFacts>;
+    readonly services: ExtensionServices;
+    readonly scopes: ExtensionResourceScope[];
+    /** The SDK calls this after admission, outside the composition manager's serial lane. */
+    ready(call: ExtensionOperationContext): Promise<void>;
+    assertLive(): void;
+    retire(): void;
+    get hasReferences(): boolean;
+    pin(): () => void;
+    constructor(toolRuntime: ExtensionToolRuntime, id: string, epoch: number, agentServices: ExtensionServices, operations: ExtensionOperations, capabilities: ExtensionCapabilitySnapshot, diagnose: (diagnostic: ExtensionDiagnostic) => void, baseTools?: (context?: ExtensionOperationContext) => readonly ExtensionToolBinding[], models?: ExtensionModelsBackend | undefined, checkpoint?: ExtensionCheckpointBackend | undefined, sessionBackend?: ExtensionSessionBackend | undefined, hostPorts?: AgentHostExtensionPorts | undefined, agentsBackend?: ExtensionAgentsBackend | undefined, allowTool?: (name: string, definition?: ExtensionToolBinding['definition']) => boolean, scheduleTool?: <T>(definition: ExtensionToolBinding['definition'], run: () => Promise<T>) => Promise<T>, store?: ExtensionStoreBackend | undefined);
+    context(extension: AgentExtension, scope: ExtensionResourceScope): SessionExtensionContext;
+    withTools<T>(bindings: ReadonlyMap<string, ExtensionToolBinding>, schedule: <Value>(definition: ExtensionToolBinding['definition'], run: () => Promise<Value>) => Promise<Value>, run: () => T): T;
+    capture(context?: ExtensionOperationContext, includeStaged?: boolean, base?: readonly ExtensionToolBinding[]): ReadonlyMap<string, ExtensionToolBinding>;
+    invoke(call: ToolCall, context: ExtensionOperationContext, snapshot?: ReadonlyMap<string, ExtensionToolBinding>): Promise<ToolExecutionResult>;
+    readonly agentAction: ExtensionAgentAction;
+    modelEvent(event: ExtensionModelEvent, call: ExtensionOperationContext): Promise<ExtensionModelEvent | undefined>;
+    composeModelSystem(system: string | ExtensionPromptComposition, call: ExtensionOperationContext): Promise<{
+        text: string;
+        blocks?: readonly import("../index.js").ModelTextBlock[];
+        sections?: readonly import("../extensions.js").PromptPart[];
+    }>;
+    activate(): void;
+    dispose(): Promise<void>;
+}

package/dist/extensions/session.js

@@ -0,0 +1,265 @@
+import { AgentError } from '../error.js';
+import { ExtensionHooks } from './hooks.js';
+import { ExtensionPrompts } from './prompts.js';
+import { bindCoreFiles } from './files.js';
+import { bindCoreNetwork } from './network.js';
+import { ExtensionMcp } from './mcp.js';
+import { bindCoreProcesses } from './processes.js';
+import { bindCoreEnvironment } from './environment.js';
+import { bindCoreAgents, invokeCoreAgentOperation } from './agents.js';
+import { bindCoreSettings, coreSettingsBinding, settingsCapabilities } from './settings.js';
+import { ExtensionServices } from './services.js';
+import { ExtensionSessionTools } from './session-tools.js';
+import { bindCoreModels } from './models.js';
+import { bindCoreData, ExtensionState } from './data.js';
+import { bindCoreSession } from './session-api.js';
+import { ExtensionCommands } from './commands.js';
+/** Session-local definitions and facades; SDK supplies real Host sources for each operation. */
+export class ExtensionSession {
+    toolRuntime;
+    id;
+    epoch;
+    operations;
+    capabilities;
+    diagnose;
+    baseTools;
+    models;
+    checkpoint;
+    sessionBackend;
+    hostPorts;
+    agentsBackend;
+    allowTool;
+    scheduleTool;
+    store;
+    isEnding = false;
+    mcp;
+    hooks;
+    services;
+    #commands = new ExtensionCommands((call, callback) => this.operations.callback(call, callback));
+    #promptDomain;
+    scopes = [];
+    #toolDomain;
+    #references = 0;
+    #retired = false;
+    #ready = false;
+    /** The SDK calls this after admission, outside the composition manager's serial lane. */
+    async ready(call) {
+        this.assertLive();
+        call.signal.throwIfAborted();
+        if (this.#ready)
+            return;
+        // Mark before dispatch so nested work cannot recursively initialize the same generation.
+        this.#ready = true;
+        await this.hooks.emit('session.ready', { sessionId: this.id }, call);
+    }
+    assertLive() {
+        if (this.#retired)
+            throw new AgentError('MAR_AGENT_TOOL_NOT_AVAILABLE', 'Session runtime is retired.');
+    }
+    retire() {
+        this.#retired = true;
+        for (const scope of this.scopes)
+            scope.retire();
+    }
+    get hasReferences() {
+        return this.#references > 0;
+    }
+    pin() {
+        this.assertLive();
+        this.#references++;
+        let released = false;
+        return () => {
+            if (!released) {
+                released = true;
+                this.#references--;
+            }
+        };
+    }
+    constructor(toolRuntime, id, epoch, agentServices, operations, capabilities, diagnose, baseTools = () => [], models, checkpoint, sessionBackend, hostPorts, agentsBackend, allowTool = () => true, scheduleTool = (_definition, run) => run(), store) {
+        this.toolRuntime = toolRuntime;
+        this.id = id;
+        this.epoch = epoch;
+        this.operations = operations;
+        this.capabilities = capabilities;
+        this.diagnose = diagnose;
+        this.baseTools = baseTools;
+        this.models = models;
+        this.checkpoint = checkpoint;
+        this.sessionBackend = sessionBackend;
+        this.hostPorts = hostPorts;
+        this.agentsBackend = agentsBackend;
+        this.allowTool = allowTool;
+        this.scheduleTool = scheduleTool;
+        this.store = store;
+        this.services = new ExtensionServices('session', agentServices);
+        this.hooks = new ExtensionHooks(diagnose, (call, callback, settled) => this.operations.callback(call, callback, settled));
+        this.#promptDomain = new ExtensionPrompts(this.hooks, () => this.assertLive());
+        this.#toolDomain = new ExtensionSessionTools(this.toolRuntime, this.operations, this.hooks, this.baseTools, this.allowTool, this.scheduleTool, () => this.assertLive(), () => this.#retired);
+        this.mcp = new ExtensionMcp(this.#toolDomain.tools, this.hooks, (call) => this.capture(call, false, this.baseTools(call)), (binding) => this.#toolDomain.toolRef(binding), (ref) => this.#toolDomain.isMcp(ref), (input, call) => this.#toolDomain.invoke(input, call, this.#toolDomain.invocationSnapshot(input, call)), () => this.diagnose({ code: 'MAR_AGENT_MCP_CLEANUP_FAILED', sessionId: this.id }), (catalog) => this.toolRuntime.validateMcpCatalog(catalog));
+    }
+    context(extension, scope) {
+        const instanceId = scope.instanceId;
+        const settings = coreSettingsBinding(extension.bindings);
+        if (this.sessionBackend)
+            scope.effect(() => this.sessionBackend.own(instanceId));
+        const state = new ExtensionState(scope, () => this.diagnose({
+            code: 'MAR_AGENT_EXTENSION_STATE_OBSERVER_FAILED',
+            extensionId: extension.id,
+            sessionId: this.id
+        }), (call, callback) => this.operations.callback(call, callback));
+        const run = (operation, signal) => {
+            const parentSignal = this.operations.current()?.signal;
+            const inherited = signal && parentSignal ? AbortSignal.any([signal, parentSignal]) : (signal ?? parentSignal);
+            return scope.run(async (signal) => {
+                const parent = this.operations.current();
+                return this.operations.run({
+                    sessionId: this.id,
+                    sessionEpoch: this.epoch,
+                    ownerInstanceId: instanceId,
+                    extensionId: extension.id,
+                    actor: 'extension',
+                    entry: 'native-api',
+                    signal,
+                    ...(parent?.executionId ? { executionId: parent.executionId } : {}),
+                    ...(parent?.turnId ? { turnId: parent.turnId } : {})
+                }, operation);
+            }, inherited);
+        };
+        const callback = (handler) => async (signal) => {
+            await this.#toolDomain.independent(() => this.hooks.independent(() => this.toolRuntime.independent(() => this.operations.enter({
+                sessionId: this.id,
+                sessionEpoch: this.epoch,
+                ownerInstanceId: instanceId,
+                extensionId: extension.id,
+                actor: 'extension',
+                entry: 'native-api',
+                signal
+            }, (call) => this.operations.callback(call, handler)))));
+        };
+        return {
+            sessionId: this.id,
+            ...(this.agentsBackend
+                ? {
+                    agents: bindCoreAgents(this.agentsBackend, scope, run, this.hooks)
+                }
+                : {}),
+            ...(settings ? { settings: bindCoreSettings(settings, run, this.hooks) } : {}),
+            ...(this.hostPorts?.environment
+                ? { environment: bindCoreEnvironment(this.hostPorts.environment, run, this.hooks) }
+                : {}),
+            ...(this.hostPorts?.processes
+                ? {
+                    processes: bindCoreProcesses(this.hostPorts.processes, run, scope, this.hooks, () => this.diagnose({
+                        code: 'MAR_AGENT_PROCESS_CLEANUP_FAILED',
+                        extensionId: extension.id,
+                        sessionId: this.id
+                    }))
+                }
+                : {}),
+            ...(this.sessionBackend
+                ? {
+                    session: bindCoreSession(this.sessionBackend, scope, run, this.operations, this.hooks)
+                }
+                : {}),
+            ...(this.hostPorts?.files
+                ? { files: bindCoreFiles(this.hostPorts.files, run, this.hooks) }
+                : {}),
+            ...(this.hostPorts?.network
+                ? {
+                    network: bindCoreNetwork(this.hostPorts.network, run, scope, this.hooks, () => this.diagnose({
+                        code: 'MAR_AGENT_NETWORK_CLEANUP_FAILED',
+                        extensionId: extension.id,
+                        sessionId: this.id
+                    }))
+                }
+                : {}),
+            data: bindCoreData(state, this.store, extension.dataDirectory, this.checkpoint, extension.id, run),
+            ...(this.models
+                ? {
+                    models: bindCoreModels(this.models, run, this.hooks, (event, call) => this.modelEvent(event, call), (code, call) => this.diagnose({
+                        code,
+                        sessionId: this.id,
+                        extensionId: extension.id,
+                        operationId: call.operationId
+                    }))
+                }
+                : {}),
+            ...(this.hostPorts?.mcp
+                ? { mcp: this.mcp.bind(scope, extension.id, this.hostPorts.mcp, run) }
+                : {}),
+            resources: scope,
+            services: this.services.bind(scope),
+            capabilities: settingsCapabilities(this.capabilities, settings !== undefined),
+            bindings: Object.freeze({ ...(extension.bindings ?? {}) }),
+            observability: {
+                log: (message) => this.diagnose({
+                    code: 'MAR_AGENT_EXTENSION_LOG',
+                    extensionId: extension.id,
+                    sessionId: this.id,
+                    message: message.slice(0, 1000)
+                })
+            },
+            hooks: {
+                intercept: (key, handler, options) => this.hooks.intercept(scope, key, handler, options),
+                observe: (key, handler, options) => this.hooks.observe(scope, key, handler, options)
+            },
+            tools: this.#toolDomain.bind(scope, extension.id, run, () => this.operations.current()),
+            commands: this.#commands.bind(scope, run),
+            prompts: this.#promptDomain.bind(scope, run, this.sessionBackend),
+            clock: {
+                now: () => Date.now(),
+                sleep: (input) => run((call) => scope.sleep(input.durationMs, call.signal), input.signal),
+                after: (duration, handler) => scope.after(duration, callback(handler), () => this.diagnose({
+                    code: 'MAR_AGENT_EXTENSION_TIMER_FAILED',
+                    extensionId: extension.id,
+                    sessionId: this.id
+                })),
+                every: (duration, handler) => scope.every(duration, callback(handler), () => this.diagnose({
+                    code: 'MAR_AGENT_EXTENSION_TIMER_FAILED',
+                    extensionId: extension.id,
+                    sessionId: this.id
+                }))
+            }
+        };
+    }
+    withTools(bindings, schedule, run) {
+        return this.#toolDomain.withTools(bindings, schedule, run);
+    }
+    capture(context, includeStaged = false, base) {
+        return this.#toolDomain.capture(context, includeStaged, base);
+    }
+    invoke(call, context, snapshot) {
+        return this.#toolDomain.invoke(call, context, snapshot);
+    }
+    agentAction = (key, input, leaf) => {
+        const call = this.operations.current();
+        if (!call)
+            throw new AgentError('MAR_AGENT_SUBAGENT_FAILED', 'Agent operation context is unavailable.');
+        return invokeCoreAgentOperation(this.hooks, key, input, call, leaf);
+    };
+    async modelEvent(event, call) {
+        await this.hooks.emit('model.event', event, call);
+        return this.hooks.invoke('model.event', event, call, async (view) => view);
+    }
+    composeModelSystem(system, call) {
+        return this.#promptDomain.composeModelSystem(system, call);
+    }
+    activate() {
+        for (const scope of this.scopes)
+            scope.activate();
+    }
+    async dispose() {
+        this.retire();
+        let failures = 0;
+        for (const scope of [...this.scopes].reverse()) {
+            try {
+                await scope.dispose();
+            }
+            catch {
+                failures++;
+            }
+        }
+        if (failures)
+            throw new AgentError('MAR_AGENT_EXTENSION_CLEANUP_FAILED', 'Session extension cleanup failed.', { details: { failures } });
+    }
+}

package/dist/extensions/settings.d.ts

@@ -0,0 +1,76 @@
+import { type ExtensionJsonValue } from './data.js';
+import type { ExtensionCapabilitySnapshot } from './capabilities.js';
+import type { ExtensionHooks } from './hooks.js';
+import type { ExtensionOperationContext } from './operation.js';
+export interface ExtensionSettingsReadInput {
+    readonly scope?: string;
+    readonly signal?: AbortSignal;
+}
+export interface ExtensionSettingDefinition {
+    readonly key: string;
+    readonly schema: boolean | Readonly<Record<string, ExtensionJsonValue>>;
+    readonly source: string;
+    readonly writable: boolean;
+    readonly sensitive?: boolean;
+    readonly owner?: string;
+    readonly label?: string;
+}
+export interface ExtensionSettingsDescription {
+    readonly revision: number;
+    readonly definitions: readonly ExtensionSettingDefinition[];
+}
+export interface ExtensionSettingsSnapshot {
+    readonly revision: number;
+    readonly values: Readonly<Record<string, ExtensionJsonValue>>;
+}
+export interface ExtensionSettingsUpdate extends ExtensionSettingsReadInput {
+    readonly key: string;
+    readonly value: ExtensionJsonValue;
+    readonly expectedRevision?: number;
+}
+export type ExtensionSettingsResult = {
+    readonly status: 'updated' | 'unchanged';
+    readonly revision: number;
+    readonly value: ExtensionJsonValue;
+} | {
+    readonly status: 'denied';
+    readonly revision: number;
+    readonly reason: {
+        readonly code: string;
+        readonly message: string;
+    };
+};
+export interface ExtensionSettingsApi {
+    describe(input?: ExtensionSettingsReadInput): Promise<ExtensionSettingsDescription>;
+    read(input?: ExtensionSettingsReadInput): Promise<ExtensionSettingsSnapshot>;
+    update(input: ExtensionSettingsUpdate): Promise<ExtensionSettingsResult>;
+}
+export type ExtensionSettingsBackend = {
+    [Name in keyof ExtensionSettingsApi]: (input: NonNullable<Parameters<ExtensionSettingsApi[Name]>[0]>, call: ExtensionOperationContext) => Promise<Awaited<ReturnType<ExtensionSettingsApi[Name]>>>;
+};
+export interface ExtensionSettingsCompletion {
+    readonly operation: keyof ExtensionSettingsApi;
+    readonly revision: number;
+    readonly scope?: string;
+    readonly status?: ExtensionSettingsResult['status'];
+}
+export declare function coreSettingsBinding(bindings?: Readonly<Record<string, unknown>>): ExtensionSettingsBackend | undefined;
+export declare function settingsCapabilities(base: ExtensionCapabilitySnapshot, bound: boolean): ExtensionCapabilitySnapshot;
+export declare function bindCoreSettings(backend: ExtensionSettingsBackend, run: <Value>(operation: (call: ExtensionOperationContext) => Promise<Value>, signal?: AbortSignal) => Promise<Value>, hooks: Pick<ExtensionHooks<DomainSettingsOperations, DomainSettingsFacts>, 'invoke' | 'emit'>): ExtensionSettingsApi;
+export interface DomainSettingsOperations {
+    'settings.describe': {
+        input: ExtensionSettingsReadInput;
+        output: ExtensionSettingsDescription;
+    };
+    'settings.read': {
+        input: ExtensionSettingsReadInput;
+        output: ExtensionSettingsSnapshot;
+    };
+    'settings.update': {
+        input: ExtensionSettingsUpdate;
+        output: ExtensionSettingsResult;
+    };
+}
+export interface DomainSettingsFacts {
+    'settings.completed': ExtensionSettingsCompletion;
+}