@qwen-code/arena-agent 0.0.10-dev.0 → 0.0.10-dev.10

package/dist/tools.js

@@ -1,6 +1,6 @@
 import { spawn } from "node:child_process";
-import { existsSync, mkdirSync, realpathSync, } from "node:fs";
-import { open, readFile, realpath, stat, writeFile, } from "node:fs/promises";
+import { copyFileSync, existsSync, mkdirSync, realpathSync } from "node:fs";
+import { open, readFile, realpath, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { Ajv } from "ajv";
 import addFormats from "ajv-formats";
@@ -13,15 +13,30 @@ import { CodeToolExecutor } from "./code-tools.js";
 import { supportsImageInput } from "./config.js";
 import { extractStructuredDocument, isStructuredDocument, } from "./document-reader.js";
 import { FetchPageReader } from "./fetch-page.js";
+import { replaceFirstText } from "./file-edit.js";
 import { generatedImageBytesForExtension, prepareImageForModel, } from "./image.js";
 import { imageTextFromFallbackModel } from "./image-input-fallback.js";
 import { isCodeArenaMode } from "./mode.js";
 import { generateImageWithModelRouter, generateSpeechWithModelRouter, } from "./model-router-media.js";
 import { processManagerForWorkspace, } from "./process-manager.js";
 import { HttpModelClient } from "./provider.js";
+import { replayResponseFor, } from "./replay-responses.js";
 import { RoutifyFetchPageReader, routifyWebFetchEnabled, } from "./routify-web-fetch.js";
 import { toolDefinitions } from "./spec.js";
+import { createSandboxFile, privilegedFileCreationEnabled } from "./sandbox-file-write.js";
 import { voiceRegistryForWorkspace, } from "./voice-registry.js";
+export function imageInputFallbackConnection(config) {
+    if (!config.imageInputFallbackBaseUrl &&
+        !config.imageInputFallbackApiKey &&
+        !config.imageInputFallbackProtocol) {
+        return undefined;
+    }
+    return {
+        baseUrl: config.imageInputFallbackBaseUrl,
+        apiKey: config.imageInputFallbackApiKey,
+        protocol: config.imageInputFallbackProtocol,
+    };
+}
 const knownTextApplicationMimeTypes = new Set([
     "application/ecmascript",
     "application/javascript",
@@ -202,7 +217,7 @@ const visualIntroText = "<arena-system-message>\n" +
     "treat them as the authentic output of the tool call.\n" +
     "</arena-system-message>";
 const bashOutputLimit = 20_000;
-const textFileByteLimit = 256 * 1024;
+const textFileOutputByteLimit = 256 * 1024;
 const toolResultCharacterLimit = 1_000_000;
 // 中段截断，逐字反推自 3 个 truncated:true 参考样本：头尾各 9987 字符 +
 // 26 字符标记，总长恰 20000（由 T1(b) 执行回放发现，非首段截断）。
@@ -216,6 +231,39 @@ function capBashOutput(value) {
         truncated: true,
     };
 }
+class BashOutputBuffer {
+    text = "";
+    truncated = false;
+    append(chunk) {
+        // Once capped, text still contains the original prefix and latest suffix.
+        // Capping again after an append therefore preserves the same head/tail as
+        // capping the full stream, without ever retaining the discarded middle.
+        const output = capBashOutput(this.text + chunk.toString("utf8"));
+        this.text = output.text;
+        this.truncated ||= output.truncated;
+    }
+    result() {
+        return { text: this.text, truncated: this.truncated };
+    }
+}
+function readTextResult(data) {
+    if (data.length <= textFileOutputByteLimit) {
+        return { content: decodeText(data), truncated: false };
+    }
+    const half = textFileOutputByteLimit / 2;
+    const prefixBreak = data.lastIndexOf(0x0a, half);
+    const suffixBreak = data.indexOf(0x0a, data.length - half);
+    const prefixEnd = prefixBreak === -1 ? half : prefixBreak;
+    const suffixStart = suffixBreak === -1 ? data.length - half : suffixBreak + 1;
+    const elidedBytes = Math.max(0, suffixStart - prefixEnd);
+    const marker = `\n\n[${Math.round(elidedBytes / 1024)} KB elided from the middle of the file]\n\n`;
+    return {
+        content: decodeText(data.subarray(0, prefixEnd)) +
+            marker +
+            decodeText(data.subarray(suffixStart)),
+        truncated: true,
+    };
+}
 const mimeTypes = {
     ".aac": "audio/aac",
     ".bmp": "image/bmp",
@@ -269,8 +317,7 @@ function decodeUtf32(data, littleEndian) {
         const codePoint = littleEndian
             ? data.readUInt32LE(index)
             : data.readUInt32BE(index);
-        characters.push(codePoint <= 0x10ffff &&
-            !(codePoint >= 0xd800 && codePoint <= 0xdfff)
+        characters.push(codePoint <= 0x10ffff && !(codePoint >= 0xd800 && codePoint <= 0xdfff)
             ? String.fromCodePoint(codePoint)
             : "\ufffd");
     }
@@ -349,6 +396,182 @@ function json(value) {
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
+function jsonPointerPath(instancePath) {
+    if (!instancePath)
+        return [];
+    return instancePath
+        .slice(1)
+        .split("/")
+        .map((part) => part.replace(/~1/g, "/").replace(/~0/g, "~"))
+        .map((part) => (/^(0|[1-9]\d*)$/.test(part) ? Number(part) : part));
+}
+function valueAtPath(value, pathParts) {
+    let current = value;
+    for (const part of pathParts) {
+        if (current === null || typeof current !== "object")
+            return undefined;
+        current = current[part];
+    }
+    return current;
+}
+function zodTypeName(type) {
+    return type === "integer" ? "number" : type;
+}
+function receivedType(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    return typeof value;
+}
+function arenaEnumIssue(values, pathParts) {
+    return {
+        code: "invalid_value", values, path: pathParts,
+        message: `Invalid option: expected one of ${values.map((item) => JSON.stringify(item)).join("|")}`,
+    };
+}
+function arenaValidationIssue(error, value) {
+    const pathParts = jsonPointerPath(error.instancePath);
+    if (error.keyword === "required") {
+        const missingProperty = String(error.params.missingProperty);
+        const parentSchema = error.parentSchema;
+        const missingSchema = parentSchema?.properties?.[missingProperty];
+        if (missingSchema?.enum) {
+            return arenaEnumIssue(missingSchema.enum, [...pathParts, missingProperty]);
+        }
+        const expected = zodTypeName(missingSchema?.type || "unknown");
+        return {
+            expected,
+            code: "invalid_type",
+            path: [...pathParts, missingProperty],
+            message: `Invalid input: expected ${expected}, received undefined`,
+        };
+    }
+    if (error.keyword === "type") {
+        const expected = zodTypeName(String(error.params.type));
+        return {
+            expected,
+            code: "invalid_type",
+            path: pathParts,
+            message: `Invalid input: expected ${expected}, received ` +
+                receivedType(valueAtPath(value, pathParts)),
+        };
+    }
+    if (error.keyword === "maxLength" || error.keyword === "minLength") {
+        const tooBig = error.keyword === "maxLength";
+        const limitKey = tooBig ? "maximum" : "minimum";
+        const limit = Number(error.params.limit);
+        return {
+            origin: "string",
+            code: tooBig ? "too_big" : "too_small",
+            [limitKey]: limit,
+            inclusive: true,
+            path: pathParts,
+            message: `${tooBig ? "Too big" : "Too small"}: expected string to have ` +
+                `${tooBig ? "<=" : ">="}${limit} characters`,
+        };
+    }
+    if (error.keyword === "maximum" || error.keyword === "minimum") {
+        const tooBig = error.keyword === "maximum";
+        const limitKey = tooBig ? "maximum" : "minimum";
+        const limit = Number(error.params.limit);
+        return {
+            origin: "number",
+            code: tooBig ? "too_big" : "too_small",
+            [limitKey]: limit,
+            inclusive: true,
+            path: pathParts,
+            message: `${tooBig ? "Too big" : "Too small"}: expected number to be ` +
+                `${tooBig ? "<=" : ">="}${limit}`,
+        };
+    }
+    if (error.keyword === "maxItems" || error.keyword === "minItems") {
+        const tooBig = error.keyword === "maxItems";
+        const limitKey = tooBig ? "maximum" : "minimum";
+        const limit = Number(error.params.limit);
+        return {
+            origin: "array",
+            code: tooBig ? "too_big" : "too_small",
+            [limitKey]: limit,
+            inclusive: true,
+            path: pathParts,
+            message: `${tooBig ? "Too big" : "Too small"}: expected array to have ` +
+                `${tooBig ? "<=" : ">="}${limit} items`,
+        };
+    }
+    if (error.keyword === "enum") {
+        return arenaEnumIssue(error.params.allowedValues, pathParts);
+    }
+    if (error.keyword === "format") {
+        return {
+            ...(error.params.format === "uri" ? {} : { origin: "string" }),
+            code: "invalid_format",
+            format: error.params.format === "uri" ? "url" : error.params.format,
+            path: pathParts,
+            message: error.params.format === "uri" ? "Invalid URL" : "Invalid string",
+        };
+    }
+    return {
+        code: "custom",
+        path: pathParts,
+        message: error.message || "Invalid input",
+    };
+}
+function arenaValidationIssues(error, value) {
+    const issues = [arenaValidationIssue(error, value)];
+    if (error.keyword !== "type" || error.params.type !== "array")
+        return issues;
+    const pathParts = jsonPointerPath(error.instancePath);
+    const received = valueAtPath(value, pathParts);
+    if (typeof received !== "string")
+        return issues;
+    const parentSchema = error.parentSchema;
+    const maximum = parentSchema?.maxItems;
+    if (typeof maximum === "number" && received.length > maximum) {
+        issues.push({
+            origin: "string",
+            code: "too_big",
+            maximum,
+            inclusive: true,
+            path: pathParts,
+            message: `Too big: expected string to have <=${maximum} characters`,
+        });
+    }
+    const minimum = parentSchema?.minItems;
+    if (typeof minimum === "number" && received.length < minimum) {
+        issues.push({
+            origin: "string",
+            code: "too_small",
+            minimum,
+            inclusive: true,
+            path: pathParts,
+            message: `Too small: expected string to have >=${minimum} characters`,
+        });
+    }
+    return issues;
+}
+function arenaValidationError(toolName, value, errors, customIssues = []) {
+    const issues = (errors || []).flatMap((error) => arenaValidationIssues(error, value)).concat(customIssues);
+    return (`Invalid input for tool ${toolName}: Type validation failed: Value: ` +
+        `${JSON.stringify(value)}.\nError message: ${JSON.stringify(issues, null, 2)}`);
+}
+function arenaJsonParsingError(toolName, text, error) {
+    return (`Invalid input for tool ${toolName}: JSON parsing failed: Text: ${text}.\n` +
+        `Error message: ${errorMessage(error)}`);
+}
+function unavailableToolError(toolName, availableToolNames) {
+    return (`Model tried to call unavailable tool '${toolName}'. Available tools: ` +
+        `${[...availableToolNames, "compact"].join(", ")}.`);
+}
+function prefixedFailure(prefix, message) {
+    return message.startsWith(prefix) ? message : `${prefix}${message}`;
+}
+function fetchPageFailure(message) {
+    const status = message.match(/(?:fetch_page|Firecrawl|Jina Reader) failed \((\d{3})\b/i)?.[1];
+    return status
+        ? `Failed to fetch page (HTTP ${status})`
+        : "Failed to fetch page";
+}
 function displayByteSize(value) {
     if (value >= 1024 * 1024) {
         return `${(value / (1024 * 1024)).toFixed(1)} MB`;
@@ -374,17 +597,27 @@ class ArenaToolExecutor {
     config;
     workspace;
     workspaceReal;
+    tmpReal;
+    varTmpReal;
     validators = new Map();
     pendingVisualContent = new Map();
     askUserHandler;
     imageInputFallbackClient;
     signal;
     workspaceContext;
+    nativeSandboxPaths;
     pageReader;
     routifyPageReader;
     processManager;
     voiceRegistry;
-    ajv = new Ajv({ allErrors: true, strict: false });
+    ajv = new Ajv({
+        allErrors: true,
+        strict: false,
+        verbose: true,
+        // The captured runtime uses Zod object parsing: unknown object keys are
+        // stripped before dispatch instead of being emitted as validation issues.
+        removeAdditional: "all",
+    });
     // ask_user needs a handler: TUI/WebUI collect real user input, while
     // headless `-p` may delegate to a configured remote User Agent. add_voice
     // remains available without one and deterministically registers a fallback.
@@ -394,13 +627,24 @@ class ArenaToolExecutor {
         this.workspace = path.resolve(config.workspace);
         mkdirSync(this.workspace, { recursive: true });
         this.workspaceReal = realpathSync(this.workspace);
+        // A Linux /home/user workspace is already an OS-level sandbox. Other
+        // callers still confine ordinary workspace paths, while /tmp and /var/tmp
+        // always refer to the actual system directories seen by Bash.
+        this.nativeSandboxPaths =
+            process.platform === "linux" && this.workspaceReal === "/home/user";
+        this.tmpReal = realpathSync("/tmp");
+        this.varTmpReal = realpathSync("/var/tmp");
         this.processManager = processManagerForWorkspace(this.workspaceReal);
         this.voiceRegistry = voiceRegistryForWorkspace(this.workspaceReal);
         this.askUserHandler = options.askUserHandler;
         this.askUserEnabled = Boolean(options.askUserHandler);
         if (config.imageInputFallbackModel?.trim()) {
+            const connection = imageInputFallbackConnection(config);
             this.imageInputFallbackClient =
-                options.modelClient || new HttpModelClient(config);
+                options.imageInputFallbackClient ||
+                    (connection
+                        ? new HttpModelClient(config, { connection })
+                        : options.modelClient || new HttpModelClient(config));
         }
         this.signal = options.signal;
         this.workspaceContext = options.workspaceContext;
@@ -409,6 +653,13 @@ class ArenaToolExecutor {
             signal: options.signal,
         });
         addFormats(this.ajv);
+        // WHATWG URL parsing matches the captured fetch_page behavior. ajv-formats'
+        // RFC URI checker rejects a recorded URL containing `|` in its query even
+        // though Arena accepted and fetched it successfully.
+        this.ajv.addFormat("uri", {
+            type: "string",
+            validate: (value) => URL.canParse(value),
+        });
         for (const definition of toolDefinitions(this.workspaceContext)) {
             this.validators.set(definition.function.name, this.ajv.compile(definition.function.parameters));
         }
@@ -424,6 +675,102 @@ class ArenaToolExecutor {
         const disallowed = new Set(this.config.disallowedTools || []);
         return definitions.filter((definition) => !disallowed.has(definition.function.name));
     }
+    parseArguments(call) {
+        const rawArguments = typeof call.function?.arguments === "string"
+            ? call.function.arguments
+            : "{}";
+        let value;
+        try {
+            // Captured empty arguments validate as an empty object, while whitespace
+            // and other incomplete JSON still produce parsing errors.
+            value = JSON.parse(rawArguments === "" ? "{}" : rawArguments);
+        }
+        catch (error) {
+            return { rawArguments, invalidJsonText: rawArguments, error };
+        }
+        const malformedArguments = value !== null && typeof value === "object" && !Array.isArray(value)
+            ? value.__malformedToolArguments
+            : undefined;
+        if (typeof malformedArguments === "string") {
+            if (malformedArguments === "")
+                return { rawArguments, value: {} };
+            try {
+                JSON.parse(malformedArguments);
+            }
+            catch (error) {
+                return { rawArguments, invalidJsonText: malformedArguments, error };
+            }
+        }
+        return { rawArguments, value };
+    }
+    validateArguments(name, value, validate) {
+        const validatedArguments = structuredClone(value);
+        if (!validate(validatedArguments)) {
+            return {
+                validationMessage: arenaValidationError(name, value, validate.errors),
+            };
+        }
+        if (name === "ask_user") {
+            const issues = validatedArguments.questions.flatMap((question, index) => {
+                const ids = question.options.map((option) => option.id);
+                return new Set(ids).size === ids.length ? [] : [{
+                        code: "custom", path: ["questions", index, "options"],
+                        message: "Option IDs must be unique within a question",
+                    }];
+            });
+            if (issues.length)
+                return { validationMessage: arenaValidationError(name, value, [], issues) };
+        }
+        return { value: validatedArguments };
+    }
+    inspect(call) {
+        const id = String(call.id || "");
+        const name = String(call.function?.name || "");
+        const originalRawArguments = typeof call.function?.arguments === "string"
+            ? call.function.arguments
+            : "{}";
+        const parsed = this.parseArguments(call);
+        const validate = this.validators.get(name);
+        if (this.config.disallowedTools?.includes(name) || !validate) {
+            return {
+                id,
+                name,
+                rawArguments: originalRawArguments,
+                ...(parsed.error === undefined ? { arguments: parsed.value } : {}),
+                validation: "unknown_tool",
+                validationMessage: this.config.disallowedTools?.includes(name)
+                    ? `tool is disallowed: ${name}`
+                    : unavailableToolError(name, toolDefinitions(this.workspaceContext).map((definition) => definition.function.name)),
+            };
+        }
+        if (parsed.error !== undefined) {
+            return {
+                id,
+                name,
+                rawArguments: parsed.rawArguments,
+                validation: "invalid_json",
+                validationMessage: arenaJsonParsingError(name, parsed.invalidJsonText, parsed.error),
+            };
+        }
+        const validated = this.validateArguments(name, parsed.value, validate);
+        if (validated.validationMessage !== undefined) {
+            return {
+                id,
+                name,
+                rawArguments: parsed.rawArguments,
+                arguments: parsed.value,
+                validation: "invalid_arguments",
+                validationMessage: validated.validationMessage,
+            };
+        }
+        return {
+            id,
+            name,
+            rawArguments: parsed.rawArguments,
+            arguments: parsed.value,
+            validation: "valid",
+        };
+    }
     async execute(call, context) {
         const callId = String(call.id || "");
         const name = String(call.function?.name || "");
@@ -431,23 +778,91 @@ class ArenaToolExecutor {
         try {
             // 监听器不会补发已发生的 abort：已取消的 signal 必须在产生任何副作用
             // 之前短路，否则命令会照常 spawn 直到自然结束。
-            this.signal?.throwIfAborted();
+            if (this.signal?.aborted) {
+                return {
+                    role: "tool",
+                    tool_call_id: callId,
+                    content: json({ status: "aborted" }),
+                };
+            }
             if (this.config.disallowedTools?.includes(name)) {
                 throw new Error(`tool is disallowed: ${name}`);
             }
-            const argumentsValue = JSON.parse(typeof call.function?.arguments === "string"
-                ? call.function.arguments
-                : "{}");
             const validate = this.validators.get(name);
-            if (!validate)
-                throw new Error(`unknown tool: ${name}`);
-            if (!validate(argumentsValue)) {
-                const errors = (validate.errors || [])
-                    .map((error) => `${error.instancePath || "/"} ${error.message}`)
-                    .join("; ");
-                throw new Error(`invalid arguments: ${errors}`);
+            if (!validate) {
+                return {
+                    role: "tool",
+                    tool_call_id: callId,
+                    content: unavailableToolError(name, toolDefinitions(this.workspaceContext).map((definition) => definition.function.name)),
+                };
+            }
+            const parsed = this.parseArguments(call);
+            if (parsed.error !== undefined) {
+                return {
+                    role: "tool",
+                    tool_call_id: callId,
+                    content: arenaJsonParsingError(name, parsed.invalidJsonText, parsed.error),
+                };
+            }
+            const argumentsValue = parsed.value;
+            // Replay mode (CODE_HARNESS_REPLAY_RESPONSES set): serve recorded
+            // outputs BEFORE schema validation. Recorded arguments can violate the
+            // current schema — PII-redacted placeholder URLs fail format=url, or
+            // the schema evolved since recording (voice_identity vs voice_id) —
+            // and the recording must still replay verbatim. Canned lookup consumes
+            // the entry, so this must be the single serving point: dispatch() only
+            // sees calls without a recorded response. Unlisted calls fall through
+            // to validation and real execution.
+            const replayed = replayResponseFor(name, argumentsValue);
+            if (replayed) {
+                for (const artifact of replayed.artifacts ?? []) {
+                    this.materializeReplayArtifact(artifact);
+                }
+                const replayContent = typeof replayed.output === "string"
+                    ? replayed.output
+                    : json(replayed.output);
+                if (replayContent.length > toolResultCharacterLimit) {
+                    return {
+                        role: "tool",
+                        tool_call_id: callId,
+                        content: json({
+                            status: "error",
+                            message: `Tool result from ${name} (${replayContent.length} characters) exceeds the ` +
+                                `maximum allowed size (${toolResultCharacterLimit} characters). ` +
+                                "Retry with narrower arguments or inspect the data in smaller portions.",
+                        }),
+                    };
+                }
+                return { role: "tool", tool_call_id: callId, content: replayContent };
+            }
+            const validated = this.validateArguments(name, argumentsValue, validate);
+            if (validated.validationMessage !== undefined) {
+                return {
+                    role: "tool",
+                    tool_call_id: callId,
+                    content: validated.validationMessage,
+                };
+            }
+            const validatedArguments = validated.value;
+            const startedAt = Date.now();
+            let result;
+            try {
+                result = await this.dispatch(name, validatedArguments, callId, context);
+            }
+            catch (error) {
+                if (error instanceof AskUserHandlerError) {
+                    return {
+                        role: "tool",
+                        tool_call_id: callId,
+                        content: json({ status: "error", message: error.message }),
+                    };
+                }
+                return {
+                    role: "tool",
+                    tool_call_id: callId,
+                    content: json(this.runtimeFailureResult(name, validatedArguments, error, startedAt)),
+                };
             }
-            const result = await this.dispatch(name, argumentsValue, callId, context);
             const content = typeof result === "string" ? result : json(result);
             if (content.length > toolResultCharacterLimit) {
                 return {
@@ -468,13 +883,6 @@ class ArenaToolExecutor {
             };
         }
         catch (error) {
-            if (error instanceof AskUserHandlerError) {
-                return {
-                    role: "tool",
-                    tool_call_id: callId,
-                    content: json({ status: "error", message: error.message }),
-                };
-            }
             return {
                 role: "tool",
                 tool_call_id: callId,
@@ -485,6 +893,82 @@ class ArenaToolExecutor {
             };
         }
     }
+    runtimeFailureResult(name, values, error, startedAt) {
+        if (this.signal?.aborted)
+            return { status: "aborted" };
+        const message = errorMessage(error);
+        const durationMs = Date.now() - startedAt;
+        if (name === "bash") {
+            return {
+                status: "shell_error",
+                stderr: message,
+                stdout: "",
+                exit_code: null,
+                duration_ms: durationMs,
+                stderr_truncated: false,
+                stdout_truncated: false,
+            };
+        }
+        if (name === "start_process") {
+            const cwd = String(values.cwd || "/home/user");
+            const code = error?.code;
+            const logTail = code === "ENOENT"
+                ? `[invalid_argument] cwd '${cwd}' does not exist`
+                : message;
+            return {
+                status: "shell_error",
+                process_id: null,
+                pid: null,
+                exit_code: null,
+                log_tail: logTail,
+                listening_ports: [],
+                new_ports: [],
+                duration_ms: durationMs,
+            };
+        }
+        if (name === "get_process_output") {
+            return {
+                status: "shell_error",
+                log_tail: message,
+                exit_code: null,
+                listening_ports: [],
+            };
+        }
+        if (name === "stop_process") {
+            return { status: "shell_error", log_tail: message };
+        }
+        if (name === "fetch_page") {
+            return { status: "error", error: fetchPageFailure(message) };
+        }
+        if (name === "add_voice") {
+            return {
+                status: "error",
+                message: prefixedFailure("Failed to audition voices: ", message),
+            };
+        }
+        if (name === "generate_image") {
+            return {
+                status: "error",
+                message: prefixedFailure("Failed to generate image: ", message),
+            };
+        }
+        if (name === "generate_speech") {
+            return {
+                status: "error",
+                message: prefixedFailure("Failed to generate speech: ", message),
+            };
+        }
+        if (name === "image_search") {
+            return {
+                status: "error",
+                message: prefixedFailure("Image search failed: ", message),
+            };
+        }
+        if (name === "present_file") {
+            return { status: "error", message: "Error calling present file tool" };
+        }
+        return { status: "error", message };
+    }
     takeVisualMessage(toolCallIds) {
         // 生产契约：同一组 tool call 的全部图片汇入一条 user message，
         // 由一个 arena-system-message 文本 part 领头。
@@ -503,6 +987,8 @@ class ArenaToolExecutor {
         };
     }
     async dispatch(name, values, toolCallId, context) {
+        // Canned replay responses are served in execute() before schema
+        // validation (the lookup consumes entries — single serving point).
         switch (name) {
             case "bash":
                 return this.bash(String(values.command), String(values.cwd ||
@@ -555,32 +1041,76 @@ class ArenaToolExecutor {
                 throw new Error(`unknown tool: ${name}`);
         }
     }
+    // Copy a pre-staged replay artifact blob into the workspace. Recorded
+    // artifact paths must stay workspace-relative: an absolute path or one
+    // escaping the workspace is a corrupt recording, so reject it loudly.
+    materializeReplayArtifact(artifact) {
+        const normalized = path.posix.normalize(artifact.path);
+        if (path.posix.isAbsolute(artifact.path) ||
+            path.posix.isAbsolute(normalized) ||
+            normalized === ".." ||
+            normalized.startsWith("../")) {
+            throw new Error(`replay artifact path escapes the workspace: ${JSON.stringify(artifact.path)}`);
+        }
+        const target = path.resolve(this.workspace, normalized);
+        mkdirSync(path.dirname(target), { recursive: true });
+        copyFileSync(artifact.file, target);
+    }
     async confinedPath(raw) {
         if (!raw)
             throw new Error("path must not be empty");
         let candidate;
-        if (raw === "/home/user") {
-            candidate = this.workspace;
+        let confinementRoot = this.workspace;
+        let confinementRootReal = this.workspaceReal;
+        const expanded = raw === "~"
+            ? "/home/user"
+            : raw.startsWith("~/")
+                ? `/home/user/${raw.slice(2)}`
+                : raw;
+        const virtualAbsolute = path.posix.resolve("/home/user", expanded);
+        let suffix;
+        if (virtualAbsolute === "/var/tmp" ||
+            virtualAbsolute.startsWith("/var/tmp/")) {
+            confinementRoot = "/var/tmp";
+            confinementRootReal = this.varTmpReal;
+            suffix = virtualAbsolute.slice("/var/tmp".length).replace(/^\/+/, "");
+            candidate = path.join(confinementRoot, suffix);
         }
-        else if (raw.startsWith("/home/user/")) {
-            candidate = path.join(this.workspace, raw.slice("/home/user/".length));
+        else if (virtualAbsolute === "/tmp" ||
+            virtualAbsolute.startsWith("/tmp/")) {
+            confinementRoot = "/tmp";
+            confinementRootReal = this.tmpReal;
+            suffix = virtualAbsolute.slice("/tmp".length).replace(/^\/+/, "");
+            candidate = path.join(confinementRoot, suffix);
+        }
+        else if (this.nativeSandboxPaths && path.posix.isAbsolute(raw)) {
+            confinementRoot = "/";
+            confinementRootReal = "/";
+            candidate = raw;
         }
-        else if (!this.workspaceContext && raw === "~") {
+        else if (!this.workspaceContext) {
+            if (virtualAbsolute === "/home/user" ||
+                virtualAbsolute.startsWith("/home/user/")) {
+                suffix = virtualAbsolute.slice("/home/user".length).replace(/^\/+/, "");
+            }
+            else {
+                throw new Error(`path is outside the workspace: ${raw}`);
+            }
+            candidate = path.join(confinementRoot, suffix);
+        }
+        else if (raw === "/home/user") {
             candidate = this.workspace;
         }
-        else if (!this.workspaceContext && raw.startsWith("~/")) {
-            candidate = path.join(this.workspace, raw.slice(2));
+        else if (raw.startsWith("/home/user/")) {
+            candidate = path.join(this.workspace, raw.slice("/home/user/".length));
         }
         else {
-            const defaultCwd = this.workspaceContext
-                ? path.resolve(this.workspaceContext.cwd)
-                : this.workspace;
+            const defaultCwd = path.resolve(this.workspaceContext.cwd);
             candidate = path.isAbsolute(raw) ? raw : path.join(defaultCwd, raw);
         }
         const absolute = path.resolve(candidate);
-        const lexicalRelative = path.relative(this.workspace, absolute);
-        if (lexicalRelative.startsWith("..") ||
-            path.isAbsolute(lexicalRelative)) {
+        const lexicalRelative = path.relative(confinementRoot, absolute);
+        if (lexicalRelative.startsWith("..") || path.isAbsolute(lexicalRelative)) {
             throw new Error(`path is outside the workspace: ${raw}`);
         }
         let ancestor = absolute;
@@ -592,33 +1122,45 @@ class ArenaToolExecutor {
         }
         const ancestorReal = await realpath(ancestor);
         const resolved = path.resolve(ancestorReal, path.relative(ancestor, absolute));
-        const realRelative = path.relative(this.workspaceReal, resolved);
+        const realRelative = path.relative(confinementRootReal, resolved);
         if (realRelative.startsWith("..") || path.isAbsolute(realRelative)) {
             throw new Error(`path is outside the workspace: ${raw}`);
         }
         return resolved;
     }
     relativePath(target) {
+        for (const [root, virtualRoot] of [
+            [this.varTmpReal, "/var/tmp"],
+            [this.tmpReal, "/tmp"],
+        ]) {
+            const relative = path.relative(root, target);
+            if (!relative.startsWith("..") && !path.isAbsolute(relative)) {
+                const suffix = relative.split(path.sep).join("/");
+                return suffix ? `${virtualRoot}/${suffix}` : virtualRoot;
+            }
+        }
         return path.relative(this.workspaceReal, target).split(path.sep).join("/");
     }
-    virtualizeBashOutput(value) {
-        if (this.workspaceContext)
-            return value;
-        let virtualized = value;
-        const workspaceRoots = [...new Set([this.workspace, this.workspaceReal])]
-            .filter((root) => root !== path.parse(root).root)
-            .sort((left, right) => right.length - left.length);
-        for (const root of workspaceRoots) {
-            virtualized = virtualized.replaceAll(root, "/home/user");
-        }
-        return virtualized;
+    displayWorkspacePath(rawPath) {
+        if (!this.workspaceContext) {
+            if (rawPath === "/home/user" || rawPath === "~")
+                return ".";
+            if (rawPath.startsWith("/home/user/")) {
+                return rawPath.slice("/home/user/".length);
+            }
+            if (rawPath.startsWith("~/"))
+                return rawPath.slice(2);
+        }
+        return rawPath;
     }
     sandboxEnvironment() {
         const env = {
             ...process.env,
             ARENA_WORKSPACE: this.workspace,
-            LANG: "C.UTF-8",
-            LC_ALL: "C.UTF-8",
+            // Agent Arena captures use C character classification (grep -P, wc -w).
+            // This controls command behavior, not the UTF-8 encoding of stored files.
+            LANG: "C",
+            LC_ALL: "C",
         };
         delete env.FORCE_COLOR;
         delete env.CLICOLOR_FORCE;
@@ -626,28 +1168,30 @@ class ArenaToolExecutor {
     }
     async bash(command, cwd, timeoutSeconds) {
         const workdir = await this.confinedPath(cwd);
-        if (!(await stat(workdir)).isDirectory()) {
+        const metadata = await stat(workdir).catch((error) => {
+            // A missing cwd prevents shell startup; captured Bash stderr is empty.
+            // Keep other filesystem failures and start_process diagnostics intact.
+            if (error.code === "ENOENT")
+                throw new Error("");
+            throw error;
+        });
+        if (!metadata.isDirectory()) {
             throw new Error(`cwd is not a directory: ${cwd}`);
         }
-        // Legacy callers without runtime context retain the captured /home/user
-        // contract. Runtime-aware callers execute and report their actual paths.
-        const translatedCommand = this.workspaceContext
-            ? command
-            : command.replaceAll("/home/user", "\"$ARENA_WORKSPACE\"");
         return new Promise((resolve, reject) => {
             const env = this.sandboxEnvironment();
             // detached：管道成员（npm、tail…）与 bash 同进程组。只杀 bash 会留下
             // 孤儿持有 stdout/stderr 管道，close 永不触发，整个 turn 挂死；
             // 必须杀整组，并在宽限期后强制结算兜底。
-            const child = spawn("/bin/bash", ["-lc", translatedCommand], {
+            const child = spawn("/bin/bash", ["-lc", command], {
                 cwd: workdir,
                 env,
                 stdio: ["ignore", "pipe", "pipe"],
                 detached: process.platform !== "win32",
             });
             const startedAt = Date.now();
-            let stdout = "";
-            let stderr = "";
+            const stdout = new BashOutputBuffer();
+            const stderr = new BashOutputBuffer();
             let timedOut = false;
             let settled = false;
             let forceSettle;
@@ -684,8 +1228,8 @@ class ArenaToolExecutor {
                     reject(this.signal.reason || new Error("operation cancelled"));
                     return;
                 }
-                const out = capBashOutput(this.virtualizeBashOutput(stdout));
-                const err = capBashOutput(this.virtualizeBashOutput(stderr));
+                const out = stdout.result();
+                const err = stderr.result();
                 resolve({
                     status: timedOut ? "timeout" : signal ? "killed" : "completed",
                     stderr: err.text,
@@ -715,10 +1259,10 @@ class ArenaToolExecutor {
             };
             this.signal?.addEventListener("abort", abort, { once: true });
             child.stdout.on("data", (chunk) => {
-                stdout += chunk.toString("utf8");
+                stdout.append(chunk);
             });
             child.stderr.on("data", (chunk) => {
-                stderr += chunk.toString("utf8");
+                stderr.append(chunk);
             });
             child.once("error", (error) => {
                 if (settled)
@@ -738,12 +1282,9 @@ class ArenaToolExecutor {
         if (!(await stat(workdir)).isDirectory()) {
             throw new Error(`cwd is not a directory: ${cwd}`);
         }
-        const translatedCommand = this.workspaceContext
-            ? command
-            : command.replaceAll("/home/user", '"$ARENA_WORKSPACE"');
         return this.processManager.start({
             name,
-            command: translatedCommand,
+            command,
             cwd: workdir,
             startupWaitSeconds,
             env: this.sandboxEnvironment(),
@@ -752,10 +1293,12 @@ class ArenaToolExecutor {
     }
     async askUser(questions, toolCallId, context) {
         if (this.askUserHandler) {
-            return this.askUserHandler(toolCallId, questions, context ? {
-                ...context,
-                signal: this.signal || context.signal,
-            } : undefined);
+            return this.askUserHandler(toolCallId, questions, context
+                ? {
+                    ...context,
+                    signal: this.signal || context.signal,
+                }
+                : undefined);
         }
         // ask_user is not offered in non-interactive sessions; if the model still
         // emits it (e.g. resumed history or a hallucinated call), report an error
@@ -820,28 +1363,55 @@ class ArenaToolExecutor {
         };
     }
     async editFile(rawPath, oldText, newText) {
-        const target = await this.confinedPath(rawPath);
-        const source = await readFile(target, "utf8");
-        // 仅精确匹配：曾有空白容错回退，但 T1(b) 回放证实生产没有——case-003
-        // 四个 old_text 精确缺失的 edit 生产全部返回 Context not found，而回退
-        // 会静默改错文件；全部参考成功样本也都能走精确路径复现。
-        // 注意：spec/tools.json 的 edit_file description（与生产逐字一致，受
-        // T1(c) 门禁保护）声称支持 fuzzy matching——那是上游自身的描述与行为
-        // 不一致，按实测行为对齐，描述不改。见 TRAJECTORY_FIDELITY.md §5。
-        if (!source.includes(oldText)) {
+        let target;
+        let source;
+        try {
+            target = await this.confinedPath(rawPath);
+            if (!(await stat(target)).isFile()) {
+                return {
+                    status: "error",
+                    message: `File not found: ${rawPath}`,
+                };
+            }
+            source = await readFile(target, "utf8");
+        }
+        catch {
+            return {
+                status: "error",
+                message: `Failed to read workspace file: ${this.displayWorkspacePath(rawPath)}`,
+            };
+        }
+        // Agent Arena replaces the first match and tolerates multiline whitespace
+        // drift. Code Arena deliberately uses a separate unique-match policy.
+        const edited = replaceFirstText(source, oldText, newText, {
+            whitespaceInsensitiveMultiline: true,
+        });
+        if (edited === undefined) {
             return {
                 status: "error",
                 message: "Context not found. Read the file to verify the text exists.",
             };
         }
-        await writeFile(target, source.replace(oldText, newText), "utf8");
+        try {
+            // Replacement text is literal. String.replace(string, string) expands
+            // $&, $`, $' and $$ sequences and therefore corrupts JavaScript/jQuery
+            // snippets observed in production trajectories.
+            await writeFile(target, edited, "utf8");
+        }
+        catch {
+            return {
+                status: "error",
+                message: `Failed to write workspace file: ${rawPath}`,
+            };
+        }
         return { status: "success", message: `Edited ${rawPath}.` };
     }
     async readWorkspaceFile(rawPath, toolCallId) {
-        const target = await this.confinedPath(rawPath);
+        let target;
         let fileSize;
         let sample;
         try {
+            target = await this.confinedPath(rawPath);
             const metadata = await stat(target);
             if (!metadata.isFile())
                 throw new Error("not a regular file");
@@ -858,26 +1428,25 @@ class ArenaToolExecutor {
             }
         }
         catch {
-            // 逐字对齐生产错误文案，路径按调用方原样回显。
             return {
                 status: "error",
-                message: `Failed to read workspace file: ${rawPath}`,
+                message: `Failed to read workspace file: ${this.displayWorkspacePath(rawPath)}`,
             };
         }
         const extension = path.extname(target).toLowerCase();
         const kind = workspaceFileKind(target, sample);
-        if (kind === "text" && fileSize > textFileByteLimit) {
-            return {
-                status: "error",
-                message: `File content (${displayByteSize(fileSize)}) exceeds the maximum allowed size ` +
-                    `(${displayByteSize(textFileByteLimit)}). Use bash with sed/head/tail to read ` +
-                    "specific portions of the file, or grep/rg to search for specific content " +
-                    "instead of reading the whole file.",
-            };
-        }
         if (kind === "image" && fileSize > 20 * 1024 * 1024) {
             throw new Error(`image exceeds 20 MB: ${rawPath}`);
         }
+        // Current Arena v2 captures consistently expose local PDFs as binary
+        // metadata. PDF text extraction belongs to fetch_page, not read_file.
+        if (extension === ".pdf") {
+            return {
+                kind: "unsupported",
+                mediaType: "application/pdf",
+                size: fileSize,
+            };
+        }
         const mainModelSupportsImages = kind === "image" ? supportsImageInput(this.config) : false;
         const fallbackModel = mainModelSupportsImages
             ? undefined
@@ -892,7 +1461,7 @@ class ArenaToolExecutor {
         catch {
             return {
                 status: "error",
-                message: `Failed to read workspace file: ${rawPath}`,
+                message: `Failed to read workspace file: ${this.displayWorkspacePath(rawPath)}`,
             };
         }
         if (isStructuredDocument(target)) {
@@ -920,12 +1489,13 @@ class ArenaToolExecutor {
             return result;
         }
         if (kind === "text") {
-            const content = decodeText(data);
+            const text = readTextResult(data);
             return {
                 kind: "text",
-                lines: content.split("\n").length,
-                size: Buffer.byteLength(content, "utf8"),
-                content,
+                lines: data.reduce((count, byte) => count + (byte === 0x0a ? 1 : 0), 1),
+                size: data.length,
+                content: text.content,
+                ...(text.truncated ? { truncated: true } : {}),
             };
         }
         const mimeType = mime.getType(target) ||
@@ -975,9 +1545,29 @@ class ArenaToolExecutor {
         };
     }
     async writeWorkspaceFile(rawPath, content) {
-        const target = await this.confinedPath(rawPath);
-        mkdirSync(path.dirname(target), { recursive: true });
-        await writeFile(target, content, "utf8");
+        try {
+            const target = await this.confinedPath(rawPath);
+            mkdirSync(path.dirname(target), { recursive: true });
+            try {
+                await writeFile(target, content, "utf8");
+            }
+            catch (error) {
+                const code = error.code;
+                if (!["EACCES", "EPERM"].includes(code || "") || !privilegedFileCreationEnabled({
+                    platform: process.platform, workspace: this.workspaceReal,
+                    docker: existsSync("/.dockerenv"), flag: process.env.ARENA_SANDBOX_PRIVILEGED_FILE_CREATION,
+                    uid: process.getuid?.(),
+                }))
+                    throw error;
+                await createSandboxFile(target, content);
+            }
+        }
+        catch {
+            return {
+                status: "error",
+                message: `Failed to write workspace file: ${rawPath}`,
+            };
+        }
         return { status: "success" };
     }
     async webSearch(query, depth) {
@@ -993,18 +1583,21 @@ class ArenaToolExecutor {
         const slug = query
             .toLowerCase()
             .replace(/[^a-z0-9]+/g, "-")
-            .slice(0, 40);
+            .replace(/^-+|-+$/g, "")
+            .slice(0, 40) || "results";
         for (const value of results) {
             if (saved.length >= count)
                 break;
             const item = record(value);
             const properties = record(item.properties);
             const thumbnail = record(item.thumbnail);
-            const sourceUrl = stringValue(properties.url) || stringValue(thumbnail.src);
-            const thumbnailUrl = stringValue(thumbnail.src) || sourceUrl;
-            if (!sourceUrl)
+            // Brave's result URL is the source page; properties.url is an image asset.
+            const sourceUrl = stringValue(item.url);
+            const imageUrl = stringValue(properties.url) || stringValue(thumbnail.src);
+            const thumbnailUrl = stringValue(thumbnail.src) || imageUrl;
+            if (!imageUrl)
                 continue;
-            const downloadUrls = [...new Set([sourceUrl, thumbnailUrl])];
+            const downloadUrls = [...new Set([imageUrl, thumbnailUrl])];
             for (const downloadUrl of downloadUrls) {
                 try {
                     const imageResponse = await fetch(downloadUrl, {
@@ -1019,7 +1612,9 @@ class ArenaToolExecutor {
                         .split(";")[0]
                         ?.trim()
                         .toLowerCase();
-                    const extension = Object.entries(mimeTypes).find(([, mime]) => mime === normalizedType)?.[0] || ".jpg";
+                    const extension = normalizedType === "image/jpeg"
+                        ? ".jpg"
+                        : Object.entries(mimeTypes).find(([, mime]) => mime === normalizedType)?.[0] || ".jpg";
                     const target = await this.confinedPath(`image-search/${slug}-${saved.length + 1}${extension}`);
                     mkdirSync(path.dirname(target), { recursive: true });
                     await writeFile(target, await responseBytes(imageResponse));
@@ -1038,22 +1633,40 @@ class ArenaToolExecutor {
                 }
             }
         }
+        if (!saved.length) {
+            return {
+                status: "error",
+                message: "Image search failed: Strict safe search filtered all results for this query. " +
+                    "Try a different or more specific query.",
+            };
+        }
         return { status: "success", results: saved };
     }
     async presentFile(rawPath) {
-        const target = await this.confinedPath(rawPath);
-        if (!(await stat(target)).isFile())
-            throw new Error(rawPath);
-        return { path: rawPath, status: "success" };
+        try {
+            const target = await this.confinedPath(rawPath);
+            if (!(await stat(target)).isFile())
+                throw new Error(rawPath);
+            return { path: rawPath, status: "success" };
+        }
+        catch {
+            return { status: "error", message: "Error calling present file tool" };
+        }
     }
     async generateImage(rawPath, prompt, images) {
+        if (!rawPath) {
+            return { status: "error", message: "File path cannot be empty." };
+        }
         const target = await this.confinedPath(rawPath);
         const extension = path.extname(target).toLowerCase();
         if (![".jpg", ".jpeg", ".png"].includes(extension)) {
-            throw new Error("file_path must end in .jpg, .jpeg, or .png");
+            return {
+                status: "error",
+                message: "File path must end in .jpg, .jpeg, or .png.",
+            };
         }
         mkdirSync(path.dirname(target), { recursive: true });
-        const model = process.env.ARENA_IMAGE_MODEL || "gemini-2.5-flash-image";
+        const model = process.env.ARENA_IMAGE_MODEL || "gemini-3.1-flash-image";
         const references = [];
         for (const imagePath of images || []) {
             const source = await this.confinedPath(imagePath);
@@ -1062,7 +1675,13 @@ class ArenaToolExecutor {
             if (!mimeType?.startsWith("image/")) {
                 throw new Error(`unsupported reference image format: ${imagePath}`);
             }
-            const bytes = await readFile(source);
+            let bytes;
+            try {
+                bytes = await readFile(source);
+            }
+            catch {
+                throw new Error(`Failed to read workspace file: ${imagePath}`);
+            }
             if (bytes.length > 20 * 1024 * 1024) {
                 throw new Error(`reference image exceeds 20 MB: ${imagePath}`);
             }
@@ -1082,7 +1701,7 @@ class ArenaToolExecutor {
         await writeFile(target, await generatedImageBytesForExtension(generated.bytes, generated.mimeType, extension));
         return {
             status: "success",
-            file_path: this.relativePath(target),
+            file_path: rawPath,
         };
     }
     async generateSpeech(rawPath, text, voiceId, language) {
@@ -1095,7 +1714,7 @@ class ArenaToolExecutor {
             ".opus": "opus",
         }[extension];
         if (!format) {
-            throw new Error("ModelRouter Doubao TTS output supports .mp3, .wav, .ogg, or .opus");
+            throw new Error("ModelRouter TTS output supports .mp3, .wav, .ogg, or .opus");
         }
         mkdirSync(path.dirname(target), { recursive: true });
         const registered = this.voiceRegistry.resolve(voiceId);
@@ -1111,14 +1730,15 @@ class ArenaToolExecutor {
         const voice = process.env.ARENA_SPEECH_VOICE || registered.providerVoice;
         await writeFile(target, await generateSpeechWithModelRouter({
             format,
-            model: process.env.ARENA_SPEECH_MODEL || "doubao-tts",
+            model: registered.model,
+            language: language || registered.language,
             signal: this.signal,
             text,
             voice,
         }));
         return {
             status: "success",
-            file_path: this.relativePath(target),
+            file_path: rawPath,
         };
     }
 }
@@ -1143,6 +1763,9 @@ export class ToolExecutor {
     availableTools() {
         return this.implementation.availableTools();
     }
+    inspect(call) {
+        return this.implementation.inspect(call);
+    }
     execute(call, context) {
         return this.implementation.execute(call, context);
     }