@myagentroam/agent 0.9.141 → 0.9.142

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

@@ -0,0 +1,209 @@
+import { addModelCredentialProviders, closeModelAdapters, resolveAgentModels } from './model-runtime.js';
+import { createSessionOpener } from './session.js';
+import { MarAgentError } from '../error.js';
+import { negotiateHost } from '../host/contracts.js';
+import { AnthropicMessagesAdapter } from '../model/anthropic-messages.js';
+import { OpenAiResponsesAdapter } from '../model/openai-responses.js';
+import { resolveRolloutBudgetOptions } from '../runtime/rollout-budget.js';
+import { JsonlSessionStore } from '../session/jsonl-store.js';
+/** Validate models before Host negotiation and expose only built-in protocol adapters. */
+export async function createMarAgent(options) {
+    if (Object.hasOwn(options, 'adapterFactory'))
+        throw new MarAgentError('MAR_AGENT_MODEL_CONFIG_INVALID', 'Custom model adapters are not supported.');
+    return createMarAgentWithAdapter(options);
+}
+/** Package-internal seam for deterministic adapter tests; not a package export. */
+export async function createMarAgentWithAdapter(options) {
+    const rolloutBudgetOptions = resolveRolloutBudgetOptions(options.rolloutBudget);
+    const resolvedModels = resolveAgentModels(options.models);
+    let { models, defaultModelId } = resolvedModels;
+    let modelGeneration = 0;
+    const { credentialProviders } = resolvedModels;
+    const description = negotiateHost(await options.host.describe());
+    if (description.mode !== options.mode)
+        throw new MarAgentError('MAR_AGENT_HOST_INCOMPATIBLE', 'Host mode does not match Agent mode.');
+    const store = await JsonlSessionStore.open(description.homeDirectory);
+    const active = new Map();
+    const activeExecutionAdapters = new Set();
+    const executionResults = new Map();
+    const sessionRuntimes = new Map();
+    const sessionWriterOwner = {};
+    let disposed = false;
+    let reconfiguring = false;
+    const createAdapter = (modelId, configuredModels = models) => {
+        const configuration = configuredModels.get(modelId);
+        if (!configuration)
+            throw new MarAgentError('MAR_AGENT_MODEL_DISABLED', 'Selected model is unavailable.');
+        return (options.adapterFactory?.(configuration) ??
+            (configuration.protocol === 'OPENAI_RESPONSES'
+                ? new OpenAiResponsesAdapter(configuration)
+                : new AnthropicMessagesAdapter(configuration)));
+    };
+    const activeSessionIds = () => new Set([...active.keys()].map((key) => key.slice(0, key.indexOf(':'))));
+    const activeAdaptersExcept = (sessionId) => {
+        const activeAdapters = new Set();
+        for (const [candidateSessionId, runtime] of sessionRuntimes)
+            if (candidateSessionId !== sessionId && activeSessionIds().has(candidateSessionId))
+                for (const adapter of runtime.adapters.values())
+                    activeAdapters.add(adapter);
+        return activeAdapters;
+    };
+    const openSession = createSessionOpener({
+        host: options.host,
+        description,
+        settings: {
+            ...(options.workspaceMapping === undefined
+                ? {}
+                : { workspaceMapping: options.workspaceMapping }),
+            ...(options.systemInstruction === undefined
+                ? {}
+                : { systemInstruction: options.systemInstruction })
+        },
+        store,
+        registry: {
+            active,
+            activeExecutionAdapters,
+            executionResults,
+            sessionRuntimes,
+            sessionWriterOwner
+        },
+        rolloutBudgetOptions,
+        hasCustomAdapters: options.adapterFactory !== undefined,
+        modelState: () => ({ models, defaultModelId, generation: modelGeneration }),
+        createAdapter,
+        activeAdaptersExcept,
+        assertCanStart: () => {
+            if (disposed)
+                throw new MarAgentError('MAR_AGENT_DISPOSED', 'Agent is disposed.');
+            if (reconfiguring)
+                throw new MarAgentError('MAR_AGENT_EXECUTION_ACTIVE', 'Models are being reconfigured for the next execution.');
+        }
+    });
+    return {
+        createSession: async (input) => openSession((await store.createSession(input)).id, input.workspace),
+        openSession: (id) => openSession(id),
+        listSessions: (input) => store.list(input),
+        clearSession: async (id) => {
+            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);
+        },
+        reconfigureModels: async (input) => {
+            if (disposed)
+                throw new MarAgentError('MAR_AGENT_DISPOSED', 'Agent is disposed.');
+            if (reconfiguring)
+                throw new MarAgentError('MAR_AGENT_EXECUTION_ACTIVE', 'Models are already being reconfigured for the next execution.');
+            const next = resolveAgentModels(input.models, input.defaultModelId);
+            const activeSessions = activeSessionIds();
+            if ([...activeSessions].some((sessionId) => sessionRuntimes.get(sessionId)?.sourceType !== 'subagent'))
+                throw new MarAgentError('MAR_AGENT_EXECUTION_ACTIVE', 'Models cannot be reconfigured while a main execution is active.');
+            const activeAdapters = new Set(activeExecutionAdapters);
+            for (const [sessionId, runtime] of sessionRuntimes)
+                if (activeSessions.has(sessionId))
+                    for (const adapter of runtime.adapters.values())
+                        activeAdapters.add(adapter);
+            const inactiveRuntimes = [...sessionRuntimes].flatMap(([sessionId, runtime]) => activeSessions.has(sessionId) ? [] : [runtime]);
+            reconfiguring = true;
+            try {
+                const reconfigurationCommits = new Map();
+                for (const runtime of inactiveRuntimes)
+                    for (const [modelId, adapter] of runtime.adapters) {
+                        if (activeAdapters.has(adapter))
+                            continue;
+                        const configuration = next.models.get(modelId);
+                        const commit = configuration === undefined ? undefined : adapter.prepareReconfigure?.(configuration);
+                        if (commit !== undefined)
+                            reconfigurationCommits.set(adapter, commit);
+                    }
+                const retainedAdapters = new Set(reconfigurationCommits.keys());
+                const adapters = [
+                    ...new Set(inactiveRuntimes.flatMap((runtime) => [...runtime.adapters.values()]))
+                ].filter((adapter) => !activeAdapters.has(adapter) && !retainedAdapters.has(adapter));
+                for (const runtime of inactiveRuntimes) {
+                    for (const [modelId, adapter] of runtime.adapters)
+                        if (!retainedAdapters.has(adapter))
+                            runtime.adapters.delete(modelId);
+                }
+                await closeModelAdapters(adapters);
+                if (disposed)
+                    throw new MarAgentError('MAR_AGENT_DISPOSED', 'Agent is disposed.');
+                for (const commit of reconfigurationCommits.values())
+                    commit();
+                models = next.models;
+                defaultModelId = next.defaultModelId;
+                modelGeneration++;
+                for (const provider of next.credentialProviders)
+                    credentialProviders.add(provider);
+                for (const runtime of inactiveRuntimes) {
+                    runtime.adapterGeneration = modelGeneration;
+                }
+                const liveProviders = new Set(next.credentialProviders);
+                for (const adapter of activeExecutionAdapters)
+                    addModelCredentialProviders(liveProviders, adapter.configuration);
+                for (const runtime of sessionRuntimes.values())
+                    for (const adapter of runtime.adapters.values())
+                        addModelCredentialProviders(liveProviders, adapter.configuration);
+                const obsoleteProviders = [...credentialProviders].filter((provider) => !liveProviders.has(provider));
+                const providerCloseResults = await Promise.allSettled(obsoleteProviders.map((provider) => provider.close()));
+                for (const [index, result] of providerCloseResults.entries())
+                    if (result.status === 'fulfilled')
+                        credentialProviders.delete(obsoleteProviders[index]);
+            }
+            finally {
+                reconfiguring = false;
+            }
+        },
+        deleteSession: async (id) => {
+            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();
+            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;
+            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;
+        }
+    };
+}

