@myagentroam/agent 0.11.33 → 0.11.34

package/dist/sdk/execution-model-request.js

@@ -0,0 +1,45 @@
+import { randomUUID } from 'node:crypto';
+import { isDeepStrictEqual } from 'node:util';
+import { AgentError } from '../error.js';
+import { ExtensionRequestBridge } from '../extensions/model-request.js';
+import { projectPermissionTool } from '../tools/permissions.js';
+/** Captures Extension rewrites against immutable tool bindings and attributes model usage. */
+export function createExecutionModelRequest(ports) {
+    return async (candidate, bindings = ports.capture(), modelId = ports.modelId, purpose = ports.compact ? 'compact' : 'conversation') => {
+        let lowered = candidate;
+        if (ports.hooks.hasInterceptors('model.request')) {
+            const bridge = new ExtensionRequestBridge(modelId, candidate, undefined, ports.turn.continuationInputCount?.() ?? 0);
+            const request = await ports.operation((call) => ports.hooks.invoke('model.request', bridge.view, call, async (view) => view));
+            lowered = bridge.lower(request);
+            if (bridge.rewroteCommittedInput)
+                ports.turn.resetContinuation?.();
+        }
+        for (const definition of lowered.tools) {
+            const binding = bindings.get(definition.name);
+            const { description: _description, ...contract } = definition;
+            const { description: _capturedDescription, ...capturedContract } = binding
+                ? ports.autoPermission
+                    ? projectPermissionTool(binding.definition)
+                    : binding.definition
+                : {};
+            if (!binding || !isDeepStrictEqual(contract, capturedContract))
+                throw new AgentError('MAR_AGENT_EXTENSION_MODEL_REQUEST_INVALID', 'Request tools do not match captured sources.');
+        }
+        return {
+            ...lowered,
+            usageRequestId: randomUUID(),
+            ...(ports.host.modelUsage === undefined
+                ? {}
+                : {
+                    onModelUsage: (usage) => ports.host.modelUsage({
+                        ...usage,
+                        sessionId: ports.sessionId,
+                        executionId: ports.executionId,
+                        purpose,
+                        agentRole: ports.source === 'subagent' ? 'subagent' : 'root'
+                    }),
+                    onModelUsageFailure: ports.usageFailed
+                })
+        };
+    };
+}

package/dist/sdk/execution-round-preparation.d.ts

@@ -0,0 +1,11 @@
+/** Owns round retries when late input or resource collection invalidates a candidate. */
+export declare function createExecutionRoundPreparer<Continuation, Candidate, Round>(ports: {
+    prepareInputs(includeSubagentUpdates: boolean): Promise<void>;
+    buildCandidate(continuation: Continuation | undefined): Promise<Candidate>;
+    adoptLateInput(): Promise<boolean>;
+    prepareResources(candidate: Candidate): Promise<{
+        round: Round;
+    } | {
+        retry: true;
+    }>;
+}): (continuation: Continuation | undefined) => Promise<Round>;

package/dist/sdk/execution-round-preparation.js

@@ -0,0 +1,18 @@
+/** Owns round retries when late input or resource collection invalidates a candidate. */
+export function createExecutionRoundPreparer(ports) {
+    return async (continuation) => {
+        let includeSubagentUpdates = true;
+        for (;;) {
+            await ports.prepareInputs(includeSubagentUpdates);
+            const candidate = await ports.buildCandidate(continuation);
+            if (await ports.adoptLateInput()) {
+                includeSubagentUpdates = false;
+                continue;
+            }
+            const prepared = await ports.prepareResources(candidate);
+            if ('round' in prepared)
+                return prepared.round;
+            includeSubagentUpdates = false;
+        }
+    };
+}

package/dist/sdk/execution-round-request.d.ts

