@armadra/agent 0.0.0-stage → 0.3.0

package/dist/tools/shell.d.ts

@@ -0,0 +1,38 @@
+/**
+ * shell 选择与参数拼装（设计 §5.2 bash）。[B3]
+ *
+ * - POSIX：`AMA_SHELL` → `/bin/bash` → `sh`；参数 `-c <command>`。
+ * - Windows：`AMA_SHELL` → Git Bash 已知路径 → `powershell -NoProfile -NonInteractive -Command`；
+ *   PowerShell 回退时在命令末尾追加 `$LASTEXITCODE` 透传，使 exit_code 取自它。
+ * - `AMA_SHELL` 按文件名判类型：`powershell` / `pwsh` → PowerShell，`cmd` → `cmd /d /s /c`，其它按 POSIX。
+ * - 工具环境：继承进程环境并注入 `AMA_SESSION_ID / AMA_SESSION_FILE / AMA_PROVIDER / AMA_MODEL /
+ *   AMA_THINKING / AMA_DEPTH`（每条命令启动时取值；缺值则删掉继承来的旧值）。
+ */
+export type ShellKind = "posix" | "powershell" | "cmd";
+export interface ShellConfig {
+    shell: string;
+    kind: ShellKind;
+}
+export interface ShellDeps {
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+    exists?(path: string): boolean;
+}
+export declare const POWERSHELL_ARGS: readonly ["-NoProfile", "-NonInteractive", "-Command"];
+export declare function shellKindOf(shell: string): ShellKind;
+/** Windows 上 Git Bash 的已知安装位置（按优先级）。 */
+export declare function gitBashCandidates(env: NodeJS.ProcessEnv): string[];
+export declare function resolveShell(deps?: ShellDeps): ShellConfig;
+/** PowerShell：命令后透传原生程序的 `$LASTEXITCODE`；cmdlet 失败（`$?` 为假）给 1。 */
+export declare function wrapPowerShellCommand(command: string): string;
+export declare function buildShellArgs(config: ShellConfig, command: string): string[];
+export interface ToolEnvInput {
+    sessionId: string;
+    sessionFile?: string | undefined;
+    provider?: string | undefined;
+    model?: string | undefined;
+    thinkingLevel?: string | undefined;
+    depth: number;
+}
+export declare const INJECTED_ENV_VARS: readonly ["AMA_SESSION_ID", "AMA_SESSION_FILE", "AMA_PROVIDER", "AMA_MODEL", "AMA_THINKING", "AMA_DEPTH"];
+export declare function buildToolEnv(base: NodeJS.ProcessEnv, info: ToolEnvInput): NodeJS.ProcessEnv;

package/dist/tools/shell.js

