@myagentroam/agent 0.9.159 → 0.9.161

package/dist/agent-core/sdk/extension-models.js

@@ -0,0 +1,128 @@
+import { MarAgentError } from '../error.js';
+import { ExtensionRequestBridge } from '../extensions/model-request.js';
+import { transformCoreModelStream } from '../extensions/model-stream.js';
+import { modelTextInput } from '../model/text-blocks.js';
+export function createExtensionModels(state, createAdapter, resolveSnapshot) {
+    return {
+        list: () => {
+            const { models, defaultModelId } = state();
+            return Object.freeze([...models.values()].map((model) => Object.freeze({
+                id: model.id,
+                name: model.name,
+                modelId: model.modelId,
+                contextWindowTokens: model.contextWindowTokens,
+                maxOutputTokens: model.maxOutputTokens,
+                inputCapabilities: Object.freeze([...model.inputCapabilities]),
+                reasoningEfforts: Object.freeze([...model.reasoningEfforts]),
+                isDefault: model.id === defaultModelId
+            })));
+        },
+        async generate(input, call, transform, transformEvent, diagnoseCleanup) {
+            call.signal.throwIfAborted();
+            const { models, defaultModelId } = state();
+            const snapshot = input.requestSnapshot === undefined
+                ? undefined
+                : resolveSnapshot?.(input.requestSnapshot, call);
+            if (input.requestSnapshot !== undefined && !snapshot)
+                throw new MarAgentError('MAR_AGENT_MODEL_SNAPSHOT_INVALID', 'Request snapshot is unavailable.');
+            if (input.retainToolCatalog && !snapshot)
+                throw new MarAgentError('MAR_AGENT_MODEL_SNAPSHOT_INVALID', 'A retained tool catalog requires a real request snapshot.');
+            const modelId = input.modelId ?? snapshot?.modelId ?? defaultModelId;
+            const configuration = models.get(modelId);
+            if (!configuration)
+                throw new MarAgentError('MAR_AGENT_MODEL_DISABLED', 'Selected model is unavailable.');
+            if (input.outputLimit !== undefined &&
+                (!Number.isSafeInteger(input.outputLimit) || input.outputLimit < 1))
+                throw new MarAgentError('MAR_AGENT_MODEL_REQUEST_INVALID', 'Output limit must be a positive integer.');
+            const system = input.system === undefined ? undefined : modelTextInput(input.system);
+            const prompt = input.prompt === undefined ? undefined : modelTextInput(input.prompt);
+            const { systemBlocks: capturedBlocks, ...captured } = snapshot?.request ?? {};
+            const systemBlocks = system ? system.blocks : capturedBlocks;
+            const bridge = new ExtensionRequestBridge(modelId, {
+                ...captured,
+                system: system?.text ?? snapshot?.request.system ?? '',
+                ...(systemBlocks === undefined ? {} : { systemBlocks }),
+                messages: snapshot?.request.messages ?? [],
+                tools: input.retainToolCatalog ? snapshot.request.tools : [],
+                toolChoice: 'none'
+            }, snapshot?.view.messages);
+            const view = await transform({
+                ...bridge.view,
+                messages: [
+                    ...(input.messages ?? bridge.view.messages),
+                    ...(prompt
+                        ? [
+                            {
+                                role: 'user',
+                                content: prompt.text,
+                                ...(prompt.blocks === undefined ? {} : { textBlocks: prompt.blocks })
+                            }
+                        ]
+                        : [])
+                ],
+                ...(input.reasoningEffort ? { reasoningEffort: input.reasoningEffort } : {})
+            });
+            const lowered = bridge.lower(view);
+            if (lowered.tools.length && !input.retainToolCatalog)
+                throw new MarAgentError('MAR_AGENT_MODEL_REQUEST_INVALID', 'Independent generation does not execute tools.');
+            const request = {
+                ...lowered,
+                ...(input.retainToolCatalog &&
+                    snapshot.request.systemBlocks === undefined &&
+                    snapshot.request.messages.every((message) => message.textBlocks === undefined)
+                    ? { cachePrefixMessages: Math.max(0, lowered.messages.length - (prompt ? 1 : 0)) }
+                    : {}),
+                toolChoice: 'none',
+                allowTools: input.retainToolCatalog === true,
+                outputLimit: Math.min(input.outputLimit ?? configuration.maxOutputTokens, configuration.maxOutputTokens)
+            };
+            const adapter = createAdapter(modelId, models);
+            let text = '';
+            const chunks = new Map();
+            let stopReason;
+            let usage;
+            let failed = false;
+            try {
+                for await (const event of transformCoreModelStream((signal) => adapter.start(request, signal), call.signal, transformEvent, () => diagnoseCleanup?.('MAR_AGENT_MODEL_STREAM_CLEANUP_FAILED'))) {
+                    call.signal.throwIfAborted();
+                    if (event.type === 'text.delta' && event.phase === 'final_answer')
+                        chunks.set(event.itemId, (chunks.get(event.itemId) ?? '') + event.delta);
+                    else if (event.type === 'text.completed' && event.phase !== 'commentary')
+                        chunks.set(event.itemId, event.text);
+                    else if (event.type === 'output.reset')
+                        chunks.clear();
+                    else if (event.type === 'usage')
+                        usage = { ...event.usage };
+                    else if (event.type === 'completed')
+                        stopReason = event.reason;
+                    else if (event.type === 'client_tool.call' && !input.retainToolCatalog)
+                        throw new MarAgentError('MAR_AGENT_MODEL_REQUEST_INVALID', 'Independent generation received a tool call.');
+                }
+                call.signal.throwIfAborted();
+                if (!stopReason)
+                    throw new MarAgentError('MAR_AGENT_MODEL_STREAM_INCOMPLETE', 'Model stream ended without a terminal outcome.');
+                text = [...chunks.values()].join('');
+                return {
+                    outcome: stopReason === 'cancelled' ? 'cancelled' : text ? 'text' : 'empty',
+                    text,
+                    stopReason,
+                    ...(usage ? { usage: Object.freeze(usage) } : {})
+                };
+            }
+            catch (error) {
+                failed = true;
+                throw error;
+            }
+            finally {
+                try {
+                    await adapter.close?.();
+                }
+                catch (error) {
+                    if (!failed)
+                        throw error;
+                    diagnoseCleanup?.('MAR_AGENT_MODEL_ADAPTER_CLEANUP_FAILED');
+                }
+            }
+        }
+    };
+}

