@myagentroam/agent 0.11.20 → 0.11.22

package/dist/agent-core/tools/code-mode/observations.d.ts

@@ -1,3 +1,4 @@
+import type { ModelImage } from '../../model/image.js';
 /** Execution metadata is independent of explicit model observations. */
 export interface CodeToolCallRecord {
     callId: string;
@@ -41,10 +42,7 @@ export type CodeObservation = {
 };
 export declare function observationContent(value: CodeObservation): string;
 export declare function observationImages(value: CodeObservation): readonly number[];
-export declare function selectObservationImages(values: readonly CodeObservation[], images: readonly {
-    mimeType: string;
-    dataBase64: string;
-}[], offset?: number): {
+export declare function selectObservationImages(values: readonly CodeObservation[], images: readonly ModelImage[], offset?: number): {
     observations: ({
         result: {
             imageIndices: number[];
@@ -68,10 +66,7 @@ export declare function selectObservationImages(values: readonly CodeObservation
         value: string;
         truncated?: boolean;
     })[];
-    images: {
-        mimeType: string;
-        dataBase64: string;
-    }[];
+    images: ModelImage[];
 };
 /** Only the visible projection crosses into model text; program data and inputs stay private. */
 export declare function visibleObservation(value: CodeObservation): Record<string, unknown>;
@@ -90,19 +85,13 @@ export declare function observationModelParts(message: {
         readonly text: string;
     }[];
     observations?: readonly CodeObservation[];
-    images?: readonly {
-        mimeType: string;
-        dataBase64: string;
-    }[];
+    images?: readonly import('../../model/image.js').ModelImage[];
 }): Array<{
     type: 'text';
     text: string;
 } | {
     type: 'image';
-    image: {
-        mimeType: string;
-        dataBase64: string;
-    };
+    image: import('../../model/image.js').ModelImage;
 }> | undefined;
 /** Uses the same visible text as both adapters, without pixels or private observation data. */
 export declare function observationModelText(message: Parameters<typeof observationModelParts>[0]): string | undefined;

package/dist/agent-core/tools/code-mode/quickjs-engine.js

@@ -1,4 +1,5 @@
 import { BoundedTextOutput } from './text-output.js';
+import { sourcePreview } from '../input-diagnostics/source-preview.js';
 // This trusted module runs only in the Host-managed worker, never in the model's JS context.
 /** @returns {Promise<import('./engine.js').CodeModeEngine>} */
 export async function createCodeModeEngine(options) {
@@ -80,19 +81,25 @@ export async function createCodeModeEngine(options) {
                     throw executionTimeout();
                 let message = String(error?.message ?? error).slice(0, 4096);
                 const syntaxError = locateSource && error?.name === 'SyntaxError';
-                if (syntaxError)
-                    message = `JavaScript compilation failed before tool execution: ${message}`.slice(0, 4096);
+                if (syntaxError) {
+                    const reason = message === 'unexpected end of string' ? 'Unterminated string literal.' : message;
+                    const location = compilerSourceLocation(error, input.code);
+                    message = `${reason.slice(0, 256)}\n${location ? `Line ${location.line}${location.column === undefined ? '' : `, column ${location.column}`}. ` : ''}No tools were executed.`;
+                    if (location?.column !== undefined) {
+                        const source = input.code.split(/\r\n|[\r\n\u2028\u2029]/u)[location.line - 1];
+                        const preview = sourcePreview(source, location.column);
+                        const gutter = String(location.line);
+                        message += `\n\n${gutter} | ${preview.text}\n${' '.repeat(gutter.length)} | ${' '.repeat(preview.caret)}^`;
+                    }
+                }
                 if (error?.name === 'ReferenceError' &&
                     ["'text' is not defined", "'console' is not defined"].includes(message))
                     message =
                         `${message} Code Mode has no console or standalone text/image helpers; use observe.text(value) or observe.image(value).`.slice(0, 4096);
-                const location = locateSource ? compilerSourceLocation(error, input.code) : '';
-                if (location)
-                    message = message.slice(0, 4096 - location.length) + location;
-                const code = message.includes('out of memory')
-                    ? 'MAR_AGENT_CODE_MEMORY_LIMIT'
-                    : syntaxError
-                        ? 'MAR_AGENT_CODE_SYNTAX_ERROR'
+                const code = syntaxError
+                    ? 'MAR_AGENT_CODE_SYNTAX_ERROR'
+                    : message.includes('out of memory')
+                        ? 'MAR_AGENT_CODE_MEMORY_LIMIT'
                         : typeof error?.code === 'string'
                             ? error.code
                             : 'MAR_AGENT_CODE_FAILED';
@@ -711,12 +718,12 @@ function compilerSourceLocation(error, source) {
         error.fileName !== 'code-mode.js' ||
         !Number.isSafeInteger(error.lineNumber) ||
         error.lineNumber <= 1)
-        return '';
+        return undefined;
     // QuickJS counts LF lines and Unicode code-point columns; the wrapper adds one LF line.
     const lines = source.split('\n');
     const line = error.lineNumber - 1;
     if (line > lines.length)
-        return compilerCaret(source, source, true);
+        return originalSourceLocation(source);
     const column = Number(typeof error.stack === 'string'
         ? error.stack.match(/^\s*at code-mode\.js:\d+:(\d+)(?:\n|$)/u)?.[1]
         : undefined);
@@ -725,9 +732,9 @@ function compilerSourceLocation(error, source) {
         column > Array.from(lines[line - 1]).length + 1) {
         // Without a valid column, intra-LF-line separators make the original source line ambiguous.
         if (/[\r\u2028\u2029]/u.test(lines[line - 1].replace(/\r$/u, '')))
-            return '';
+            return undefined;
         const preceding = line > 1 ? lines.slice(0, line - 1).join('\n') + '\n' : '';
-        return ` (code-mode.js:${preceding.split(/\r\n|[\r\n\u2028\u2029]/u).length})`;
+        return { line: preceding.split(/\r\n|[\r\n\u2028\u2029]/u).length };
     }
     const prefix = [
         ...lines.slice(0, line - 1),
@@ -735,23 +742,13 @@ function compilerSourceLocation(error, source) {
             .slice(0, column - 1)
             .join('')
     ].join('\n');
-    return compilerCaret(source, prefix);
+    return originalSourceLocation(prefix);
 }
-function compilerCaret(source, prefix, endOfInput = false) {
+function originalSourceLocation(prefix) {
     const segments = prefix.split(/\r\n|[\r\n\u2028\u2029]/u);
     const line = segments.length;
     const column = Array.from(segments.at(-1)).length + 1;
-    const character = source.slice(prefix.length)[Symbol.iterator]().next().value;
-    // Source may contain credentials, commands or private code. Show only a punctuation token.
-    const token = endOfInput
-        ? '<end of input>'
-        : character === undefined || /[\r\n\u2028\u2029]/u.test(character)
-            ? '<end of line>'
-            : /^[{}[\]():;,.=+*/?!<>|&%\-]$/u.test(character)
-                ? character
-                : '<character omitted>';
-    const preview = '<source omitted>';
-    return ` (code-mode.js:${line}${endOfInput ? ', end of input' : ''})\nSyntax location: line ${line}, column ${column}\n${line} | ${preview}${token}\n${' '.repeat(String(line).length)} | ${' '.repeat(preview.length)}^`;
+    return { line, column };
 }
 function isParameterlessTool(tool) {
     if (tool.parameterless === true)

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

@@ -98,10 +98,7 @@ export interface ToolExecutionResult {
     /** Runtime-only definitions used to encode a Tool Search output. */
     toolSearchTools?: readonly ClientToolDefinition[];
     truncated?: boolean;
-    images?: readonly {
-        mimeType: string;
-        dataBase64: string;
-    }[];
+    images?: readonly import('../model/image.js').ModelImage[];
     artifacts?: readonly MarAgentToolArtifact[];
     /** Host-facing evidence, excluded from model and programmatic guest results. */
     resultExtensions?: readonly import('./result-extensions.js').ToolResultExtension[];
@@ -164,10 +161,23 @@ export interface ReadEventData {
     }>;
     truncated: boolean;
 }
+export interface ViewImageRegion {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
 export interface ViewImageResult {
-    path: string;
+    /** The input source; transformations may produce a different output resource. */
+    path?: string;
+    resourceId?: string;
     mimeType: 'image/png' | 'image/jpeg' | 'image/webp';
     bytes: number;
+    width: number;
+    height: number;
+    sourceWidth?: number;
+    sourceHeight?: number;
+    region?: ViewImageRegion;
     sha256: string;
 }
 export interface TodoItem {

package/dist/agent-core/tools/execution-limits.d.ts

@@ -5,7 +5,9 @@ export declare const TOOL_EXECUTION_LIMITS: Readonly<{
     readMaxBatchItems: 16;
     readBatchConcurrency: 4;
     readMaxBatchBytes: 4194304;
-    viewImageMaxBytes: 20971520;
+    viewImageMaxBytes: 3145728;
+    viewImageMaxSourceBytes: 20971520;
+    viewImageMaxPixels: 16777216;
     execMaxTimeoutMs: 3600000;
     execDefaultYieldMs: 10000;
     execMaxYieldMs: 30000;

package/dist/agent-core/tools/execution-limits.js

@@ -5,7 +5,9 @@ export const TOOL_EXECUTION_LIMITS = Object.freeze({
     readMaxBatchItems: 16,
     readBatchConcurrency: 4,
     readMaxBatchBytes: 4_194_304,
-    viewImageMaxBytes: 20_971_520,
+    viewImageMaxBytes: 3_145_728,
+    viewImageMaxSourceBytes: 20_971_520,
+    viewImageMaxPixels: 16_777_216,
     execMaxTimeoutMs: 3_600_000,
     execDefaultYieldMs: 10_000,
     execMaxYieldMs: 30_000,

package/dist/agent-core/tools/execution.d.ts

@@ -11,6 +11,7 @@ export type ExecutedToolCall = {
     call: ClientToolCall;
     content: string;
     images?: ToolExecutionResult['images'];
+    sourceImages?: ToolExecutionResult['images'];
     observations?: ToolExecutionResult['observations'];
     calls?: ToolExecutionResult['calls'];
 } & ({
@@ -31,7 +32,7 @@ export interface RoundToolScope {
     readonly assertExecutionLive: () => void;
     readonly emit: (event: EventPayload, assertLive?: () => void) => Promise<void>;
     readonly searchMcpTools: NonNullable<ToolRuntimeContext['searchMcpTools']>;
-    readonly recentImages: () => ToolRuntimeImage[];
+    readonly recentImages: () => Promise<ToolRuntimeImage[]>;
     readonly captureCodeContext: () => Omit<ToolRuntimeContext, 'signal' | 'codeMode' | 'expectedMcpTool' | 'searchMcpTools'>;
     readonly codeModeContext: (call: ToolCall & {
         readonly callId: string;

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

@@ -4,6 +4,7 @@ import { allowsToolCaller } from './callers.js';
 import { CodeCellExecutionError } from './code-mode/cells.js';
 import { createCodeToolDispatch } from './code-mode/dispatch.js';
 import { boundedModelToolOutput, structuredToolArtifacts, structuredToolEventData, structuredToolFailureData } from './output-projection.js';
+import { publishModelResources } from '../runtime/resource-publication.js';
 import { executeRegisteredTool } from './runtime.js';
 import { failedToolResultExtensions } from './result-extensions.js';
 import { permissionStopFromError } from './permissions.js';
@@ -13,6 +14,11 @@ export async function createRoundToolRuntimeContext(scope, call, signal) {
     scope.assertLive();
     signal.throwIfAborted();
     const codeMode = await scope.codeModeContext(call);
+    const recentImages = scope.extensionToolNames.has(call.name) ||
+        call.name === 'code_exec' ||
+        call.name === 'code_exec_wait'
+        ? await scope.recentImages()
+        : undefined;
     scope.assertLive();
     signal.throwIfAborted();
     const assertSessionLive = scope.assertLive;
@@ -52,7 +58,10 @@ export async function createRoundToolRuntimeContext(scope, call, signal) {
                     }
                 }),
             invoke: createCodeToolDispatch({
-                context: scope.captureCodeContext(),
+                context: {
+                    ...scope.captureCodeContext(),
+                    ...(recentImages === undefined ? {} : { recentImages })
+                },
                 tools: scope.tools,
                 expectations: scope.expectations,
                 parentCallId: call.callId,
@@ -61,7 +70,9 @@ export async function createRoundToolRuntimeContext(scope, call, signal) {
                 emit: (event) => emitCodeEvent(event, assertDispatchLive)
             })
         },
-        ...(scope.extensionToolNames.has(call.name) ? { recentImages: scope.recentImages() } : {})
+        ...(scope.extensionToolNames.has(call.name) && recentImages !== undefined
+            ? { recentImages }
+            : {})
     };
 }
 /** Complete every call in model order even if individual execution fails. */
@@ -84,9 +95,19 @@ export async function executeRoundTools(calls, scope) {
                 signal.throwIfAborted();
                 return executeRegisteredTool(call.name, call.arguments, call.callId, context);
             };
-            const output = call.name === 'code_exec' || call.name === 'code_exec_wait'
+            const rawOutput = call.name === 'code_exec' || call.name === 'code_exec_wait'
                 ? await runTool()
                 : await scope.schedule(scope.tools.find((tool) => tool.name === call.name), runTool);
+            const publishedImages = await publishModelResources(scope.context.host, rawOutput.images, {
+                sessionId: scope.context.sessionId,
+                executionId: scope.context.executionId
+            }, scope.context.imageStore);
+            const output = publishedImages === rawOutput.images
+                ? rawOutput
+                : {
+                    ...rawOutput,
+                    ...(publishedImages === undefined ? {} : { images: publishedImages })
+                };
             const modelOutput = boundedModelToolOutput(call.name, output.content, output.data);
             const eventSummary = toolEventSummary(output.content);
             const structuredData = structuredToolEventData(call.name, output.data);
@@ -106,6 +127,7 @@ export async function executeRoundTools(calls, scope) {
                 call,
                 output,
                 content: modelOutput.content,
+                ...(rawOutput.images?.length ? { sourceImages: rawOutput.images } : {}),
                 ...(output.calls
                     ? { calls: output.calls.map(({ resultExtensions: _evidence, ...call }) => call) }
                     : {}),
@@ -116,7 +138,11 @@ export async function executeRoundTools(calls, scope) {
         }
         catch (error) {
             const diagnostic = describeMarAgentError(error, 'MAR_AGENT_HOST_OPERATION_FAILED');
-            const partial = error instanceof CodeCellExecutionError ? error.result : undefined;
+            const partialResult = error instanceof CodeCellExecutionError ? error.result : undefined;
+            const publishedPartialImages = await publishModelResources(scope.context.host, partialResult?.images, { sessionId: scope.context.sessionId, executionId: scope.context.executionId }, scope.context.imageStore);
+            const partial = partialResult !== undefined && publishedPartialImages !== partialResult.images
+                ? { ...partialResult, images: publishedPartialImages }
+                : partialResult;
             const failureData = structuredToolFailureData(call.name, error);
             const eventData = failureData ??
                 (partial?.data === undefined
@@ -151,6 +177,7 @@ export async function executeRoundTools(calls, scope) {
                     }), failureData).content
                     : boundedModelToolOutput(call.name, partial.content, partial.data).content,
                 ...(partial?.images?.length ? { images: partial.images } : {}),
+                ...(partialResult?.images?.length ? { sourceImages: partialResult.images } : {}),
                 failed: true,
                 ...(partial?.calls
                     ? { calls: partial.calls.map(({ resultExtensions: _evidence, ...call }) => call) }

package/dist/agent-core/tools/input-diagnostics/source-preview.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Preview only the submitted line around a one-based Unicode character column.
+ * Escape controls and measure rendered graphemes, not source columns, for the caret.
+ * @param {string} source
+ * @param {number} column
+ */
+export function sourcePreview(source: string, column: number): {
+    text: string;
+    caret: number;
+};

package/dist/agent-core/tools/input-diagnostics/source-preview.js

@@ -0,0 +1,64 @@
+/**
+ * Preview only the submitted line around a one-based Unicode character column.
+ * Escape controls and measure rendered graphemes, not source columns, for the caret.
+ * @param {string} source
+ * @param {number} column
+ */
+export function sourcePreview(source, column) {
+    const characters = Array.from(source);
+    const index = column - 1;
+    let before = '';
+    let start = index;
+    let width = 0;
+    while (start > 0) {
+        const token = displayCharacter(characters[start - 1]);
+        const candidate = token + before;
+        const size = displayWidth(candidate);
+        if (size > 60 || Array.from(candidate).length > 60)
+            break;
+        before = candidate;
+        width = size;
+        start--;
+    }
+    const prefix = start > 0 ? '… ' : '';
+    const caret = width + prefix.length;
+    let text = before;
+    let end = index;
+    while (end < characters.length) {
+        const token = displayCharacter(characters[end]);
+        const candidate = text + token;
+        if (displayWidth(candidate) > 156 || Array.from(candidate).length > 156)
+            break;
+        text = candidate;
+        end++;
+    }
+    return {
+        text: `${prefix}${text}${end < characters.length ? ' …' : ''}`,
+        caret
+    };
+}
+const graphemes = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
+function displayWidth(text) {
+    let width = 0;
+    for (const { segment } of graphemes.segment(text)) {
+        const base = segment.match(/[^\p{Mark}\p{Cf}]/u)?.[0];
+        if (base === undefined)
+            continue;
+        // Match conventional monospace cells: combining marks join their base and emoji occupy two.
+        width +=
+            /[\p{Emoji_Presentation}\ufe0f\u20e3]/u.test(segment) ||
+                /[\u1100-\u115f\u2329\u232a\u2e80-\ua4cf\uac00-\ud7a3\uf900-\ufaff\ufe10-\ufe19\ufe30-\ufe6f\uff01-\uff60\uffe0-\uffe6\u{20000}-\u{3fffd}]/u.test(base)
+                ? 2
+                : 1;
+    }
+    return width;
+}
+function displayCharacter(character) {
+    if (character === '\t')
+        return '    ';
+    if (/[\u0000-\u001f\u007f-\u009f\u2028\u2029\p{Bidi_Control}]/u.test(character)) {
+        const escaped = JSON.stringify(character).slice(1, -1);
+        return escaped === character ? `\\u{${character.codePointAt(0).toString(16)}}` : escaped;
+    }
+    return character;
+}

package/dist/agent-core/tools/local/apply-patch-parser.js

@@ -1,24 +1,13 @@
 import { isAbsolute, resolve } from 'node:path';
 import { MarAgentError } from '../../error.js';
 import { TOOL_EXECUTION_LIMITS } from '../execution-limits.js';
+import { sourcePreview } from '../input-diagnostics/source-preview.js';
 const beginMarker = '*** Begin Patch';
 const endMarker = '*** End Patch';
 const addHeader = '*** Add File: ';
 const updateHeader = '*** Update File: ';
 const deleteHeader = '*** Delete File: ';
 const moveHeader = '*** Move to: ';
-const syntaxTokens = [
-    `${beginMarker} ***`,
-    `${endMarker} ***`,
-    addHeader,
-    updateHeader,
-    deleteHeader,
-    moveHeader,
-    '@@ ',
-    '+',
-    '-',
-    ' '
-];
 export function parsePatch(patch) {
     if (typeof patch !== 'string')
         throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Patch must be a string.');
@@ -169,7 +158,7 @@ class FreeformPatchParser {
         const line = index + 1;
         const column = characterCount(source.slice(0, characterOffset)) + 1;
         const offset = this.#lineOffsets[index] + characterOffset;
-        const preview = syntaxPreview(source, characterOffset);
+        const preview = sourcePreview(source, column);
         const gutter = String(line);
         throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', `Patch syntax error at line ${line}, column ${column}: ${message}\n${gutter} | ${preview.text}\n${' '.repeat(gutter.length)} | ${' '.repeat(preview.caret)}^`, { details: { line, column, offset } });
     }
@@ -186,43 +175,3 @@ function characterCount(value) {
         count++;
     return count;
 }
-function syntaxPreview(source, characterOffset) {
-    // Only grammar tokens and one offending character are public; paths and file bodies are not.
-    const trimmed = source.trimStart();
-    const leading = source.length - trimmed.length;
-    const tokenLength = Math.max(...syntaxTokens.map((token) => commonPrefixLength(trimmed, token)));
-    const token = trimmed.slice(0, tokenLength);
-    if (characterOffset < leading) {
-        const before = characterOffset > 40 ? '… ' : displaySyntax(source.slice(0, characterOffset));
-        return {
-            text: `${before}${displayCharacter(source[characterOffset])}<content omitted>`,
-            caret: before.length
-        };
-    }
-    const prefix = leading > 40 ? '… ' : displaySyntax(source.slice(0, leading));
-    const syntaxEnd = leading + tokenLength;
-    if (characterOffset < syntaxEnd) {
-        return {
-            text: `${prefix}${token}${source.length > syntaxEnd ? '<content omitted>' : ''}`,
-            caret: prefix.length + characterOffset - leading
-        };
-    }
-    const gap = characterOffset > syntaxEnd ? '<content omitted>' : '';
-    const character = source.slice(characterOffset)[Symbol.iterator]().next().value;
-    const before = `${prefix}${token}${gap}`;
-    return {
-        text: `${before}${character === undefined ? '<end of line>' : displayCharacter(character)}${character !== undefined && source.length > characterOffset + character.length ? '<content omitted>' : ''}`,
-        caret: before.length
-    };
-}
-function displayCharacter(character) {
-    const point = character.codePointAt(0);
-    if (point >= 0x7f)
-        return `\\u{${point.toString(16)}}`;
-    return JSON.stringify(character).slice(1, -1);
-}
-function displaySyntax(value) {
-    return [...value]
-        .map((character) => (character === '\t' ? '    ' : displayCharacter(character)))
-        .join('');
-}

package/dist/agent-core/tools/local/apply-patch.js

@@ -11,7 +11,7 @@ export const applyPatchToolDefinition = {
     allowedCallers: ['direct', 'programmatic'],
     codeModeExposure: 'both',
     parallelSafety: 'serial',
-    description: `Preferred for precise, reviewable local edits. Do not batch all task files merely to reduce tool calls. Group only a few tightly coupled edits whose combined patch is quick to generate and review; split broad or independent work into successive bounded patches before composing them. Submit a raw *** Begin Patch / *** End Patch patch, each marker on its own line. Surrounding marker whitespace and an optional trailing *** are accepted; incomplete markers or extra text are rejected. Add File content lines, including blank lines, must start with +. Syntax errors include line/column and a bounded caret diagnostic with file content omitted. Supports Add File, Update File, Delete File, and Move to. Add File may replace an existing regular file, and Move to may replace an existing regular destination; duplicate operations on the same resolved path remain invalid. Update hunks accept @@ or @@ <change context>. Context-only hunks, including trailing hunks, and unchanged file sections are validated in order but are not written or reported as edits. The patch must include a change or move. Context is searched forward with Codex-style exact, whitespace-tolerant, then common Unicode punctuation-tolerant matching. Syntax and resolved paths are validated before writing, then file units are committed in order. Each file unit is atomic, and a Move keeps its source and destination atomic. On MAR_AGENT_PATCH_PARTIAL, earlier files remain applied; the error lists applied, failed, and pending paths, so retry only failed and pending paths. Existing file permissions, line endings, and final-newline state are preserved. Returns changed file paths and operations with per-file and total line counts when all units succeed. In Code Mode, the Promise resolves on success and rejects with code/message on failure; the returned envelope has data.files and data.totals, not an ok or success flag. Oversized patches are rejected without advertising defensive limits as recommended patch sizes. A first-unit MAR_AGENT_PATCH_CONFLICT applies nothing; hunk match conflicts identify the affected path and hunk so you can reread only that file before retrying.`,
+    description: `Preferred for precise, reviewable local edits. Do not batch all task files merely to reduce tool calls. Group only a few tightly coupled edits whose combined patch is quick to generate and review; split broad or independent work into successive bounded patches before composing them. Submit a raw *** Begin Patch / *** End Patch patch, each marker on its own line. Surrounding marker whitespace and an optional trailing *** are accepted; incomplete markers or extra text are rejected. Add File content lines, including blank lines, must start with +. Syntax errors include line/column and a bounded excerpt of the submitted patch with a caret at the error. Supports Add File, Update File, Delete File, and Move to. Add File may replace an existing regular file, and Move to may replace an existing regular destination; duplicate operations on the same resolved path remain invalid. Update hunks accept @@ or @@ <change context>. Context-only hunks, including trailing hunks, and unchanged file sections are validated in order but are not written or reported as edits. The patch must include a change or move. Context is searched forward with Codex-style exact, whitespace-tolerant, then common Unicode punctuation-tolerant matching. Syntax and resolved paths are validated before writing, then file units are committed in order. Each file unit is atomic, and a Move keeps its source and destination atomic. On MAR_AGENT_PATCH_PARTIAL, earlier files remain applied; the error lists applied, failed, and pending paths, so retry only failed and pending paths. Existing file permissions, line endings, and final-newline state are preserved. Returns changed file paths and operations with per-file and total line counts when all units succeed. In Code Mode, the Promise resolves on success and rejects with code/message on failure; the returned envelope has data.files and data.totals, not an ok or success flag. Oversized patches are rejected without advertising defensive limits as recommended patch sizes. A first-unit MAR_AGENT_PATCH_CONFLICT applies nothing; hunk match conflicts identify the affected path and hunk so you can reread only that file before retrying.`,
     inputMode: 'freeform',
     outputSchema: {
         type: 'object',

package/dist/agent-core/tools/local/image-processing.d.ts

@@ -0,0 +1,24 @@
+import type { ViewImageRegion, ViewImageResult } from '../contracts.js';
+export interface ImageResizeBounds {
+    maxWidth?: number;
+    maxHeight?: number;
+}
+export interface ImageMetadata {
+    width: number;
+    height: number;
+    pages: number;
+}
+export interface ProcessedImage {
+    bytes: Buffer;
+    width: number;
+    height: number;
+    mimeType: 'image/png';
+    sourceWidth?: number;
+    sourceHeight?: number;
+    region?: ViewImageRegion;
+}
+export declare function readImageMetadata(data: Buffer, mimeType: ViewImageResult['mimeType'], signal?: AbortSignal): Promise<ImageMetadata>;
+export declare function processImage(data: Buffer, metadata: ImageMetadata, options: {
+    region?: ViewImageRegion;
+    resize?: ImageResizeBounds;
+}, signal?: AbortSignal): Promise<ProcessedImage>;

package/dist/agent-core/tools/local/image-processing.js

@@ -0,0 +1,135 @@
+import { MarAgentError } from '../../error.js';
+import { TOOL_EXECUTION_LIMITS } from '../execution-limits.js';
+export async function readImageMetadata(data, mimeType, signal) {
+    throwIfAborted(signal);
+    try {
+        const sharp = await loadSharp();
+        const metadata = await sharp(data, {
+            failOn: 'warning',
+            limitInputPixels: TOOL_EXECUTION_LIMITS.viewImageMaxPixels,
+            pages: 1
+        }).metadata();
+        throwIfAborted(signal);
+        if (metadata.format !== expectedSharpFormat(mimeType) ||
+            !isPositiveSafeInteger(metadata.width) ||
+            !isPositiveSafeInteger(metadata.height))
+            return incompleteImage();
+        const width = metadata.autoOrient?.width ?? metadata.width;
+        const height = metadata.autoOrient?.height ?? metadata.height;
+        assertPixelLimit(width, height);
+        return { width, height, pages: metadata.pages ?? 1 };
+    }
+    catch (error) {
+        throwIfAborted(signal);
+        if (error instanceof MarAgentError)
+            throw error;
+        if (isPixelLimitError(error))
+            return imagePixelLimit();
+        return incompleteImage();
+    }
+}
+export async function processImage(data, metadata, options, signal) {
+    throwIfAborted(signal);
+    if (metadata.pages > 1)
+        throw new MarAgentError('MAR_AGENT_IMAGE_FORMAT_UNSUPPORTED', 'Animated images cannot be cropped or resized.');
+    const region = options.region;
+    const regionWidth = region?.width ?? metadata.width;
+    const regionHeight = region?.height ?? metadata.height;
+    const resize = options.resize;
+    try {
+        const sharp = await loadSharp();
+        const image = sharp(data, {
+            failOn: 'warning',
+            limitInputPixels: TOOL_EXECUTION_LIMITS.viewImageMaxPixels,
+            pages: 1,
+            autoOrient: true
+        });
+        if (region)
+            image.extract({
+                left: region.x,
+                top: region.y,
+                width: region.width,
+                height: region.height
+            });
+        if (resize) {
+            image.resize({
+                ...(resize.maxWidth === undefined ? {} : { width: Math.min(resize.maxWidth, regionWidth) }),
+                ...(resize.maxHeight === undefined
+                    ? {}
+                    : { height: Math.min(resize.maxHeight, regionHeight) }),
+                fit: 'inside',
+                withoutEnlargement: true
+            });
+        }
+        const output = await image.png().toBuffer({ resolveWithObject: true });
+        throwIfAborted(signal);
+        if (output.data.byteLength > TOOL_EXECUTION_LIMITS.viewImageMaxBytes)
+            throw imageOutputLimit();
+        const changedRegion = region !== undefined &&
+            (region.x !== 0 ||
+                region.y !== 0 ||
+                region.width !== metadata.width ||
+                region.height !== metadata.height);
+        const changedSize = output.info.width !== regionWidth || output.info.height !== regionHeight;
+        return {
+            bytes: output.data,
+            width: output.info.width,
+            height: output.info.height,
+            mimeType: 'image/png',
+            ...(changedRegion || changedSize
+                ? { sourceWidth: metadata.width, sourceHeight: metadata.height }
+                : {}),
+            ...(changedRegion ? { region } : {})
+        };
+    }
+    catch (error) {
+        throwIfAborted(signal);
+        if (error instanceof MarAgentError)
+            throw error;
+        if (isPixelLimitError(error))
+            return imagePixelLimit();
+        return incompleteImage();
+    }
+}
+function expectedSharpFormat(mimeType) {
+    switch (mimeType) {
+        case 'image/png':
+            return 'png';
+        case 'image/jpeg':
+            return 'jpeg';
+        case 'image/webp':
+            return 'webp';
+    }
+}
+function assertPixelLimit(width, height) {
+    if (!isPositiveSafeInteger(width) ||
+        !isPositiveSafeInteger(height) ||
+        width > Math.floor(TOOL_EXECUTION_LIMITS.viewImageMaxPixels / height))
+        imagePixelLimit();
+}
+function isPositiveSafeInteger(value) {
+    return Number.isSafeInteger(value) && value > 0;
+}
+function isPixelLimitError(error) {
+    return error instanceof Error && /pixel limit/iu.test(error.message);
+}
+function throwIfAborted(signal) {
+    signal?.throwIfAborted();
+}
+function imageOutputLimit() {
+    return new MarAgentError('MAR_AGENT_TOOL_OUTPUT_LIMIT', `Image output exceeds ${TOOL_EXECUTION_LIMITS.viewImageMaxBytes} bytes. Use a smaller resize or region.`);
+}
+function imagePixelLimit() {
+    throw new MarAgentError('MAR_AGENT_TOOL_OUTPUT_LIMIT', `Image exceeds the source pixel-area limit (equivalent to ${Math.sqrt(TOOL_EXECUTION_LIMITS.viewImageMaxPixels)}×${Math.sqrt(TOOL_EXECUTION_LIMITS.viewImageMaxPixels)} pixels).`);
+}
+function incompleteImage() {
+    throw new MarAgentError('MAR_AGENT_IMAGE_INCOMPLETE', 'Image file is incomplete, malformed, or changed while reading. Wait for the writer to finish and read it again.');
+}
+async function loadSharp() {
+    try {
+        return (await import('sharp')).default;
+    }
+    catch {
+        throw new MarAgentError('MAR_AGENT_IMAGE_PROCESSING_UNAVAILABLE', 'Native image processing is unavailable because the sharp dependency could not be loaded.');
+    }
+}

package/dist/agent-core/tools/local/read.js

@@ -289,7 +289,7 @@ function readKey(input) {
 }
 function readError(path, error) {
     if (error instanceof MarAgentError)
-        return { path, error: { code: error.code, message: error.message } };
+        return { path, error: { code: error.code, message: error.publicMessage } };
     const code = typeof error === 'object' && error !== null && 'code' in error && typeof error.code === 'string'
         ? error.code
         : 'MAR_AGENT_TOOL_FAILED';