@@ -0,0 +1,91 @@
+/**
+ * shell 选择与参数拼装（设计 §5.2 bash）。[B3]
+ *
+ * - POSIX：`AMA_SHELL` → `/bin/bash` → `sh`；参数 `-c <command>`。
+ * - Windows：`AMA_SHELL` → Git Bash 已知路径 → `powershell -NoProfile -NonInteractive -Command`；
+ *   PowerShell 回退时在命令末尾追加 `$LASTEXITCODE` 透传，使 exit_code 取自它。
+ * - `AMA_SHELL` 按文件名判类型：`powershell` / `pwsh` → PowerShell，`cmd` → `cmd /d /s /c`，其它按 POSIX。
+ * - 工具环境：继承进程环境并注入 `AMA_SESSION_ID / AMA_SESSION_FILE / AMA_PROVIDER / AMA_MODEL /
+ *   AMA_THINKING / AMA_DEPTH`（每条命令启动时取值；缺值则删掉继承来的旧值）。
+ */
+import { existsSync } from "node:fs";
+export const POWERSHELL_ARGS = ["-NoProfile", "-NonInteractive", "-Command"];
+export function shellKindOf(shell) {
+    const base = (shell.split(/[\\/]/).pop() ?? shell).toLowerCase().replace(/\.exe$/, "");
+    if (base === "powershell" || base === "pwsh")
+        return "powershell";
+    if (base === "cmd")
+        return "cmd";
+    return "posix";
+}
+/** Windows 上 Git Bash 的已知安装位置（按优先级）。 */
+export function gitBashCandidates(env) {
+    const out = [];
+    const add = (root, rest) => {
+        if (root)
+            out.push(`${root.replace(/[\\/]+$/, "")}\\${rest}`);
+    };
+    add(env["ProgramFiles"], "Git\\bin\\bash.exe");
+    add(env["ProgramW6432"], "Git\\bin\\bash.exe");
+    add(env["ProgramFiles(x86)"], "Git\\bin\\bash.exe");
+    add(env["LOCALAPPDATA"], "Programs\\Git\\bin\\bash.exe");
+    out.push("C:\\Program Files\\Git\\bin\\bash.exe");
+    return [...new Set(out)];
+}
+export function resolveShell(deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    const env = deps.env ?? process.env;
+    const exists = deps.exists ?? existsSync;
+    const custom = env["AMA_SHELL"]?.trim();
+    if (custom)
+        return { shell: custom, kind: shellKindOf(custom) };
+    if (platform === "win32") {
+        for (const candidate of gitBashCandidates(env)) {
+            if (exists(candidate))
+                return { shell: candidate, kind: "posix" };
+        }
+        return { shell: "powershell.exe", kind: "powershell" };
+    }
+    if (exists("/bin/bash"))
+        return { shell: "/bin/bash", kind: "posix" };
+    return { shell: "sh", kind: "posix" };
+}
+/** PowerShell：命令后透传原生程序的 `$LASTEXITCODE`；cmdlet 失败（`$?` 为假）给 1。 */
+export function wrapPowerShellCommand(command) {
+    return (`${command}\n` +
+        "if ($null -ne $LASTEXITCODE) { exit $LASTEXITCODE } elseif (-not $?) { exit 1 } else { exit 0 }");
+}
+export function buildShellArgs(config, command) {
+    switch (config.kind) {
+        case "powershell":
+            return [...POWERSHELL_ARGS, wrapPowerShellCommand(command)];
+        case "cmd":
+            return ["/d", "/s", "/c", command];
+        default:
+            return ["-c", command];
+    }
+}
+export const INJECTED_ENV_VARS = [
+    "AMA_SESSION_ID",
+    "AMA_SESSION_FILE",
+    "AMA_PROVIDER",
+    "AMA_MODEL",
+    "AMA_THINKING",
+    "AMA_DEPTH",
+];
+export function buildToolEnv(base, info) {
+    const env = { ...base };
+    for (const key of INJECTED_ENV_VARS)
+        delete env[key];
+    const set = (key, value) => {
+        if (value !== undefined && value !== "")
+            env[key] = value;
+    };
+    set("AMA_SESSION_ID", info.sessionId);
+    set("AMA_SESSION_FILE", info.sessionFile);
+    set("AMA_PROVIDER", info.provider);
+    set("AMA_MODEL", info.model);
+    set("AMA_THINKING", info.thinkingLevel);
+    set("AMA_DEPTH", String(info.depth));
+    return env;
+}