package/dist/agent-core/sdk/model-runtime.d.ts

@@ -0,0 +1,13 @@
+import { type MarAgentModelConfiguration, type MarAgentReasoningEffort, type ModelCredentialProvider } from '../model/configuration.js';
+import type { ModelAdapter, ModelTurnSession } from '../model/contracts.js';
+export type ResolvedModelConfiguration = MarAgentModelConfiguration & {
+    readonly defaultReasoningEffort: MarAgentReasoningEffort;
+};
+export declare function resolveAgentModels(configurations: readonly MarAgentModelConfiguration[], requestedDefaultModelId?: string): {
+    readonly models: Map<string, ResolvedModelConfiguration>;
+    readonly defaultModelId: string;
+    readonly credentialProviders: Set<ModelCredentialProvider>;
+};
+export declare function createModelTurnSession(adapter: ModelAdapter): ModelTurnSession;
+export declare function closeModelAdapters(adapters: Iterable<ModelAdapter>): Promise<void>;
+export declare function addModelCredentialProviders(target: Set<ModelCredentialProvider>, configuration: MarAgentModelConfiguration): void;

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

@@ -0,0 +1,63 @@
+import { MarAgentError } from '../error.js';
+import { resolveModelDefaultReasoningEffort } from '../model/configuration.js';
+export function resolveAgentModels(configurations, requestedDefaultModelId) {
+    const configuredModels = configurations.map((model) => ({
+        ...model,
+        defaultReasoningEffort: resolveModelDefaultReasoningEffort(model)
+    }));
+    const credentialProviders = new Set();
+    for (const model of configuredModels) {
+        if ((model.apiKey === undefined) === (model.credentialProvider === undefined))
+            throw new MarAgentError('MAR_AGENT_MODEL_CONFIG_INVALID', 'Exactly one model credential source is required.');
+        if (model.responsesEncoding !== undefined &&
+            (model.protocol !== 'OPENAI_RESPONSES' ||
+                !['STANDARD', 'LITE'].includes(model.responsesEncoding)))
+            throw new MarAgentError('MAR_AGENT_MODEL_CONFIG_INVALID', 'Responses encoding is invalid.');
+        if (model.fastMode === true && model.protocol !== 'OPENAI_RESPONSES')
+            throw new MarAgentError('MAR_AGENT_MODEL_CONFIG_INVALID', 'Fast mode requires Responses.');
+        if (model.serviceTier !== undefined &&
+            (model.protocol !== 'OPENAI_RESPONSES' ||
+                !['auto', 'default', 'flex', 'priority', 'fast', 'ultrafast'].includes(model.serviceTier)))
+            throw new MarAgentError('MAR_AGENT_MODEL_CONFIG_INVALID', 'Responses service tier is invalid.');
+        if (model.credentialProvider !== undefined)
+            credentialProviders.add(model.credentialProvider);
+    }
+    const models = new Map(configuredModels.filter((model) => model.enabled).map((model) => [model.id, model]));
+    if (models.size === 0)
+        throw new MarAgentError('MAR_AGENT_MODEL_CONFIG_INVALID', 'At least one enabled model is required.');
+    const defaultModelId = requestedDefaultModelId ?? models.keys().next().value;
+    if (!models.has(defaultModelId))
+        throw new MarAgentError('MAR_AGENT_MODEL_CONFIG_INVALID', 'Default model is unavailable.');
+    return { models, defaultModelId, credentialProviders };
+}
+export function createModelTurnSession(adapter) {
+    const turn = adapter.createTurnSession?.() ?? {
+        start: (request, signal) => adapter.start(request, signal),
+        close: async () => undefined
+    };
+    return {
+        async *start(request, signal) {
+            const before = request.retryState?.attempts;
+            try {
+                yield* turn.start(request, signal);
+            }
+            finally {
+                // Custom adapters may not participate in the shared attempt accounting.
+                if (request.retryState && request.retryState.attempts === before)
+                    request.retryState.attempts++;
+            }
+        },
+        resetContinuation: () => turn.resetContinuation?.(),
+        close: () => turn.close()
+    };
+}
+export async function closeModelAdapters(adapters) {
+    const results = await Promise.allSettled([...new Set(adapters)].flatMap((adapter) => adapter.close === undefined ? [] : [adapter.close()]));
+    const failure = results.find((result) => result.status === 'rejected');
+    if (failure !== undefined)
+        throw failure.reason;
+}
+export function addModelCredentialProviders(target, configuration) {
+    if (configuration.credentialProvider !== undefined)
+        target.add(configuration.credentialProvider);
+}

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

