@myagentroam/agent 0.10.30 → 0.10.31

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

@@ -10,6 +10,7 @@ export interface ModelInputMetadata {
     recordId?: string;
     extensionId?: string;
     truncated?: true;
+    smartCompaction?: true;
 }
 /** SDK-owned provenance. Text labels never grant instruction authority. */
 export interface ModelContextualBlock {

package/dist/agent-core/model/openai-responses.js

@@ -1771,6 +1771,8 @@ function strictFunctionSchema(value, optional = false) {
         return value;
     const schema = value;
     const supportedSchema = Object.fromEntries(Object.entries(schema).filter(([keyword]) => keyword !== 'propertyNames' && keyword !== 'uniqueItems'));
+    if (optional && Array.isArray(schema.enum) && !schema.enum.includes(null))
+        supportedSchema.enum = [...schema.enum, null];
     if (schema.type === 'object') {
         const properties = record(schema.properties);
         const required = new Set(Array.isArray(schema.required) ? schema.required : []);
@@ -1795,11 +1797,13 @@ function strictFunctionSchema(value, optional = false) {
         return supportedSchema;
     if (typeof schema.type === 'string')
         return { ...supportedSchema, type: [schema.type, 'null'] };
-    if (Array.isArray(schema.enum))
+    if (Array.isArray(schema.type))
         return {
             ...supportedSchema,
-            enum: schema.enum.includes(null) ? schema.enum : [...schema.enum, null]
+            type: schema.type.includes('null') ? schema.type : [...schema.type, 'null']
         };
+    if (Array.isArray(schema.enum))
+        return supportedSchema;
     return { anyOf: [supportedSchema, { type: 'null' }] };
 }
 function responseCitations(response) {

package/dist/agent-core/runtime/compaction/smart.d.ts

@@ -0,0 +1,14 @@
+import type { ModelMessage } from '../../model/contracts.js';
+import { type SessionRecord } from '../../session/jsonl-store.js';
+export declare const SMART_COMPACTION_MARKER = "<mar_runtime>\n<smart_compaction scope=\"this_message\">eligible</smart_compaction>\n</mar_runtime>";
+export interface SmartCompactionInput {
+    readonly recordId: string;
+    readonly eligible: boolean;
+    requested: boolean;
+    error?: unknown;
+}
+/** A measured watermark, not the stricter native-request budget calibration. */
+export declare function latestSmartContextTokens(records: readonly SessionRecord[], modelId: string, contextWindowTokens: number): number | undefined;
+/** Only provider views receive the marker; durable message content stays unchanged. */
+export declare function projectSmartCompactionMessage(message: ModelMessage): ModelMessage;
+export declare function requestSmartCompaction(input: SmartCompactionInput | undefined, start: () => void): void;

package/dist/agent-core/runtime/compaction/smart.js

@@ -0,0 +1,59 @@
+import { MarAgentError } from '../../error.js';
+import { compactSummaryFromCheckpoint } from '../../session/jsonl-store.js';
+export const SMART_COMPACTION_MARKER = '<mar_runtime>\n<smart_compaction scope="this_message">eligible</smart_compaction>\n</mar_runtime>';
+/** A measured watermark, not the stricter native-request budget calibration. */
+export function latestSmartContextTokens(records, modelId, contextWindowTokens) {
+    let tokens;
+    let matchingModel = false;
+    for (const record of records) {
+        const payload = record.payload;
+        if (compactSummaryFromCheckpoint(record) !== undefined) {
+            tokens = undefined;
+            // A sliced checkpoint does not prove the input window used by later usage.
+            matchingModel = false;
+        }
+        if (record.type === 'context.gc.completed')
+            tokens = undefined;
+        if (record.type === 'execution.header' && payload.mode !== 'compact') {
+            matchingModel =
+                payload.modelId === modelId && payload.contextWindowTokens === contextWindowTokens;
+            if (!matchingModel)
+                tokens = undefined;
+        }
+        if (matchingModel && payload.type === 'usage.updated' && payload.purpose !== 'compact') {
+            const value = payload.contextInputTokens ?? payload.inputTokens;
+            if (typeof value === 'number' && Number.isSafeInteger(value) && value >= 0)
+                tokens = value;
+        }
+    }
+    return tokens;
+}
+/** Only provider views receive the marker; durable message content stays unchanged. */
+export function projectSmartCompactionMessage(message) {
+    if (message.role !== 'user' ||
+        message.contextKind !== undefined ||
+        !message.metadata?.smartCompaction)
+        return message;
+    const suffix = '\n\n' + SMART_COMPACTION_MARKER;
+    return {
+        ...message,
+        content: message.content + suffix,
+        ...(message.textBlocks ? { textBlocks: [...message.textBlocks, { text: suffix }] } : {})
+    };
+}
+export function requestSmartCompaction(input, start) {
+    if (!input?.eligible)
+        throw new MarAgentError('MAR_AGENT_SMART_COMPACT_DENIED', 'The current user input is not eligible for Smart Compaction.');
+    if ('error' in input)
+        throw input.error;
+    if (input.requested)
+        return;
+    input.requested = true;
+    try {
+        start();
+    }
+    catch (error) {
+        input.error = error;
+        throw error;
+    }
+}

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

@@ -4,6 +4,7 @@ export declare const AGENT_EXECUTION_POLICY: Readonly<{
     modelToolOutputTokens: 10000;
     automaticCompactionPercent: 90;
     backgroundCompactionPercent: 85;
+    smartCompactionPercent: 60;
     subagentVerificationCharacters: 500;
     estimatedTokensPerImage: 1000;
 }>;

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

@@ -4,6 +4,7 @@ export const AGENT_EXECUTION_POLICY = Object.freeze({
     modelToolOutputTokens: 10_000,
     automaticCompactionPercent: 90,
     backgroundCompactionPercent: 85,
+    smartCompactionPercent: 60,
     subagentVerificationCharacters: 500,
     estimatedTokensPerImage: 1_000
 });

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

@@ -41,6 +41,7 @@ import { ContextGcRuntime } from '../runtime/context/gc-runtime.js';
 import { AGENT_EXECUTION_POLICY } from '../runtime/execution-policy.js';
 import { loadAgentInstructions, renderAgentInstructions } from '../runtime/context/instructions.js';
 import { normalizeMessagesForModel } from '../runtime/context/normalize.js';
+import { latestSmartContextTokens, projectSmartCompactionMessage, requestSmartCompaction } from '../runtime/compaction/smart.js';
 import { compactSummaryFromCheckpoint, inputMetadataFromRecord } from '../session/jsonl-store.js';
 import { SubagentSessionController } from '../subagent/session-controller.js';
 import { agentStartToolDefinitionWithModels } from '../tools/agent/agent-start.js';
@@ -417,6 +418,7 @@ export function createSessionOpener(services) {
                     pendingAppends.length = 0;
                     immediateTarget = messages;
                     let recordedEnvironment = restored.environmentState;
+                    let smartInput;
                     let compactContext;
                     let startCompact;
                     const writeInputRecord = async (content, type, metadata, call, committed) => {
@@ -425,6 +427,16 @@ export function createSessionOpener(services) {
                             throw new MarAgentError('MAR_AGENT_INPUT_CAPABILITY_UNSUPPORTED', 'Selected model does not support image input.');
                         await withRecordProjection(async () => {
                             call.signal.throwIfAborted();
+                            const smartPercent = smartContextTokens === undefined
+                                ? undefined
+                                : (smartContextTokens * 100) / selectedModel.contextWindowTokens;
+                            const smartCompaction = mode !== 'compact' &&
+                                sessionSource.type === 'user' &&
+                                type === 'turn.user' &&
+                                metadata.inputSource === undefined &&
+                                smartPercent !== undefined &&
+                                smartPercent >= AGENT_EXECUTION_POLICY.smartCompactionPercent &&
+                                smartPercent < AGENT_EXECUTION_POLICY.automaticCompactionPercent;
                             const images = content.images?.length
                                 ? await store.persistInputImages(sessionId, content.images)
                                 : [];
@@ -433,6 +445,7 @@ export function createSessionOpener(services) {
                                 payload: {
                                     ...metadata,
                                     prompt: content.text,
+                                    ...(smartCompaction ? { smartCompaction: true } : {}),
                                     ...(content.modelText === undefined ? {} : { modelText: content.modelText }),
                                     ...(content.context === undefined ? {} : { context: content.context }),
                                     ...(content.modelContext === undefined
@@ -444,6 +457,11 @@ export function createSessionOpener(services) {
                                 turnId
                             }, { signal: call.signal });
                             const inputMetadata = inputMetadataFromRecord(record);
+                            smartInput = {
+                                recordId: record.recordId,
+                                eligible: smartCompaction,
+                                requested: false
+                            };
                             compactionUserMessages.push({
                                 content: content.modelText ?? content.text,
                                 metadata: inputMetadata
@@ -549,6 +567,7 @@ export function createSessionOpener(services) {
                     const selected = createModelTurnSession(selectedAdapter);
                     selectedTurn = selected;
                     let lastServerUsage = latestModelUsage(contextRecords, selectedModel.id);
+                    let smartContextTokens = latestSmartContextTokens(contextRecords, selectedModel.id, selectedModel.contextWindowTokens);
                     const compactUserTokenLimit = Math.min(20_000, Math.floor(selectedModel.contextWindowTokens / 8));
                     const reasoningEffort = input.reasoningEffort ?? selectedModel.defaultReasoningEffort;
                     const useEffortUpdates = usesResponsesConfigurationUpdates(selectedModel);
@@ -887,8 +906,24 @@ export function createSessionOpener(services) {
                         const parentFrame = subagents === undefined || mode === 'compact'
                             ? undefined
                             : subagents.captureParentFrame(executionId);
+                        const roundSmartInput = smartInput;
                         const toolContext = {
                             host: host,
+                            requestSmartCompact: () => {
+                                controller.signal.throwIfAborted();
+                                requestSmartCompaction(roundSmartInput === smartInput ? roundSmartInput : undefined, () => {
+                                    // The Session owns this background operation, not the short-lived tool callback.
+                                    services.extensions.operations.enter({
+                                        sessionId,
+                                        sessionEpoch: coreExtensions.epoch,
+                                        executionId,
+                                        turnId,
+                                        actor: 'sdk',
+                                        entry: 'native-api',
+                                        signal: controller.signal
+                                    }, () => startCompact({ async: true }));
+                                });
+                            },
                             permissionPolicy,
                             writeToolResultResource: (text) => store.writeToolResultResource(sessionId, text),
                             todo,
@@ -1185,7 +1220,7 @@ export function createSessionOpener(services) {
                                 (entry.metadata?.recordId
                                     ? message.metadata?.recordId === entry.metadata.recordId
                                     : message.content === entry.content)));
-                            const snapshotTools = structuredClone(executionTools);
+                            const snapshotTools = structuredClone(projectTools(executionTools));
                             const generation = contextualWorldState.generation;
                             const snapshotUsage = lastServerUsage;
                             const snapshotEffort = requestReasoningEffort ?? reasoningEffort;
@@ -1201,7 +1236,7 @@ export function createSessionOpener(services) {
                             const compactSystemPrompt = compactComposition.system;
                             const projectedHistory = normalizeMessagesForModel(compactHistory, {
                                 supportsImages: false
-                            });
+                            }).map(projectSmartCompactionMessage);
                             const nativeCompactMessages = buildNativeCompactionMessages(projectedHistory, {
                                 ...(input.focus === undefined ? {} : { focus: input.focus })
                             });
@@ -1358,6 +1393,7 @@ export function createSessionOpener(services) {
                             await resetCompactWorldState(compactRecord.recordId, { resources: compactResources });
                             lastServerContextTokens = undefined;
                             lastServerUsage = undefined;
+                            smartContextTokens = undefined;
                             requestReasoningEffort = reasoningEffort;
                             effectiveReasoningEffort = reasoningEffort;
                             await emit({
@@ -1371,7 +1407,7 @@ export function createSessionOpener(services) {
                         };
                         startCompact = (input = {}) => {
                             const id = manualCompactionId ?? randomUUID();
-                            return compactCoordinator.start(id, input.focus, async (prepare, signal) => {
+                            const flight = compactCoordinator.start(id, input.focus, async (prepare, signal) => {
                                 const linked = AbortSignal.any([signal, controller.signal, compactSignal]);
                                 try {
                                     if (mode === 'compact' && inputs.currentCompact())
@@ -1393,6 +1429,9 @@ export function createSessionOpener(services) {
                                     throw error;
                                 }
                             });
+                            if (smartInput)
+                                smartInput.requested = true;
+                            return flight;
                         };
                         compactContext = async (input = {}) => {
                             const flight = startCompact(input);
@@ -1576,10 +1615,12 @@ export function createSessionOpener(services) {
                             },
                             observeContextTokens: (tokens) => {
                                 lastServerContextTokens = tokens;
+                                smartContextTokens = tokens;
                             },
                             observeUsage: (usage) => {
                                 if (usage !== undefined) {
                                     lastServerContextTokens = usage.contextInputTokens;
+                                    smartContextTokens = usage.contextInputTokens;
                                     lastServerUsage = { ...usage, historyMessages: [...messages] };
                                 }
                             },
@@ -1622,6 +1663,7 @@ export function createSessionOpener(services) {
                                         }
                                     });
                                     if (committed) {
+                                        smartContextTokens = undefined;
                                         selected.resetContinuation?.();
                                         const refreshed = await restoreMessages(store, sessionId, committed.records, {
                                             includeImages: true,
@@ -2070,7 +2112,7 @@ function projectSessionRequestMessages(messages, entries, supportsImages, codeMo
         supportsImages
     }).map((message) => projectCodeModeSearchResult(autoPermission && message.toolSearchTools
         ? { ...message, toolSearchTools: message.toolSearchTools.map(projectPermissionTool) }
-        : message, codeMode));
+        : projectSmartCompactionMessage(message), codeMode));
 }
 function projectAppendedModelMessage(input) {
     if (input.visibility === 'transcript')

package/dist/agent-core/session/jsonl-store.js

@@ -2527,7 +2527,8 @@ export function parseModelInputMetadata(value) {
         ...(typeof metadata.extensionId === 'string' && metadata.extensionId.length <= 128
             ? { extensionId: metadata.extensionId }
             : {}),
-        ...(metadata.truncated === true ? { truncated: true } : {})
+        ...(metadata.truncated === true ? { truncated: true } : {}),
+        ...(metadata.smartCompaction === true ? { smartCompaction: true } : {})
     };
 }
 export function inputMetadataFromRecord(record) {
@@ -2540,6 +2541,7 @@ export function inputMetadataFromRecord(record) {
                 ? 'parent_agent'
                 : 'user',
         recordId: record.recordId,
+        ...(payload.smartCompaction === true ? { smartCompaction: true } : {}),
         ...(typeof source?.extensionId === 'string' && source.extensionId.length <= 128
             ? { extensionId: source.extensionId }
             : {})

package/dist/agent-core/tools/agent/smart-compact.d.ts

@@ -0,0 +1,9 @@
+import type { ClientToolDefinition } from '../../model/contracts.js';
+import type { ToolRuntimeContext } from '../runtime-context.js';
+export declare const smartCompactToolDefinition: ClientToolDefinition;
+export declare function executeSmartCompact(arguments_: unknown, context: ToolRuntimeContext): Promise<{
+    content: string;
+    data: {
+        status: string;
+    };
+}>;

package/dist/agent-core/tools/agent/smart-compact.js

@@ -0,0 +1,20 @@
+import { MarAgentError } from '../../error.js';
+export const smartCompactToolDefinition = {
+    name: 'smart_compact',
+    allowedCallers: ['direct', 'programmatic'],
+    parallelSafety: 'safe',
+    description: 'Request background context compaction only when the current real user message ends with <mar_runtime><smart_compaction scope="this_message">eligible</smart_compaction></mar_runtime> (on separate lines). The scope applies only to the containing user message; a historical marker does not authorize the current input. Call only when prior work is substantially complete, the request begins a sustained new work phase, and prior detailed context has low continuation value while key state can be retained in a summary. Do not call merely because the conversation is long, for a one-off question, or while prior evidence is still needed. Prefer calling alongside the first batch of necessary read/search/exec tools rather than creating a separate rollout. Acceptance does not wait for generation or installation.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false }
+};
+export function executeSmartCompact(arguments_, context) {
+    if (!arguments_ ||
+        typeof arguments_ !== 'object' ||
+        Array.isArray(arguments_) ||
+        Object.keys(arguments_).length)
+        throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Smart Compaction input must be an empty object.');
+    if (!context.requestSmartCompact)
+        throw new MarAgentError('MAR_AGENT_SMART_COMPACT_DENIED', 'The current user input is not eligible for Smart Compaction.');
+    context.requestSmartCompact();
+    const data = { status: 'accepted' };
+    return Promise.resolve({ content: JSON.stringify(data), data });
+}

package/dist/agent-core/tools/registry.js

@@ -12,6 +12,7 @@ import { executeTodoRead, todoReadToolDefinition } from './agent/todo-read.js';
 import { executeTodoWrite, todoWriteToolDefinition } from './agent/todo-write.js';
 import { executeToolSearch, toolSearchToolDefinition } from './mcp/tool-search.js';
 import { viewImageToolDefinition } from './local/view-image.js';
+import { smartCompactToolDefinition, executeSmartCompact } from './agent/smart-compact.js';
 export const BUILTIN_TOOL_DEFINITIONS = [
     skillToolDefinition,
     toolSearchToolDefinition,
@@ -28,10 +29,12 @@ export const BUILTIN_TOOL_DEFINITIONS = [
     agentStartToolDefinition,
     agentWaitToolDefinition,
     agentMessageToolDefinition,
-    agentCancelToolDefinition
+    agentCancelToolDefinition,
+    smartCompactToolDefinition
 ];
 export const AGENT_TOOL_HANDLERS = new Map([
     ['skill', executeSkill],
+    ['smart_compact', executeSmartCompact],
     ['tool_search', executeToolSearch],
     ['question', executeQuestion],
     ['todo_read', (_arguments, context) => executeTodoRead(context)],

package/dist/agent-core/tools/runtime-context.d.ts

@@ -40,6 +40,7 @@ export interface ToolRuntimeImage {
 export interface ToolRuntimeContext {
     host: MarAgentHost;
     todo: TodoStore;
+    requestSmartCompact?: () => void;
     subagents?: SubagentController;
     mode: ExecutionMode;
     sessionId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myagentroam/agent",
-  "version": "0.10.30",
+  "version": "0.10.31",
   "description": "Embeddable MAR coding agent SDK and CLI.",
   "license": "Apache-2.0",
   "type": "module",