package/dist/tools/task.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `task` 工具：同进程子 Agent（设计 §5.2、D14）。[B3]
+ *
+ * 子会话由 `ctx.spawnSubagent`（B2 的 AgentSession 提供）创建：独立 JSONL、继承权限模式与 broker、
+ * 审批串到父。本工具负责：
+ * - 深度 ≤ 1：`ctx.depth ≥ 1` 或无 `spawnSubagent` → 错误（子 Agent 里没有 task）；
+ * - 并发 ≤ 4：由会话的 `SubagentPool`（agent/session-subagent.ts，`subagents.maxConcurrent`）排队，
+ *   本工具不再自带一层信号量；排队中父 abort → 子会话抛 aborted，这里返回 aborted；
+ * - 工具子集：`tools` 里去掉 `task`（缺省交给 spawnSubagent = 父活动集去掉 task）；
+ * - 父 abort 级联：把 `ctx.signal` 传给子；
+ * - 结果 = 子的最后助手文本 + `details{ sessionFile, usage, stopReason }`。
+ */
+import type { ModelThinkingLevel } from "../ai/types.js";
+import type { SubagentRequest, ToolContext, ToolDefinition } from "./types.js";
+export declare const MAX_TASK_DEPTH = 1;
+export declare const DEFAULT_TASK_MAX_TURNS = 30;
+export interface TaskInput {
+    prompt: string;
+    description?: string;
+    tools?: string[];
+    model?: string;
+    thinkingLevel?: ModelThinkingLevel;
+    maxTurns?: number;
+}
+/** 预留（并发上限在会话的 SubagentPool，见文件头）。 */
+export interface TaskToolOptions {
+}
+export declare function buildSubagentRequest(input: TaskInput, ctx: ToolContext): SubagentRequest | string;
+export declare function createTaskTool(_options?: TaskToolOptions): ToolDefinition<TaskInput>;

package/dist/tools/task.js

@@ -0,0 +1,107 @@
+/**
+ * `task` 工具：同进程子 Agent（设计 §5.2、D14）。[B3]
+ *
+ * 子会话由 `ctx.spawnSubagent`（B2 的 AgentSession 提供）创建：独立 JSONL、继承权限模式与 broker、
+ * 审批串到父。本工具负责：
+ * - 深度 ≤ 1：`ctx.depth ≥ 1` 或无 `spawnSubagent` → 错误（子 Agent 里没有 task）；
+ * - 并发 ≤ 4：由会话的 `SubagentPool`（agent/session-subagent.ts，`subagents.maxConcurrent`）排队，
+ *   本工具不再自带一层信号量；排队中父 abort → 子会话抛 aborted，这里返回 aborted；
+ * - 工具子集：`tools` 里去掉 `task`（缺省交给 spawnSubagent = 父活动集去掉 task）；
+ * - 父 abort 级联：把 `ctx.signal` 传给子；
+ * - 结果 = 子的最后助手文本 + `details{ sessionFile, usage, stopReason }`。
+ */
+export const MAX_TASK_DEPTH = 1;
+export const DEFAULT_TASK_MAX_TURNS = 30;
+const THINKING = [
+    "off",
+    "minimal",
+    "low",
+    "medium",
+    "high",
+    "xhigh",
+];
+function fail(message) {
+    return { content: message, isError: true };
+}
+export function buildSubagentRequest(input, ctx) {
+    if (typeof input.prompt !== "string" || input.prompt.trim() === "") {
+        return "prompt must be a non-empty string";
+    }
+    const maxTurns = input.maxTurns ?? DEFAULT_TASK_MAX_TURNS;
+    if (!Number.isInteger(maxTurns) || maxTurns < 1)
+        return "maxTurns must be an integer ≥ 1";
+    if (input.thinkingLevel !== undefined && !THINKING.includes(input.thinkingLevel)) {
+        return `thinkingLevel must be one of ${THINKING.join(", ")}`;
+    }
+    const request = {
+        prompt: input.prompt,
+        maxTurns,
+        parentToolCallId: ctx.toolCallId,
+        signal: ctx.signal,
+        onUpdate: (partial) => ctx.onUpdate(partial),
+    };
+    if (input.description !== undefined)
+        request.description = input.description;
+    if (input.tools !== undefined)
+        request.tools = input.tools.filter((t) => t !== "task");
+    if (input.model !== undefined)
+        request.model = input.model;
+    if (input.thinkingLevel !== undefined)
+        request.thinkingLevel = input.thinkingLevel;
+    return request;
+}
+export function createTaskTool(_options = {}) {
+    return {
+        name: "task",
+        label: "Task",
+        description: "Delegate to a fresh sub-agent. It cannot see this chat: give full instructions. " +
+            "Returns its final answer.",
+        parameters: {
+            type: "object",
+            properties: {
+                prompt: { type: "string" },
+                description: { type: "string", description: "Label" },
+                tools: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Default: all but task",
+                },
+                model: { type: "string", description: "provider/model" },
+                thinkingLevel: { type: "string", enum: [...THINKING] },
+                maxTurns: { type: "integer", description: `Default ${DEFAULT_TASK_MAX_TURNS}` },
+            },
+            required: ["prompt"],
+            additionalProperties: false,
+        },
+        permission: "execute",
+        executionMode: "sequential",
+        promptSnippet: "task: run a sub-agent",
+        async execute(input, ctx) {
+            if (ctx.depth >= MAX_TASK_DEPTH || ctx.spawnSubagent === undefined) {
+                return fail("Sub-agents are not available here (nested tasks are not allowed).");
+            }
+            const request = buildSubagentRequest(input, ctx);
+            if (typeof request === "string")
+                return fail(request);
+            if (ctx.signal.aborted)
+                return fail("aborted by user");
+            try {
+                const result = await ctx.spawnSubagent(request);
+                const details = {
+                    ...(result.sessionFile !== undefined ? { sessionFile: result.sessionFile } : {}),
+                    usage: result.usage,
+                    stopReason: result.stopReason,
+                };
+                if (ctx.signal.aborted)
+                    return { content: "aborted by user", isError: true, details };
+                const text = result.text.trim() === "" ? "(the sub-agent returned no text)" : result.text;
+                return { content: text, isError: result.isError, details };
+            }
+            catch (err) {
+                if (ctx.signal.aborted)
+                    return fail("aborted by user");
+                return fail(`Sub-agent failed: ${err.message}`);
+            }
+        },
+    };
+}

