@myagentroam/agent 0.9.135 → 0.9.137

package/dist/sdk/mcp-catalog.js

@@ -0,0 +1,219 @@
+import { MarAgentError } from '../error.js';
+export const MCP_DEFINITION_LIMITS = Object.freeze({
+    depth: 64,
+    nodes: 32768,
+    definitionBytes: 256 * 1024,
+    catalogBytes: 16 * 1024 * 1024,
+    tools: 10000,
+    servers: 256
+});
+function invalid() {
+    throw new MarAgentError('MAR_AGENT_MCP_CATALOG_INVALID', 'MCP catalog contains invalid or oversized definitions.');
+}
+const record = (value) => value !== null &&
+    typeof value === 'object' &&
+    !Array.isArray(value) &&
+    [Object.prototype, null].includes(Object.getPrototypeOf(value));
+const text = (value, maximum) => typeof value === 'string' && value.length > 0 && value.length <= maximum;
+const onlyKeys = (value, keys) => Object.keys(value).every((key) => keys.includes(key));
+/** Bound all JSON, including unknown extension keywords, before recursive lowering. */
+function assertJson(value) {
+    const stack = [{ value, depth: 0 }];
+    const seen = new Set();
+    let nodes = 0;
+    while (stack.length) {
+        const current = stack.pop();
+        if (current.exit) {
+            seen.delete(current.value);
+            continue;
+        }
+        if (++nodes > MCP_DEFINITION_LIMITS.nodes || current.depth > MCP_DEFINITION_LIMITS.depth)
+            invalid();
+        const item = current.value;
+        if (item === null ||
+            typeof item === 'string' ||
+            typeof item === 'boolean' ||
+            (typeof item === 'number' && Number.isFinite(item)))
+            continue;
+        if (!Array.isArray(item) && !record(item))
+            invalid();
+        if (seen.has(item))
+            invalid();
+        seen.add(item);
+        stack.push({ value: item, depth: current.depth, exit: true });
+        for (const child of Object.values(item))
+            stack.push({ value: child, depth: current.depth + 1 });
+    }
+}
+function assertSchema(schema) {
+    if (!record(schema) || schema.type !== 'object')
+        invalid();
+    assertJson(schema);
+    const stack = [schema];
+    const types = new Set(['null', 'boolean', 'object', 'array', 'number', 'integer', 'string']);
+    while (stack.length) {
+        const value = stack.pop();
+        if (typeof value === 'boolean')
+            continue;
+        if (!record(value))
+            invalid();
+        if (value.type !== undefined) {
+            const entries = Array.isArray(value.type) ? value.type : [value.type];
+            if (!entries.length ||
+                new Set(entries).size !== entries.length ||
+                entries.some((type) => typeof type !== 'string' || !types.has(type)))
+                invalid();
+        }
+        if (value.required !== undefined &&
+            (!Array.isArray(value.required) ||
+                value.required.some((name) => typeof name !== 'string') ||
+                new Set(value.required).size !== value.required.length))
+            invalid();
+        for (const key of [
+            'properties',
+            'patternProperties',
+            '$defs',
+            'definitions',
+            'dependentSchemas'
+        ]) {
+            const children = value[key];
+            if (children === undefined)
+                continue;
+            if (!record(children))
+                invalid();
+            stack.push(...Object.values(children));
+        }
+        for (const key of ['allOf', 'anyOf', 'oneOf', 'prefixItems']) {
+            const children = value[key];
+            if (children === undefined)
+                continue;
+            if (!Array.isArray(children) || !children.length)
+                invalid();
+            stack.push(...children);
+        }
+        for (const key of [
+            'additionalProperties',
+            'unevaluatedProperties',
+            'additionalItems',
+            'unevaluatedItems',
+            'contains',
+            'propertyNames',
+            'not',
+            'if',
+            'then',
+            'else',
+            'items'
+        ]) {
+            const child = value[key];
+            if (child !== undefined) {
+                if (key === 'items' && Array.isArray(child))
+                    stack.push(...child);
+                else
+                    stack.push(child);
+            }
+        }
+        for (const key of ['$ref', '$id', '$schema', 'title', 'description', 'format', 'pattern'])
+            if (value[key] !== undefined && typeof value[key] !== 'string')
+                invalid();
+        for (const key of ['minimum', 'maximum', 'exclusiveMinimum', 'exclusiveMaximum', 'multipleOf'])
+            if (value[key] !== undefined &&
+                (typeof value[key] !== 'number' ||
+                    !Number.isFinite(value[key]) ||
+                    (key === 'multipleOf' && Number(value[key]) <= 0)))
+                invalid();
+        for (const key of [
+            'minLength',
+            'maxLength',
+            'minItems',
+            'maxItems',
+            'minProperties',
+            'maxProperties'
+        ])
+            if (value[key] !== undefined && (!Number.isSafeInteger(value[key]) || Number(value[key]) < 0))
+                invalid();
+        if (value.enum !== undefined && (!Array.isArray(value.enum) || !value.enum.length))
+            invalid();
+    }
+}
+/** Shared Host and Node publication boundary, not a provider-specific conversion. */
+export function assertMcpToolDefinition(value) {
+    if (!record(value) ||
+        !text(value.name, 256) ||
+        !/^mcp__[A-Za-z0-9_-]+__[A-Za-z0-9_-]+$/u.test(value.name) ||
+        typeof value.description !== 'string' ||
+        value.description.length > 65536 ||
+        (value.parallelSafety !== undefined &&
+            !['safe', 'serial'].includes(String(value.parallelSafety))) ||
+        (value.agentScope !== undefined &&
+            !['ROOT_AND_SUBAGENTS', 'ROOT_ONLY'].includes(String(value.agentScope))) ||
+        (value.allowedCallers !== undefined &&
+            (!Array.isArray(value.allowedCallers) ||
+                !value.allowedCallers.length ||
+                value.allowedCallers.some((caller) => caller !== 'direct' && caller !== 'programmatic'))) ||
+        (value.inputMode !== undefined && value.inputMode !== 'json'))
+        invalid();
+    assertJson(value);
+    assertSchema(value.inputSchema);
+    if (value.outputSchema !== undefined)
+        assertSchema(value.outputSchema);
+    if (Buffer.byteLength(JSON.stringify(value)) > MCP_DEFINITION_LIMITS.definitionBytes)
+        invalid();
+}
+export function assertMcpToolCatalog(value) {
+    if (!record(value) ||
+        typeof value.revision !== 'string' ||
+        value.revision.length > 512 ||
+        !onlyKeys(value, ['revision', 'servers', 'tools']) ||
+        !Array.isArray(value.servers) ||
+        value.servers.length > MCP_DEFINITION_LIMITS.servers ||
+        !Array.isArray(value.tools) ||
+        value.tools.length > MCP_DEFINITION_LIMITS.tools)
+        invalid();
+    const servers = new Set();
+    for (const server of value.servers) {
+        if (!record(server) ||
+            !text(server.id, 512) ||
+            !text(server.name, 256) ||
+            servers.has(server.id) ||
+            !onlyKeys(server, ['id', 'name', 'description', 'instructions']) ||
+            (server.description !== undefined &&
+                (typeof server.description !== 'string' || server.description.length > 65536)) ||
+            (server.instructions !== undefined &&
+                (typeof server.instructions !== 'string' || server.instructions.length > 65536)))
+            invalid();
+        servers.add(server.id);
+    }
+    const names = new Set();
+    for (const tool of value.tools) {
+        if (!record(tool) ||
+            !text(tool.serverId, 512) ||
+            !servers.has(tool.serverId) ||
+            !onlyKeys(tool, [
+                'definition',
+                'serverId',
+                'rawName',
+                'sourceIdentity',
+                'definitionRevision',
+                'lifetime',
+                'exposure',
+                'annotations'
+            ]) ||
+            !text(tool.rawName, 256) ||
+            !text(tool.sourceIdentity, 512) ||
+            !text(tool.definitionRevision, 512) ||
+            !['session', 'execution'].includes(String(tool.lifetime)) ||
+            !['direct', 'deferred'].includes(String(tool.exposure)))
+            invalid();
+        assertMcpToolDefinition(tool.definition);
+        if (tool.annotations !== undefined) {
+            if (!record(tool.annotations))
+                invalid();
+            assertJson(tool.annotations);
+        }
+        if (names.has(tool.definition.name))
+            invalid();
+        names.add(tool.definition.name);
+    }
+    if (Buffer.byteLength(JSON.stringify(value)) > MCP_DEFINITION_LIMITS.catalogBytes)
+        invalid();
+}

