@myagentroam/agent 0.9.141 → 0.9.142

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

@@ -0,0 +1,142 @@
+import type { MarAgentReasoningEffort } from '../model/configuration.js';
+import type { CodeCellEventData, MarAgentToolArtifact } from '../tools/contracts.js';
+import type { ExecutionMode } from './contracts.js';
+export interface MarAgentEventBase {
+    eventId: string;
+    sequence: number;
+    timestamp: string;
+    sessionId: string;
+    executionId: string;
+    turnId?: string;
+}
+export type MarAgentEvent = MarAgentEventBase & ({
+    type: 'execution.started';
+    mode: ExecutionMode;
+} | {
+    type: 'message.delta';
+    itemId: string;
+    phase: 'commentary' | 'final_answer';
+    delta: string;
+} | {
+    type: 'message.completed';
+    itemId: string;
+    phase: 'commentary' | 'final_answer';
+    text: string;
+    modelId: string;
+    modelName: string;
+} | {
+    type: 'model.performance';
+    latencyMs: number;
+    outputTokens?: number | undefined;
+    outputDurationMs?: number | undefined;
+    tokensPerSecond?: number | undefined;
+} | {
+    /** Legacy history event; new executions publish model.performance instead. */
+    type: 'message.performance';
+    itemId: string;
+    ttftMs: number;
+    outputTokens?: number | undefined;
+    outputDurationMs?: number | undefined;
+    tokensPerSecond?: number | undefined;
+} | {
+    type: 'plan.completed';
+    itemId: string;
+    text: string;
+} | {
+    type: 'reasoning.summary';
+    text: string;
+} | {
+    type: 'hosted_tool.updated';
+    itemId: string;
+    kind: 'WEB_SEARCH' | 'WEB_FETCH';
+    status: 'RUNNING' | 'COMPLETED' | 'FAILED';
+    summary: {
+        query?: string | undefined;
+        url?: string | undefined;
+        title?: string | undefined;
+        sources?: readonly {
+            url: string;
+            title?: string | undefined;
+        }[] | undefined;
+        sourcesTruncated?: boolean | undefined;
+    };
+} | {
+    type: 'citation.added';
+    id: string;
+    url: string;
+    title?: string;
+} | {
+    type: 'tool.started';
+    toolName: string;
+    callId: string;
+    parentCallId?: string;
+    input?: unknown;
+} | {
+    type: 'tool.completed';
+    toolName: string;
+    callId: string;
+    parentCallId?: string;
+    summary: string;
+    truncated?: boolean;
+    artifacts?: readonly MarAgentToolArtifact[];
+    data?: CodeCellEventData | import('../tools/contracts.js').ExecResult | Omit<import('../tools/contracts.js').ExecResult, 'stdout' | 'stderr'> | import('../tools/contracts.js').ApplyPatchResult | import('../tools/contracts.js').ReadEventData | import('../tools/contracts.js').ViewImageResult | import('../subagent/contracts.js').SubagentTaskSnapshot;
+} | {
+    type: 'tool.failed';
+    toolName: string;
+    callId: string;
+    parentCallId?: string;
+    code: string;
+    message?: string;
+} | {
+    type: 'usage.updated';
+    inputTokens?: number | undefined;
+    contextInputTokens?: number | undefined;
+    outputTokens?: number | undefined;
+    cacheReadTokens?: number | undefined;
+    cacheWriteTokens?: number | undefined;
+} | {
+    type: 'todo.updated';
+    revision: number;
+    items: readonly import('../tools/contracts.js').TodoItem[];
+} | {
+    type: 'user_input.requested';
+    requestId: string;
+    questions: unknown[];
+} | {
+    type: 'user_input.resolved';
+    requestId: string;
+} | {
+    type: 'subagent.started';
+    agentId: string;
+    description: string;
+    modelId?: string;
+    modelName?: string;
+    reasoningEffort?: MarAgentReasoningEffort;
+} | {
+    type: 'subagent.completed';
+    agentId: string;
+    description?: string;
+    status: string;
+    modelId?: string;
+    modelName?: string;
+    reasoningEffort?: MarAgentReasoningEffort;
+    latestMessage?: import('../subagent/contracts.js').SubagentLatestMessage;
+    latestActivity?: import('../subagent/contracts.js').SubagentLatestActivity;
+    errorCode?: string;
+    errorMessage?: string;
+} | {
+    type: 'execution.completed';
+} | {
+    type: 'execution.failed';
+    code: string;
+    message?: string;
+} | {
+    type: 'execution.cancelled';
+} | {
+    type: 'context.compacting';
+    compactionId: string;
+} | {
+    type: 'context.compacted';
+    compactionId: string;
+});
+export type EventPayload<T = MarAgentEvent> = T extends MarAgentEvent ? Omit<T, 'eventId' | 'sequence' | 'timestamp' | 'sessionId' | 'executionId' | 'turnId'> : never;

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