package/dist/tools/todo.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `todo` 工具（设计 §5.2）。[B3]
+ *
+ * 会话内任务清单：`set` 整表替换并写 `custom{customType:"ama.todo"}` 条目（不进上下文），`get`
+ * 读活动分支上最近一条。`renderTodoList()` 给 TUI / 结果文本共用。待定项「todo 是否进系统提示」：
+ * 第一期不进（只有 promptSnippet 一行说明工具存在）。
+ */
+import type { ToolContext, ToolDefinition, ToolResult } from "./types.js";
+export declare const TODO_CUSTOM_TYPE = "ama.todo";
+export type TodoStatus = "pending" | "in_progress" | "done";
+export interface TodoItem {
+    id: string;
+    text: string;
+    status: TodoStatus;
+}
+export interface TodoState {
+    items: TodoItem[];
+}
+export interface TodoInput {
+    action: "set" | "get";
+    items?: TodoItem[];
+}
+export declare function validateTodoItems(items: unknown): string | undefined;
+/** 读当前清单；无记录或形状不对返回空表。 */
+export declare function readTodoState(ctx: Pick<ToolContext, "session">): TodoState;
+export declare function renderTodoList(items: readonly TodoItem[]): string[];
+export declare function executeTodo(input: TodoInput, ctx: ToolContext): Promise<ToolResult>;
+export declare function createTodoTool(): ToolDefinition<TodoInput>;

package/dist/tools/todo.js

