@myagentroam/agent 0.9.141 → 0.9.143

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

@@ -0,0 +1,138 @@
+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';
+export function latestModelUsage(records, selectedModelId) {
+    let usage;
+    const toolCallIds = new Set();
+    // readContext starts at compact.completed, whose execution header is before the boundary.
+    let activeModelId = selectedModelId;
+    for (const record of records) {
+        const payload = record.payload;
+        if (compactSummaryFromCheckpoint(record) !== undefined) {
+            usage = undefined;
+            toolCallIds.clear();
+            activeModelId = modelIdFromPayload(payload);
+            continue;
+        }
+        if (record.type === 'execution.header') {
+            activeModelId = modelIdFromPayload(payload);
+            usage = undefined;
+            toolCallIds.clear();
+            continue;
+        }
+        if (record.type === 'model.context' && payload.role === 'tool_call') {
+            if (typeof payload.callId === 'string' && payload.callId.length > 0)
+                toolCallIds.add(payload.callId);
+            else
+                usage = undefined;
+        }
+        if (usage !== undefined) {
+            if (record.type === 'model.context') {
+                const role = payload.role;
+                if (role === 'tool') {
+                    if (typeof payload.callId !== 'string' || !toolCallIds.has(payload.callId))
+                        usage = undefined;
+                    else
+                        usage = {
+                            ...usage,
+                            appendedMessages: [
+                                ...(usage.appendedMessages ?? []),
+                                payload
+                            ]
+                        };
+                }
+                else if (role !== 'tool_call' && role !== 'assistant' && role !== 'provider')
+                    usage = undefined;
+            }
+            else if (invalidatesUsageCalibration(record.type, payload.type))
+                usage = undefined;
+        }
+        if (payload.type === 'usage.updated' && activeModelId === selectedModelId) {
+            const value = payload.contextInputTokens ?? payload.inputTokens;
+            if (typeof value === 'number' && Number.isSafeInteger(value) && value >= 0)
+                usage = {
+                    contextInputTokens: value,
+                    outputTokens: typeof payload.outputTokens === 'number' &&
+                        Number.isSafeInteger(payload.outputTokens) &&
+                        payload.outputTokens >= 0
+                        ? payload.outputTokens
+                        : undefined
+                };
+        }
+    }
+    return usage;
+}
+export function reasoningEffortBaseline(records, modelId) {
+    let baseline;
+    for (let index = records.length - 1; index >= 0; index--) {
+        const record = records[index];
+        if (compactSummaryFromCheckpoint(record) !== undefined)
+            break;
+        if (record.type !== 'execution.header')
+            continue;
+        const payload = record.payload;
+        if (payload.modelId !== modelId)
+            break;
+        const effort = marAgentReasoningEffortSchema.safeParse(payload.reasoningEffort);
+        if (effort.success)
+            baseline = effort.data;
+    }
+    return baseline;
+}
+export function lastConfigurationEffort(messages, modelId) {
+    for (let index = messages.length - 1; index >= 0; index--) {
+        const message = messages[index];
+        if (message.role !== 'provider' ||
+            message.provider !== 'OPENAI_RESPONSES' ||
+            message.providerModelId !== modelId ||
+            message.item?.type !== 'configuration_update')
+            continue;
+        const reasoning = message.item.reasoning;
+        const effort = marAgentReasoningEffortSchema.safeParse(reasoning?.effort);
+        if (effort.success)
+            return effort.data;
+    }
+    return undefined;
+}
+export function shouldUseNativeCompaction(input) {
+    if (input.estimatedRequestTokens <= input.contextWindowTokens)
+        return true;
+    if (input.latestUsage === undefined || input.latestUsage.outputTokens === undefined)
+        return false;
+    const historyDelta = appendOnlyUsageDelta(input.latestUsage, input.historyMessages);
+    if (historyDelta === undefined)
+        return false;
+    const appendedTokens = countModelTokens(stableJson([...historyDelta, ...input.appendedMessages]));
+    return (input.latestUsage.contextInputTokens + input.latestUsage.outputTokens + appendedTokens <=
+        input.contextWindowTokens);
+}
+function appendOnlyUsageDelta(usage, historyMessages) {
+    if (usage.historyMessages === undefined)
+        return usage.appendedMessages ?? [];
+    if (historyMessages.length < usage.historyMessages.length)
+        return undefined;
+    for (let index = 0; index < usage.historyMessages.length; index++)
+        if (!isDeepStrictEqual(usage.historyMessages[index], historyMessages[index]))
+            return undefined;
+    const appended = historyMessages.slice(usage.historyMessages.length);
+    const toolCallIds = new Set(usage.historyMessages
+        .filter((message) => message.role === 'tool_call')
+        .map((message) => message.callId));
+    return appended.every((message) => (message.role === 'tool' && toolCallIds.has(message.callId)) ||
+        (message.role === 'user' && message.contextKind === 'environment'))
+        ? appended
+        : undefined;
+}
+function invalidatesUsageCalibration(recordType, payloadType) {
+    if (recordType === 'turn.user' ||
+        recordType === 'context.environment' ||
+        recordType === 'context.gc.completed')
+        return true;
+    return payloadType === 'message.completed';
+}
+function modelIdFromPayload(payload, key = 'modelId') {
+    const value = payload[key];
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}

