@myagentroam/agent 0.11.32 → 0.11.34

package/dist/tools/local/exec.d.ts

@@ -0,0 +1,28 @@
+import type { ClientToolDefinition, ExecResult, ToolExecutionResult } from '../contracts.js';
+export type { ExecResult } from '../contracts.js';
+/** Share the model-facing body across direct calls and original Code Mode observations. */
+export declare function formatExecResult(result: ExecResult): ToolExecutionResult;
+export type ExecInput = {
+    action?: 'start';
+    command: string;
+    cwd?: string;
+    login?: boolean;
+    timeoutMs?: number;
+    yieldMs?: number;
+} | {
+    action: 'poll';
+    processId: string;
+    yieldMs?: number;
+} | {
+    action: 'write';
+    processId: string;
+    data: string;
+} | {
+    action: 'cancel';
+    processId: string;
+};
+export declare const execToolDefinition: ClientToolDefinition;
+export declare const execWaitToolDefinition: ClientToolDefinition;
+/** Validate the public entry points before delegating to the single process manager. */
+export declare function execToolInput(name: 'exec' | 'exec_wait', value: unknown): ExecInput;
+export declare function parseExecInput(value: unknown): ExecInput;

package/dist/tools/local/exec.js

@@ -0,0 +1,194 @@
+import { AgentError } from '../../error.js';
+import { TOOL_EXECUTION_LIMITS } from '../execution-limits.js';
+/** Share the model-facing body across direct calls and original Code Mode observations. */
+export function formatExecResult(result) {
+    const visible = { ...result };
+    if (result.stderr === '')
+        delete visible.stderr;
+    if (!result.truncated) {
+        delete visible.truncated;
+        // Incremental output may be smaller than the cumulative stream counts.
+        if (result.stdoutBytes === Buffer.byteLength(result.stdout))
+            delete visible.stdoutBytes;
+        if (result.stderrBytes === Buffer.byteLength(result.stderr))
+            delete visible.stderrBytes;
+    }
+    if (result.stdoutDroppedBytes === 0)
+        delete visible.stdoutDroppedBytes;
+    if (result.stderrDroppedBytes === 0)
+        delete visible.stderrDroppedBytes;
+    if (result.cached === false)
+        delete visible.cached;
+    return { content: JSON.stringify(visible), data: result, truncated: result.truncated };
+}
+export const execToolDefinition = {
+    name: 'exec',
+    allowedCallers: ['direct', 'programmatic'],
+    parallelSafety: 'safe',
+    description: 'Start a platform-native command, script, or program in workspace/default cwd. Returns a stable processId (p_ plus 12 lowercase hex characters), status, bounded stdout/stderr, cumulative byte counts, dropped-byte counts, exitCode and truncated. A completed status does not imply exitCode 0; inspect stderr/exitCode. For subsequent waiting, stdin writes or cancellation, call exec_wait directly with processId, not exec. Truncation does not stop the process. Cancelling the initial wait does not terminate the process. waitOutcome distinguishes snapshot, completion, and timeout. A foreground wait may return interrupted with reason=steer; the process keeps running.',
+    outputSchema: {
+        type: 'object',
+        required: ['content', 'data'],
+        properties: {
+            content: { type: 'string' },
+            data: {
+                type: 'object',
+                required: [
+                    'status',
+                    'stdout',
+                    'stderr',
+                    'truncated',
+                    'stdoutBytes',
+                    'stderrBytes',
+                    'stdoutDroppedBytes',
+                    'stderrDroppedBytes'
+                ],
+                properties: {
+                    status: { enum: ['running', 'completed', 'cancelled'] },
+                    waitOutcome: { enum: ['snapshot', 'completion', 'timeout', 'yield', 'interrupted'] },
+                    reason: { enum: ['steer'] },
+                    processId: { type: 'string' },
+                    stdout: { type: 'string' },
+                    stderr: { type: 'string' },
+                    exitCode: { type: ['number', 'null'] },
+                    truncated: { type: 'boolean' },
+                    stdoutBytes: { type: 'number' },
+                    stderrBytes: { type: 'number' },
+                    stdoutDroppedBytes: { type: 'number' },
+                    stderrDroppedBytes: { type: 'number' },
+                    cached: { type: 'boolean' }
+                }
+            }
+        }
+    },
+    inputSchema: {
+        type: 'object',
+        properties: {
+            command: {
+                type: 'string',
+                description: 'Platform-native command to start.'
+            },
+            cwd: {
+                type: 'string',
+                description: 'Optional relative/absolute start directory; defaults to workspace. Command-internal relative paths resolve from this directory.'
+            },
+            login: {
+                type: 'boolean',
+                default: true,
+                description: 'Use the Shell login/profile initialization. Defaults to true; false skips login startup. Does not force an interactive Shell.'
+            },
+            timeoutMs: {
+                type: 'integer',
+                minimum: 1,
+                maximum: TOOL_EXECUTION_LIMITS.execMaxTimeoutMs,
+                description: 'Optional process lifetime limit in milliseconds. Omitted means no process timeout; yieldMs only controls waiting.'
+            },
+            yieldMs: {
+                type: 'integer',
+                minimum: 0,
+                maximum: TOOL_EXECUTION_LIMITS.execMaxYieldMs,
+                default: TOOL_EXECUTION_LIMITS.execDefaultYieldMs,
+                description: `Wait before yielding output. Defaults to ${TOOL_EXECUTION_LIMITS.execDefaultYieldMs} ms. Maximum ${TOOL_EXECUTION_LIMITS.execMaxYieldMs} ms. Zero returns immediately. This does not extend the process timeout.`
+            }
+        },
+        required: ['command'],
+        additionalProperties: false
+    }
+};
+export const execWaitToolDefinition = {
+    name: 'exec_wait',
+    allowedCallers: ['direct', 'programmatic'],
+    parallelSafety: 'safe',
+    description: 'Wait for or control a managed process by processId. action defaults to poll: collect output until termination or the wait window ends, then return incremental stdout/stderr. New output does not end the wait. write sends data to stdin; cancel terminates the process or removes its cached result. Terminal polls return a bounded snapshot marked cached for up to five minutes. Cancelling a wait does not terminate the process. Uses the same Session-owned processes as exec; cannot start a process or extend its timeout. Inspect stderr/exitCode; completed does not imply success. Supports direct and programmatic calls; in Code Mode use tools.exec_wait. Poll results include waitOutcome; interrupted with reason=steer ends only a foreground wait, never the process.',
+    outputSchema: execToolDefinition.outputSchema,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            processId: {
+                type: 'string',
+                minLength: 1,
+                description: 'Copy the complete processId returned by exec (p_ followed by 12 lowercase hex characters). Never use a cellId (c_); use code_exec_wait for cells.'
+            },
+            action: { enum: ['poll', 'write', 'cancel'], default: 'poll' },
+            yieldMs: {
+                type: 'integer',
+                minimum: 0,
+                maximum: TOOL_EXECUTION_LIMITS.execMaxPollYieldMs,
+                default: TOOL_EXECUTION_LIMITS.execDefaultYieldMs,
+                description: `Poll wait window in milliseconds; default ${TOOL_EXECUTION_LIMITS.execDefaultYieldMs}, maximum ${TOOL_EXECUTION_LIMITS.execMaxPollYieldMs}. Zero returns immediately. Not a process timeout.`
+            },
+            data: { type: 'string', description: 'Required stdin data for write.' }
+        },
+        required: ['processId'],
+        additionalProperties: false
+    }
+};
+/** Validate the public entry points before delegating to the single process manager. */
+export function execToolInput(name, value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return invalidExecInput();
+    const input = value;
+    const allowed = name === 'exec'
+        ? ['command', 'cwd', 'login', 'timeoutMs', 'yieldMs']
+        : ['processId', 'action', 'yieldMs', 'data'];
+    if (Object.keys(input).some((key) => !allowed.includes(key)))
+        return invalidExecInput();
+    if (name === 'exec')
+        return parseExecInput(input);
+    const action = input.action ?? 'poll';
+    if (!['poll', 'write', 'cancel'].includes(String(action)))
+        return invalidExecInput();
+    return parseExecInput({ ...input, action });
+}
+export function parseExecInput(value) {
+    if (!value || typeof value !== 'object')
+        return invalidExecInput();
+    const input = value;
+    const action = input.action == null && typeof input.command === 'string' ? 'start' : input.action;
+    if (!['start', 'poll', 'write', 'cancel'].includes(String(action)))
+        return invalidExecInput();
+    const yieldMs = optionalBoundedInteger(input.yieldMs, 0, action === 'poll'
+        ? TOOL_EXECUTION_LIMITS.execMaxPollYieldMs
+        : TOOL_EXECUTION_LIMITS.execMaxYieldMs);
+    if (action === 'start') {
+        if (typeof input.command !== 'string' || input.command.trim() === '')
+            return invalidExecInput();
+        if (input.cwd !== undefined && input.cwd !== null && typeof input.cwd !== 'string')
+            return invalidExecInput();
+        if (input.login !== undefined && input.login !== null && typeof input.login !== 'boolean')
+            return invalidExecInput();
+        const timeoutMs = optionalBoundedInteger(input.timeoutMs, 1, TOOL_EXECUTION_LIMITS.execMaxTimeoutMs);
+        return {
+            ...(input.action === 'start' ? { action: 'start' } : {}),
+            command: input.command,
+            ...(typeof input.cwd === 'string' ? { cwd: input.cwd } : {}),
+            ...(typeof input.login === 'boolean' ? { login: input.login } : {}),
+            ...(timeoutMs === undefined ? {} : { timeoutMs }),
+            ...(yieldMs === undefined ? {} : { yieldMs })
+        };
+    }
+    if (typeof input.processId !== 'string' || input.processId === '')
+        return invalidExecInput();
+    if (action === 'poll')
+        return {
+            action,
+            processId: input.processId,
+            yieldMs: yieldMs ?? TOOL_EXECUTION_LIMITS.execDefaultYieldMs
+        };
+    if (action === 'write') {
+        if (typeof input.data !== 'string')
+            return invalidExecInput();
+        return { action, processId: input.processId, data: input.data };
+    }
+    return { action: 'cancel', processId: input.processId };
+}
+function optionalBoundedInteger(value, minimum, maximum) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (!Number.isInteger(value) || value < minimum)
+        invalidExecInput();
+    return Math.min(value, maximum);
+}
+function invalidExecInput() {
+    throw new AgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Exec input is invalid.');
+}

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