@@ -0,0 +1,30 @@
+import { splitContextualPrompt } from '../runtime/context/contextual-blocks.js';
+import { type ContextualWorldState } from '../runtime/context/world-state.js';
+import type { AgentModelConfiguration } from '../model/configuration.js';
+import type { SessionModelMessage, SessionModelRequest } from '../session/model-request.js';
+import type { ClientToolDefinition } from '../tools/contracts.js';
+/** Capture, transform and commit the world state for one actual model request. */
+export declare function prepareExecutionRoundRequest<Bindings, Scope>(input: {
+    readonly messages: SessionModelMessage[];
+    readonly continuation: SessionModelMessage | undefined;
+    readonly model: Pick<AgentModelConfiguration, 'protocol' | 'inputCapabilities'>;
+    readonly requestBase: Omit<SessionModelRequest, 'system' | 'systemBlocks' | 'messages' | 'tools'>;
+    residentTools(): readonly ClientToolDefinition[];
+    readonly autoPermission: boolean;
+    readonly signal: AbortSignal;
+    capture(): {
+        roundTools: readonly ClientToolDefinition[];
+        roundBindings: Bindings;
+        toolScope: Scope;
+        composeSystemPrompt(): Promise<Parameters<typeof splitContextualPrompt>[0]>;
+    };
+    bind(scope: Scope): void;
+    world(): ContextualWorldState;
+    commitWorld(world: ContextualWorldState): Promise<void>;
+    preparing(messages: readonly SessionModelMessage[] | undefined, baseLength: number): void;
+    transform(request: SessionModelRequest, bindings: Bindings): Promise<SessionModelRequest>;
+}): Promise<{
+    candidateRequest: SessionModelRequest;
+    request: SessionModelRequest;
+    toolScope: Scope;
+}>;

package/dist/sdk/execution-round-request.js

@@ -0,0 +1,31 @@
+import { splitContextualPrompt } from '../runtime/context/contextual-blocks.js';
+import { updatePromptWorldState } from '../runtime/context/world-state.js';
+import { prepareSessionModelRequest } from './request-preparation.js';
+/** Capture, transform and commit the world state for one actual model request. */
+export async function prepareExecutionRoundRequest(input) {
+    const { roundTools, roundBindings, toolScope, composeSystemPrompt } = input.capture();
+    const residentTools = input.residentTools();
+    const requestMessages = input.continuation === undefined ? input.messages : [...input.messages, input.continuation];
+    input.bind(toolScope);
+    const composed = splitContextualPrompt(await composeSystemPrompt());
+    const world = updatePromptWorldState(input.world(), input.messages.length, composed.parts);
+    const candidateRequest = prepareSessionModelRequest({
+        ...input.requestBase,
+        system: composed.system,
+        ...(composed.systemBlocks ? { systemBlocks: composed.systemBlocks } : {}),
+        messages: requestMessages,
+        tools: roundTools
+    }, input.model, world.entries, residentTools, input.autoPermission);
+    input.preparing(candidateRequest.messages, input.messages.length);
+    let request;
+    try {
+        request = await input.transform(candidateRequest, roundBindings);
+    }
+    finally {
+        input.preparing(undefined, input.messages.length);
+    }
+    input.signal.throwIfAborted();
+    if (world !== input.world())
+        await input.commitWorld(world);
+    return { candidateRequest, request, toolScope };
+}

package/dist/sdk/execution-tool-catalog.d.ts