@@ -0,0 +1,3 @@
+import type { MarAgentReasoningEffort } from '../model/configuration.js';
+import type { ModelAdapter, ModelAttemptDiagnostic } from '../model/contracts.js';
+export declare function generateSessionTitle(adapter: ModelAdapter, prompt: string, reasoningEffort: MarAgentReasoningEffort, signal: AbortSignal, onAttemptDiagnostic: (diagnostic: ModelAttemptDiagnostic) => Promise<void> | void): Promise<string | undefined>;

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

@@ -0,0 +1,42 @@
+import { sessionTitlePrompt } from '../prompts/title.js';
+import { createModelTurnSession } from './model-runtime.js';
+export async function generateSessionTitle(adapter, prompt, reasoningEffort, signal, onAttemptDiagnostic) {
+    let titleInput = '';
+    let characters = 0;
+    for (const character of prompt) {
+        if (characters++ >= 1000)
+            break;
+        titleInput += character;
+    }
+    let output = '';
+    let completed = false;
+    const turn = createModelTurnSession(adapter);
+    try {
+        for await (const event of turn.start({
+            retryState: { attempts: 0, maxAttempts: 1 },
+            system: sessionTitlePrompt,
+            messages: [{ role: 'user', content: titleInput }],
+            tools: [],
+            reasoningEffort,
+            onAttemptDiagnostic
+        }, signal)) {
+            if (event.type === 'text.completed')
+                output = event.text;
+            else if (event.type === 'completed')
+                completed = event.reason === 'completed';
+        }
+    }
+    finally {
+        await turn.close();
+    }
+    if (!completed)
+        return undefined;
+    const line = output
+        .replace(/<think>[\s\S]*?<\/think>\s*/giu, '')
+        .split(/\r?\n/u)
+        .map((value) => value.trim())
+        .find(Boolean);
+    if (!line)
+        return undefined;
+    return [...line].slice(0, 50).join('');
+}

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