package/dist/sdk/types.d.ts

@@ -1,7 +1,9 @@
 import type { HostDescription } from '../host/contracts.js';
 import type { MarAgentModelConfiguration, MarAgentReasoningEffort } from '../model/configuration.js';
+import type { ClientToolDefinition } from '../model/contracts.js';
 import type { MarAgentSessionPage, MarAgentSessionSummary } from '../session/catalog.js';
 import type { SessionListInput, SessionSource } from '../session/types.js';
+import type { CodeModeStateEntry, CodeModeStateMutation } from '../tools/code-mode/state.js';
 /** @deprecated MAR Agent always executes tools directly through the Host. */
 export type AccessMode = 'full-access';
 export type ExecutionMode = 'run' | 'plan' | 'compact';
@@ -22,6 +24,8 @@ export interface ToolExecutionContext {
     codeMode?: {
         supportsImages?: boolean;
         tools: readonly import('../model/contracts.js').ClientToolDefinition[];
+        state?: readonly CodeModeStateEntry[];
+        commitState?(mutations: readonly CodeModeStateMutation[]): Promise<readonly CodeModeStateEntry[]>;
         invoke(call: ToolCall, signal: AbortSignal): Promise<ToolExecutionResult>;
     };
 }
@@ -29,6 +33,34 @@ export interface McpToolCatalogContext extends Pick<ToolExecutionContext, 'sessi
     executionScopeId?: string;
     claimExecutionScope?: boolean;
 }