@@ -0,0 +1,107 @@
+/**
+ * `todo` 工具（设计 §5.2）。[B3]
+ *
+ * 会话内任务清单：`set` 整表替换并写 `custom{customType:"ama.todo"}` 条目（不进上下文），`get`
+ * 读活动分支上最近一条。`renderTodoList()` 给 TUI / 结果文本共用。待定项「todo 是否进系统提示」：
+ * 第一期不进（只有 promptSnippet 一行说明工具存在）。
+ */
+export const TODO_CUSTOM_TYPE = "ama.todo";
+const STATUSES = ["pending", "in_progress", "done"];
+const MARK = { pending: "[ ]", in_progress: "[~]", done: "[x]" };
+export function validateTodoItems(items) {
+    if (!Array.isArray(items))
+        return "items must be an array";
+    const ids = new Set();
+    for (const [i, item] of items.entries()) {
+        if (typeof item !== "object" || item === null)
+            return `items[${i}] must be an object`;
+        const { id, text, status } = item;
+        if (typeof id !== "string" || id === "")
+            return `items[${i}].id must be a non-empty string`;
+        if (typeof text !== "string" || text === "")
+            return `items[${i}].text must be a non-empty string`;
+        if (!STATUSES.includes(status)) {
+            return `items[${i}].status must be one of ${STATUSES.join(", ")}`;
+        }
+        if (ids.has(id))
+            return `duplicate id "${id}"`;
+        ids.add(id);
+    }
+    return undefined;
+}
+/** 读当前清单；无记录或形状不对返回空表。 */
+export function readTodoState(ctx) {
+    const data = ctx.session.lastCustom(TODO_CUSTOM_TYPE);
+    if (typeof data === "object" && data !== null && Array.isArray(data.items)) {
+        const items = data.items;
+        if (validateTodoItems(items) === undefined)
+            return { items: items.map((it) => ({ ...it })) };
+    }
+    return { items: [] };
+}
+export function renderTodoList(items) {
+    if (items.length === 0)
+        return ["(no tasks)"];
+    return items.map((it) => `${MARK[it.status]} ${it.id}. ${it.text}`);
+}
+function summary(items) {
+    const done = items.filter((it) => it.status === "done").length;
+    return `${done}/${items.length} done`;
+}
+export async function executeTodo(input, ctx) {
+    if (input.action === "get") {
+        const state = readTodoState(ctx);
+        return {
+            content: [`Tasks (${summary(state.items)}):`, ...renderTodoList(state.items)].join("\n"),
+            details: state,
+        };
+    }
+    if (input.action !== "set")
+        return { content: 'action must be "set" or "get"', isError: true };
+    const problem = validateTodoItems(input.items ?? []);
+    if (problem !== undefined)
+        return { content: problem, isError: true };
+    const state = { items: (input.items ?? []).map((it) => ({ ...it })) };
+    ctx.session.appendCustom(TODO_CUSTOM_TYPE, state);
+    return {
+        content: [`Updated tasks (${summary(state.items)}):`, ...renderTodoList(state.items)].join("\n"),
+        details: state,
+    };
+}
+export function createTodoTool() {
+    return {
+        name: "todo",
+        label: "Todo",
+        description: "Session task list for multi-step work: `set` replaces the whole list, `get` returns it.",
+        parameters: {
+            type: "object",
+            properties: {
+                action: { type: "string", enum: ["set", "get"] },
+                items: {
+                    type: "array",
+                    description: "Full list (set)",
+                    items: {
+                        type: "object",
+                        properties: {
+                            id: { type: "string" },
+                            text: { type: "string" },
+                            status: { type: "string", enum: ["pending", "in_progress", "done"] },
+                        },
+                        required: ["id", "text", "status"],
+                        additionalProperties: false,
+                    },
+                },
+            },
+            required: ["action"],
+            additionalProperties: false,
+        },
+        permission: "read",
+        executionMode: "parallel",
+        promptSnippet: "todo: track multi-step work",
+        execute: executeTodo,
+        renderResult: (result) => {
+            const state = result.details;
+            return state && Array.isArray(state.items) ? renderTodoList(state.items) : [];
+        },
+    };
+}

