@armadra/agent 0.3.0 → 0.4.0

package/dist/modes/print/print-mode.js

@@ -1,15 +1,24 @@
 /**
  * print 模式（`ama -p`，设计 §11.1 第 15–16 步）。[B6]
  *
- * - 提示 = 位置参数 + stdin 管道（stdin 非 TTY 时读到 EOF），两者都有时空一行拼接；都没有 → 用法错误 2。
+ * - 提示 = 位置参数 + stdin，两者都有时空一行拼接；都没有 → 用法错误 2。stdin 的读法：
+ *   - 没有提示参数，或显式写了位置参数 `-`：读到 EOF（超过 3 s 时 stderr 提示一次正在等待）；
+ *   - 有提示参数且 stdin 是管道（shell 管道或父进程留的管道）：等首字节，`AMA_STDIN_WAIT_MS`
+ *     （缺省 2000，0 = 不等）内一个字节都没有 → 忽略 stdin 并在 stderr 提示；收到首字节后读到 EOF；
+ *   - stdin 是普通文件 / 空设备：直接读（不会卡）；TTY 或 `--no-stdin`：不读。
  * - 图片：`--image`（可重复）与提示里的 `@图片路径` / 图片文件路径作为附件（modes/image-input.ts）；
  *   显式附件遇到当前模型不收图片、文件不存在或超限 → 用法错误 2，不发请求。
  * - `--output-format text`（缺省）：运行结束后输出最后一条助手文本；`json`：一个结果对象（文本、
  *   停止原因、用量、缓存命中率、[W3-C2] `cache` 统计（同 `get_session_stats.cache`）、全部条目）；
  *   `stream-json`：每个会话事件一行（线上形状同 RPC，含 `cache_miss` / `cache_warm` /
  *   `context_pressure`）。
- * - 无人值守：ask → deny（bootstrap 已按 print 设 unattended）。
- * - 退出码：最终助手消息 `error / aborted` 或提示被拒 → 1；SIGINT 130、SIGTERM 143（先 abort）。
+ * - 重试：text / json 格式在 stderr 打一行 `↻ 重试 n/m`（stream-json 里本来就有事件），等待期间不再无声。
+ * - 无人值守：ask → deny（bootstrap 已按 print 设 unattended）。被拒的调用（`tool_execution_end`
+ *   带 `denied`）在 stderr 汇总一行（工具 ×次数、首个原因、放行办法），json 结果带 `deniedTools`。
+ * - `--max-turns N`：到达上限时若最后一条助手消息停在 toolUse（还有活没做完）→ stderr 一行、
+ *   json 带 `maxTurnsReached`、退出码 1。
+ * - 退出码：最终助手消息 `error / aborted` 或提示被拒 → 1；有工具调用被拒 → 7；SIGINT 130、
+ *   SIGTERM 143（先 abort）。
  */
 import { currentSession } from "../../cli/compose-session.js";
 import { ExitCode } from "../../cli/exit-codes.js";
@@ -20,10 +29,70 @@ export function joinPrompt(argument, piped) {
     const parts = [argument ?? "", piped.replace(/\s+$/, "")].filter((p) => p.trim() !== "");
     return parts.join("\n\n");
 }