@@ -0,0 +1,46 @@
+import type { ExtensionToolBinding } from '../extensions/tools.js';
+import type { AgentHost } from '../host/contracts.js';
+import type { ClientToolDefinition, McpToolCatalog, McpToolCatalogContext } from '../tools/contracts.js';
+import { DeferredMcpRegistry } from '../tools/mcp/tool-search.js';
+import type { SessionModelMessage } from '../session/model-request.js';
+import type { ExecutionMode } from './types.js';
+import type { ResolvedModelConfiguration } from './model-runtime.js';
+import { ExecutionToolSources } from './extension-tools.js';
+/** Initializes one Execution's catalog before Extension attachment owns its bindings. */
+export declare function initializeExecutionToolCatalog(input: {
+    host: Pick<AgentHost, 'listMcpToolCatalog' | 'listMcpTools' | 'listExecutionExtensions'>;
+    context: McpToolCatalogContext;
+    models: ReadonlyMap<string, ResolvedModelConfiguration>;
+    messages: SessionModelMessage[];
+    supplemental(names: ReadonlySet<string>): readonly ExtensionToolBinding[];
+}): Promise<{
+    catalog: McpToolCatalog;
+    registry: DeferredMcpRegistry;
+    extensions: import("./types.js").HostExecutionExtensions;
+    supplemental: readonly ExtensionToolBinding[];
+    sources: ExecutionToolSources;
+}>;
+/** Owns the live MCP projection while source identities remain tied to one Execution. */
+export declare class ExecutionToolCatalog {
+    #private;
+    private readonly input;
+    constructor(input: {
+        catalog: McpToolCatalog;
+        registry: DeferredMcpRegistry;
+        messages: SessionModelMessage[];
+        model: ResolvedModelConfiguration;
+        child: boolean;
+        mode: ExecutionMode;
+        codeExecute: boolean;
+        capture(): ReadonlyMap<string, ExtensionToolBinding>;
+        servers(): McpToolCatalog['servers'];
+        hasSkills(): boolean;
+    });
+    eligible(tool: ClientToolDefinition): boolean;
+    updateRegistry(): void;
+    available(): ClientToolDefinition[];
+    base(): ClientToolDefinition[];
+    refresh(): void;
+    get tools(): readonly ClientToolDefinition[];
+    restore(): void;
+}

package/dist/sdk/execution-tool-catalog.js

@@ -0,0 +1,103 @@
+import { createHash } from 'node:crypto';
+import { AgentError } from '../error.js';
+import { coreMcpCatalog } from '../extensions/mcp.js';
+import { assertMcpToolCatalog } from '../tools/mcp/catalog.js';
+import { DeferredMcpRegistry } from '../tools/mcp/tool-search.js';
+import { discoveredMcpToolNames, rebindMcpToolSearchOutputs } from '../tools/mcp/history.js';
+import { BUILTIN_TOOL_DEFINITIONS } from '../tools/registry.js';
+import { agentStartToolDefinitionWithModels } from '../tools/agent/agent-start.js';
+import { toolCallers } from '../tools/callers.js';
+import { ExecutionToolSources } from './extension-tools.js';
+/** Initializes one Execution's catalog before Extension attachment owns its bindings. */
+export async function initializeExecutionToolCatalog(input) {
+    const { host, context } = input;
+    let catalog;
+    if (host.listMcpToolCatalog) {
+        catalog = await host.listMcpToolCatalog(context);
+        assertMcpToolCatalog(catalog);
+    }
+    else {
+        const definitions = (await host.listMcpTools?.(context)) ?? [];
+        catalog = {
+            revision: createHash('sha256').update(JSON.stringify(definitions)).digest('hex'),
+            servers: [{ id: 'legacy', name: 'External MCP' }],
+            tools: definitions.map((definition) => ({
+                definition,
+                serverId: 'legacy',
+                rawName: definition.name,
+                sourceIdentity: `legacy:${context.executionId}`,
+                definitionRevision: createHash('sha256').update(JSON.stringify(definition)).digest('hex'),
+                lifetime: 'execution',
+                exposure: 'deferred'
+            }))
+        };
+    }
+    const registry = new DeferredMcpRegistry(discoveredMcpToolNames(input.messages));
+    const extensions = (await host.listExecutionExtensions?.(context)) ?? {};
+    if (extensions.tools?.some((tool) => tool.name.startsWith('mcp__')))
+        throw new AgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Host tools cannot use the MCP namespace.');
+    const builtins = BUILTIN_TOOL_DEFINITIONS.map((tool) => tool.name === 'agent_start'
+        ? agentStartToolDefinitionWithModels([...input.models.values()]
+            .filter((configuration) => configuration.conversationModel !== false)
+            .map(({ id, name, reasoningEfforts }) => ({ id, name, reasoningEfforts })))
+        : tool);
+    const tools = [
+        ...builtins,
+        ...(extensions.tools ?? []),
+        ...catalog.tools.map((tool) => tool.definition)
+    ];
+    const names = new Set(tools.map((tool) => tool.name));
+    if (names.size !== tools.length)
+        throw new AgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Tool names conflict.');
+    const supplemental = input.supplemental(names);
+    const sources = new ExecutionToolSources(context.executionId, context.sessionId, tools, builtins, catalog, supplemental);
+    return { catalog, registry, extensions, supplemental, sources };
+}
+/** Owns the live MCP projection while source identities remain tied to one Execution. */
+export class ExecutionToolCatalog {
+    input;
+    #tools = [];
+    constructor(input) {
+        this.input = input;
+    }
+    eligible(tool) {
+        toolCallers(tool);
+        if (this.input.child &&
+            (tool.agentScope === 'ROOT_ONLY' ||
+                tool.name.startsWith('agent_') ||
+                tool.name === 'question'))
+            return false;
+        if (tool.name === 'tool_search')
+            return this.input.registry.hasDeferred;
+        return tool.name === 'code_exec' || tool.name === 'code_exec_wait'
+            ? this.input.model.codeMode && this.input.codeExecute
+            : tool.name === 'question'
+                ? this.input.mode === 'plan'
+                : tool.name !== 'view_image' || this.input.model.inputCapabilities.includes('IMAGE');
+    }
+    updateRegistry() {
+        this.input.registry.update(coreMcpCatalog([...this.input.catalog.servers, ...this.input.servers()], this.input.capture()), (tool) => this.eligible(tool.definition), { nativeToolNames: true });
+    }
+    available() {
+        return [...this.input.capture().values()]
+            .map((binding) => binding.definition)
+            .filter((tool) => this.eligible(tool));
+    }
+    base() {
+        return [...this.input.capture().values()]
+            .filter((binding) => binding.mcp === undefined)
+            .map((binding) => binding.definition)
+            .filter((tool) => this.eligible(tool) && (tool.name !== 'skill' || this.input.hasSkills()));
+    }
+    refresh() {
+        this.#tools = this.input.registry.project(this.base());
+    }
+    get tools() {
+        return this.#tools;
+    }
+    restore() {
+        this.input.registry.restore(discoveredMcpToolNames(this.input.messages));
+        rebindMcpToolSearchOutputs(this.input.messages, this.input.registry);
+        this.refresh();
+    }
+}