@@ -0,0 +1,146 @@
+import { AgentError } 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, mimeType };
+    }
+    catch (error) {
+        throwIfAborted(signal);
+        if (error instanceof AgentError)
+            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 AgentError('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
+            });
+        }
+        switch (metadata.mimeType) {
+            case 'image/png':
+                image.png();
+                break;
+            case 'image/jpeg':
+                image.jpeg({ quality: 90 });
+                break;
+            case 'image/webp':
+                image.webp({ quality: 90 });
+                break;
+        }
+        const output = await image.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: metadata.mimeType,
+            ...(changedRegion || changedSize
+                ? { sourceWidth: metadata.width, sourceHeight: metadata.height }
+                : {}),
+            ...(changedRegion ? { region } : {})
+        };
+    }
+    catch (error) {
+        throwIfAborted(signal);
+        if (error instanceof AgentError)
+            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 AgentError('MAR_AGENT_TOOL_OUTPUT_LIMIT', `Image output exceeds ${TOOL_EXECUTION_LIMITS.viewImageMaxBytes} bytes. Use a smaller resize or region.`);
+}
+function imagePixelLimit() {
+    throw new AgentError('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 AgentError('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 AgentError('MAR_AGENT_IMAGE_PROCESSING_UNAVAILABLE', 'Native image processing is unavailable because the sharp dependency could not be loaded.');
+    }
+}