+/** 等 stdin 多久后提示一次「正在等待」。 */
+export const STDIN_WAIT_HINT_MS = 3_000;
+/** 有提示参数时等管道首字节的缺省上限；`AMA_STDIN_WAIT_MS` 覆盖，0 = 不等待。 */
+export const STDIN_FIRST_BYTE_MS = 2_000;
+export function stdinWaitMs(env) {
+    const raw = env["AMA_STDIN_WAIT_MS"];
+    if (raw === undefined || raw.trim() === "")
+        return STDIN_FIRST_BYTE_MS;
+    const value = Number(raw);
+    return Number.isFinite(value) && value >= 0 ? value : STDIN_FIRST_BYTE_MS;
+}
+/** io 没有首字节读取时的退化：整段读取与超时赛跑。 */
+function readWithin(io, ms) {
+    if (io.readStdinFirstByte !== undefined)
+        return io.readStdinFirstByte(ms);
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => resolve(undefined), ms);
+        io.readStdin().then((text) => {
+            clearTimeout(timer);
+            resolve(text);
+        }, (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+}
+/**
+ * 决定读不读 stdin（规则见文件头）。`mode`：`auto` 按提示参数与 stdin 类型决定，`explicit`
+ * （位置参数 `-`）一直等到 EOF，`off`（`--no-stdin`）不读。
+ */
+export async function readPromptStdin(io, prompt, mode, hintMs = STDIN_WAIT_HINT_MS) {
+    if (io.stdinIsTTY || mode === "off")
+        return "";
+    const kind = io.stdinKind?.() ?? "other";
+    const safe = kind === "file" || kind === "null";
+    if (prompt !== undefined && prompt !== "" && mode === "auto" && !safe) {
+        const waitMs = stdinWaitMs(io.env);
+        if (waitMs === 0)
+            return "";
+        const text = await readWithin(io, waitMs);
+        if (text === undefined) {
+            io.stderr(`ama: 未在 ${formatSeconds(waitMs)}内收到管道输入，已忽略；需要等待请在末尾加 -\n`);
+            return "";
+        }
+        return text;
+    }
+    const timer = safe
+        ? undefined
+        : setTimeout(() => io.stderr("ama: 正在等待 stdin 输入结束（Ctrl+D 结束；提示也可以直接写成参数）…\n"), hintMs);
+    try {
+        return await io.readStdin();
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function formatSeconds(ms) {
+    return ms % 1000 === 0 ? `${ms / 1000} 秒` : `${ms} 毫秒`;
+}
 export async function runPrintMode(runtime, context) {
     const { io } = context;
     const format = context.args.outputFormat ?? "text";
-    const piped = io.stdinIsTTY ? "" : await io.readStdin();
+    const stdinMode = context.args.noStdin ? "off" : context.args.stdin ? "explicit" : "auto";
+    const piped = await readPromptStdin(io, context.prompt, stdinMode);
     const prompt = joinPrompt(context.prompt, piped);
     if (prompt === "") {
         io.stderr("ama: -p 需要提示（位置参数或 stdin 管道）\n");
@@ -38,9 +107,19 @@ export async function runPrintMode(runtime, context) {
         io.stderr(`ama: ${errorText(error)}\n`);
         return ExitCode.Usage;
     }
-    const unsubscribe = format === "stream-json"
-        ? session.subscribe((event) => io.stdout(`${toJsonLine(toWireEvent(event))}\n`))
-        : () => undefined;
+    const denied = [];
+    const unsubscribe = session.subscribe((event) => {
+        if (event.type === "tool_execution_end" && event.denied === true)
+            denied.push({
+                toolCallId: event.toolCallId,
+                toolName: event.toolName,
+                reason: textOf(event),
+            });
+        if (format === "stream-json")
+            io.stdout(`${toJsonLine(toWireEvent(event))}\n`);
+        else if (event.type === "auto_retry_start")
+            io.stderr(`ama: ↻ 重试 ${event.attempt}/${event.maxAttempts}（${Math.round(event.delayMs / 1000)}s 后）：${event.errorMessage}\n`);
+    });
     let signalled;
     const offSignals = onTerminationSignals((code) => {
         signalled ??= code;
@@ -65,6 +144,9 @@ export async function runPrintMode(runtime, context) {
     }
     const last = lastAssistant(session);
     const text = session.getLastAssistantText() ?? "";
+    // 回合上限在工具执行之后结束运行：最后一条助手消息停在 toolUse 即「没做完」
+    const maxTurns = context.args.maxTurns;
+    const turnsExhausted = maxTurns !== undefined && failure === undefined && last?.stopReason === "toolUse";
     const stopReason = failure !== undefined ? "error" : (last?.stopReason ?? "stop");
     if (format === "text") {
         // 部分模型在正文前多发空行：只去前导空行，保留首行缩进；json / stream-json 原样。
@@ -88,6 +170,8 @@ export async function runPrintMode(runtime, context) {
             cost: stats.cost,
             cacheHitRate: stats.cacheHitRate,
             ...(stats.cache !== undefined ? { cache: stats.cache } : {}),
+            ...(denied.length > 0 ? { deniedTools: denied } : {}),
+            ...(turnsExhausted ? { maxTurnsReached: true } : {}),
             entries: session.entries,
         })}\n`);
     }
@@ -103,5 +187,30 @@ export async function runPrintMode(runtime, context) {
         io.stderr(`ama: ${last.errorMessage ?? "模型调用失败"}\n`);
         return ExitCode.RuntimeError;
     }
+    if (denied.length > 0)
+        io.stderr(`${describeDenied(denied)}\n`);
+    if (turnsExhausted) {
+        io.stderr(`ama: 已达到 --max-turns ${maxTurns}，运行在完成前结束\n`);
+        return ExitCode.RuntimeError;
+    }
+    if (denied.length > 0)
+        return ExitCode.ToolDenied;
     return ExitCode.Ok;
 }
+function textOf(event) {
+    const content = event.result.content;
+    const text = typeof content === "string"
+        ? content
+        : content.map((b) => (b.type === "text" ? b.text : "")).join("");
+    return text.split("\n")[0]?.trim().slice(0, 200) ?? "";
+}
+/** stderr 一行：被拒的工具 ×次数、首个原因、放行办法。 */
+export function describeDenied(denied) {
+    const counts = new Map();
+    for (const item of denied)
+        counts.set(item.toolName, (counts.get(item.toolName) ?? 0) + 1);
+    const tools = [...counts].map(([name, n]) => `${name} ×${n}`).join("、");
+    const reason = denied[0]?.reason ?? "";
+    return (`ama: ${denied.length} 次工具调用被拒：${tools}${reason !== "" ? `（${reason}）` : ""}；` +
+        "-p 没有人审批，需要放行时用 --permission-mode auto-edit|auto 或 --allow <规则>");
+}

package/dist/modes/rpc/commands.js

@@ -14,6 +14,8 @@ import { AgentSessionImpl } from "../../agent/session.js";
 import { getSupportedLevels } from "../../ai/thinking.js";
 import { switchSession } from "../../cli/compose-session.js";
 import { AmaError } from "../../errors.js";
+import { isPermissionMode } from "../../permissions/modes.js";
+import { PERMISSION_MODES_STRICT_FIRST } from "../../permissions/types.js";
 import { BUILTIN_COMMANDS } from "../commands-core.js";
 /** 审批 broker：等客户端 `permission_response`。 */
 export class RpcApprovals {
@@ -254,6 +256,9 @@ export const handlers = {
         };
     },
     set_permission_mode: async (p, ctx) => {
+        if (!isPermissionMode(p.mode)) {
+            throw new AmaError("invalid_arguments", `mode 应为 ${PERMISSION_MODES_STRICT_FIRST.join(" | ")}`);
+        }
         ctx.session().setPermissionMode(p.mode);
         return { mode: p.mode };
     },

package/dist/permissions/auto-safe.d.ts

@@ -0,0 +1,60 @@
+/**
+ * auto 模式下 bash 的规则层与静态判定（§7.4，docs/permissions.md）。
+ *
+ * 规则层（命中即询问，不调模型）——外层与每层嵌套命令（`sh -c`、`eval`、`xargs`、`find -exec`，
+ * 见 dangerous.ts）的每一段都查：
+ * - 网络命令（{@link networkReason}）：curl / wget / ssh / git push|pull|fetch|clone / npm install / npx …
+ * - 删除与回退（{@link destructiveReason}）：rm -r|-f、find -delete、git clean / restore / checkout -- …
+ * - 写入目标：重定向（`>`、`>>`、`&>`）、tee、cp / mv / mkdir / touch / ln / chmod 等的目标在项目外或受保护；
+ * - 参数里出现机密路径（`cat .env`、`< ~/.ssh/id_rsa`、`--env-file=.env`）。
+ *
+ * 静态判定（全部满足即放行）：每一段都命中安全名单（{@link AUTO_SAFE_COMMANDS} + 用户追加），整条命令
+ * 没有命令替换、参数没有变量展开 `$X`、没有可能匹配点文件的通配、没有超深嵌套。
+ *
+ * 分段与分词复用 rules.ts / dangerous.ts（引号内不切、剥环境赋值与 env / nohup / time 等前缀）。
+ */
+export interface SafeCommandSpec {
+    /** 词前缀：`["git", "status"]` 命中 `git status -s`。git 的全局选项只允许 `-C <dir>` 与 `--no-pager`。 */
+    words: readonly string[];
+    /** 前缀之后任一参数命中即不安全。 */
+    forbid?: RegExp;
+    /** 前缀之后必须出现的参数。 */
+    require?: string;
+}
+/** 初始安全名单（每条在 auto-safe.test.ts 有正反例）。 */
+export declare const AUTO_SAFE_COMMANDS: readonly SafeCommandSpec[];
+/**
+ * 用户追加的安全命令（`permission.autoSafeCommands`）：不含 `*` 按词前缀；含 `*` 按通配匹配整段
+ * （剥过前缀、重定向之后的命令文本）。
+ */
+export declare function extraSafeMatches(argv: readonly string[], entry: string): boolean;
+/** 网络命令：返回说明；不是返回 undefined。 */
+export declare function networkReason(argv: readonly string[]): string | undefined;
+/** 删除与丢弃改动的命令：返回说明；不是返回 undefined。 */
+export declare function destructiveReason(argv: readonly string[]): string | undefined;
+export interface Redirects {
+    /** 输出重定向目标（`>`、`>>`、`>|`、`&>`）。 */
+    outputs: string[];
+    /** 输入重定向来源（`<`）。 */
+    inputs: string[];
+    /** 去掉重定向之后的段文本。 */
+    rest: string;
+}
+/** 从一段命令里取出重定向（引号内不算）；`2>&1`、`>&2` 是复制描述符，没有目标。 */
+export declare function extractRedirects(segment: string): Redirects;
+export interface BashAutoOptions {
+    cwd: string;
+    projectRoot: string;
+    /** `permission.autoSafeCommands`。 */
+    extraSafe?: readonly string[];
+}
+export interface BashAutoAnalysis {
+    /** 规则层要询问的原因；undefined = 规则层不管。 */
+    ask?: string;
+    /** 静态判定放行。 */
+    safe: boolean;
+    /** 不安全（交给分类器）的原因，审计用。 */
+    reason: string;
+}
+/** auto 模式下一条 bash 命令的规则层与静态判定结论。 */
+export declare function analyzeBashForAuto(command: string, options: BashAutoOptions): BashAutoAnalysis;