@@ -0,0 +1,50 @@
+import type { MarAgentModelConfiguration } from '../model/configuration.js';
+import type { ModelEvent, ModelMessage, ModelRequest, ModelUsage } from '../model/contracts.js';
+import { type RoundToolScope } from '../tools/execution.js';
+import type { ToolRuntimeImage } from '../tools/runtime-context.js';
+import type { AuthoritativeModelUsage } from './context/usage.js';
+import type { ExecutionMode } from './contracts.js';
+import type { EventPayload } from './events.js';
+import type { RolloutBudget } from './rollout-budget.js';
+export interface PreparedExecutionRound {
+    readonly request: ModelRequest;
+    readonly toolScope: RoundToolScope;
+}
+/** Internal execution-local ports. No Session/Agent object, OS handles or terminal publisher. */
+export interface ExecutionLoopInput {
+    readonly mode: ExecutionMode;
+    readonly sourceType: 'user' | 'subagent';
+    readonly signal: AbortSignal;
+    readonly model: Pick<MarAgentModelConfiguration, 'id' | 'name'>;
+    readonly messages: ModelMessage[];
+    readonly toolImages: ToolRuntimeImage[];
+    readonly rolloutBudget: RolloutBudget | undefined;
+    readonly publish: (event: EventPayload) => Promise<void>;
+    readonly appendContext: (message: ModelMessage) => Promise<void>;
+    readonly prepareRound: (continuation: ModelMessage | undefined) => Promise<PreparedExecutionRound>;
+    readonly startModel: (request: ModelRequest) => AsyncIterable<ModelEvent>;
+    readonly recoverySignal: () => AbortSignal;
+    readonly compactContext: () => Promise<boolean>;
+    readonly compactionFallback?: (() => boolean) | undefined;
+    readonly observeUsage: (usage: Omit<AuthoritativeModelUsage, 'historyMessages'> | undefined) => void;
+    readonly observeContextTokens: (tokens: number) => void;
+    readonly checkpoint: (round: PreparedExecutionRound, usage: ModelUsage | undefined) => Promise<void>;
+    readonly mailbox: {
+        hasPending(): boolean;
+        append(): Promise<boolean>;
+        close(): void;
+    };
+}
+/** Own the single model/tool loop; the SDK owns its handle, terminal events and cleanup. */
+export declare class ExecutionLoop {
+    #private;
+    private readonly input;
+    private readonly planOutputPrefixes;
+    get finalAnswer(): string;
+    private set finalAnswer(value);
+    constructor(input: ExecutionLoopInput);
+    run(): Promise<{
+        finalAnswer: string;
+        usage?: ModelUsage;
+    }>;
+}

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

