@myagentroam/agent 0.9.140 → 0.9.142

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,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;
+    }>;
+}