@myagentroam/agent 0.9.159 → 0.9.160

package/dist/agent-core/runtime/context/restore.d.ts

@@ -4,9 +4,14 @@ import type { EnvironmentContextState } from './contracts.js';
 import { type ContextProjection } from './projection.js';
 export declare function restoreMessages(store: JsonlSessionStore, sessionId: string, records: readonly import('../../session/jsonl-store.js').SessionRecord[], options: {
     includeImages: boolean;
+    strictImages?: boolean;
     currentTurnId?: string;
     projection?: ContextProjection;
 }): Promise<{
+    toolOutcomes: WeakMap<ModelMessage, {
+        isError: boolean;
+        result?: unknown;
+    }>;
     environmentState: EnvironmentContextState | undefined;
     userMessages: string[];
     messages: ModelMessage[];

package/dist/agent-core/runtime/context/restore.js

@@ -2,9 +2,11 @@ import { MarAgentError } from '../../error.js';
 import { compactSummaryFromCheckpoint, replacementHistoryFromCheckpoint } from '../../session/jsonl-store.js';
 import { compactedHistoryMessages, continuationMessage } from '../compaction/history.js';
 import { environmentContextUpdate, restoreEnvironmentState } from './environment.js';
-import { buildContextProjection } from './projection.js';
+import { buildContextProjection, restoreModelContext } from './projection.js';
 export async function restoreMessages(store, sessionId, records, options) {
     const messages = [];
+    const outcomes = new Map();
+    const toolOutcomes = new WeakMap();
     const modelProjection = new Map((options.projection ??
         buildContextProjection(records, (await store.getSession(sessionId)).workspace)).entries.map((entry) => [entry.record.recordId, entry.message]));
     let userMessages = [];
@@ -13,15 +15,30 @@ export async function restoreMessages(store, sessionId, records, options) {
     let environmentState;
     for (const record of records) {
         const payload = record.payload;
+        if ((record.type === 'tool.completed' || record.type === 'tool.failed') &&
+            typeof payload.callId === 'string') {
+            const result = record.type === 'tool.failed' ? payload.message : payload.data;
+            outcomes.set(JSON.stringify([record.executionId, payload.callId]), {
+                isError: record.type === 'tool.failed',
+                ...(result === undefined ? {} : { result: structuredClone(result) })
+            });
+        }
         const compactSummary = compactSummaryFromCheckpoint(record);
-        if (record.type === 'turn.user' && typeof payload.prompt === 'string') {
+        if ((record.type === 'turn.user' || record.type === 'extension.input') &&
+            typeof payload.prompt === 'string') {
             userMessages.push(payload.prompt);
             let images = [];
             if (options.includeImages)
                 try {
                     images = await store.readInputImages(sessionId, payload.images);
+                    if (options.strictImages &&
+                        payload.images !== undefined &&
+                        (!Array.isArray(payload.images) || images.length !== payload.images.length))
+                        throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Session input images cannot be fully restored.');
                 }
                 catch (error) {
+                    if (options.strictImages)
+                        throw error;
                     if (!(error instanceof MarAgentError) || error.code !== 'MAR_AGENT_SESSION_CORRUPT')
                         throw error;
                     ignoredImages += Array.isArray(payload.images) ? payload.images.length : 1;
@@ -30,9 +47,20 @@ export async function restoreMessages(store, sessionId, records, options) {
                 currentTurnUserIndex = messages.length;
             messages.push({
                 role: 'user',
-                content: payload.prompt,
+                content: typeof payload.modelText === 'string' ? payload.modelText : payload.prompt,
                 ...(images.length ? { images } : {})
             });
+            const context = payload.modelContext ?? payload.context;
+            if (payload.contextRecords !== true && Array.isArray(context))
+                for (const text of context)
+                    if (typeof text === 'string')
+                        messages.push({ role: 'user', content: text });
+        }
+        else if (record.type === 'input.context') {
+            if (Array.isArray(payload.modelContext))
+                for (const text of payload.modelContext)
+                    if (typeof text === 'string')
+                        messages.push({ role: 'user', content: text });
         }
         else if ((record.type === 'message.completed' || record.type === 'plan.completed') &&
             typeof payload.text === 'string')
@@ -49,6 +77,14 @@ export async function restoreMessages(store, sessionId, records, options) {
             messages.push(...(history
                 ? compactedHistoryMessages(history)
                 : [{ role: 'user', content: continuationMessage(compactSummary) }]));
+            if (Array.isArray(payload.retainedModelContext))
+                for (const item of payload.retainedModelContext) {
+                    if (!item || typeof item !== 'object' || item.role !== 'user')
+                        continue;
+                    const message = restoreModelContext(item);
+                    if (message)
+                        messages.push(message);
+                }
         }
         else if (record.type === 'context.environment') {
             const current = restoreEnvironmentState(payload);
@@ -61,12 +97,19 @@ export async function restoreMessages(store, sessionId, records, options) {
         }
         else if (record.type === 'model.context') {
             const message = modelProjection.get(record.recordId);
-            if (message)
+            if (message) {
                 messages.push(message);
+                if (message.role === 'tool' && message.callId !== undefined) {
+                    const outcome = outcomes.get(JSON.stringify([record.executionId, message.callId]));
+                    if (outcome)
+                        toolOutcomes.set(message, outcome);
+                }
+            }
         }
     }
     const completedToolCalls = new Set(messages.filter((message) => message.role === 'tool').map((message) => message.callId));
     return {
+        toolOutcomes,
         environmentState,
         userMessages,
         messages: messages.filter((message) => {

package/dist/agent-core/runtime/context/usage.js

@@ -1,8 +1,7 @@
 import { isDeepStrictEqual } from 'node:util';
 import { marAgentReasoningEffortSchema } from '../../model/configuration.js';
 import { compactSummaryFromCheckpoint } from '../../session/jsonl-store.js';
-import { countModelTokens } from '../token-budget.js';
-import { stableJson } from './request-budget.js';
+import { estimatedRequestTokens } from './request-budget.js';
 export function latestModelUsage(records, selectedModelId) {
     let usage;
     const toolCallIds = new Set();
@@ -104,7 +103,7 @@ export function shouldUseNativeCompaction(input) {
     const historyDelta = appendOnlyUsageDelta(input.latestUsage, input.historyMessages);
     if (historyDelta === undefined)
         return false;
-    const appendedTokens = countModelTokens(stableJson([...historyDelta, ...input.appendedMessages]));
+    const appendedTokens = estimatedRequestTokens('', [...historyDelta, ...input.appendedMessages], []);
     return (input.latestUsage.contextInputTokens + input.latestUsage.outputTokens + appendedTokens <=
         input.contextWindowTokens);
 }

package/dist/agent-core/runtime/contracts.d.ts

@@ -25,6 +25,8 @@ export interface ExecutionResult {
     executionId: string;
     status: 'completed' | 'failed' | 'cancelled';
     finalAnswer: string;
+    /** The input hook answered without admitting input; no model Turn was requested. */
+    inputHandled?: boolean;
     errorCode?: string;
     errorMessage?: string;
 }

package/dist/agent-core/runtime/execution.js

@@ -302,6 +302,8 @@ export class ExecutionLoop {
                 const message = {
                     role: 'tool',
                     callId: result.call.callId,
+                    name: result.call.name,
+                    isError: result.failed,
                     content: result.content,
                     ...(result.calls ? { calls: result.calls } : {}),
                     ...(result.observations ? { observations: result.observations } : {}),
@@ -312,6 +314,8 @@ export class ExecutionLoop {
                 await input.appendContext({
                     role: message.role,
                     callId: result.call.callId,
+                    name: result.call.name,
+                    isError: result.failed,
                     content: message.content,
                     ...(message.calls ? { calls: message.calls } : {}),
                     ...(message.observations ? { observations: message.observations } : {}),
@@ -351,8 +355,7 @@ export class ExecutionLoop {
                 throw aborted ?? new MarAgentError('MAR_AGENT_EXECUTION_CANCELLED', 'Execution cancelled.');
             }
             input.rolloutBudget?.assertAvailable();
-            if (input.mailbox.hasPending()) {
-                await input.mailbox.append();
+            if (input.mailbox.hasPending() && (await input.mailbox.append())) {
                 this.finalAnswer = '';
                 continue;
             }

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

@@ -1,7 +1,10 @@
 import { addModelCredentialProviders, closeModelAdapters, resolveAgentModels } from './model-runtime.js';
 import { createSessionOpener } from './session.js';
 import { MarAgentError } from '../error.js';
+import { ExtensionManager } from '../extensions/manager.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 { resolveRolloutBudgetOptions } from '../runtime/rollout-budget.js';
@@ -29,6 +32,16 @@ export async function createMarAgentWithAdapter(options) {
     const sessionRuntimes = new Map();
     const sessionWriterOwner = {};
     let disposed = false;
+    let disposal;
+    const sessionLifecycles = new Set();
+    const trackSessionLifecycle = (operation) => {
+        if (disposed)
+            return Promise.reject(new MarAgentError('MAR_AGENT_DISPOSED', 'Agent is disposed.'));
+        const pending = operation();
+        sessionLifecycles.add(pending);
+        void pending.finally(() => sessionLifecycles.delete(pending)).catch(() => undefined);
+        return pending;
+    };
     let reconfiguring = false;
     const createAdapter = (modelId, configuredModels = models) => {
         const configuration = configuredModels.get(modelId);
@@ -40,6 +53,85 @@ export async function createMarAgentWithAdapter(options) {
                 : new AnthropicMessagesAdapter(configuration)));
     };
     const activeSessionIds = () => new Set([...active.keys()].map((key) => key.slice(0, key.indexOf(':'))));
+    const extensions = new ExtensionManager({
+        ...(options.host.extensionPorts === undefined
+            ? {}
+            : { hostPorts: options.host.extensionPorts }),
+        extensions: options.runtimeExtensions ?? [],
+        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, (snapshot, call) => {
+            const snapshots = sessionRuntimes.get(call.sessionId)?.requestSnapshots;
+            if (!snapshots)
+                throw new MarAgentError('MAR_AGENT_MODEL_SNAPSHOT_INVALID', 'Request snapshot is unavailable.');
+            return snapshots.resolve(snapshot);
+        }),
+        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 MarAgentError('MAR_AGENT_TOOL_NOT_AVAILABLE', 'Session tool scheduler is unavailable.');
+            return schedule(definition, run);
+        },
+        baseTools: (id, context) => {
+            const execution = sessionRuntimes.get(id)?.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();
         for (const [candidateSessionId, runtime] of sessionRuntimes)
@@ -61,6 +153,7 @@ export async function createMarAgentWithAdapter(options) {
         description,
         settings,
         store,
+        extensions,
         registry: {
             active,
             activeExecutionAdapters,
@@ -81,21 +174,40 @@ export async function createMarAgentWithAdapter(options) {
         }
     });
     return {
+        extensionDiagnostics: () => extensions.diagnostics(),
         createSession: async (input) => openSession((await store.createSession(input)).id, input.workspace),
         openSession: (id) => openSession(id),
         listSessions: (input) => store.list(input),
         getSession: (id) => store.getSession(id),
         setSessionTitle: (id, title, input) => store.updateTitle(id, title, { ...input, automatic: input?.automatic ?? false }, sessionWriterOwner),
-        clearSession: async (id) => {
+        clearSession: (id) => trackSessionLifecycle(async () => {
             const runtime = sessionRuntimes.get(id);
             if ([...active.keys()].some((key) => key.startsWith(`${id}:`)))
                 throw new MarAgentError('MAR_AGENT_EXECUTION_ACTIVE', 'A session cannot be cleared while an execution is active.');
-            await runtime?.subagents?.dispose();
-            await closeModelAdapters(runtime === undefined ? [] : [...runtime.adapters.values()]);
-            sessionRuntimes.delete(id);
-            await options.host.disposeSessionResources?.(id);
-            await store.clearSession(id);
-        },
+            await extensions.endSession(id, 'clear');
+            extensions.retireSession(id);
+            await completeAgentCleanup([
+                () => extensions.clearSession(id),
+                () => runtime?.inputs?.retire(),
+                () => runtime?.subagents?.dispose(),
+                () => closeModelAdapters(runtime === undefined ? [] : [...runtime.adapters.values()]),
+                () => {
+                    // Existing SDK Session handles share this runtime and remain usable after clear.
+                    if (runtime) {
+                        runtime.adapters.clear();
+                        runtime.adapterGeneration = modelGeneration;
+                        delete runtime.todo;
+                        delete runtime.subagents;
+                        delete runtime.subagentsOpening;
+                        delete runtime.contextualWorldState;
+                        delete runtime.inputs;
+                        delete runtime.requestSnapshots;
+                    }
+                },
+                () => options.host.disposeSessionResources?.(id),
+                () => store.clearSession(id)
+            ]);
+        }),
         setSystemInstruction: (systemInstruction) => {
             if (disposed)
                 throw new MarAgentError('MAR_AGENT_DISPOSED', 'Agent is disposed.');
@@ -169,52 +281,77 @@ export async function createMarAgentWithAdapter(options) {
                 reconfiguring = false;
             }
         },
-        deleteSession: async (id) => {
+        deleteSession: (id) => trackSessionLifecycle(async () => {
             const sessionIds = await store.sessionTree(id);
             const sessionIdSet = new Set(sessionIds);
             const executionKeys = [...active.keys()].filter((key) => sessionIdSet.has(key.slice(0, key.indexOf(':'))));
             for (const key of executionKeys)
                 active.get(key)?.abort();
+            await Promise.all(sessionIds.map((sessionId) => extensions.endSession(sessionId, 'other', false)));
+            for (const sessionId of sessionIds)
+                extensions.retireSession(sessionId);
             const runtimes = sessionIds.flatMap((sessionId) => {
                 const runtime = sessionRuntimes.get(sessionId);
                 sessionRuntimes.delete(sessionId);
                 return runtime === undefined ? [] : [runtime];
             });
-            await Promise.all(runtimes.map((runtime) => runtime.subagents?.dispose()));
-            await Promise.allSettled(executionKeys.flatMap((key) => {
-                const result = executionResults.get(key);
-                return result === undefined ? [] : [result];
-            }));
-            await closeModelAdapters(runtimes.flatMap((runtime) => [...runtime.adapters.values()]));
-            await Promise.all(sessionIds.map((sessionId) => options.host.disposeSessionResources?.(sessionId)));
-            await store.delete(id);
-        },
-        dispose: async () => {
-            if (disposed)
-                return;
+            await completeAgentCleanup([
+                ...sessionIds.map((sessionId) => () => extensions.clearSession(sessionId)),
+                ...runtimes.map((runtime) => () => runtime.inputs?.retire()),
+                ...runtimes.map((runtime) => () => runtime.subagents?.dispose()),
+                () => Promise.allSettled(executionKeys.flatMap((key) => {
+                    const result = executionResults.get(key);
+                    return result === undefined ? [] : [result];
+                })),
+                () => closeModelAdapters(runtimes.flatMap((runtime) => [...runtime.adapters.values()])),
+                ...sessionIds.map((sessionId) => () => options.host.disposeSessionResources?.(sessionId)),
+                () => store.delete(id)
+            ]);
+        }),
+        dispose: () => {
+            if (disposal)
+                return disposal;
             disposed = true;
             for (const controller of active.values())
                 controller.abort();
-            await Promise.all([...sessionRuntimes.values()].map((runtime) => runtime.subagents?.dispose().catch(() => undefined)));
-            await Promise.allSettled([...executionResults.values()]);
-            await closeModelAdapters([...sessionRuntimes.values()].flatMap((runtime) => [...runtime.adapters.values()]));
-            let disposalError;
-            const providerResults = await Promise.allSettled([...credentialProviders].map((provider) => provider.close()));
-            disposalError = providerResults.find((result) => result.status === 'rejected')?.reason;
-            try {
-                await options.host.dispose();
-            }
-            catch (error) {
-                disposalError ??= error;
-            }
-            try {
-                await store.close();
-            }
-            catch (error) {
-                disposalError ??= error;
-            }
-            if (disposalError !== undefined)
-                throw disposalError;
+            // Explicit end observers finish in a separate lifecycle frame before Session retirement.
+            const extensionDisposal = extensions.dispose();
+            void extensionDisposal.catch(() => undefined);
+            const runtimes = [...sessionRuntimes.values()];
+            disposal = completeAgentCleanup([
+                async () => {
+                    const results = await Promise.allSettled([...sessionLifecycles]);
+                    const failure = results.find((result) => result.status === 'rejected');
+                    if (failure?.status === 'rejected')
+                        throw failure.reason;
+                },
+                () => extensionDisposal,
+                ...runtimes.map((runtime) => () => runtime.inputs?.retire()),
+                ...runtimes.map((runtime) => () => runtime.subagents?.dispose()),
+                () => Promise.allSettled([...executionResults.values()]),
+                () => closeModelAdapters(runtimes.flatMap((runtime) => [...runtime.adapters.values()])),
+                ...[...credentialProviders].map((provider) => () => provider.close()),
+                () => options.host.dispose(),
+                () => store.close()
+            ]);
+            return disposal;
         }
     };
 }
+/** Finish independent cleanup steps and preserve the first authoritative failure. */
+async function completeAgentCleanup(steps) {
+    let failed = false;
+    let failure;
+    for (const step of steps) {
+        try {
+            await step();
+        }
+        catch (error) {
+            if (!failed)
+                failure = error;
+            failed = true;
+        }
+    }
+    if (failed)
+        throw failure;
+}

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

@@ -0,0 +1,9 @@
+import type { CoreAgentsBackend } from '../extensions/agents.js';
+import type { CoreOperationContext } 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: CoreOperationContext) => SubagentParentOperation;
+}): CoreAgentsBackend;

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

@@ -0,0 +1,51 @@
+import { MarAgentError } from '../error.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 MarAgentError(created.errorCode ?? 'MAR_AGENT_SUBAGENT_FAILED', created.errorMessage ?? 'Agent could not start.');
+            }
+        })),
+        list: (call) => withController(call, async (controller) => controller.inspectAll()),
+        inspect: (target, call) => withController(call, (controller) => controller.inspect(target.agentId)),
+        wait: (target, call) => withController(call, (controller) => {
+            const options = {
+                waitMs: target.waitMs ?? 30_000,
+                ...(target.untilSettled === undefined ? {} : { untilSettled: target.untilSettled }),
+                ...(target.waitFor === undefined ? {} : { waitFor: target.waitFor }),
+                signal: call.signal
+            };
+            if (target.untilSettled && target.agentId === undefined)
+                throw new MarAgentError('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))
+    };
+}

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

@@ -0,0 +1,13 @@
+import type { CoreModelsBackend } from '../extensions/models.js';
+import type { CoreOperationContext } from '../extensions/operation.js';
+import type { CoreModelRequest, CoreRequestSnapshot } from '../extensions/model-request.js';
+import type { ModelAdapter, ModelRequest } from '../model/contracts.js';
+import type { ResolvedModelConfiguration } from './model-runtime.js';
+export declare function createExtensionModels(state: () => {
+    models: ReadonlyMap<string, ResolvedModelConfiguration>;
+    defaultModelId: string;
+}, createAdapter: (modelId: string, models: ReadonlyMap<string, ResolvedModelConfiguration>) => ModelAdapter, resolveSnapshot?: (snapshot: CoreRequestSnapshot, call: CoreOperationContext) => {
+    modelId: string;
+    request: ModelRequest;
+    view: CoreModelRequest;
+}): CoreModelsBackend;