@@ -0,0 +1,393 @@
+import { MarAgentError } from '../error.js';
+import { isProviderContextOverflow, recoverModelStream } from '../model/recovery.js';
+import { modelStreamEventObservedAt } from '../model/sse.js';
+import { modelOutputContinuationMessage } from '../prompts/output.js';
+import { executeRoundTools } from '../tools/execution.js';
+import { publicModelUsage } from './event-projection.js';
+import { PlanOutputPrefix, splitPlanOutput } from './plan-output.js';
+/** Own the single model/tool loop; the SDK owns its handle, terminal events and cleanup. */
+export class ExecutionLoop {
+    input;
+    #finalAnswer = '';
+    planOutputPrefixes = new Map();
+    get finalAnswer() {
+        return this.#finalAnswer;
+    }
+    set finalAnswer(value) {
+        this.#finalAnswer = value;
+    }
+    constructor(input) {
+        this.input = input;
+    }
+    async run() {
+        const input = this.input;
+        const { mode, messages } = input;
+        let recoveringFromContextOverflow = false;
+        let maxOutputContinuationUsed = false;
+        let pendingOutputContinuation;
+        const modelRetryState = { attempts: 0 };
+        while (true) {
+            let stop;
+            let sawTool = false;
+            let latestUsage;
+            let roundServerUsage;
+            const pendingTools = [];
+            let incompleteToolCall = false;
+            const round = await input.prepareRound(pendingOutputContinuation);
+            let sawModelSemanticEvent = false;
+            let requestStartedAt;
+            let firstModelResponseAt;
+            let firstOutputDeltaAt;
+            let lastOutputDeltaAt;
+            let requestCompletedAt;
+            let requestOutputTokens;
+            const roundMessageCount = messages.length;
+            const emitLatency = async () => {
+                if (mode === 'compact' || firstModelResponseAt === undefined)
+                    return;
+                await input.publish({
+                    type: 'model.performance',
+                    latencyMs: Math.max(0, Math.round(firstModelResponseAt - requestStartedAt))
+                });
+            };
+            const emitFinalPerformance = async (completedAt) => {
+                if (mode === 'compact' ||
+                    firstModelResponseAt === undefined ||
+                    firstOutputDeltaAt === undefined ||
+                    lastOutputDeltaAt === undefined ||
+                    lastOutputDeltaAt - firstOutputDeltaAt < 1)
+                    return;
+                const outputDuration = completedAt - firstOutputDeltaAt;
+                const outputTokens = requestOutputTokens;
+                if (outputTokens === undefined || outputDuration < 1 || completedAt < lastOutputDeltaAt)
+                    return;
+                await input.publish({
+                    type: 'model.performance',
+                    latencyMs: Math.max(0, Math.round(firstModelResponseAt - requestStartedAt)),
+                    outputTokens,
+                    outputDurationMs: Math.round(outputDuration),
+                    tokensPerSecond: Number(((outputTokens * 1000) / outputDuration).toFixed(2))
+                });
+            };
+            const persistToolCalls = async (calls) => {
+                for (const call of calls) {
+                    const message = {
+                        role: 'tool_call',
+                        callId: call.callId,
+                        name: call.name,
+                        arguments: call.arguments,
+                        ...(call.inputMode ? { inputMode: call.inputMode } : {}),
+                        content: ''
+                    };
+                    messages.push(message);
+                    await input.appendContext(message);
+                }
+            };
+            try {
+                requestStartedAt = performance.now();
+                for await (const event of input.startModel({
+                    ...round.request,
+                    retryState: modelRetryState
+                })) {
+                    if (event.type === 'output.reset') {
+                        firstOutputDeltaAt = undefined;
+                        lastOutputDeltaAt = undefined;
+                        requestOutputTokens = undefined;
+                        continue;
+                    }
+                    const modelResponseAt = mode !== 'compact' && isModelResponseEvent(event)
+                        ? Math.max(requestStartedAt, modelStreamEventObservedAt(event) ?? performance.now())
+                        : undefined;
+                    const isFirstModelResponse = modelResponseAt !== undefined && firstModelResponseAt === undefined;
+                    if (modelResponseAt !== undefined) {
+                        if (event.type !== 'output.delta')
+                            sawModelSemanticEvent = true;
+                        firstModelResponseAt ??= modelResponseAt;
+                        if (event.type === 'output.delta' ||
+                            (event.type === 'text.delta' && event.delta.length > 0)) {
+                            firstOutputDeltaAt ??= modelResponseAt;
+                            lastOutputDeltaAt = modelResponseAt;
+                        }
+                    }
+                    if (event.type === 'response.item') {
+                        // Compaction keeps only its successful checkpoint, never intermediate native output.
+                        if (mode === 'compact')
+                            continue;
+                        const message = {
+                            role: 'provider',
+                            content: '',
+                            provider: event.provider,
+                            providerModelId: input.model.id,
+                            ...(event.provider === 'ANTHROPIC_MESSAGES'
+                                ? { contextKind: 'private' }
+                                : {}),
+                            item: event.item
+                        };
+                        messages.push(message);
+                        await input.appendContext(message);
+                    }
+                    else if (event.type === 'text.delta') {
+                        let delta = event.delta;
+                        if (mode === 'plan' && input.sourceType !== 'subagent') {
+                            let prefix = this.planOutputPrefixes.get(event.itemId);
+                            if (!prefix) {
+                                prefix = new PlanOutputPrefix();
+                                this.planOutputPrefixes.set(event.itemId, prefix);
+                            }
+                            delta = prefix.push(delta);
+                        }
+                        if (mode !== 'compact' && delta) {
+                            await input.publish({
+                                type: 'message.delta',
+                                itemId: event.itemId,
+                                phase: event.phase,
+                                delta
+                            });
+                        }
+                    }
+                    else if (event.type === 'text.completed') {
+                        const phase = event.phase ?? 'final_answer';
+                        if (phase === 'final_answer')
+                            this.finalAnswer = event.text;
+                        this.planOutputPrefixes.delete(event.itemId);
+                        if (mode !== 'compact') {
+                            if (mode === 'plan' && input.sourceType !== 'subagent') {
+                                const parts = splitPlanOutput(event.text);
+                                for (const [index, part] of parts.entries()) {
+                                    const itemId = index === 0 ? event.itemId : `${event.itemId}:plan-part:${index}`;
+                                    if (part.kind === 'plan')
+                                        await input.publish({ type: 'plan.completed', itemId, text: part.text });
+                                    else {
+                                        await input.publish({
+                                            type: 'message.completed',
+                                            itemId,
+                                            phase,
+                                            text: part.text,
+                                            modelId: input.model.id,
+                                            modelName: input.model.name
+                                        });
+                                    }
+                                }
+                            }
+                            else {
+                                await input.publish({
+                                    type: 'message.completed',
+                                    itemId: event.itemId,
+                                    phase,
+                                    text: event.text,
+                                    modelId: input.model.id,
+                                    modelName: input.model.name
+                                });
+                            }
+                        }
+                        messages.push({ role: 'assistant', content: event.text });
+                    }
+                    else if (event.type === 'usage') {
+                        latestUsage = event.usage;
+                        const outputTokens = typeof event.usage.outputTokens === 'number' &&
+                            Number.isSafeInteger(event.usage.outputTokens) &&
+                            event.usage.outputTokens >= 0
+                            ? event.usage.outputTokens
+                            : undefined;
+                        if (outputTokens !== undefined) {
+                            requestOutputTokens = outputTokens;
+                        }
+                        const reportedContext = event.usage.contextInputTokens ?? event.usage.inputTokens;
+                        if (reportedContext !== undefined &&
+                            Number.isSafeInteger(reportedContext) &&
+                            reportedContext >= 0) {
+                            input.observeContextTokens(reportedContext);
+                            roundServerUsage = {
+                                contextInputTokens: reportedContext,
+                                outputTokens: typeof event.usage.outputTokens === 'number' &&
+                                    Number.isSafeInteger(event.usage.outputTokens) &&
+                                    event.usage.outputTokens >= 0
+                                    ? event.usage.outputTokens
+                                    : undefined
+                            };
+                        }
+                        await input.publish({ type: 'usage.updated', ...publicModelUsage(event.usage) });
+                    }
+                    else if (event.type === 'reasoning.summary') {
+                        if (mode !== 'compact')
+                            await input.publish({ type: 'reasoning.summary', text: event.text });
+                    }
+                    else if (event.type === 'hosted_tool') {
+                        if (mode !== 'compact')
+                            await input.publish({
+                                type: 'hosted_tool.updated',
+                                itemId: event.itemId,
+                                kind: event.kind,
+                                status: event.status,
+                                summary: event.summary
+                            });
+                    }
+                    else if (event.type === 'citation') {
+                        if (mode !== 'compact')
+                            await input.publish({
+                                type: 'citation.added',
+                                id: event.citation.id,
+                                url: event.citation.url,
+                                ...(event.citation.title ? { title: event.citation.title } : {})
+                            });
+                    }
+                    else if (event.type === 'client_tool.call') {
+                        if (mode === 'compact')
+                            throw new MarAgentError('MAR_AGENT_MODEL_PROTOCOL_ERROR', 'Compaction returned a tool call while tools were disabled.');
+                        sawTool = true;
+                        pendingTools.push(event);
+                    }
+                    else if (event.type === 'completed') {
+                        stop = event.reason;
+                        requestCompletedAt = modelStreamEventObservedAt(event) ?? performance.now();
+                    }
+                    if (isFirstModelResponse)
+                        await emitLatency();
+                }
+                if (mode !== 'compact' && firstModelResponseAt !== undefined) {
+                    const completedAt = requestCompletedAt ?? performance.now();
+                    await emitFinalPerformance(completedAt);
+                }
+                pendingOutputContinuation = undefined;
+                incompleteToolCall = pendingTools.some((call) => call.argumentError !== undefined);
+                if (!(stop === 'max_output' && incompleteToolCall)) {
+                    await persistToolCalls(pendingTools);
+                }
+                else
+                    pendingTools.splice(0, pendingTools.length);
+                modelRetryState.attempts = 0;
+            }
+            catch (error) {
+                this.planOutputPrefixes.clear();
+                if (await recoverModelStream(error, modelRetryState, input.recoverySignal())) {
+                    this.finalAnswer = '';
+                    if (mode === 'compact')
+                        messages.splice(roundMessageCount);
+                    if (pendingTools.some((call) => call.argumentError !== undefined))
+                        pendingTools.splice(0, pendingTools.length);
+                    else if (pendingTools.length > 0)
+                        await persistToolCalls(pendingTools);
+                    if (pendingTools.length === 0)
+                        continue;
+                }
+                else if (mode === 'compact' &&
+                    !sawModelSemanticEvent &&
+                    isProviderContextOverflow(error) &&
+                    input.compactionFallback?.()) {
+                    modelRetryState.attempts = 0;
+                    this.finalAnswer = '';
+                    continue;
+                }
+                else if (mode !== 'compact' &&
+                    !sawModelSemanticEvent &&
+                    isProviderContextOverflow(error)) {
+                    if (!recoveringFromContextOverflow && (await input.compactContext())) {
+                        modelRetryState.attempts = 0;
+                        recoveringFromContextOverflow = true;
+                        continue;
+                    }
+                    throw new MarAgentError('MAR_AGENT_CONTEXT_LIMIT', 'The model rejected the compacted context as too large.', { cause: error });
+                }
+                else
+                    throw error;
+            }
+            recoveringFromContextOverflow = false;
+            input.observeUsage(roundServerUsage);
+            if (pendingTools.length === 0 && input.mailbox.hasPending()) {
+                await input.mailbox.append();
+                this.finalAnswer = '';
+                continue;
+            }
+            const toolResults = await executeRoundTools(pendingTools, round.toolScope);
+            for (const result of toolResults) {
+                if ('images' in result && result.images?.length)
+                    input.toolImages.push(...result.images.map((image) => ({
+                        mimeType: image.mimeType,
+                        data: Buffer.from(image.dataBase64, 'base64')
+                    })));
+                const toolSearchTools = result.call.name === 'tool_search' && !result.failed
+                    ? result.output.toolSearchTools
+                    : undefined;
+                const message = {
+                    role: 'tool',
+                    callId: result.call.callId,
+                    content: result.content,
+                    ...(toolSearchTools === undefined ? {} : { toolSearchTools }),
+                    ...('images' in result && result.images?.length ? { images: result.images } : {})
+                };
+                messages.push(message);
+                await input.appendContext({
+                    role: message.role,
+                    callId: result.call.callId,
+                    content: message.content,
+                    ...(message.toolSearchTools === undefined
+                        ? {}
+                        : { toolSearchTools: message.toolSearchTools })
+                });
+            }
+            if (sawTool) {
+                modelRetryState.attempts = 0;
+                if (input.sourceType === 'subagent')
+                    this.finalAnswer = '';
+            }
+            input.rolloutBudget?.recordUsage(latestUsage);
+            if (mode !== 'compact' && stop === 'max_output') {
+                const needsContinuation = !sawTool || incompleteToolCall;
+                if (needsContinuation) {
+                    if (maxOutputContinuationUsed ||
+                        (input.rolloutBudget?.active && input.rolloutBudget.stage === 'exhausted'))
+                        throw new MarAgentError('MAR_AGENT_MODEL_OUTPUT_INCOMPLETE', 'Model output reached its limit before completing.');
+                    maxOutputContinuationUsed = true;
+                    pendingOutputContinuation = {
+                        role: 'user',
+                        content: modelOutputContinuationMessage
+                    };
+                    this.finalAnswer = '';
+                    continue;
+                }
+                maxOutputContinuationUsed = false;
+            }
+            else
+                maxOutputContinuationUsed = false;
+            await input.checkpoint(round, latestUsage);
+            if (input.signal.aborted) {
+                const aborted = toolResults.find((result) => result.failed)?.error;
+                throw aborted ?? new MarAgentError('MAR_AGENT_EXECUTION_CANCELLED', 'Execution cancelled.');
+            }
+            if (input.mailbox.hasPending()) {
+                await input.mailbox.append();
+                this.finalAnswer = '';
+                continue;
+            }
+            if (stop === 'completed' && !sawTool) {
+                input.mailbox.close();
+                const compactSummary = mode === 'compact' ? this.finalAnswer.trim() : '';
+                if (mode === 'compact' && !compactSummary)
+                    throw new MarAgentError('MAR_AGENT_COMPACT_FAILED', 'Compaction returned an empty handoff.');
+                if (mode !== 'compact' && !this.finalAnswer.trim())
+                    throw new MarAgentError(input.sourceType === 'subagent'
+                        ? 'MAR_AGENT_SUBAGENT_FAILED'
+                        : 'MAR_AGENT_MODEL_OUTPUT_INCOMPLETE', input.sourceType === 'subagent'
+                        ? 'Subagent completed without a final summary.'
+                        : 'Model completed without an answer or tool request.');
+                return {
+                    finalAnswer: this.finalAnswer,
+                    ...(latestUsage === undefined ? {} : { usage: latestUsage })
+                };
+            }
+            if (!sawTool && stop !== 'pause')
+                throw new MarAgentError('MAR_AGENT_MODEL_OUTPUT_INCOMPLETE', 'Model did not complete or request a tool.');
+        }
+    }
+}
+function isModelResponseEvent(event) {
+    if (event.type === 'text.delta')
+        return event.delta.length > 0;
+    if (event.type === 'text.completed' || event.type === 'reasoning.summary')
+        return event.text.length > 0;
+    return (event.type === 'response.item' ||
+        event.type === 'output.delta' ||
+        event.type === 'client_tool.call' ||
+        event.type === 'hosted_tool' ||
+        event.type === 'citation');
+}

package/dist/{runtime → agent-core/runtime}/rollout-budget.d.ts

@@ -1,5 +1,5 @@
 import type { ModelUsage } from '../model/contracts.js';
-import type { RolloutBudgetOptions } from '../sdk/types.js';
+import type { RolloutBudgetOptions } from './contracts.js';
 export type RolloutBudgetStage = 'normal' | 'conserve' | 'finalize' | 'exhausted';
 export interface ResolvedRolloutBudgetOptions {
     limitTokens: number;