package/dist/agent-core/runtime/context/world-state.d.ts

@@ -0,0 +1,35 @@
+import type { ModelMessage } from '../../model/contracts.js';
+export interface ContextualWorldState {
+    generation: string | undefined;
+    initialized: boolean;
+    instructionSnapshot: string | undefined;
+    resourceSnapshot: string | undefined;
+    mcpSnapshot?: string | undefined;
+    entries: Array<{
+        index: number;
+        kind: 'instructions' | 'resources' | 'mcp';
+        content: string;
+    }>;
+}
+export declare function insertContextualWorldState(messages: readonly ModelMessage[], entries: readonly {
+    index: number;
+    kind: 'instructions' | 'resources' | 'mcp';
+    content: string;
+}[]): ModelMessage[];
+export declare function latestContextualWorldStateGeneration(records: readonly import('../../session/jsonl-store.js').SessionRecord[]): string | undefined;
+export declare function parsePersistedContextualWorldState(payload: unknown): ContextualWorldState | undefined;
+export declare function persistContextualWorldState(store: import('../../session/jsonl-store.js').JsonlSessionStore, sessionId: string, state: ContextualWorldState): Promise<void>;
+export declare function compactHistoryMayContainRetainedResources(records: readonly import('../../session/jsonl-store.js').SessionRecord[]): boolean;
+export declare function updateContextualWorldState(state: ContextualWorldState, index: number, current: {
+    instructionSnapshot: string | undefined;
+    instructionContent: string | undefined;
+    resourceSnapshot: string | undefined;
+    previousMayContainResources?: boolean;
+}): ContextualWorldState;
+export declare function resetContextualWorldState(generation: string | undefined, index: number, current: {
+    instructionSnapshot: string | undefined;
+    instructionContent: string | undefined;
+    resourceSnapshot: string | undefined;
+    previousMayContainResources?: boolean;
+}): ContextualWorldState;
+export declare function contextualInstructionInsertIndex(messages: readonly ModelMessage[]): number;

package/dist/agent-core/runtime/context/world-state.js