package/dist/sdk/execution-tool-scope.d.ts

@@ -0,0 +1,67 @@
+import { currentExecutionImages } from '../tools/output-projection.js';
+import { type SmartCompactionInput } from '../runtime/compaction/smart.js';
+import type { SessionStore } from '../session/store/contracts.js';
+import type { ClientToolDefinition } from '../tools/contracts.js';
+import type { ModelImage } from '../model/image.js';
+import type { ToolRuntimeContext } from '../tools/runtime-context.js';
+import type { RoundToolScope } from '../tools/execution.js';
+import type { SessionRuntime } from './session-runtime.js';
+import type { ExecutionToolSources } from './extension-tools.js';
+import type { ExtensionSession } from '../extensions/session.js';
+import type { ExtensionOperations, ExtensionOperationContext } from '../extensions/operation.js';
+import type { ExtensionPromptComposition } from '../extensions/prompt-composition.js';
+import type { DeferredMcpRegistry } from '../tools/mcp/tool-search.js';
+import type { SubagentSessionController } from '../subagent/session-controller.js';
+import type { ResolvedModelConfiguration } from './model-runtime.js';
+import type { ExecutionMode } from './types.js';
+import type { CompactFlight } from '../runtime/compaction/coordinator.js';
+import type { ExecutionEventPayload } from './session-execution.js';
+/** Capture immutable round tool identities, parent scope and resource capabilities. */
+export declare function createExecutionToolScope(input: {
+    readonly store: Pick<SessionStore, 'readResource' | 'writeToolResultResource' | 'readCodeModeState' | 'retainSessionLease' | 'append' | 'commitCodeModeState' | 'persistResource' | 'setResourceUrl'>;
+    readonly host: ToolRuntimeContext['host'];
+    readonly sessionId: string;
+    readonly executionId: string;
+    readonly turnId: string;
+    readonly mode: ExecutionMode;
+    readonly controller: AbortController;
+    readonly sessionWriterOwner: object;
+    readonly selectedModel: ResolvedModelConfiguration;
+    readonly permissionPolicy: NonNullable<ToolRuntimeContext['permissionPolicy']>;
+    readonly todo: ToolRuntimeContext['todo'];
+    readonly waitInterrupt: ToolRuntimeContext['waitInterrupt'];
+    readonly skills: ToolRuntimeContext['skills'];
+    readonly subagents: Pick<SubagentSessionController, 'captureParentFrame' | 'captureExecution' | 'modelMessages'> | undefined;
+    readonly coreExtensions: Pick<ExtensionSession, 'epoch' | 'agentAction' | 'withTools' | 'invoke' | 'assertLive' | 'pin' | 'diagnose' | 'composeModelSystem'>;
+    readonly operations: Pick<ExtensionOperations, 'enter'>;
+    readonly scheduleTool: SessionRuntime['scheduleTool'];
+    readonly sources: Pick<ExecutionToolSources, 'withFrame' | 'assertActive'>;
+    readonly mcpRegistry: Pick<DeferredMcpRegistry, 'expectedTool' | 'expose'>;
+    readonly autoPermissionPrompt: string;
+    readonly currentExecutionToolImages: Parameters<typeof currentExecutionImages>[1];
+    readonly inputImageBytes: Map<string, ModelImage>;
+    snapshotTools(): readonly ClientToolDefinition[];
+    baseTools(): readonly ClientToolDefinition[];
+    captureTools(): ReturnType<ExtensionSession['capture']>;
+    promptComposition(tools: readonly ClientToolDefinition[], mode: ExecutionMode): ExtensionPromptComposition & {
+        sections: ExtensionPromptComposition['sections'];
+    };
+    smartInput(): SmartCompactionInput | undefined;
+    modelInputImages(): readonly ModelImage[] | undefined;
+    startCompact(input: {
+        async: true;
+    }): CompactFlight;
+    preparedPrompt(): Awaited<ReturnType<ExtensionSession['composeModelSystem']>> | undefined;
+    clearPreparedPrompt(): void;
+    operation<T>(run: (call: ExtensionOperationContext) => T): T;
+    emit(event: ExecutionEventPayload, assertLive?: () => void): Promise<void>;
+}): () => {
+    roundTools: readonly ClientToolDefinition[];
+    roundBindings: Map<string, import("../extensions/tools.js").ExtensionToolBinding>;
+    toolScope: RoundToolScope;
+    composeSystemPrompt(): Promise<{
+        text: string;
+        blocks?: readonly import("../model/contracts.js").ModelTextBlock[];
+        sections?: readonly import("../prompts/prompt-sections.js").PromptPart[];
+    }>;
+};