package/dist/agent-core/sdk/extension-session.d.ts

@@ -0,0 +1,30 @@
+import type { ExecutionHandle } from './types.js';
+import type { CoreOperationContext } from '../extensions/operation.js';
+import type { CoreRequestSnapshot } from '../extensions/model-request.js';
+import type { CorePromptComposition, CorePromptFacts } from '../extensions/prompt-composition.js';
+import { SessionInputCoordinator, type CoreSessionBackend, type CoreSessionRequest, type SessionInputEntry, type CoreSessionMessages, type CoreSessionMessagesInput, type CoreSessionActionResult } from '../extensions/session-input.js';
+import type { CoreSessionDescription } from '../extensions/session-input.js';
+export interface ExtensionSessionPorts {
+    describe?(call: CoreOperationContext): Promise<CoreSessionDescription>;
+    composePrompt?(facts: CorePromptFacts, call: CoreOperationContext): Promise<CorePromptComposition>;
+    captureRequest(call: CoreOperationContext, input?: {
+        readonly completed?: boolean;
+    }): Promise<CoreRequestSnapshot | undefined>;
+    readonly sessionId: string;
+    coordinator(): SessionInputCoordinator;
+    activeExecutionId(): string | undefined;
+    messages(input: CoreSessionMessagesInput, call: CoreOperationContext): Promise<CoreSessionMessages>;
+    append(entry: SessionInputEntry, request: Extract<CoreSessionRequest, {
+        kind: 'append';
+    }>, call: CoreOperationContext): Promise<CoreSessionActionResult>;
+    launch(entry: SessionInputEntry, request: Exclude<CoreSessionRequest, {
+        kind: 'append';
+    }>, call: CoreOperationContext): Promise<ExecutionHandle & {
+        readonly inputCommitted: Promise<CoreSessionActionResult>;
+    }>;
+    diagnose(code: string, operationId: string): void;
+}
+/** Admission and idle execution reuse the same Session coordinator and SDK entry. */
+export declare function createExtensionSessionBackend(ports: ExtensionSessionPorts): CoreSessionBackend & {
+    kick(): void;
+};