@@ -0,0 +1,133 @@
+import { retainedSessionResourcesUpdate } from '../../prompts/resources.js';
+import { compactSummaryFromCheckpoint } from '../../session/jsonl-store.js';
+export function insertContextualWorldState(messages, entries) {
+    const result = [...messages];
+    let offset = 0;
+    for (const entry of entries) {
+        const insertionIndex = Math.max(0, Math.min(entry.index + offset, result.length));
+        result.splice(insertionIndex, 0, { role: 'user', content: entry.content });
+        offset++;
+    }
+    return result;
+}
+export function latestContextualWorldStateGeneration(records) {
+    let generation;
+    for (const record of records)
+        if (record.type === 'context.gc.completed' ||
+            compactSummaryFromCheckpoint(record) !== undefined)
+            generation = record.recordId;
+    return generation;
+}
+const MAX_CONTEXTUAL_WORLD_STATE_ENTRIES = 1_024;
+const MAX_CONTEXTUAL_WORLD_STATE_CONTENT_BYTES = 8 * 1024 * 1024;
+export function parsePersistedContextualWorldState(payload) {
+    if (payload === null || typeof payload !== 'object' || Array.isArray(payload))
+        return undefined;
+    const record = payload;
+    if (record.version !== 1)
+        return undefined;
+    const generation = record.generation === null
+        ? undefined
+        : typeof record.generation === 'string' && record.generation.length <= 128
+            ? record.generation
+            : null;
+    if (generation === null)
+        return undefined;
+    const instructionSnapshot = nullableWorldStateString(record.instructionSnapshot);
+    const resourceSnapshot = nullableWorldStateString(record.resourceSnapshot);
+    if (instructionSnapshot === null || resourceSnapshot === null || !Array.isArray(record.entries))
+        return undefined;
+    if (record.entries.length > MAX_CONTEXTUAL_WORLD_STATE_ENTRIES)
+        return undefined;
+    const entries = [];
+    let contentBytes = 0;
+    for (const value of record.entries) {
+        if (value === null || typeof value !== 'object' || Array.isArray(value))
+            return undefined;
+        const entry = value;
+        if (!Number.isSafeInteger(entry.index) ||
+            entry.index < 0 ||
+            (entry.kind !== 'instructions' && entry.kind !== 'resources' && entry.kind !== 'mcp') ||
+            typeof entry.content !== 'string' ||
+            entry.content.length === 0)
+            return undefined;
+        contentBytes += Buffer.byteLength(entry.content);
+        if (contentBytes > MAX_CONTEXTUAL_WORLD_STATE_CONTENT_BYTES)
+            return undefined;
+        entries.push({
+            index: entry.index,
+            kind: entry.kind,
+            content: entry.content
+        });
+    }
+    return {
+        generation,
+        initialized: true,
+        instructionSnapshot,
+        resourceSnapshot,
+        mcpSnapshot: typeof record.mcpSnapshot === 'string' ? record.mcpSnapshot : undefined,
+        entries
+    };
+}
+function nullableWorldStateString(value) {
+    if (value === null)
+        return undefined;
+    return typeof value === 'string' &&
+        Buffer.byteLength(value) <= MAX_CONTEXTUAL_WORLD_STATE_CONTENT_BYTES
+        ? value
+        : null;
+}
+export async function persistContextualWorldState(store, sessionId, state) {
+    await store.writeContextualWorldState(sessionId, {
+        version: 1,
+        generation: state.generation ?? null,
+        instructionSnapshot: state.instructionSnapshot ?? null,
+        resourceSnapshot: state.resourceSnapshot ?? null,
+        mcpSnapshot: state.mcpSnapshot ?? null,
+        entries: state.entries
+    });
+}
+export function compactHistoryMayContainRetainedResources(records) {
+    return records.some((record) => compactSummaryFromCheckpoint(record)?.includes('# Retained Session resources'));
+}
+export function updateContextualWorldState(state, index, current) {
+    const entries = [...state.entries];
+    if (!state.initialized || state.instructionSnapshot !== current.instructionSnapshot) {
+        if (current.instructionContent !== undefined)
+            entries.push({ index, kind: 'instructions', content: current.instructionContent });
+    }
+    const resourceContent = retainedSessionResourcesUpdate(current.resourceSnapshot, state.initialized ? state.resourceSnapshot : undefined, current.previousMayContainResources);
+    if (resourceContent !== undefined)
+        entries.push({ index, kind: 'resources', content: resourceContent });
+    return {
+        generation: state.generation,
+        mcpSnapshot: state.mcpSnapshot,
+        initialized: true,
+        instructionSnapshot: current.instructionSnapshot,
+        resourceSnapshot: current.resourceSnapshot,
+        entries
+    };
+}
+export function resetContextualWorldState(generation, index, current) {
+    const entries = [];
+    if (current.instructionContent !== undefined)
+        entries.push({ index, kind: 'instructions', content: current.instructionContent });
+    const resourceContent = retainedSessionResourcesUpdate(current.resourceSnapshot, undefined, current.previousMayContainResources);
+    if (resourceContent !== undefined)
+        entries.push({ index, kind: 'resources', content: resourceContent });
+    return {
+        generation,
+        initialized: true,
+        instructionSnapshot: current.instructionSnapshot,
+        resourceSnapshot: current.resourceSnapshot,
+        entries
+    };
+}
+export function contextualInstructionInsertIndex(messages) {
+    let index = messages.findLastIndex((message) => message.role === 'user' && message.contextKind !== 'environment');
+    if (index < 0)
+        return 0;
+    if (index > 0 && messages[index - 1]?.contextKind === 'environment')
+        index--;
+    return index;
+}

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