package/dist/sdk/execution-tool-scope.js

@@ -0,0 +1,147 @@
+import { bindAgentController } from './extension-agent-controller.js';
+import { createExecutionCodeModeContext } from './execution-code-mode.js';
+import { currentExecutionImages } from '../tools/output-projection.js';
+import { requestSmartCompaction } from '../runtime/compaction/smart.js';
+import { renderPromptSections } from '../prompts/prompt-sections.js';
+import { withToolPermissions } from '../tools/permissions.js';
+/** Capture immutable round tool identities, parent scope and resource capabilities. */
+export function createExecutionToolScope(input) {
+    const { store, host, sessionId, executionId, turnId, mode, controller, sessionWriterOwner, selectedModel, permissionPolicy, todo, waitInterrupt, skills, subagents, coreExtensions, operations, scheduleTool, sources, mcpRegistry, autoPermissionPrompt, currentExecutionToolImages, inputImageBytes, snapshotTools, baseTools, captureTools, promptComposition, smartInput, modelInputImages, startCompact, preparedPrompt, clearPreparedPrompt, operation, emit } = input;
+    const captureRoundToolScope = () => {
+        const roundTools = snapshotTools();
+        const availableBindings = captureTools();
+        const roundBindings = new Map(roundTools.map((tool) => [tool.name, availableBindings.get(tool.name)]));
+        const defaultComposition = promptComposition(roundTools, mode === 'compact' ? 'run' : mode);
+        if (permissionPolicy.mode === 'auto')
+            defaultComposition.sections = [
+                ...defaultComposition.sections,
+                { id: 'core:auto-permission', text: autoPermissionPrompt }
+            ];
+        const defaultSystemPrompt = renderPromptSections(defaultComposition.sections);
+        let systemPrompt = defaultSystemPrompt;
+        const roundMcpExpectations = new Map(roundTools
+            .filter((tool) => roundBindings.get(tool.name)?.mcp !== undefined)
+            .map((tool) => [tool.name, mcpRegistry.expectedTool(tool.name)]));
+        const parentFrame = subagents === undefined || mode === 'compact'
+            ? undefined
+            : subagents.captureParentFrame(executionId);
+        const roundSmartInput = smartInput();
+        const toolContext = {
+            imageStore: store,
+            host: host,
+            requestSmartCompact: () => {
+                controller.signal.throwIfAborted();
+                requestSmartCompaction(roundSmartInput === smartInput() ? roundSmartInput : undefined, () => {
+                    // The Session owns this background operation, not the short-lived tool callback.
+                    operations.enter({
+                        sessionId,
+                        sessionEpoch: coreExtensions.epoch,
+                        executionId,
+                        turnId,
+                        actor: 'sdk',
+                        entry: 'native-api',
+                        signal: controller.signal
+                    }, () => startCompact({ async: true }));
+                });
+            },
+            permissionPolicy,
+            writeToolResultResource: (text) => store.writeToolResultResource(sessionId, text),
+            todo,
+            ...(subagents === undefined || mode === 'compact'
+                ? {}
+                : {
+                    subagents: bindAgentController(subagents.captureExecution(executionId), coreExtensions.agentAction),
+                    subagentMessages: subagents.modelMessages
+                }),
+            mode,
+            sessionId,
+            executionId,
+            modelId: selectedModel.id,
+            signal: controller.signal,
+            waitInterrupt,
+            emit,
+            skills: skills,
+            invokeTool: (call, context, caller) => {
+                const invoke = () => coreExtensions.withTools(roundBindings, scheduleTool, () => withToolPermissions(permissionPolicy, () => operations.enter({
+                    sessionId,
+                    sessionEpoch: coreExtensions.epoch,
+                    executionId,
+                    turnId,
+                    actor: caller === 'programmatic' ? 'code-mode' : 'model',
+                    entry: caller,
+                    ...(context.parentCallId === undefined
+                        ? {}
+                        : { parentToolCallId: context.parentCallId }),
+                    signal: context.signal
+                }, (operation) => coreExtensions.invoke(call, operation, roundBindings))));
+                return sources.withFrame(context, () => parentFrame === undefined ? invoke() : parentFrame(invoke));
+            }
+        };
+        const recentImages = async () => {
+            const inputImages = await Promise.all((modelInputImages() ?? []).map(async (image) => {
+                if (image.dataBase64 !== undefined || image.resourceId === undefined)
+                    return image;
+                const cached = inputImageBytes.get(image.resourceId);
+                if (cached !== undefined)
+                    return cached;
+                const source = await store.readResource(sessionId, image.resourceId);
+                const restored = { ...image, ...source };
+                inputImageBytes.set(image.resourceId, restored);
+                return restored;
+            }));
+            return currentExecutionImages(inputImages, currentExecutionToolImages);
+        };
+        const toolScope = {
+            context: toolContext,
+            tools: roundTools,
+            expectations: roundMcpExpectations,
+            extensionToolNames: new Set([...roundBindings.values()]
+                .filter((binding) => binding.source.kind === 'host' || binding.source.kind === 'extension')
+                .map((binding) => binding.definition.name)),
+            schedule: scheduleTool,
+            assertLive: () => coreExtensions.assertLive(),
+            assertExecutionLive: () => sources.assertActive(),
+            emit: (event, assertLive) => emit(event, () => {
+                coreExtensions.assertLive();
+                assertLive?.();
+            }),
+            searchMcpTools: (arguments_, searchSignal) => mcpRegistry.expose(arguments_, {
+                signal: searchSignal,
+                base: baseTools(),
+                window: selectedModel.contextWindowTokens,
+                system: systemPrompt
+            }),
+            recentImages,
+            captureCodeContext: () => ({
+                ...toolContext,
+                waitInterrupt: undefined
+            }),
+            codeModeContext: createExecutionCodeModeContext({
+                store,
+                sessionId,
+                executionId,
+                turnId,
+                writerOwner: sessionWriterOwner,
+                supportsImages: selectedModel.inputCapabilities.includes('IMAGE'),
+                tools: roundTools,
+                permissionStop: (callId) => permissionPolicy.stop?.source.parentCallId === callId ? permissionPolicy.stop : undefined,
+                assertLive: () => coreExtensions.assertLive(),
+                pin: () => coreExtensions.pin(),
+                cleanupFailed: () => coreExtensions.diagnose({ code: 'MAR_AGENT_EXTENSION_CLEANUP_FAILED', sessionId })
+            })
+        };
+        return {
+            roundTools,
+            roundBindings,
+            toolScope,
+            async composeSystemPrompt() {
+                const composed = preparedPrompt() ??
+                    (await operation((call) => coreExtensions.composeModelSystem(defaultComposition, call)));
+                clearPreparedPrompt();
+                systemPrompt = composed.text;
+                return composed;
+            }
+        };
+    };
+    return captureRoundToolScope;
+}