@@ -0,0 +1,62 @@
+import type { ContextualWorldState } from '../runtime/context/world-state.js';
+import type { ResolvedModelConfiguration } from './model-runtime.js';
+import type { HostDescription, MarAgentHost } from '../host/contracts.js';
+import { type MarAgentReasoningEffort } from '../model/configuration.js';
+import type { ModelAdapter } 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';
+import { createSessionToolScheduler } from '../tools/scheduler.js';
+import { TodoStore } from '../tools/agent/todo.js';
+import type { CreateMarAgentOptions, ExecutionResult, MarAgentSession } from './types.js';
+export interface SessionRuntime {
+    todo?: TodoStore;
+    readonly scheduleTool: ReturnType<typeof createSessionToolScheduler>;
+    readonly sourceType: 'user' | 'subagent';
+    adapterGeneration: number;
+    adapters: Map<string, ModelAdapter>;
+    contextualWorldState?: ContextualWorldState;
+    subagents?: SubagentSessionController;
+    subagentsOpening?: Promise<SubagentSessionController>;
+}
+interface InternalMarAgentSession extends MarAgentSession {
+    startSubagentTurn(input: {
+        readonly prompt: string;
+        readonly modelId: string;
+        readonly reasoningEffort: MarAgentReasoningEffort;
+        readonly role: 'general-purpose' | 'explore';
+        readonly initialMailbox: readonly SubagentMailboxMessage[];
+        readonly turnId: string;
+        readonly delivery?: SubagentMessageDelivery;
+        readonly sharedRolloutBudget?: RolloutBudget;
+        readonly mcpExecutionScopeId: string;
+    }): SubagentTurnHandle;
+}
+/** Agent-owned registries shared with Session orchestration, not public execution state. */
+export interface AgentSessionRegistry {
+    readonly active: Map<string, AbortController>;
+    readonly activeExecutionAdapters: Set<ModelAdapter>;
+    readonly executionResults: Map<string, Promise<ExecutionResult>>;
+    readonly sessionRuntimes: Map<string, SessionRuntime>;
+    readonly sessionWriterOwner: object;
+}
+interface SessionServices {
+    readonly host: MarAgentHost;
+    readonly description: HostDescription;
+    readonly settings: Pick<CreateMarAgentOptions, 'workspaceMapping' | 'systemInstruction'>;
+    readonly store: JsonlSessionStore;
+    readonly registry: AgentSessionRegistry;
+    readonly rolloutBudgetOptions: ReturnType<typeof resolveRolloutBudgetOptions>;
+    readonly hasCustomAdapters: boolean;
+    readonly modelState: () => {
+        readonly models: ReadonlyMap<string, ResolvedModelConfiguration>;
+        readonly defaultModelId: string;
+        readonly generation: number;
+    };
+    readonly createAdapter: (modelId: string, models: ReadonlyMap<string, ResolvedModelConfiguration>) => ModelAdapter;
+    readonly activeAdaptersExcept: (sessionId: string) => ReadonlySet<ModelAdapter>;
+    readonly assertCanStart: () => void;
+}
+/** SDK Session orchestration owns warm resources; Runtime owns only the model/tool loop. */
+export declare function createSessionOpener(services: SessionServices): (sessionId: string, workspace?: string) => Promise<InternalMarAgentSession>;
+export {};