package/dist/tools/truncate.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 头 / 尾截断（行数 + 字节双阈值，先到者为准）与全文落盘（设计 §5.2、§4.4）。[B3]
+ *
+ * - read / grep 用**头截断**（保留开头，提示 offset 续读）；bash 用**尾截断**（保留结尾）。
+ * - 字节按 UTF-8 计；不切断多字节字符；单行超过字节上限时按字符边界截该行。
+ */
+export declare const DEFAULT_MAX_LINES = 2000;
+export declare const DEFAULT_MAX_BYTES: number;
+/** grep 匹配行的字符上限。 */
+export declare const GREP_MAX_LINE_CHARS = 500;
+export interface TruncateOptions {
+    maxLines?: number;
+    maxBytes?: number;
+}
+export interface TruncateResult {
+    content: string;
+    truncated: boolean;
+    /** 哪个阈值先到；未截断为 null。 */
+    truncatedBy: "lines" | "bytes" | null;
+    totalLines: number;
+    totalBytes: number;
+    outputLines: number;
+    outputBytes: number;
+}
+export declare function byteLength(text: string): number;
+/** 末尾换行不算一行：`"a\nb\n"` 是 2 行。 */
+export declare function splitLines(text: string): string[];
+/** 按 UTF-8 字节数从头截取，不切断字符。 */
+export declare function sliceHeadBytes(text: string, maxBytes: number): string;
+/** 按 UTF-8 字节数从尾截取，不切断字符。 */
+export declare function sliceTailBytes(text: string, maxBytes: number): string;
+/** 保留开头。 */
+export declare function truncateHead(text: string, options?: TruncateOptions): TruncateResult;
+/** 保留结尾。 */
+export declare function truncateTail(text: string, options?: TruncateOptions): TruncateResult;
+/** 单行按字符截断，附省略提示。 */
+export declare function truncateLine(line: string, maxChars?: number): string;
+export declare function formatSize(bytes: number): string;
+/** 截断全文的落盘目录：`ctx.outputDir`，内存会话落到系统临时目录。 */
+export declare function resolveOutputDir(outputDir: string | undefined): string;
+/** 文件名里只保留安全字符。 */
+export declare function safeFileName(name: string): string;
+/** 写全文，返回绝对路径。 */
+export declare function writeFullOutput(outputDir: string | undefined, fileName: string, content: string | Buffer): string;

package/dist/tools/truncate.js

