@myagentroam/agent 0.9.71 → 0.9.72

package/dist/prompts/index.d.ts

@@ -2,7 +2,7 @@ import type { ExecutionMode } from '../sdk/types.js';
 import { type ExecutionBudgetPromptState } from './execution-budget.js';
 import { type RetainedSessionResources } from './resources.js';
 import { type CurrentAgentModel, type SubagentModelOption } from './subagent.js';
-export declare const MAR_AGENT_PROMPT_VERSION = "1.41";
+export declare const MAR_AGENT_PROMPT_VERSION = "1.42";
 export declare function buildSystemPrompt(input: {
     mode: ExecutionMode;
     platform: string;

package/dist/prompts/index.js

@@ -6,7 +6,7 @@ import { outputStylePrompt } from './output.js';
 import { retainedSessionResourcesPrompt } from './resources.js';
 import { subagentModelOptionsPrompt, subagentPrompt, currentAgentModelPrompt } from './subagent.js';
 import { interactionPrompt, longRunningPrompt, safetyPrompt, toolUsagePrompt, workflowPrompt } from './workflow.js';
-export const MAR_AGENT_PROMPT_VERSION = '1.41';
+export const MAR_AGENT_PROMPT_VERSION = '1.42';
 export function buildSystemPrompt(input) {
     const toolNames = new Set(input.tools);
     const hasLongRunningCapability = [

package/dist/prompts/workflow.js

@@ -3,14 +3,14 @@ export function toolUsagePrompt(tools) {
     const names = new Set(tools);
     const clauses = [
         `# Tools and execution\nAvailable client tools: ${tools.join(', ')}.`,
-        'Inspect before editing, do not manufacture file contents from memory, and treat tool success as evidence only for what its result actually proves. A model response may request multiple independent tools; the Runtime may parallelize calls declared safe while preserving serial barriers and model call order.'
+        'Inspect before editing, do not manufacture file contents from memory, and treat tool success as evidence only for what its result actually proves. Start exploration with the smallest evidence that can change the next decision: locate relevant symbols, headings, or files before reading bodies, and expand only when current evidence is insufficient. Do not request multiple broad outputs merely because tools can run in parallel. A model response may request multiple independent tools; the Runtime may parallelize calls declared safe while preserving serial barriers and model call order.'
     ];
     if (names.has('skill'))
         clauses.push('If the request names or clearly matches an available Skill description, call skill before generic tools and follow the loaded workflow; semantic matches do not require the user to know the Skill name. Do not load unrelated Skills or claim to use one without calling skill.');
     if (names.has('exec'))
         clauses.push('Use exec for platform-native commands, scripts, verification, and mechanical edits. Prefer rg or rg --files for search. Batch independent lookups and already-decided commands, preserving failure ordering. Use scripts for mechanical substitutions instead of reproducing long unchanged text in a patch; inspect actual effects afterward.');
     if (names.has('read'))
-        clauses.push('Use read to batch known files and ranges. Read only what can affect the next decision, use returned continuation metadata when needed, and avoid rereading unchanged content.');
+        clauses.push('Use read to batch known files and ranges. Batch only already-located, bounded ranges that are likely to fit together; for large files or documents, locate relevant sections before reading them. Read only what can affect the next decision, continue only relevant incomplete results using returned metadata, and avoid rereading unchanged content.');
     if (names.has('apply_patch'))
         clauses.push('Prefer apply_patch for precise local edits. After a conflict, use the reported evidence to refresh only the affected context before retrying.');
     if (names.has('apply_patch') || names.has('exec'))

package/dist/runtime/context-gc.js

@@ -459,6 +459,8 @@ function collectStageACandidates(input, groups, existingReplacements, existingTa
             if (!parsed)
                 continue;
             const selected = parsed.items.flatMap((item) => {
+                if (item.pathTruncated)
+                    return [];
                 const itemKey = `${read.result.record.recordId}:${item.index}`;
                 if (claimedReadItems.has(itemKey))
                     return [];

package/dist/runtime/token-budget.d.ts

@@ -1,6 +1,7 @@
 export declare const MODEL_TOKEN_ESTIMATOR: "UTF8_BYTES_V1";
 /** Local budget estimate only; provider usage remains authoritative. */
 export declare function countModelTokens(value: string): number;
+export declare function modelTokenBudgetBytes(maximumTokens: number): number;
 export declare function truncateModelText(value: string, maximumTokens: number, omittedLabel?: string): {
     content: string;
     truncated: boolean;

package/dist/runtime/token-budget.js

@@ -4,12 +4,16 @@ const BYTES_PER_TOKEN = 4;
 export function countModelTokens(value) {
     return Math.ceil(Buffer.byteLength(value, 'utf8') / BYTES_PER_TOKEN);
 }
+export function modelTokenBudgetBytes(maximumTokens) {
+    return Math.max(0, Math.floor(maximumTokens)) * BYTES_PER_TOKEN;
+}
 export function truncateModelText(value, maximumTokens, omittedLabel = 'tool output') {
     const tokens = countModelTokens(value);
     if (tokens <= maximumTokens)
         return { content: value, truncated: false, omittedTokens: 0 };
-    const maximumBytes = Math.max(0, Math.floor(maximumTokens)) * BYTES_PER_TOKEN;
+    const maximumBytes = modelTokenBudgetBytes(maximumTokens);
     const bytes = Buffer.from(value, 'utf8');
+    const warning = `Warning: truncated output (original token count: ${tokens})\nTotal output lines: ${lineCount(value)}\n\n`;
     let retainedBytes = Math.max(0, maximumBytes - 16 * BYTES_PER_TOKEN);
     for (let attempt = 0; attempt < 8; attempt++) {
         let head = Math.ceil(retainedBytes / 2);
@@ -21,10 +25,14 @@ export function truncateModelText(value, maximumTokens, omittedLabel = 'tool out
             tail++;
         const omittedTokens = Math.ceil((tail - head) / BYTES_PER_TOKEN);
         const marker = `\n...[${omittedTokens} tokens of ${omittedLabel} omitted]...\n`;
-        const candidateBytes = head + Buffer.byteLength(marker, 'utf8') + bytes.length - tail;
+        const candidateBytes = Buffer.byteLength(warning, 'utf8') +
+            head +
+            Buffer.byteLength(marker, 'utf8') +
+            bytes.length -
+            tail;
         if (candidateBytes <= maximumBytes)
             return {
-                content: `${bytes.toString('utf8', 0, head)}${marker}${bytes.toString('utf8', tail)}`,
+                content: `${warning}${bytes.toString('utf8', 0, head)}${marker}${bytes.toString('utf8', tail)}`,
                 truncated: true,
                 omittedTokens
             };
@@ -33,12 +41,22 @@ export function truncateModelText(value, maximumTokens, omittedLabel = 'tool out
         retainedBytes = Math.max(0, retainedBytes - (candidateBytes - maximumBytes));
     }
     const marker = `\n...[${tokens} tokens of ${omittedLabel} omitted]...\n`;
+    const fallback = `${warning}${marker}`;
     return {
-        content: countModelTokens(marker) <= maximumTokens ? marker : '',
+        content: countModelTokens(fallback) <= maximumTokens ? fallback : '',
         truncated: true,
         omittedTokens: tokens
     };
 }
+function lineCount(value) {
+    let lines = value.length === 0 ? 0 : 1;
+    for (let index = 0; index < value.length; index++)
+        if (value.charCodeAt(index) === 10)
+            lines++;
+    if (value.endsWith('\n'))
+        lines--;
+    return lines;
+}
 function isContinuationByte(byte) {
     return byte !== undefined && (byte & 0xc0) === 0x80;
 }

package/dist/sdk/agent.js

@@ -931,14 +931,17 @@ export async function createMarAgent(options) {
                                         })
                                 });
                                 const modelOutput = boundedModelToolOutput(output.content);
+                                const eventSummary = output.content.slice(0, AGENT_EXECUTION_POLICY.toolEventSummaryCharacters);
                                 const structuredData = structuredToolEventData(call.name, output.data);
                                 const artifacts = structuredToolArtifacts(call.name, output.artifacts);
                                 await emit({
                                     type: 'tool.completed',
                                     toolName: call.name,
                                     callId: call.callId,
-                                    summary: output.content.slice(0, AGENT_EXECUTION_POLICY.toolEventSummaryCharacters),
-                                    truncated: output.truncated === true || modelOutput.truncated,
+                                    summary: eventSummary,
+                                    truncated: output.truncated === true ||
+                                        modelOutput.truncated ||
+                                        eventSummary.length < output.content.length,
                                     ...(artifacts === undefined ? {} : { artifacts }),
                                     ...(structuredData === undefined ? {} : { data: structuredData })
                                 });

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

@@ -243,7 +243,8 @@ function replacementMatchesRecords(replacement, records, recordsBySequence, work
         return replacement.items.every((item) => {
             const original = originalItems.get(item.index);
             const evidence = successfulPatchEvidenceForPath(records, recordsBySequence, item.evidenceSequence, item.path, workspace, platform);
-            return (original?.path === item.path &&
+            return (original?.pathTruncated === false &&
+                original?.path === item.path &&
                 evidence !== undefined &&
                 item.replacement ===
                     contextGcStaleReadReplacement({

package/dist/subagent/session-controller.js

@@ -77,7 +77,8 @@ export class SubagentSessionController {
             changedFiles: [],
             verification: [],
             evidence: [],
-            terminalPending: false
+            terminalPending: false,
+            terminalObserved: false
         };
         this.#createdInExecution++;
         this.#agents.set(state.agentId, state);
@@ -96,7 +97,7 @@ export class SubagentSessionController {
             this.#setFailure(state, error);
         }
         try {
-            await options.onCreated?.(this.#snapshot(state));
+            await options.onCreated?.(this.#receiptSnapshot(state));
             if (this.#disposed)
                 throw new MarAgentError('MAR_AGENT_DISPOSED', 'Subagent controller is disposed.');
             options.signal?.throwIfAborted();
@@ -106,6 +107,7 @@ export class SubagentSessionController {
         }
         if (state.status === 'failed') {
             await this.#publishTerminal(state);
+            state.terminalObserved = true;
             return this.#snapshot(state);
         }
         this.#queueTurn(state, input.prompt, execution.startTurn, []);
@@ -115,9 +117,13 @@ export class SubagentSessionController {
             })
             : undefined;
         try {
-            if (!input.background)
-                await state.turn.completion;
-            return this.#snapshot(state);
+            if (input.background)
+                return this.#receiptSnapshot(state);
+            await state.turn.completion;
+            const includeLatestMessage = this.#hasUnreadMessage(state);
+            const includeTerminalDetails = this.#observeTerminal(state);
+            this.#observeLatestMessage(state);
+            return this.#snapshot(state, { includeLatestMessage, includeTerminalDetails });
         }
         finally {
             detachParentAbort?.();
@@ -129,10 +135,21 @@ export class SubagentSessionController {
         options.signal?.throwIfAborted();
         validateOutputOptions(options);
         if (options.waitMs === undefined || options.waitMs === 0)
-            return { ...this.#snapshot(state), waitOutcome: 'snapshot' };
+            return {
+                ...this.#snapshot(state, {
+                    includeLatestMessage: false,
+                    includeTerminalDetails: false
+                }),
+                waitOutcome: 'snapshot'
+            };
         if (isTerminalState(state)) {
+            const includeLatestMessage = this.#hasUnreadMessage(state);
+            const includeTerminalDetails = this.#observeTerminal(state);
             this.#observeLatestMessage(state);
-            return { ...this.#snapshot(state), waitOutcome: 'completion' };
+            return {
+                ...this.#snapshot(state, { includeLatestMessage, includeTerminalDetails }),
+                waitOutcome: 'completion'
+            };
         }
         const waitFor = options.waitFor ?? 'completion';
         if (waitFor === 'message' && this.#hasUnreadMessage(state)) {
@@ -143,19 +160,27 @@ export class SubagentSessionController {
         if (waitFor === 'completion') {
             const completed = await this.#waitForCompletion(state, waitMs, options.signal);
             options.signal?.throwIfAborted();
+            const includeLatestMessage = completed ? this.#hasUnreadMessage(state) : false;
+            const includeTerminalDetails = completed ? this.#observeTerminal(state) : false;
             if (completed)
                 this.#observeLatestMessage(state);
             return {
-                ...this.#snapshot(state),
+                ...this.#snapshot(state, { includeLatestMessage, includeTerminalDetails }),
                 waitOutcome: completed ? 'completion' : 'timeout'
             };
         }
         const activity = await this.#waitForMessageOrCompletion([state], waitMs, options.signal);
         options.signal?.throwIfAborted();
+        const includeLatestMessage = activity?.kind === 'message' ||
+            (activity?.kind === 'completion' && this.#hasUnreadMessage(activity.state));
+        const includeTerminalDetails = activity?.kind === 'completion' ? this.#observeTerminal(activity.state) : false;
         if (activity)
             this.#observeLatestMessage(activity.state);
         return {
-            ...this.#snapshot(activity?.state ?? state),
+            ...this.#snapshot(activity?.state ?? state, {
+                includeLatestMessage,
+                includeTerminalDetails
+            }),
             waitOutcome: activity?.kind === 'message'
                 ? 'message'
                 : activity?.kind === 'completion'
@@ -172,13 +197,21 @@ export class SubagentSessionController {
         const live = states.filter((state) => state.status === 'queued' || state.status === 'running');
         if (options.waitMs === undefined || options.waitMs === 0)
             return {
-                ...this.#snapshot(live.at(-1) ?? states.at(-1)),
+                ...this.#snapshot(live.at(-1) ?? states.at(-1), {
+                    includeLatestMessage: false,
+                    includeTerminalDetails: false
+                }),
                 waitOutcome: 'snapshot'
             };
         if (live.length === 0) {
             const state = states.at(-1);
+            const includeLatestMessage = this.#hasUnreadMessage(state);
+            const includeTerminalDetails = this.#observeTerminal(state);
             this.#observeLatestMessage(state);
-            return { ...this.#snapshot(state), waitOutcome: 'completion' };
+            return {
+                ...this.#snapshot(state, { includeLatestMessage, includeTerminalDetails }),
+                waitOutcome: 'completion'
+            };
         }
         const waitFor = options.waitFor ?? 'completion';
         if (waitFor === 'message') {
@@ -192,10 +225,16 @@ export class SubagentSessionController {
         if (waitFor === 'message') {
             const activity = await this.#waitForMessageOrCompletion(live, waitMs, options.signal);
             options.signal?.throwIfAborted();
+            const includeLatestMessage = activity?.kind === 'message' ||
+                (activity?.kind === 'completion' && this.#hasUnreadMessage(activity.state));
+            const includeTerminalDetails = activity?.kind === 'completion' ? this.#observeTerminal(activity.state) : false;
             if (activity)
                 this.#observeLatestMessage(activity.state);
             return {
-                ...this.#snapshot(activity?.state ?? live.at(-1)),
+                ...this.#snapshot(activity?.state ?? live.at(-1), {
+                    includeLatestMessage,
+                    includeTerminalDetails
+                }),
                 waitOutcome: activity?.kind === 'message'
                     ? 'message'
                     : activity?.kind === 'completion'
@@ -205,10 +244,15 @@ export class SubagentSessionController {
         }
         const completed = await this.#waitForAnyCompletion(live, waitMs, options.signal);
         options.signal?.throwIfAborted();
+        const includeLatestMessage = completed ? this.#hasUnreadMessage(completed) : false;
+        const includeTerminalDetails = completed ? this.#observeTerminal(completed) : false;
         if (completed)
             this.#observeLatestMessage(completed);
         return {
-            ...this.#snapshot(completed ?? live.at(-1)),
+            ...this.#snapshot(completed ?? live.at(-1), {
+                includeLatestMessage,
+                includeTerminalDetails
+            }),
             waitOutcome: completed ? 'completion' : 'timeout'
         };
     }
@@ -250,14 +294,14 @@ export class SubagentSessionController {
                     state.turn === turn &&
                     turn.handle?.enqueueMessage(message, delivery)) {
                     state.receipt = mutableReceipt;
-                    return this.#snapshot(state);
+                    return this.#messageReceiptSnapshot(state);
                 }
                 await turn.completion;
             }
             else if (state.status === 'queued' && state.turn) {
                 state.turn.pendingMessages.push({ text: message, delivery });
                 state.receipt = mutableReceipt;
-                return this.#snapshot(state);
+                return this.#messageReceiptSnapshot(state);
             }
             this.#requireExecution();
             options.signal?.throwIfAborted();
@@ -268,12 +312,16 @@ export class SubagentSessionController {
             mutableReceipt.turnId = randomUUID();
             state.receipt = mutableReceipt;
             this.#queueTurn(state, message, execution.startTurn, [], mutableReceipt.turnId, delivery);
-            return this.#snapshot(state);
+            return this.#messageReceiptSnapshot(state);
         });
     }
     async cancel(agentId) {
         const state = await this.#find(agentId);
-        return this.#control(state, () => this.#cancelState(state));
+        await this.#control(state, () => this.#cancelState(state));
+        const includeLatestMessage = this.#hasUnreadMessage(state);
+        const includeTerminalDetails = this.#observeTerminal(state);
+        this.#observeLatestMessage(state);
+        return this.#snapshot(state, { includeLatestMessage, includeTerminalDetails });
     }
     #control(state, operation) {
         const result = (state.controlTail ?? Promise.resolve()).then(operation);
@@ -304,7 +352,6 @@ export class SubagentSessionController {
             }
             await turn.completion;
         }
-        return this.#snapshot(state);
     }
     listSessionResources() {
         return [...this.#agents.values()].map((state) => ({
@@ -493,6 +540,12 @@ export class SubagentSessionController {
     #observeLatestMessage(state) {
         state.observedMessageRevision = state.messageRevision;
     }
+    #observeTerminal(state) {
+        if (!isTerminalState(state) || state.terminalObserved)
+            return false;
+        state.terminalObserved = true;
+        return true;
+    }
     #closeReceipt(state) {
         if (state.receipt?.deliveryStatus === 'accepted' && state.receipt.turnId === state.turn?.turnId)
             state.receipt.deliveryStatus = state.status === 'cancelled' ? 'cancelled' : 'failed';
@@ -527,12 +580,28 @@ export class SubagentSessionController {
             throw new MarAgentError('MAR_AGENT_SUBAGENT_FAILED', 'Subagent control requires an active parent execution.');
         return this.#execution;
     }
-    #snapshot(state) {
+    #receiptSnapshot(state) {
+        return this.#snapshot(state, {
+            includeLatestMessage: false,
+            includeLatestActivity: false,
+            includeTerminalDetails: false
+        });
+    }
+    #messageReceiptSnapshot(state) {
+        // A follow-up starts a new observation boundary; messages from the preceding state
+        // must not be returned later as fresh progress for the newly requested work.
+        this.#observeLatestMessage(state);
+        return this.#receiptSnapshot(state);
+    }
+    #snapshot(state, options = {}) {
         const terminal = state.status === 'completed' ||
             state.status === 'failed' ||
             state.status === 'cancelled' ||
             state.status === 'interrupted';
-        const latestMessage = state.latestMessage === undefined
+        const includeLatestMessage = options.includeLatestMessage ?? true;
+        const includeLatestActivity = options.includeLatestActivity ?? true;
+        const includeTerminalDetails = options.includeTerminalDetails ?? true;
+        const latestMessage = !includeLatestMessage || state.latestMessage === undefined
             ? undefined
             : terminal
                 ? { ...state.latestMessage }
@@ -546,17 +615,17 @@ export class SubagentSessionController {
             ...(state.modelName === undefined ? {} : { modelName: state.modelName }),
             ...(state.reasoningEffort === undefined ? {} : { reasoningEffort: state.reasoningEffort }),
             ...(latestMessage === undefined ? {} : { latestMessage }),
-            ...(state.latestActivity === undefined
+            ...(!includeLatestActivity || state.latestActivity === undefined
                 ? {}
                 : { latestActivity: { ...state.latestActivity } }),
-            ...(state.summary === undefined ? {} : { summary: state.summary }),
-            ...(!terminal || state.changedFiles.length === 0
+            ...(!includeTerminalDetails || state.summary === undefined ? {} : { summary: state.summary }),
+            ...(!includeTerminalDetails || !terminal || state.changedFiles.length === 0
                 ? {}
                 : { changedFiles: [...state.changedFiles] }),
-            ...(!terminal || state.verification.length === 0
+            ...(!includeTerminalDetails || !terminal || state.verification.length === 0
                 ? {}
                 : { verification: [...state.verification] }),
-            ...(!terminal || state.evidence.length === 0
+            ...(!includeTerminalDetails || !terminal || state.evidence.length === 0
                 ? {}
                 : { evidence: state.evidence.map((item) => ({ ...item })) }),
             ...(state.errorCode === undefined ? {} : { errorCode: state.errorCode }),
@@ -667,7 +736,8 @@ function restoreAgentState(session) {
         changedFiles: [],
         verification: [],
         evidence: [],
-        terminalPending: false
+        terminalPending: false,
+        terminalObserved: false
     };
     for (const record of currentRecords) {
         if (!isRecord(record.payload) ||

package/dist/tools/agent-message.js

@@ -3,7 +3,7 @@ import { TOOL_EXECUTION_LIMITS } from './execution-limits.js';
 export const agentMessageToolDefinition = {
     name: 'agent_message',
     parallelSafety: 'serial',
-    description: 'Send a real user message to an existing child agent. Default delivery=append inserts guidance into a running child turn at the next safe boundary after the current model response or complete tool batch. Explicit delivery=replace immediately requests cancellation, waits for the old turn to close, then starts a new turn in the same Session. When idle, either mode starts a new turn using persisted history. Returns messageId, turnId and deliveryStatus: accepted means queued in memory; applied means persisted in model context, not that the guidance has been executed. Use agent_wait for the latest receipt and task status. Does not wait for the new task to complete or roll back existing side effects.',
+    description: 'Send a real user message to an existing child agent. Default delivery=append inserts guidance into a running child turn at the next safe boundary after the current model response or complete tool batch. Explicit delivery=replace immediately requests cancellation, waits for the old turn to close, then starts a new turn in the same Session. When idle, either mode starts a new turn using persisted history. Returns messageId, turnId, deliveryStatus, current status, and model metadata without repeating the child’s previous latestMessage, latestActivity, summary, or verification evidence. accepted means queued in memory; applied means persisted in model context, not that the guidance has been executed. Use agent_wait for subsequent progress or completion. Does not wait for the new task to complete or roll back existing side effects.',
     inputSchema: {
         type: 'object',
         properties: {

package/dist/tools/agent-wait.js

@@ -3,7 +3,7 @@ import { TOOL_EXECUTION_LIMITS } from './execution-limits.js';
 export const agentWaitToolDefinition = {
     name: 'agent_wait',
     parallelSafety: 'serial',
-    description: 'Read or wait a bounded time for a child agent result. waitFor defaults to "completion"; use "message" only when a fresh public commentary/final message would change the next decision. Omit agentId to wait for whichever live child returns first, matching Codex-style untargeted waiting and avoiding UUID transcription; provide the exact agentId returned by agent_start only when observing a specific child. If no child is live, untargeted waiting reads the most recently created child. For an exec processId, use exec with action:"poll" instead. Omitting waitMs waits up to 30 seconds by default; waitMs=0 returns the current snapshot immediately. Positive waits range up to 5 minutes, and positive values below 10 seconds are raised to 10 seconds. When blocked on a live child result, prefer one 300000 ms completion wait rather than repeated short waits. Every result includes waitOutcome as snapshot, message, completion, or timeout plus the real agentId and description. latestMessage is the most recent public assistant commentary/final message, never hidden reasoning or a tool result; latestActivity identifies whether the latest observed activity was a public message or a bounded tool started/completed/failed status. A queued or running result is not completion. A message wait consumes only the latest unread public message in the current Session runtime; tool activity does not wake it, and parent cancellation preserves unread progress for a later Execution. Do not use message waits as heartbeat checks or request progress merely to confirm that a child is still running. Terminal results include bounded summary, changedFiles, verification, and read evidence with path/line ranges; use that evidence to avoid repeating the full exploration, while independently checking consequential edits and claims.',
+    description: 'Read or wait a bounded time for a child agent result. waitFor defaults to "completion"; use "message" only when a fresh public commentary/final message would change the next decision. Omit agentId to wait for whichever live child returns first, matching Codex-style untargeted waiting and avoiding UUID transcription; provide the exact agentId returned by agent_start only when observing a specific child. If no child is live, untargeted waiting reads the most recently created child. For an exec processId, use exec with action:"poll" instead. Omitting waitMs waits up to 30 seconds by default; waitMs=0 returns the current snapshot immediately. Positive waits range up to 5 minutes, and positive values below 10 seconds are raised to 10 seconds. When blocked on a live child result, prefer one 300000 ms completion wait rather than repeated short waits. Every result includes waitOutcome as snapshot, message, completion, or timeout plus the real agentId and description. A message or first terminal completion result includes the newly observed latest public commentary/final message; snapshot, timeout, and repeated terminal results omit previously observed message text. latestActivity can still identify a public message or bounded tool started/completed/failed status. A queued or running result is not completion. A message wait consumes only the latest unread public message in the current Session runtime; tool activity does not wake it, and parent cancellation preserves unread progress for a later Execution. Do not use message waits as heartbeat checks or request progress merely to confirm that a child is still running. First terminal results include bounded summary, changedFiles, verification, and read evidence with path/line ranges; use that evidence to avoid repeating the full exploration, while independently checking consequential edits and claims.',
     inputSchema: {
         type: 'object',
         properties: {

package/dist/tools/local-registry.js

@@ -1,8 +1,9 @@
 import { MarAgentError } from '../error.js';
+import { AGENT_EXECUTION_POLICY } from '../runtime/execution-policy.js';
+import { modelTokenBudgetBytes } from '../runtime/token-budget.js';
 import { ApplyPatchTool } from './apply-patch.js';
 import { ExecTool } from './exec.js';
 import { CodeModeTool } from './code-mode.js';
-import { TOOL_EXECUTION_LIMITS } from './execution-limits.js';
 import { ReadTool } from './read.js';
 import { WorkspacePathResolver } from './shared/path-resolver.js';
 import { ViewImageTool } from './view-image.js';
@@ -188,46 +189,106 @@ async function fetchWebUrl(url, signal, allowUntrustedTls, redirects = 0) {
 function escapeAttribute(value) {
     return value.replaceAll('&', '&amp;').replaceAll('"', '&quot;').replaceAll('<', '&lt;');
 }
-function formatBatchReadResult(result, index) {
-    const path = escapeAttribute(result.path);
-    if ('error' in result)
-        return `<read_error index="${index}" path="${path}" code="${escapeAttribute(result.error.code)}">${result.error.message}</read_error>`;
-    const metadata = {
-        path: result.path,
-        encoding: result.encoding,
-        newline: result.newline,
-        startLine: result.startLine,
-        ...(result.endLine === undefined ? {} : { endLine: result.endLine }),
-        eof: result.eof,
-        truncated: result.truncated,
-        ...(result.nextOffset === undefined ? {} : { nextOffset: result.nextOffset })
+function escapeText(value) {
+    return value.replaceAll('&', '&amp;').replaceAll('<', '&lt;');
+}
+function boundedUtf8Prefix(value, maximumBytes) {
+    if (Buffer.byteLength(value) <= maximumBytes)
+        return { value, truncated: false };
+    const marker = '…';
+    const contentBudget = Math.max(0, maximumBytes - Buffer.byteLength(marker));
+    let result = '';
+    let bytes = 0;
+    for (const character of value) {
+        const characterBytes = Buffer.byteLength(character);
+        if (bytes + characterBytes > contentBudget)
+            break;
+        result += character;
+        bytes += characterBytes;
+    }
+    return { value: `${result}${marker}`, truncated: true };
+}
+function formatBatchReadResult(result, index, maximumBytes) {
+    const visiblePath = boundedUtf8Prefix(result.path, 128);
+    const path = escapeAttribute(visiblePath.value);
+    const pathTruncatedAttribute = visiblePath.truncated ? ' pathTruncated="true"' : '';
+    if ('error' in result) {
+        const message = boundedUtf8Prefix(result.error.message, 256);
+        const detailsTruncatedAttribute = message.truncated ? ' detailsTruncated="true"' : '';
+        const content = `<read_error index="${index}" path="${path}"${pathTruncatedAttribute} code="${escapeAttribute(result.error.code)}"${detailsTruncatedAttribute}>${escapeText(message.value)}</read_error>`;
+        if (Buffer.byteLength(content) <= maximumBytes)
+            return { content, previewComplete: true };
+        return {
+            content: `<read_error index="${index}" code="MAR_AGENT_TOOL_OUTPUT_LIMIT">Model-visible error metadata exceeds this item's output share.</read_error>`,
+            previewComplete: false
+        };
+    }
+    const lines = result.content ? result.content.split('\n') : [];
+    const render = (visibleLines) => {
+        const previewComplete = visibleLines === lines.length;
+        const endLine = visibleLines === 0 ? undefined : result.startLine + Math.max(0, visibleLines - 1);
+        const metadata = {
+            path: visiblePath.value,
+            ...(visiblePath.truncated ? { pathTruncated: true } : {}),
+            encoding: result.encoding,
+            newline: result.newline,
+            startLine: result.startLine,
+            ...(endLine === undefined ? {} : { endLine }),
+            eof: previewComplete ? result.eof : false,
+            truncated: previewComplete ? result.truncated : true,
+            ...(previewComplete
+                ? result.nextOffset === undefined
+                    ? {}
+                    : { nextOffset: result.nextOffset }
+                : { nextOffset: result.startLine + visibleLines }),
+            previewComplete
+        };
+        return [
+            `<read_result index="${index}" path="${path}"${pathTruncatedAttribute}>`,
+            lines.slice(0, visibleLines).join('\n'),
+            `<read_metadata>${JSON.stringify(metadata)}</read_metadata>`,
+            '</read_result>'
+        ]
+            .filter(Boolean)
+            .join('\n');
+    };
+    const full = render(lines.length);
+    if (Buffer.byteLength(full) <= maximumBytes)
+        return { content: full, previewComplete: true };
+    let low = 0;
+    let high = lines.length;
+    while (low < high) {
+        const middle = Math.ceil((low + high) / 2);
+        if (Buffer.byteLength(render(middle)) <= maximumBytes)
+            low = middle;
+        else
+            high = middle - 1;
+    }
+    const content = render(low);
+    if (Buffer.byteLength(content) <= maximumBytes)
+        return { content, previewComplete: low === lines.length };
+    return {
+        content: `<read_error index="${index}" code="MAR_AGENT_TOOL_OUTPUT_LIMIT">Model-visible read metadata exceeds this item's output share.</read_error>`,
+        previewComplete: false
     };
-    return [
-        `<read_result index="${index}" path="${path}">`,
-        result.content,
-        `<read_metadata>${JSON.stringify(metadata)}</read_metadata>`,
-        '</read_result>'
-    ]
-        .filter(Boolean)
-        .join('\n');
 }
 function formatBatchReadOutput(results) {
     const blocks = [];
     let bytes = 0;
     let truncated = false;
+    const maximumBytes = modelTokenBudgetBytes(AGENT_EXECUTION_POLICY.modelToolOutputTokens);
     for (const [index, result] of results.entries()) {
-        let block = formatBatchReadResult(result, index);
         const separatorBytes = blocks.length === 0 ? 0 : 1;
-        if (bytes + separatorBytes + Buffer.byteLength(block) >
-            TOOL_EXECUTION_LIMITS.readMaxBatchBytes) {
-            truncated = true;
-            block = `<read_error index="${index}" path="${escapeAttribute(result.path)}" code="MAR_AGENT_TOOL_OUTPUT_LIMIT">Batch output budget exhausted; read this range separately.</read_error>`;
-        }
-        const blockBytes = Buffer.byteLength(block);
-        if (bytes + separatorBytes + blockBytes > TOOL_EXECUTION_LIMITS.readMaxBatchBytes)
+        const remainingItems = results.length - index;
+        const itemBudget = Math.floor((maximumBytes - bytes - separatorBytes) / remainingItems);
+        const block = formatBatchReadResult(result, index, itemBudget);
+        const blockBytes = Buffer.byteLength(block.content);
+        if (bytes + separatorBytes + blockBytes > maximumBytes)
             break;
-        blocks.push(block);
+        blocks.push(block.content);
         bytes += separatorBytes + blockBytes;
+        if (!block.previewComplete)
+            truncated = true;
     }
     return { content: blocks.join('\n'), truncated };
 }

package/dist/tools/read-context.d.ts

@@ -1,6 +1,7 @@
 export interface ParsedReadContextItem {
     readonly index: number;
     readonly path: string;
+    readonly pathTruncated: boolean;
     readonly content: string;
     readonly metadata: Record<string, unknown>;
     readonly contentStart: number;

package/dist/tools/read-context.js

@@ -5,7 +5,7 @@ export function parseReadContextOutput(value) {
     let offset = 0;
     while (offset < value.length) {
         if (value.startsWith('<read_result ', offset)) {
-            const header = /^<read_result index="(\d+)" path="([^"]*)">\n/u.exec(value.slice(offset));
+            const header = /^<read_result index="(\d+)" path="([^"]*)"( pathTruncated="true")?>\n/u.exec(value.slice(offset));
             if (!header)
                 return undefined;
             const contentStart = offset + header[0].length;
@@ -27,15 +27,18 @@ export function parseReadContextOutput(value) {
             }
             const index = Number(header[1]);
             const path = unescapeAttribute(header[2]);
+            const pathTruncated = header[3] !== undefined;
             if (!Number.isSafeInteger(index) ||
                 index < 0 ||
                 !isRecord(metadata) ||
-                metadata.path !== path)
+                metadata.path !== path ||
+                (metadata.pathTruncated === true) !== pathTruncated)
                 return undefined;
             const blockEnd = metadataEnd + metadataEndMarker.length;
             items.push({
                 index,
                 path,
+                pathTruncated,
                 content: value.slice(contentStart, metadataStart),
                 metadata,
                 contentStart,
@@ -44,7 +47,7 @@ export function parseReadContextOutput(value) {
             offset = blockEnd;
         }
         else if (value.startsWith('<read_error ', offset)) {
-            const error = /^<read_error index="\d+" path="[^"]*" code="[^"]*">[^\n]*<\/read_error>/u.exec(value.slice(offset));
+            const error = /^<read_error index="\d+" path="[^"]*"(?: pathTruncated="true")? code="[^"]*"(?: detailsTruncated="true")?>[^\n]*<\/read_error>/u.exec(value.slice(offset));
             if (!error)
                 return undefined;
             offset += error[0].length;

package/dist/tools/read.js

@@ -46,7 +46,7 @@ export const readToolDefinition = {
             }
         }
     },
-    description: `Read one or more known text files/ranges. Strict UTF-8 with optional BOM is the default; BOM-declared UTF-16LE/UTF-16BE is supported. Invalid text returns an item error instead of replacement characters. Always pass reads; use one item for a single file and up to ${TOOL_EXECUTION_LIMITS.readMaxBatchItems} items for a batch. Results retain input order, use 1-based line numbers, and include <read_metadata> with path, encoding, newline, exact range, eof, truncation, and nextOffset. Items fail independently and run with bounded concurrency. Each item returns at most ${TOOL_EXECUTION_LIMITS.readMaxLines} lines/${TOOL_EXECUTION_LIMITS.readMaxBytes} bytes; the call shares a ${TOOL_EXECUTION_LIMITS.readMaxBatchBytes}-byte budget. Structured data.results items provide text as decoded source for the returned range, preserving line endings and excluding BOM; content is numbered display text. Large files support bounded range reads. Relative paths use the workspace; absolute paths are allowed. Prefer exec with rg for search and read for known files.`,
+    description: `Read one or more known text files/ranges. Strict UTF-8 with optional BOM is the default; BOM-declared UTF-16LE/UTF-16BE is supported. Invalid text returns an item error instead of replacement characters. Always pass reads; use one item for a single file and up to ${TOOL_EXECUTION_LIMITS.readMaxBatchItems} items for a batch. Batch only already-located, bounded ranges whose combined content is likely to fit the model-visible output budget; for exploration, locate relevant files, symbols, or headings first, then read the smallest useful ranges. Results retain input order, use 1-based line numbers, and include <read_metadata> with path, encoding, newline, exact visible range, eof, truncation, nextOffset, and whether previewComplete. Items fail independently and run with bounded concurrency. Each item returns at most ${TOOL_EXECUTION_LIMITS.readMaxLines} lines/${TOOL_EXECUTION_LIMITS.readMaxBytes} bytes; the structured call shares a ${TOOL_EXECUTION_LIMITS.readMaxBatchBytes}-byte budget, while ordinary model-visible content fairly shares the common tool-output budget across all items. Structured data.results items provide text as decoded source for the returned range, preserving line endings and excluding BOM; content is numbered display text. Large files support bounded range reads. If previewComplete is false, continue only the still-relevant item from nextOffset. Relative paths use the workspace; absolute paths are allowed. Prefer exec with rg for search and read for known files.`,
     inputSchema: {
         type: 'object',
         properties: {

package/package.json

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