package/dist/sdk/extension-agent-controller.d.ts

@@ -0,0 +1,3 @@
+import type { SubagentController } from '../subagent/contracts.js';
+import { type ExtensionAgentAction } from '../extensions/agents.js';
+export declare function bindAgentController(controller: SubagentController, action: ExtensionAgentAction): SubagentController;

package/dist/sdk/extension-agent-controller.js

@@ -0,0 +1,69 @@
+import { parseAgentWaitTargets } from '../subagent/wait-targets.js';
+import { resolveAgentSpawn } from '../extensions/agents.js';
+export function bindAgentController(controller, action) {
+    const wait = (input, waitInterrupt) => action('agent.wait', input, (target, call) => {
+        const selection = parseAgentWaitTargets(target);
+        return selection.agentIds !== undefined
+            ? controller.outputMany(selection.agentIds, {
+                ...target,
+                waitInterrupt,
+                mode: selection.mode ?? 'any',
+                signal: call.signal
+            })
+            : target.agentId === undefined
+                ? controller.outputAny({ ...target, waitInterrupt, signal: call.signal })
+                : controller.output(target.agentId, { ...target, waitInterrupt, signal: call.signal });
+    });
+    return {
+        run: (input, options) => {
+            return action('agent.spawn', {
+                ...(options?.waitFor === undefined ? {} : { waitFor: options.waitFor }),
+                prompt: input.prompt,
+                description: input.description,
+                role: input.role,
+                background: input.background ?? false,
+                ...(input.modelId === undefined ? {} : { modelId: input.modelId }),
+                ...(input.reasoningEffort === undefined ? {} : { reasoningEffort: input.reasoningEffort })
+            }, async (target, call) => {
+                const task = resolveAgentSpawn(target);
+                return controller.run({
+                    prompt: task.prompt,
+                    description: task.description ?? input.description,
+                    role: task.role ?? input.role,
+                    background: task.background ?? false,
+                    ...(input.parentSubagentId === undefined
+                        ? {}
+                        : { parentSubagentId: input.parentSubagentId }),
+                    ...(task.modelId === undefined ? {} : { modelId: task.modelId }),
+                    ...(task.reasoningEffort === undefined
+                        ? {}
+                        : { reasoningEffort: task.reasoningEffort })
+                }, {
+                    ...options,
+                    ...(task.turnSignal === undefined ? {} : { turnSignal: task.turnSignal }),
+                    ...(task.waitFor === undefined ? {} : { waitFor: task.waitFor }),
+                    signal: call.signal
+                });
+            });
+        },
+        output: (id, options) => {
+            const { waitInterrupt, ...input } = options ?? {};
+            return wait({ ...input, agentId: id }, waitInterrupt);
+        },
+        outputAny: (options) => {
+            const { waitInterrupt, ...input } = options ?? {};
+            return wait(input, waitInterrupt);
+        },
+        outputMany: (ids, options) => {
+            const { waitInterrupt, ...input } = options ?? {};
+            return wait({ ...input, agentIds: ids }, waitInterrupt);
+        },
+        message: (id, message, options) => action('agent.message', { ...options, agentId: id, message }, (target, call) => controller.message(target.agentId, target.message, {
+            ...(target.delivery === undefined ? {} : { delivery: target.delivery }),
+            signal: call.signal
+        })),
+        cancel: (id) => action('agent.cancel', { agentId: id }, (target) => controller.cancel(target.agentId)),
+        listSessionResources: () => controller.listSessionResources(),
+        dispose: () => controller.dispose()
+    };
+}