@@ -0,0 +1,175 @@
+/**
+ * 头 / 尾截断（行数 + 字节双阈值，先到者为准）与全文落盘（设计 §5.2、§4.4）。[B3]
+ *
+ * - read / grep 用**头截断**（保留开头，提示 offset 续读）；bash 用**尾截断**（保留结尾）。
+ * - 字节按 UTF-8 计；不切断多字节字符；单行超过字节上限时按字符边界截该行。
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+export const DEFAULT_MAX_LINES = 2000;
+export const DEFAULT_MAX_BYTES = 50 * 1024;
+/** grep 匹配行的字符上限。 */
+export const GREP_MAX_LINE_CHARS = 500;
+export function byteLength(text) {
+    return Buffer.byteLength(text, "utf8");
+}
+/** 末尾换行不算一行：`"a\nb\n"` 是 2 行。 */
+export function splitLines(text) {
+    if (text === "")
+        return [];
+    const lines = text.split("\n");
+    if (lines[lines.length - 1] === "")
+        lines.pop();
+    return lines;
+}
+/** 按 UTF-8 字节数从头截取，不切断字符。 */
+export function sliceHeadBytes(text, maxBytes) {
+    const buf = Buffer.from(text, "utf8");
+    if (buf.length <= maxBytes)
+        return text;
+    let end = maxBytes;
+    // 回退到字符起始字节（10xxxxxx 是续字节）。
+    while (end > 0 && ((buf[end] ?? 0) & 0xc0) === 0x80)
+        end--;
+    return buf.subarray(0, end).toString("utf8");
+}
+/** 按 UTF-8 字节数从尾截取，不切断字符。 */
+export function sliceTailBytes(text, maxBytes) {
+    const buf = Buffer.from(text, "utf8");
+    if (buf.length <= maxBytes)
+        return text;
+    let start = buf.length - maxBytes;
+    while (start < buf.length && ((buf[start] ?? 0) & 0xc0) === 0x80)
+        start++;
+    return buf.subarray(start).toString("utf8");
+}
+function limits(options) {
+    return {
+        maxLines: options.maxLines ?? DEFAULT_MAX_LINES,
+        maxBytes: options.maxBytes ?? DEFAULT_MAX_BYTES,
+    };
+}
+/** 保留开头。 */
+export function truncateHead(text, options = {}) {
+    const { maxLines, maxBytes } = limits(options);
+    const lines = splitLines(text);
+    const totalBytes = byteLength(text);
+    if (lines.length <= maxLines && totalBytes <= maxBytes) {
+        return {
+            content: text,
+            truncated: false,
+            truncatedBy: null,
+            totalLines: lines.length,
+            totalBytes,
+            outputLines: lines.length,
+            outputBytes: totalBytes,
+        };
+    }
+    const out = [];
+    let bytes = 0;
+    let truncatedBy = "lines";
+    for (const line of lines) {
+        if (out.length >= maxLines) {
+            truncatedBy = "lines";
+            break;
+        }
+        const cost = byteLength(line) + (out.length > 0 ? 1 : 0);
+        if (bytes + cost > maxBytes) {
+            truncatedBy = "bytes";
+            if (out.length === 0)
+                out.push(sliceHeadBytes(line, maxBytes));
+            break;
+        }
+        out.push(line);
+        bytes += cost;
+    }
+    const content = out.join("\n");
+    return {
+        content,
+        truncated: true,
+        truncatedBy,
+        totalLines: lines.length,
+        totalBytes,
+        outputLines: out.length,
+        outputBytes: byteLength(content),
+    };
+}
+/** 保留结尾。 */
+export function truncateTail(text, options = {}) {
+    const { maxLines, maxBytes } = limits(options);
+    const lines = splitLines(text);
+    const totalBytes = byteLength(text);
+    if (lines.length <= maxLines && totalBytes <= maxBytes) {
+        return {
+            content: text,
+            truncated: false,
+            truncatedBy: null,
+            totalLines: lines.length,
+            totalBytes,
+            outputLines: lines.length,
+            outputBytes: totalBytes,
+        };
+    }
+    const out = [];
+    let bytes = 0;
+    let truncatedBy = "lines";
+    for (let i = lines.length - 1; i >= 0; i--) {
+        if (out.length >= maxLines) {
+            truncatedBy = "lines";
+            break;
+        }
+        const line = lines[i] ?? "";
+        const cost = byteLength(line) + (out.length > 0 ? 1 : 0);
+        if (bytes + cost > maxBytes) {
+            truncatedBy = "bytes";
+            if (out.length === 0)
+                out.push(sliceTailBytes(line, maxBytes));
+            break;
+        }
+        out.push(line);
+        bytes += cost;
+    }
+    out.reverse();
+    const content = out.join("\n");
+    return {
+        content,
+        truncated: true,
+        truncatedBy,
+        totalLines: lines.length,
+        totalBytes,
+        outputLines: out.length,
+        outputBytes: byteLength(content),
+    };
+}
+/** 单行按字符截断，附省略提示。 */
+export function truncateLine(line, maxChars = GREP_MAX_LINE_CHARS) {
+    const chars = Array.from(line);
+    if (chars.length <= maxChars)
+        return line;
+    return `${chars.slice(0, maxChars).join("")}… [${chars.length - maxChars} more chars]`;
+}
+export function formatSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+/** 截断全文的落盘目录：`ctx.outputDir`，内存会话落到系统临时目录。 */
+export function resolveOutputDir(outputDir) {
+    return outputDir ?? join(tmpdir(), "ama-outputs");
+}
+/** 文件名里只保留安全字符。 */
+export function safeFileName(name) {
+    const cleaned = name.replace(/[^A-Za-z0-9._-]/g, "_");
+    return cleaned === "" ? "output" : cleaned.slice(0, 120);
+}
+/** 写全文，返回绝对路径。 */
+export function writeFullOutput(outputDir, fileName, content) {
+    const dir = resolveOutputDir(outputDir);
+    mkdirSync(dir, { recursive: true });
+    const target = join(dir, safeFileName(fileName));
+    writeFileSync(target, content);
+    return target;
+}