package/dist/agent-core/sdk/extension-session.js

@@ -0,0 +1,103 @@
+import { MarAgentError } from '../error.js';
+/** Admission and idle execution reuse the same Session coordinator and SDK entry. */
+export function createExtensionSessionBackend(ports) {
+    let scheduled;
+    const idleLeaf = async (entry, request, call) => {
+        call.signal.throwIfAborted();
+        if (request.kind === 'append')
+            return ports.append(entry, request, call);
+        const handle = await ports.launch(entry, request, call);
+        ports.coordinator().startExecution(entry, handle.executionId);
+        const cancel = () => handle.cancel();
+        call.signal.addEventListener('abort', cancel, { once: true });
+        if (call.signal.aborted)
+            cancel();
+        const completion = handle
+            .result()
+            .then((result) => {
+            ports.coordinator().settleExecution(handle.executionId, result.status);
+            return result;
+        })
+            .finally(() => call.signal.removeEventListener('abort', cancel));
+        if (request.kind === 'compact') {
+            const result = await completion;
+            if (result.status !== 'completed')
+                throw new MarAgentError(result.errorCode ?? 'MAR_AGENT_COMPACT_FAILED', 'Requested compaction did not complete.');
+        }
+        else {
+            void completion.catch(() => ports.diagnose('MAR_AGENT_SESSION_INPUT_FAILED', call.operationId));
+            return await handle.inputCommitted;
+        }
+        return { changed: true, executionId: handle.executionId };
+    };
+    const kick = () => {
+        if (scheduled ||
+            ports.activeExecutionId() ||
+            ports.coordinator().executing ||
+            !ports.coordinator().hasPending)
+            return;
+        scheduled = Promise.resolve()
+            .then(async () => {
+            if (!ports.activeExecutionId())
+                await ports.coordinator().drain(idleLeaf, undefined, 1);
+        })
+            .catch(() => ports.diagnose('MAR_AGENT_SESSION_INPUT_FAILED', 'idle-admission'))
+            .finally(() => {
+            scheduled = undefined;
+            kick();
+        });
+    };
+    return {
+        ...(ports.describe ? { describe: (call) => ports.describe(call) } : {}),
+        ...(ports.composePrompt
+            ? {
+                composePrompt: (facts, call) => ports.composePrompt(facts, call)
+            }
+            : {}),
+        captureRequest: (call, input) => ports.captureRequest(call, input),
+        kick,
+        inspect: async (call) => {
+            call.signal.throwIfAborted();
+            const executionId = ports.activeExecutionId();
+            return {
+                sessionId: ports.sessionId,
+                epoch: call.sessionEpoch,
+                ...(executionId ? { activeExecutionId: executionId } : {}),
+                operations: ports.coordinator().inspect()
+            };
+        },
+        messages: (input, call) => ports.messages(input, call),
+        handled: (input, call, value) => ports.coordinator().handled(input, call, value),
+        own: (id) => {
+            const coordinator = ports.coordinator();
+            return () => coordinator.retire(id);
+        },
+        enqueue: async (request, call, action) => {
+            const coordinator = ports.coordinator();
+            if (request.kind === 'append' && request.input.delivery === 'immediate') {
+                try {
+                    return await coordinator.performAppend(request.input, call, action, (entry, value, effective) => {
+                        if (value.kind !== 'append')
+                            throw new MarAgentError('MAR_AGENT_SESSION_INPUT_INVALID', 'Immediate record submission must remain an append.');
+                        return ports.append(entry, value, effective);
+                    });
+                }
+                finally {
+                    kick();
+                }
+            }
+            const current = request.kind === 'compact' ? coordinator.currentCompact() : undefined;
+            if (current)
+                return current;
+            const idle = !ports.activeExecutionId() && !coordinator.executing;
+            const entry = coordinator.accept(request, call, action, request.kind === 'submit' ? 'accepted' : 'queued');
+            kick();
+            if (idle && request.kind === 'submit' && request.input.waitFor === 'start')
+                await entry.started;
+            else if ((idle && request.kind !== 'submit') ||
+                (request.kind === 'submit' && request.input.waitFor === 'commit'))
+                await entry.terminal;
+            return Object.freeze({ ...entry.receipt });
+        }
+    };
+}

