dominds 1.17.7 → 1.18.2

package/dist/tools/cmd-runner.js

@@ -43,6 +43,20 @@ function sendIpc(msg) {
     }
     process.send(msg);
 }
+async function flushIpc(msg) {
+    if (typeof process.send !== 'function') {
+        throw new Error('cmd_runner must be launched with an IPC channel');
+    }
+    await new Promise((resolve, reject) => {
+        process.send?.(msg, (error) => {
+            if (error) {
+                reject(error);
+                return;
+            }
+            resolve();
+        });
+    });
+}
 async function readProcessCommandLine(pid) {
     try {
         if (process.platform === 'win32') {
@@ -140,13 +154,90 @@ async function main() {
         stdout: new ScrollingBuffer(init.scrollbackLines),
         stderr: new ScrollingBuffer(init.scrollbackLines),
     };
+    let server;
+    let closeRequested = false;
+    let timeoutHandle;
+    const closeServerAndExit = (code) => {
+        if (closeRequested) {
+            return;
+        }
+        closeRequested = true;
+        const exit = () => {
+            setImmediate(() => {
+                process.exit(code);
+            });
+        };
+        const cleanupEndpoint = () => {
+            if (process.platform !== 'win32') {
+                void promises_1.default.unlink(endpoint).catch(() => {
+                    // Best effort only.
+                });
+            }
+        };
+        if (!server) {
+            cleanupEndpoint();
+            exit();
+            return;
+        }
+        try {
+            server.close(() => {
+                cleanupEndpoint();
+                exit();
+            });
+        }
+        catch (error) {
+            const codeValue = typeof error === 'object' && error !== null
+                ? error.code
+                : undefined;
+            if (codeValue !== 'ERR_SERVER_NOT_RUNNING') {
+                throw error;
+            }
+            cleanupEndpoint();
+            exit();
+        }
+    };
+    childProcess.once('close', (code, signal) => {
+        if (timeoutHandle) {
+            clearTimeout(timeoutHandle);
+        }
+        state.isRunning = false;
+        state.exitCode = code;
+        state.exitSignal = signal;
+        void (async () => {
+            if (state.daemonCommandLine === null) {
+                await flushIpc({
+                    type: 'completed',
+                    exitCode: code,
+                    exitSignal: signal,
+                    stdout: state.stdout.snapshot(),
+                    stderr: state.stderr.snapshot(),
+                });
+            }
+            closeServerAndExit(0);
+        })().catch(() => {
+            closeServerAndExit(0);
+        });
+    });
+    childProcess.once('error', (error) => {
+        if (timeoutHandle) {
+            clearTimeout(timeoutHandle);
+        }
+        void flushIpc({
+            type: 'failed',
+            errorText: error.message,
+        })
+            .catch(() => undefined)
+            .finally(() => {
+            closeServerAndExit(1);
+        });
+    });
     childProcess.stdout?.on('data', (data) => {
         state.stdout.addText(data.toString());
     });
     childProcess.stderr?.on('data', (data) => {
         state.stderr.addText(data.toString());
     });
-    const server = node_net_1.default.createServer((socket) => {
+    server = node_net_1.default.createServer((socket) => {
         socket.setEncoding('utf8');
         let buffer = '';
         socket.on('data', (chunk) => {
@@ -211,9 +302,12 @@ async function main() {
             resolve();
         });
     });
-    const timeoutHandle = setTimeout(() => {
+    timeoutHandle = setTimeout(() => {
         void (async () => {
             const daemonCommandLine = await readProcessCommandLine(daemonPid);
+            if (!state.isRunning) {
+                return;
+            }
             if (daemonCommandLine === undefined || daemonCommandLine.trim() === '') {
                 try {
                     process.kill(daemonPid, 'SIGTERM');
@@ -221,12 +315,18 @@ async function main() {
                 catch {
                     // Best effort only.
                 }
+                if (!state.isRunning) {
+                    return;
+                }
                 sendIpc({
                     type: 'failed',
                     errorText: `failed to capture daemon command line from OS for pid ${String(daemonPid)}`,
                 });
                 return;
             }
+            if (!state.isRunning) {
+                return;
+            }
             state.daemonCommandLine = daemonCommandLine;
             sendIpc({
                 type: 'daemonized',
@@ -245,43 +345,6 @@ async function main() {
             });
         });
     }, init.timeoutSeconds * 1000);
-    childProcess.once('close', (code, signal) => {
-        clearTimeout(timeoutHandle);
-        state.isRunning = false;
-        state.exitCode = code;
-        state.exitSignal = signal;
-        if (state.daemonCommandLine === null) {
-            sendIpc({
-                type: 'completed',
-                exitCode: code,
-                exitSignal: signal,
-                stdout: state.stdout.snapshot(),
-                stderr: state.stderr.snapshot(),
-            });
-        }
-        server.close(() => {
-            if (process.platform !== 'win32') {
-                void promises_1.default.unlink(endpoint).catch(() => {
-                    // Best effort only.
-                });
-            }
-            setImmediate(() => {
-                process.exit(0);
-            });
-        });
-    });
-    childProcess.once('error', (error) => {
-        clearTimeout(timeoutHandle);
-        sendIpc({
-            type: 'failed',
-            errorText: error.message,
-        });
-        server.close(() => {
-            setImmediate(() => {
-                process.exit(1);
-            });
-        });
-    });
 }
 async function handleStopRequest(request, state, childProcess) {
     if (!state.isRunning) {
@@ -307,14 +370,12 @@ async function handleStopRequest(request, state, childProcess) {
     }
 }
 void main().catch((error) => {
-    try {
-        sendIpc({
-            type: 'failed',
-            errorText: error instanceof Error ? error.message : String(error),
-        });
-    }
-    catch {
-        // No IPC channel available.
-    }
-    process.exit(1);
+    void flushIpc({
+        type: 'failed',
+        errorText: error instanceof Error ? error.message : String(error),
+    })
+        .catch(() => undefined)
+        .finally(() => {
+        process.exit(1);
+    });
 });

package/dist/tools/picture.d.ts

@@ -0,0 +1,3 @@
+import type { FuncTool } from '../tool';
+export declare const readPictureTool: FuncTool;
+export declare const writePictureTool: FuncTool;

package/dist/tools/picture.js

@@ -0,0 +1,344 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writePictureTool = exports.readPictureTool = void 0;
+const crypto_1 = require("crypto");
+const promises_1 = __importDefault(require("fs/promises"));
+const path_1 = __importDefault(require("path"));
+const access_control_1 = require("../access-control");
+const persistence_1 = require("../persistence");
+const work_language_1 = require("../runtime/work-language");
+const tool_1 = require("../tool");
+const PICTURE_MAX_BYTES = 50 * 1024 * 1024;
+function ok(content, contentItems) {
+    return (0, tool_1.toolSuccess)(content, contentItems);
+}
+function fail(content) {
+    return (0, tool_1.toolFailure)(content);
+}
+function formatYamlCodeBlock(yaml) {
+    return `\`\`\`yaml\n${yaml}\n\`\`\``;
+}
+function yamlQuote(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
+function ensureInsideWorkspace(rel) {
+    const absPath = path_1.default.resolve(process.cwd(), rel);
+    const cwd = path_1.default.resolve(process.cwd());
+    const relative = path_1.default.relative(cwd, absPath);
+    if (relative === '' || (!relative.startsWith('..') && !path_1.default.isAbsolute(relative))) {
+        return absPath;
+    }
+    throw new Error('Path must be within rtws (runtime workspace)');
+}
+function requirePathArg(args) {
+    const value = args['path'];
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new Error('Invalid arguments: `path` must be a non-empty string');
+    }
+    return value.trim();
+}
+function optionalBooleanArg(args, key) {
+    const value = args[key];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'boolean') {
+        throw new Error(`Invalid arguments: \`${key}\` must be a boolean`);
+    }
+    return value;
+}
+function extToMimeType(relPath) {
+    switch (path_1.default.extname(relPath).toLowerCase()) {
+        case '.png':
+            return 'image/png';
+        case '.jpg':
+        case '.jpeg':
+            return 'image/jpeg';
+        case '.webp':
+            return 'image/webp';
+        case '.gif':
+            return 'image/gif';
+        default:
+            return null;
+    }
+}
+function mimeTypeToExt(mimeType) {
+    switch (mimeType) {
+        case 'image/png':
+            return 'png';
+        case 'image/jpeg':
+            return 'jpg';
+        case 'image/webp':
+            return 'webp';
+        case 'image/gif':
+            return 'gif';
+        default: {
+            const _exhaustive = mimeType;
+            return _exhaustive;
+        }
+    }
+}
+function parseSupportedMimeType(value) {
+    switch (value) {
+        case 'image/png':
+        case 'image/jpeg':
+        case 'image/webp':
+        case 'image/gif':
+            return value;
+        default:
+            return null;
+    }
+}
+function detectImageMimeType(bytes) {
+    if (bytes.length >= 8 &&
+        bytes[0] === 0x89 &&
+        bytes[1] === 0x50 &&
+        bytes[2] === 0x4e &&
+        bytes[3] === 0x47 &&
+        bytes[4] === 0x0d &&
+        bytes[5] === 0x0a &&
+        bytes[6] === 0x1a &&
+        bytes[7] === 0x0a) {
+        return 'image/png';
+    }
+    if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) {
+        return 'image/jpeg';
+    }
+    if (bytes.length >= 12 &&
+        bytes.subarray(0, 4).toString('ascii') === 'RIFF' &&
+        bytes.subarray(8, 12).toString('ascii') === 'WEBP') {
+        return 'image/webp';
+    }
+    if (bytes.length >= 6 &&
+        (bytes.subarray(0, 6).toString('ascii') === 'GIF87a' ||
+            bytes.subarray(0, 6).toString('ascii') === 'GIF89a')) {
+        return 'image/gif';
+    }
+    return null;
+}
+function validateImageBytesMatchMimeType(bytes, mimeType) {
+    const detected = detectImageMimeType(bytes);
+    if (detected === null) {
+        throw new Error('Image bytes do not match a supported PNG/JPEG/WebP/GIF signature');
+    }
+    if (detected !== mimeType) {
+        throw new Error(`Image bytes are ${detected}, but path/mime_type declares ${mimeType}`);
+    }
+}
+function stripDataUrlPrefix(value) {
+    const trimmed = value.trim();
+    if (!trimmed.startsWith('data:'))
+        return { base64: trimmed };
+    const match = /^data:([^;,]+);base64,(.*)$/s.exec(trimmed);
+    if (!match)
+        return { base64: trimmed };
+    const mimeType = parseSupportedMimeType(match[1]);
+    return {
+        base64: match[2] ?? '',
+        ...(mimeType === null ? {} : { mimeType }),
+    };
+}
+function isStrictBase64Payload(value) {
+    if (value.length === 0 || value.length % 4 !== 0)
+        return false;
+    return /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value);
+}
+function decodeStrictBase64(value) {
+    const normalized = value.replace(/\s+/g, '');
+    if (!isStrictBase64Payload(normalized)) {
+        throw new Error('Image data must be strict base64 or a base64 data URL');
+    }
+    return Buffer.from(normalized, 'base64');
+}
+function sanitizePathSegment(value) {
+    const cleaned = value.replace(/[^0-9A-Za-z._-]/g, '_').replace(/_+/g, '_');
+    const trimmed = cleaned.replace(/^_+|_+$/g, '');
+    return trimmed.length > 0 ? trimmed.slice(0, 96) : 'picture';
+}
+async function persistPictureArtifact(args) {
+    const eventsBase = persistence_1.DialogPersistence.getDialogEventsPath(args.dlg.id, args.dlg.status);
+    const relPath = path_1.default.posix.join('artifacts', 'workspace', sanitizePathSegment(args.toolName), `${Date.now().toString(36)}-${(0, crypto_1.randomUUID)()}.${mimeTypeToExt(args.mimeType)}`);
+    const absPath = path_1.default.join(eventsBase, ...relPath.split('/'));
+    await promises_1.default.mkdir(path_1.default.dirname(absPath), { recursive: true });
+    await promises_1.default.writeFile(absPath, args.bytes);
+    return {
+        type: 'input_image',
+        mimeType: args.mimeType,
+        byteLength: args.bytes.length,
+        artifact: {
+            rootId: args.dlg.id.rootId,
+            selfId: args.dlg.id.selfId,
+            status: args.dlg.status,
+            relPath,
+        },
+    };
+}
+function formatPictureResultYaml(args) {
+    return formatYamlCodeBlock([
+        `status: ${args.status}`,
+        `action: ${args.action}`,
+        `path: ${yamlQuote(args.path)}`,
+        `mime_type: ${yamlQuote(args.mimeType)}`,
+        `byte_length: ${String(args.byteLength)}`,
+        `artifact_rel_path: ${yamlQuote(args.artifactRelPath)}`,
+        'llm_context: image_attached',
+    ].join('\n'));
+}
+exports.readPictureTool = {
+    type: 'func',
+    name: 'read_picture',
+    description: 'Read a PNG/JPEG/WebP/GIF image from rtws and attach it as an image content item for the next LLM context.',
+    descriptionI18n: {
+        en: 'Read a PNG/JPEG/WebP/GIF image from rtws and attach it as an image content item for the next LLM context.',
+        zh: '读取 rtws 中的 PNG/JPEG/WebP/GIF 图片，并作为图片 content item 放入后续 LLM 上下文。',
+    },
+    parameters: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            path: {
+                type: 'string',
+                description: 'rtws-relative image path to read. Supported extensions: .png, .jpg, .jpeg, .webp, .gif.',
+            },
+        },
+        required: ['path'],
+    },
+    argsValidation: 'dominds',
+    call: async (dlg, caller, args) => {
+        const language = (0, work_language_1.getWorkLanguage)();
+        try {
+            const relPath = requirePathArg(args);
+            if (!(0, access_control_1.hasReadAccess)(caller, relPath)) {
+                return fail((0, access_control_1.getAccessDeniedMessage)('read', relPath, language));
+            }
+            const mimeType = extToMimeType(relPath);
+            if (mimeType === null) {
+                return fail('Unsupported image extension. Supported extensions: .png, .jpg, .jpeg, .webp, .gif');
+            }
+            const absPath = ensureInsideWorkspace(relPath);
+            const stat = await promises_1.default.stat(absPath);
+            if (!stat.isFile())
+                return fail(`Path is not a file: ${relPath}`);
+            if (stat.size <= 0 || stat.size > PICTURE_MAX_BYTES) {
+                return fail(`Image must be between 1 byte and ${String(PICTURE_MAX_BYTES)} bytes`);
+            }
+            const bytes = await promises_1.default.readFile(absPath);
+            validateImageBytesMatchMimeType(bytes, mimeType);
+            const item = await persistPictureArtifact({
+                dlg,
+                toolName: 'read_picture',
+                mimeType,
+                bytes,
+            });
+            return ok(formatPictureResultYaml({
+                status: 'ok',
+                action: 'read_picture',
+                path: relPath,
+                mimeType,
+                byteLength: bytes.length,
+                artifactRelPath: item.artifact.relPath,
+            }), [item]);
+        }
+        catch (error) {
+            return fail(error instanceof Error ? error.message : String(error));
+        }
+    },
+};
+exports.writePictureTool = {
+    type: 'func',
+    name: 'write_picture',
+    description: 'Write a PNG/JPEG/WebP/GIF image to rtws from strict base64 or a base64 data URL, then attach the written image as a content item.',
+    descriptionI18n: {
+        en: 'Write a PNG/JPEG/WebP/GIF image to rtws from strict base64 or a base64 data URL, then attach the written image as a content item.',
+        zh: '把 strict base64 或 base64 data URL 写成 rtws 中的 PNG/JPEG/WebP/GIF 图片，并把写出的图片作为 content item 返回。',
+    },
+    parameters: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            path: {
+                type: 'string',
+                description: 'rtws-relative destination image path. Supported extensions: .png, .jpg, .jpeg, .webp, .gif.',
+            },
+            data_base64: {
+                type: 'string',
+                description: 'Strict base64 image payload, or a base64 data URL.',
+            },
+            mime_type: {
+                type: 'string',
+                description: 'Optional MIME type. Supported values: image/png, image/jpeg, image/webp, image/gif.',
+            },
+            overwrite: {
+                type: 'boolean',
+                description: 'Whether to overwrite an existing file. Defaults to false.',
+            },
+        },
+        required: ['path', 'data_base64'],
+    },
+    argsValidation: 'dominds',
+    call: async (dlg, caller, args) => {
+        const language = (0, work_language_1.getWorkLanguage)();
+        try {
+            const relPath = requirePathArg(args);
+            if (!(0, access_control_1.hasWriteAccess)(caller, relPath)) {
+                return fail((0, access_control_1.getAccessDeniedMessage)('write', relPath, language));
+            }
+            const rawData = args['data_base64'];
+            if (typeof rawData !== 'string' || rawData.trim() === '') {
+                return fail('Invalid arguments: `data_base64` must be a non-empty string');
+            }
+            const parsedData = stripDataUrlPrefix(rawData);
+            const explicitMimeType = parseSupportedMimeType(args['mime_type']);
+            if (args['mime_type'] !== undefined && explicitMimeType === null) {
+                return fail('Unsupported mime_type. Supported values: image/png, image/jpeg, image/webp, image/gif');
+            }
+            const pathMimeType = extToMimeType(relPath);
+            if (pathMimeType === null) {
+                return fail('Unsupported image extension. Supported extensions: .png, .jpg, .jpeg, .webp, .gif');
+            }
+            const mimeType = explicitMimeType ?? parsedData.mimeType ?? pathMimeType;
+            if (mimeType !== pathMimeType) {
+                return fail(`mime_type ${mimeType} does not match destination extension for ${relPath}`);
+            }
+            const bytes = decodeStrictBase64(parsedData.base64);
+            if (bytes.length <= 0 || bytes.length > PICTURE_MAX_BYTES) {
+                return fail(`Image must be between 1 byte and ${String(PICTURE_MAX_BYTES)} bytes`);
+            }
+            validateImageBytesMatchMimeType(bytes, mimeType);
+            const overwrite = optionalBooleanArg(args, 'overwrite') ?? false;
+            const absPath = ensureInsideWorkspace(relPath);
+            if (!overwrite) {
+                try {
+                    await promises_1.default.stat(absPath);
+                    return fail(`File already exists: ${relPath}. Pass overwrite=true to replace it.`);
+                }
+                catch (error) {
+                    if (!(error instanceof Error) || !('code' in error) || error.code !== 'ENOENT') {
+                        throw error;
+                    }
+                }
+            }
+            await promises_1.default.mkdir(path_1.default.dirname(absPath), { recursive: true });
+            await promises_1.default.writeFile(absPath, bytes);
+            const item = await persistPictureArtifact({
+                dlg,
+                toolName: 'write_picture',
+                mimeType,
+                bytes,
+            });
+            return ok(formatPictureResultYaml({
+                status: 'ok',
+                action: 'write_picture',
+                path: relPath,
+                mimeType,
+                byteLength: bytes.length,
+                artifactRelPath: item.artifact.relPath,
+            }), [item]);
+        }
+        catch (error) {
+            return fail(error instanceof Error ? error.message : String(error));
+        }
+    },
+};

package/dist/tools/prompts/control/en/principles.md

@@ -92,7 +92,9 @@ Taskdoc is a **task contract** and the task's **team-shared source of current tr
 
 ### Decision Rules
 
-- If the current sideline is unfinished, blocked, uncertain, or needs an upstream clarification: call `tellaskBack({ tellaskContent })`
+- If the current sideline is unfinished, first judge whether team SOP / role ownership already identifies the responsible owner; if yes and the issue is execution work, directly use `tellask` / `tellaskSessionless` for that owner
+- Call `tellaskBack({ tellaskContent })` only when upstream must clarify the request, decide a tradeoff, confirm acceptance criteria, provide missing input, or current SOP cannot determine ownership
+- If a human must personally perform login / GUI / captcha / high-risk authorization: call `askHuman({ tellaskContent })`
 - If the current sideline is complete and the assignment header says `replyTellask`: call `replyTellask({ replyContent })`
 - If the current sideline is complete and the assignment header says `replyTellaskSessionless`: call `replyTellaskSessionless({ replyContent })`
 - If you are answering an upstream `tellaskBack` follow-up and runtime exposes `replyTellaskBack`: call `replyTellaskBack({ replyContent })`
@@ -104,7 +106,7 @@ Taskdoc is a **task contract** and the task's **team-shared source of current tr
 - Do not memorize reply variants by yourself; follow the current assignment header and the function currently exposed by runtime
 - `reply*` tool descriptions are intentionally minimal and spec-like; use this manual's principles / scenarios for situational guidance
 - If runtime exposes only one `reply*`, that is the only correct completion path for the current state
-- `tellaskBack` is for ask-back only, not final delivery
+- `tellaskBack` is the fallback when ownership cannot be determined from existing SOP, or when upstream must answer; it is not the default first move for every blocked state
 
 ## Best Practices
 

package/dist/tools/prompts/control/en/scenarios.md

@@ -89,7 +89,8 @@ tellaskBack({
 
 ### Key Points
 
-- Use `tellaskBack` while the work is still unfinished
+- This example uses `tellaskBack` because upstream input is specifically required
+- If team SOP / role ownership already identifies the responsible executor, directly use `tellask` / `tellaskSessionless` for that owner instead of mapping every unfinished state to `tellaskBack`
 - Do not use `replyTellask*` for intermediate clarifications
 
 ## Scenario 4: Upstream answered the ask-back, so use replyTellaskBack to close

package/dist/tools/prompts/control/en/tools.md

@@ -23,12 +23,12 @@
 
 The **tool descriptions themselves** for these functions intentionally stay minimal and spec-like. This section carries the smallest practical lookup for when they appear and how to choose among them.
 
-| Function                  | Minimal parameter contract   | When runtime exposes it                                                                       | Effect                                                     |
-| ------------------------- | ---------------------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
-| `replyTellask`            | `{ replyContent: string }`   | Current sideline comes from a sessioned `tellask` and is ready for final delivery             | Delivers the final result for the current tellask session  |
-| `replyTellaskSessionless` | `{ replyContent: string }`   | Current sideline comes from a one-shot `tellaskSessionless` and is ready for final delivery   | Delivers the final result for the current one-shot tellask |
-| `replyTellaskBack`        | `{ replyContent: string }`   | Current dialog holds an unresolved `tellaskBack` reply directive                              | Delivers the final answer to the upstream ask-back         |
-| `tellaskBack`             | `{ tellaskContent: string }` | Current sideline is not done yet and needs clarification / ask-back / blocked-state reporting | Sends a follow-up request upstream; not final delivery     |
+| Function                  | Minimal parameter contract   | When runtime exposes it                                                                             | Effect                                                     |
+| ------------------------- | ---------------------------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| `replyTellask`            | `{ replyContent: string }`   | Current sideline comes from a sessioned `tellask` and is ready for final delivery                   | Delivers the final result for the current tellask session  |
+| `replyTellaskSessionless` | `{ replyContent: string }`   | Current sideline comes from a one-shot `tellaskSessionless` and is ready for final delivery         | Delivers the final result for the current one-shot tellask |
+| `replyTellaskBack`        | `{ replyContent: string }`   | Current dialog holds an unresolved `tellaskBack` reply directive                                    | Delivers the final answer to the upstream ask-back         |
+| `tellaskBack`             | `{ tellaskContent: string }` | Current sideline must ask upstream back, and existing team SOP cannot directly assign another owner | Sends a follow-up request upstream; not final delivery     |
 
 ### Minimal Usage Rules
 

package/dist/tools/prompts/control/zh/principles.md

@@ -92,7 +92,9 @@
 
 ### 决策规则
 
-- 当前支线未完成、仍有疑问、被阻塞，或必须向上游补问时：调用 `tellaskBack({ tellaskContent })`
+- 当前支线未完成时，先判断团队规程 / SOP / 职责卡能否明确负责人；若能明确且属于执行性处理，直接 `tellask` / `tellaskSessionless` 对应负责人
+- 只有当必须向上游补需求、澄清目标、裁决取舍、确认验收口径、提供缺失输入，或现有规程无法明确判责时：调用 `tellaskBack({ tellaskContent })`
+- 需要人类亲自登录 / GUI / 验证码 / 高风险授权时：调用 `askHuman({ tellaskContent })`
 - 当前支线已经完成，且当前 assignment 明确要求 `replyTellask`：调用 `replyTellask({ replyContent })`
 - 当前支线已经完成，且当前 assignment 明确要求 `replyTellaskSessionless`：调用 `replyTellaskSessionless({ replyContent })`
 - 当前是在回复一条上游发来的 `tellaskBack` 续诉请，且 runtime 暴露了 `replyTellaskBack`：调用 `replyTellaskBack({ replyContent })`
@@ -104,7 +106,7 @@
 - 不要靠记忆硬选 reply 变体；以当前 assignment 头部和 runtime 当前暴露的函数名为准
 - `reply*` 函数自身说明文案故意保持极简，只承载最小规格；情景判断看本手册的 principles / scenarios
 - 若 runtime 只暴露一个 `reply*`，那就是当前应调用的唯一完成路径
-- `tellaskBack` 只用于回问，不用于最终交付
+- `tellaskBack` 是“无法按现有规程明确判责，或必须回问上游”的兜底动作，不是所有阻塞的默认第一动作
 
 ## 最佳实践
 

package/dist/tools/prompts/control/zh/scenarios.md

@@ -89,7 +89,8 @@ tellaskBack({
 
 ### 关键点
 
-- 未完成态用 `tellaskBack`，不要用 `replyTellask*`
+- 这里只是“必须向上游补输入”的例子，所以用 `tellaskBack`
+- 若团队规程 / SOP / 职责卡已经能明确执行负责人，应直接 `tellask` / `tellaskSessionless` 对应负责人，而不是机械因为“未完成态”就用 `tellaskBack`
 - `tellaskBack` 只负责把问题问回去，不负责最终交付
 
 ## 场景 4：收到 ask-back 续诉请后，用 replyTellaskBack 收口

package/dist/tools/prompts/control/zh/tools.md

@@ -28,7 +28,7 @@
 | `replyTellask`            | `{ replyContent: string }`   | 当前支线承接的是 sessioned `tellask`，且已进入可交付完成态           | 把最终结果回复给当前 `tellask` 会话 |
 | `replyTellaskSessionless` | `{ replyContent: string }`   | 当前支线承接的是 one-shot `tellaskSessionless`，且已进入可交付完成态 | 把最终结果回复给当前一次性诉请      |
 | `replyTellaskBack`        | `{ replyContent: string }`   | 当前对话持有一条未完成的 `tellaskBack` 回复指令                      | 把对上一条回问的最终答复送回上游    |
-| `tellaskBack`             | `{ tellaskContent: string }` | 当前支线尚未完成，但需要补问/澄清/报阻塞                             | 向上游发起续诉请，不算最终交付      |
+| `tellaskBack`             | `{ tellaskContent: string }` | 当前支线必须回问上游，且现有团队规程无法直接判责到其他负责人         | 向上游发起续诉请，不算最终交付      |
 
 ### 最小使用规则
 

package/dist/tools/prompts/ws_mod.en.md

@@ -13,6 +13,7 @@ You have read/write access to the rtws (runtime workspace), but **all incrementa
 - Normalization: all writes follow “each line ends with `\n` (including the last line)”; missing EOF newline will be added and shown in `normalized.*`.
 - Exception: `overwrite_entire_file` overwrites an existing file (writes immediately; does not use prepare/apply). It requires `known_old_total_lines/known_old_total_bytes` guardrails (read `total_lines/size_bytes` from the YAML header of `read_file`). `content_format` accepts any non-empty text label (for example `yaml`), but diff/patch-like content is still rejected by default unless `content_format=diff|patch`. Use it only for “small content (<100 lines)” or “intentional reset/generated output”; otherwise prefer prepare/apply.
 - Exception: `create_new_file` only creates a new file (empty content allowed). It does not do incremental edits and does not use prepare/apply; it refuses to overwrite existing files.
+- Binary image tools: use `read_picture({ path })` to inspect PNG/JPEG/WebP/GIF images as real image context; use `write_picture({ path, data_base64, mime_type, overwrite })` to write a base64 image. These are binary image operations and do not use prepare/apply.
 
 ## Which `prepare_*` to use