package/dist/sdk/extension-agents.d.ts

@@ -0,0 +1,9 @@
+import type { ExtensionAgentsBackend } from '../extensions/agents.js';
+import type { ExtensionOperationContext } from '../extensions/operation.js';
+import type { SubagentParentOperation, SubagentSessionController } from '../subagent/session-controller.js';
+/** Uses the Session's sole task controller, including its durable children and queue. */
+export declare function createExtensionAgentsBackend(input: {
+    readonly controller: () => Promise<SubagentSessionController>;
+    readonly existingController: () => SubagentSessionController | undefined;
+    readonly parent: (controller: SubagentSessionController, call: ExtensionOperationContext) => SubagentParentOperation;
+}): ExtensionAgentsBackend;

package/dist/sdk/extension-agents.js

@@ -0,0 +1,58 @@
+import { AgentError } from '../error.js';
+import { parseAgentWaitTargets } from '../subagent/wait-targets.js';
+/** Uses the Session's sole task controller, including its durable children and queue. */
+export function createExtensionAgentsBackend(input) {
+    const withController = async (call, run) => {
+        call.signal.throwIfAborted();
+        const controller = await input.controller();
+        call.signal.throwIfAborted();
+        return controller.withOperation(input.parent(controller, call), () => run(controller));
+    };
+    return {
+        own: (owner) => async () => {
+            await input.existingController()?.cancelOwned(owner);
+        },
+        spawn: (task, call) => withController(call, (controller) => controller.run({
+            description: task.description ?? 'Extension agent',
+            prompt: task.prompt,
+            role: task.role ?? 'general-purpose',
+            background: task.background ?? true,
+            ...(task.modelId === undefined ? {} : { modelId: task.modelId }),
+            ...(task.reasoningEffort === undefined ? {} : { reasoningEffort: task.reasoningEffort })
+        }, {
+            signal: call.signal,
+            ...(task.turnSignal === undefined ? {} : { turnSignal: task.turnSignal }),
+            ...(task.waitFor === undefined ? {} : { waitFor: task.waitFor }),
+            onCreated: (created) => {
+                if (created.status === 'failed')
+                    throw new AgentError(created.errorCode ?? 'MAR_AGENT_SUBAGENT_FAILED', created.errorMessage ?? 'Agent could not start.');
+            }
+        })),
+        list: (call) => withController(call, (controller) => controller.list(call.signal)),
+        inspect: (target, call) => withController(call, (controller) => controller.inspect(target.agentId)),
+        wait: (target, call) => withController(call, (controller) => {
+            const selection = parseAgentWaitTargets(target);
+            const options = {
+                waitMs: target.waitMs ?? 30_000,
+                ...(target.untilSettled === undefined ? {} : { untilSettled: target.untilSettled }),
+                ...(target.waitFor === undefined ? {} : { waitFor: target.waitFor }),
+                signal: call.signal
+            };
+            if (selection.agentIds !== undefined)
+                return controller.outputMany(selection.agentIds, {
+                    ...options,
+                    mode: selection.mode ?? 'any'
+                });
+            if (target.untilSettled && target.agentId === undefined)
+                throw new AgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'An unbounded wait requires an agent id.');
+            return target.agentId === undefined
+                ? controller.outputAny(options)
+                : controller.output(target.agentId, options);
+        }),
+        message: (target, call) => withController(call, (controller) => controller.message(target.agentId, target.message, {
+            ...(target.delivery === undefined ? {} : { delivery: target.delivery }),
+            signal: call.signal
+        })),
+        cancel: (target, call) => withController(call, (controller) => controller.cancel(target.agentId))
+    };
+}