+export interface McpToolCatalog {
+    readonly revision: string;
+    readonly servers: readonly {
+        readonly id: string;
+        readonly name: string;
+        readonly description?: string;
+        readonly instructions?: string;
+    }[];
+    readonly tools: readonly McpCatalogTool[];
+}
+export interface McpCatalogTool {
+    readonly definition: import('../model/contracts.js').ClientToolDefinition;
+    readonly serverId: string;
+    readonly rawName: string;
+    readonly sourceIdentity: string;
+    readonly definitionRevision: string;
+    readonly lifetime: 'session' | 'execution';
+    readonly exposure: 'direct' | 'deferred';
+    /** Untrusted MCP hints; never an authorization or parallel-safety decision. */
+    readonly annotations?: Readonly<Record<string, unknown>>;
+}
+export interface McpToolCallContext extends Pick<ToolExecutionContext, 'sessionId' | 'executionId'> {
+    readonly mode?: ExecutionMode;
+    readonly expectedTool?: {
+        readonly sourceIdentity: string;
+        readonly definitionRevision: string;
+    };
+}
 export interface HostSkill {
     readonly name: string;
     readonly description: string;
@@ -51,6 +83,8 @@ export type MarAgentToolArtifact = MarAgentToolImageArtifact;
 export interface ToolExecutionResult {
     content: string;
     data?: unknown;
+    /** Runtime-only definitions used to encode a Tool Search output. */
+    toolSearchTools?: readonly ClientToolDefinition[];
     truncated?: boolean;
     images?: readonly {
         mimeType: string;
@@ -78,7 +112,8 @@ export interface MarAgentHost {
         questions: unknown[];
     }, signal: AbortSignal): Promise<Record<string, unknown>>;
     listMcpTools?(context?: McpToolCatalogContext): Promise<readonly import('../model/contracts.js').ClientToolDefinition[]>;
-    callMcpTool?(call: ToolCall, signal: AbortSignal, context?: Pick<ToolExecutionContext, 'sessionId' | 'executionId'>): Promise<ToolExecutionResult>;
+    listMcpToolCatalog?(context: McpToolCatalogContext): Promise<McpToolCatalog>;
+    callMcpTool?(call: ToolCall, signal: AbortSignal, context?: McpToolCallContext): Promise<ToolExecutionResult>;
     listSessionResources?(sessionId: string): Promise<HostSessionResourceSnapshot>;
     disposeSessionResources?(sessionId: string): Promise<void>;
     dispose(): Promise<void>;
@@ -106,6 +141,20 @@ export type MarAgentEvent = MarAgentEventBase & ({
     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;
@@ -137,11 +186,13 @@ export type MarAgentEvent = MarAgentEventBase & ({
     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[];
@@ -150,6 +201,7 @@ export type MarAgentEvent = MarAgentEventBase & ({
     type: 'tool.failed';
     toolName: string;
     callId: string;
+    parentCallId?: string;
     code: string;
     message?: string;
 } | {

package/dist/session/context-gc-checkpoint.d.ts

@@ -50,7 +50,7 @@ export type ContextGcReplacement = {
     readonly evidenceSequences: readonly number[];
 } | {
     readonly kind: 'TOOL_CALL_INPUT';
-    readonly toolName: 'apply_patch' | 'exec';
+    readonly toolName: 'apply_patch' | 'exec' | 'code_mode';
     readonly callId: string;
     readonly target: ContextGcTarget;
     readonly replacementArguments: unknown;
@@ -62,6 +62,12 @@ export type ContextGcReplacement = {
     readonly target: ContextGcTarget;
     readonly replacementContent: string;
     readonly evidenceSequence: number;
+} | {
+    readonly kind: 'CODE_MODE_OUTPUT';
+    readonly callId: string;
+    readonly target: ContextGcTarget;
+    readonly replacementContent: string;
+    readonly evidenceSequence: number;
 } | {
     readonly kind: 'SUBAGENT_OUTPUT';
     readonly toolName: 'agent_wait' | 'agent_message' | 'agent_cancel';

package/dist/session/context-gc-checkpoint.js

@@ -2,7 +2,7 @@ import { createHash } from 'node:crypto';
 import { posix, win32 } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 import { parseReadContextOutput } from '../tools/read-context.js';
-import { contextGcApplyPatchInputReplacement, contextGcWebOutputReplacement, contextGcExecInputReplacement, contextGcExecOutputReplacement, contextGcPatchResultFromCompletedPayload, contextGcStaleReadReplacement, normalizeContextGcExecResult } from './context-gc-replacements.js';
+import { contextGcApplyPatchInputReplacement, contextGcCodeModeInputReplacement, contextGcCodeModeOutputReplacement, contextGcExecInputReplacement, contextGcExecOutputReplacement, contextGcPatchResultFromCompletedPayload, contextGcStaleReadReplacement, contextGcWebOutputReplacement, normalizeContextGcCodeModeInput, normalizeContextGcExecResult } from './context-gc-replacements.js';
 import { contextGcSubagentNeedsRetainedPriorFinal, contextGcSubagentOutputReplacement, contextGcSubagentSnapshotIsPreciselyCovered, contextGcSubagentSnapshotIsSuperseded, normalizeContextGcSubagentSnapshot } from './context-gc-subagent.js';
 export const CONTEXT_GC_CHECKPOINT_VERSION = 1;
 export const CONTEXT_GC_MAX_TARGETS = 4_096;
@@ -266,6 +266,25 @@ function replacementMatchesRecords(replacement, records, recordsBySequence, work
             result !== undefined &&
             isDeepStrictEqual(replacement.replacementArguments, contextGcApplyPatchInputReplacement(source.payload.arguments, result, replacement.evidenceSequence, applyPatchReplacementFormatVersion(replacement.replacementArguments))));
     }
+    if (replacement.kind === 'TOOL_CALL_INPUT' && replacement.toolName === 'code_mode') {
+        const evidence = successfulToolEvidence(records, recordsBySequence, replacement.evidenceSequence, 'code_mode');
+        const input = normalizeContextGcCodeModeInput(source.payload.arguments);
+        return (evidence?.callId === replacement.callId &&
+            evidence.call.sequence === replacement.target.sequence &&
+            input !== undefined &&
+            isDeepStrictEqual(replacement.replacementArguments, contextGcCodeModeInputReplacement(input)));
+    }
+    if (replacement.kind === 'CODE_MODE_OUTPUT') {
+        const evidence = successfulToolEvidence(records, recordsBySequence, replacement.evidenceSequence, 'code_mode');
+        return (evidence?.callId === replacement.callId &&
+            evidence.result.sequence === replacement.target.sequence &&
+            isRecord(evidence.result.payload) &&
+            typeof evidence.result.payload.content === 'string' &&
+            isRecord(evidence.completed.payload) &&
+            typeof evidence.completed.payload.truncated === 'boolean' &&
+            replacement.replacementContent ===
+                contextGcCodeModeOutputReplacement(evidence.result.payload.content, evidence.completed.payload.truncated));
+    }
     if (replacement.kind === 'SUBAGENT_OUTPUT') {
         const retainedPriorFinal = replacement.retainedPriorFinal;
         const sourceEvidence = successfulToolEvidence(records, recordsBySequence, source.sequence, replacement.toolName);
@@ -605,7 +624,9 @@ function isContextGcReplacement(value) {
             'evidenceSequence'
         ]) &&
             value.target.role === 'tool_call' &&
-            (value.toolName === 'apply_patch' || value.toolName === 'exec') &&
+            (value.toolName === 'apply_patch' ||
+                value.toolName === 'exec' ||
+                value.toolName === 'code_mode') &&
             value.target.toolName === value.toolName &&
             Array.isArray(value.providerAliasTargets) &&
             value.providerAliasTargets.every((target) => isContextGcTarget(target) &&
@@ -661,6 +682,11 @@ function isContextGcReplacement(value) {
             (value.target.toolName === undefined || value.target.toolName === value.toolName) &&
             isNonemptyString(value.replacementContent) &&
             isPositiveInteger(value.evidenceSequence));
+    if (value.kind === 'CODE_MODE_OUTPUT')
+        return (hasOnlyKeys(value, ['kind', 'callId', 'target', 'replacementContent', 'evidenceSequence']) &&
+            value.target.role === 'tool' &&
+            isNonemptyString(value.replacementContent) &&
+            isPositiveInteger(value.evidenceSequence));
     return (value.kind === 'EXEC_OUTPUT' &&
         hasOnlyKeys(value, ['kind', 'callId', 'target', 'replacementContent', 'evidenceSequence']) &&
         value.target.role === 'tool' &&

package/dist/session/context-gc-replacements.d.ts

@@ -1,4 +1,11 @@
 export type ContextGcWebToolName = 'web_search' | 'web_fetch';
+export interface ContextGcCodeModeInput {
+    readonly code: string;
+    readonly inputMode: 'freeform' | 'json';
+}
+export declare function normalizeContextGcCodeModeInput(arguments_: unknown): ContextGcCodeModeInput | undefined;
+export declare function contextGcCodeModeInputReplacement(input: ContextGcCodeModeInput): unknown;
+export declare function contextGcCodeModeOutputReplacement(originalContent: string, truncated: boolean): string;
 export interface ContextGcPatchFile {
     readonly path: string;
     readonly targetPath?: string;

package/dist/session/context-gc-replacements.js

@@ -3,6 +3,32 @@ const RAW_MODEL_CONTEXT_PREVIEW_CHARACTERS = 256;
 const EXEC_INPUT_COMPLETE_CHARACTERS = 512;
 const EXEC_INPUT_PREVIEW_CHARACTERS = 256;
 const EXEC_OUTPUT_PREVIEW_CHARACTERS = 512;
+const CODE_MODE_OUTPUT_PREVIEW_CHARACTERS = 512;
+export function normalizeContextGcCodeModeInput(arguments_) {
+    if (typeof arguments_ === 'string' && arguments_.length > 0)
+        return { code: arguments_, inputMode: 'freeform' };
+    if (isRecord(arguments_) &&
+        Object.keys(arguments_).length === 1 &&
+        typeof arguments_.code === 'string' &&
+        arguments_.code.length > 0)
+        return { code: arguments_.code, inputMode: 'json' };
+    return undefined;
+}
+export function contextGcCodeModeInputReplacement(input) {
+    const replacement = `<context_gc kind="completed_code_mode_input" originalBytes="${Buffer.byteLength(input.code)}" lines="${lineCount(input.code)}" inputMode="${input.inputMode}">Completed Code Mode source was reclaimed after six successful rollouts. The paired output, images, completion evidence, and nested tool side effects remain in history.</context_gc>`;
+    return input.inputMode === 'freeform' ? replacement : { code: replacement };
+}
+export function contextGcCodeModeOutputReplacement(originalContent, truncated) {
+    const preview = unicodeHeadTail(originalContent, CODE_MODE_OUTPUT_PREVIEW_CHARACTERS);
+    return JSON.stringify({
+        originalBytes: Buffer.byteLength(originalContent),
+        lines: lineCount(originalContent),
+        truncated,
+        preview,
+        previewComplete: !truncated && preview === originalContent,
+        contextGc: 'Detailed Code Mode output was reclaimed after six successful rollouts. An incomplete preview is not the complete cell output. The source was not replayed and nested tool side effects were not changed.'
+    });
+}
 export function contextGcPatchResultFromCompletedPayload(payload) {
     if (!isRecord(payload) || payload.type !== 'tool.completed')
         return undefined;

package/dist/session/jsonl-store.d.ts

@@ -1,5 +1,6 @@
 import type { ModelUsage } from '../model/contracts.js';
 import type { EnvironmentContextState } from '../prompts/core.js';
+import { type CodeModeStateEntry } from '../tools/code-mode/state.js';
 import { type TodoSnapshot } from '../tools/todo.js';
 import { type ContextGcCheckpointDraft } from './context-gc-checkpoint.js';
 import type { SessionListInput, SessionSource } from './types.js';
@@ -146,6 +147,11 @@ export declare class JsonlSessionStore {
         timestamp?: string;
     }): Promise<SessionRecord>;
     read(sessionId: string): Promise<SessionRecord[]>;
+    readCodeModeState(sessionId: string): Promise<CodeModeStateEntry[]>;
+    commitCodeModeState(sessionId: string, mutations: unknown, input: {
+        readonly executionId: string;
+        readonly turnId: string;
+    }): Promise<CodeModeStateEntry[]>;
     readExecutionState(sessionId: string): Promise<SessionExecutionState>;
     readContext(sessionId: string): Promise<SessionRecord[]>;
     contextGcProjectionHash(sessionId: string, boundarySequence: number): Promise<string>;