@@ -0,0 +1,37 @@
+import type { MarAgentReasoningEffort } from '../model/configuration.js';
+/** @deprecated MAR Agent always executes tools directly through the Host. */
+export type AccessMode = 'full-access';
+export type ExecutionMode = 'run' | 'plan' | 'compact';
+export interface RunInputImage {
+    name: string;
+    mimeType: string;
+    dataBase64: string;
+}
+export interface MarAgentImageMetadata {
+    name: string;
+    mimeType: string;
+    byteSize: number;
+}
+export interface RunInput {
+    prompt: string;
+    clientMessageId?: string;
+    modelId?: string;
+    reasoningEffort?: MarAgentReasoningEffort;
+    /** @deprecated Accepted for source compatibility and otherwise ignored. */
+    access?: AccessMode;
+    images?: readonly RunInputImage[];
+}
+export interface ExecutionResult {
+    executionId: string;
+    status: 'completed' | 'failed' | 'cancelled';
+    finalAnswer: string;
+    errorCode?: string;
+    errorMessage?: string;
+}
+export interface RolloutBudgetOptions {
+    limitTokens?: number;
+    conserveAtRemainingTokens?: number;
+    finalizeAtRemainingTokens?: number;
+    samplingTokenWeight?: number;
+    prefillTokenWeight?: number;
+}

package/dist/agent-core/runtime/event-projection.d.ts

@@ -0,0 +1,5 @@
+import type { ModelUsage } from '../model/contracts.js';
+import type { MarAgentEvent } from './events.js';
+/** Keep streaming deltas live-only; exec output has one durable copy in model context records. */
+export declare function eventForPersistence(event: MarAgentEvent): MarAgentEvent | undefined;
+export declare function publicModelUsage(usage: ModelUsage): Omit<ModelUsage, 'rolloutBudgetUnits'>;

package/dist/agent-core/runtime/event-projection.js

@@ -0,0 +1,17 @@
+/** Keep streaming deltas live-only; exec output has one durable copy in model context records. */
+export function eventForPersistence(event) {
+    if (event.type === 'message.delta' ||
+        event.type === 'context.compacting' ||
+        event.type === 'model.performance' ||
+        event.type === 'message.performance')
+        return undefined;
+    if (event.type !== 'tool.completed' || event.toolName !== 'exec' || !event.data)
+        return event;
+    const metadata = Object.fromEntries(Object.entries(event.data).filter(([key]) => key !== 'stdout' && key !== 'stderr'));
+    return { ...event, data: metadata };
+}
+export function publicModelUsage(usage) {
+    const { rolloutBudgetUnits, ...publicUsage } = usage;
+    void rolloutBudgetUnits;
+    return publicUsage;
+}

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

@@ -0,0 +1,143 @@
+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';
+    data?: import('../tools/contracts.js').CodeCellEventData;
+    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;
+    }>;
+}