package/dist/agent-core/sdk/extension-tools.d.ts

@@ -0,0 +1,16 @@
+import type { CoreToolBinding } from '../extensions/tools.js';
+import type { ClientToolDefinition, McpToolCatalog } from '../tools/contracts.js';
+import { type RoundToolScope } from '../tools/execution.js';
+import type { ToolRuntimeContext } from '../tools/runtime-context.js';
+/** One real Execution's sources; a retained physical frame is distinct from its active main round. */
+export declare class ExecutionToolSources {
+    #private;
+    readonly executionId: string;
+    readonly sessionId: string;
+    readonly bindings: readonly CoreToolBinding[];
+    constructor(executionId: string, sessionId: string, definitions: readonly ClientToolDefinition[], builtins: readonly ClientToolDefinition[], catalog: McpToolCatalog, supplemental?: readonly CoreToolBinding[]);
+    bind(scope: RoundToolScope): void;
+    assertActive(): void;
+    withFrame<Value>(context: ToolRuntimeContext, run: () => Value): Value;
+    close(): void;
+}

package/dist/agent-core/sdk/extension-tools.js

@@ -0,0 +1,126 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
+import { MarAgentError } from '../error.js';
+import { toolCallers } from '../tools/callers.js';
+import { createRoundToolRuntimeContext } from '../tools/execution.js';
+import { executeCapturedTool } from '../tools/runtime.js';
+/** One real Execution's sources; a retained physical frame is distinct from its active main round. */
+export class ExecutionToolSources {
+    executionId;
+    sessionId;
+    bindings;
+    #frame = new AsyncLocalStorage();
+    #scope;
+    #closed = false;
+    constructor(executionId, sessionId, definitions, builtins, catalog, supplemental = []) {
+        this.executionId = executionId;
+        this.sessionId = sessionId;
+        this.bindings = Object.freeze([
+            ...definitions.map((original) => {
+                const captured = catalog.tools.find((tool) => tool.definition.name === original.name);
+                const mcp = captured === undefined ? undefined : structuredClone(captured);
+                const kind = mcp ? 'mcp' : builtins.includes(original) ? 'builtin' : 'host';
+                const definition = Object.freeze({
+                    ...structuredClone(original),
+                    allowedCallers: Object.freeze([...toolCallers(original)])
+                });
+                return Object.freeze({
+                    definition,
+                    source: Object.freeze({
+                        kind,
+                        id: mcp?.sourceIdentity ?? `${kind}:${executionId}:${definition.name}`,
+                        revision: mcp?.definitionRevision ?? executionId
+                    }),
+                    ...(mcp === undefined ? {} : { mcp }),
+                    available: (call) => {
+                        const context = this.#context(call);
+                        if (!context)
+                            return false;
+                        if (definition.name === 'skill')
+                            return context.skills.size > 0;
+                        if (['agent_start', 'agent_wait', 'agent_message', 'agent_cancel'].includes(definition.name))
+                            return context.subagents !== undefined;
+                        if (definition.name === 'tool_search')
+                            return (this.#currentFrame()?.searchMcpTools !== undefined || this.#scope !== undefined);
+                        return true;
+                    },
+                    invoke: async (input, call) => {
+                        const context = this.#context(call);
+                        if (!context)
+                            throw unavailable();
+                        const frame = this.#currentFrame();
+                        const scope = this.#scope;
+                        const actual = frame ??
+                            (scope &&
+                                (await createRoundToolRuntimeContext(scope, { ...input, callId: input.callId ?? randomUUID() }, call.signal)));
+                        if (!actual || !this.#context(call))
+                            throw unavailable();
+                        call.signal.throwIfAborted();
+                        return executeCapturedTool(kind, input, {
+                            ...actual,
+                            signal: call.signal,
+                            ...(mcp === undefined
+                                ? {}
+                                : {
+                                    expectedMcpTool: {
+                                        sourceIdentity: mcp.sourceIdentity,
+                                        definitionRevision: mcp.definitionRevision
+                                    }
+                                })
+                        });
+                    }
+                });
+            }),
+            ...supplemental
+        ]);
+    }
+    bind(scope) {
+        if (this.#closed ||
+            scope.context.executionId !== this.executionId ||
+            scope.context.sessionId !== this.sessionId)
+            throw unavailable();
+        this.#scope = scope;
+    }
+    assertActive() {
+        if (this.#closed)
+            throw unavailable();
+    }
+    withFrame(context, run) {
+        if (context.executionId !== this.executionId || context.sessionId !== this.sessionId)
+            throw unavailable();
+        const frame = { context, active: true };
+        return this.#frame.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;
+            }
+        });
+    }
+    close() {
+        this.#closed = true;
+        this.#scope = undefined;
+    }
+    #context(call) {
+        if (call.executionId !== this.executionId || call.sessionId !== this.sessionId)
+            return;
+        const frame = this.#currentFrame();
+        const context = frame ?? (this.#closed ? undefined : this.#scope?.context);
+        return context && !context.signal.aborted ? context : undefined;
+    }
+    #currentFrame() {
+        const frame = this.#frame.getStore();
+        return frame?.active ? frame.context : undefined;
+    }
+}
+function unavailable() {
+    return new MarAgentError('MAR_AGENT_TOOL_NOT_AVAILABLE', 'Execution tool source is unavailable.');
+}