package/dist/tools/local/read.d.ts

@@ -0,0 +1,43 @@
+import type { ClientToolDefinition } from '../contracts.js';
+import { WorkspacePathResolver } from '../shared/path-resolver.js';
+export type { ReadEventData } from '../contracts.js';
+export declare const readToolDefinition: ClientToolDefinition;
+export interface ReadRequest {
+    path: string;
+    offset?: number;
+    limit?: number;
+}
+export interface ReadResult {
+    path: string;
+    content: string;
+    text: string;
+    encoding: 'utf-8' | 'utf-16le' | 'utf-16be';
+    newline: 'crlf' | 'lf';
+    startLine: number;
+    endLine?: number;
+    eof: boolean;
+    truncated: boolean;
+    nextOffset?: number;
+}
+export interface ReadErrorResult {
+    path: string;
+    error: {
+        code: string;
+        message: string;
+    };
+}
+export interface BatchReadResult {
+    mode: 'batch';
+    results: Array<ReadResult | ReadErrorResult>;
+    truncated: boolean;
+}
+export declare class ReadTool {
+    #private;
+    private readonly paths;
+    constructor(paths: WorkspacePathResolver);
+    execute(arguments_: unknown, signal?: AbortSignal): Promise<BatchReadResult>;
+}
+export declare function formatBatchReadOutput(results: Array<ReadResult | ReadErrorResult>): {
+    content: string;
+    truncated: boolean;
+};