package/dist/agent-core/sdk/session.d.ts

@@ -1,8 +1,14 @@
 import type { ContextualWorldState } from '../runtime/context/world-state.js';
 import type { ResolvedModelConfiguration } from './model-runtime.js';
+import { ExecutionToolSources } from './extension-tools.js';
+import type { ExtensionManager } from '../extensions/manager.js';
+import type { CoreOperationContext } from '../extensions/operation.js';
+import { ExtensionRequestSnapshots } from '../extensions/model-request.js';
+import { SessionInputCoordinator, type CoreSessionBackend } from '../extensions/session-input.js';
+import type { CoreAgentsBackend } from '../extensions/agents.js';
 import type { HostDescription, MarAgentHost } from '../host/contracts.js';
 import { type MarAgentReasoningEffort } from '../model/configuration.js';
-import type { ModelAdapter } from '../model/contracts.js';
+import type { ModelAdapter, ModelMessage } from '../model/contracts.js';
 import { RolloutBudget, resolveRolloutBudgetOptions } from '../runtime/rollout-budget.js';
 import { JsonlSessionStore } from '../session/jsonl-store.js';
 import { SubagentSessionController, type SubagentMailboxMessage, type SubagentMessageDelivery, type SubagentTurnHandle } from '../subagent/session-controller.js';
@@ -18,6 +24,22 @@ export interface SessionRuntime {
     contextualWorldState?: ContextualWorldState;
     subagents?: SubagentSessionController;
     subagentsOpening?: Promise<SubagentSessionController>;
+    inputs?: SessionInputCoordinator;
+    requestSnapshots?: ExtensionRequestSnapshots;
+    requestMessages?: {
+        readonly executionId: string;
+        read(): readonly ModelMessage[];
+    };
+    recordProjection?: Promise<unknown>;
+    appendedMessages?: {
+        readonly executionId: string;
+        append(recordId: string, message: ModelMessage): void;
+    };
+    sessionBackend?: CoreSessionBackend & {
+        kick(): void;
+    };
+    agentsBackend?: CoreAgentsBackend;
+    toolSources?: ExecutionToolSources;
 }
 interface InternalMarAgentSession extends MarAgentSession {
     startSubagentTurn(input: {
@@ -29,7 +51,8 @@ interface InternalMarAgentSession extends MarAgentSession {
         readonly turnId: string;
         readonly delivery?: SubagentMessageDelivery;
         readonly sharedRolloutBudget?: RolloutBudget;
-        readonly mcpExecutionScopeId: string;
+        readonly mcpExecutionScopeId?: string;
+        readonly origin?: CoreOperationContext;
     }): SubagentTurnHandle;
 }
 /** Agent-owned registries shared with Session orchestration, not public execution state. */
@@ -45,6 +68,7 @@ interface SessionServices {
     readonly description: HostDescription;
     readonly settings: Pick<CreateMarAgentOptions, 'workspaceMapping' | 'systemInstruction'>;
     readonly store: JsonlSessionStore;
+    readonly extensions: ExtensionManager;
     readonly registry: AgentSessionRegistry;
     readonly rolloutBudgetOptions: ReturnType<typeof resolveRolloutBudgetOptions>;
     readonly hasCustomAdapters: boolean;