@armadra/agent 0.0.0-stage → 0.2.1

package/dist/tools/types.d.ts

@@ -0,0 +1,135 @@
+/**
+ * 工具契约（设计 §5.1）。[B0] 契约文件，实现归 B3；也从 `./host` 再导出。
+ *
+ * 补全与偏差：
+ * - `ToolContext.readFiles` 是只读集合，但 read 工具要「成功后加入」——增加 `markRead(path)`。
+ * - bash 要注入 `AMA_PROVIDER / AMA_MODEL / AMA_THINKING`（§5.2），增加 `model` 与 `thinkingLevel`。
+ * - 截断全文落 `<sessionDir>/outputs/<toolCallId>.txt`（§4.4），增加 `outputDir`
+ *   （内存会话为 undefined，实现自行落到临时目录）。
+ * - todo 工具要写 / 读 `custom` 条目，增加 `session.appendCustom / lastCustom`。
+ * - task 工具要开子会话，但 B3 不得 import B2 的实现——增加 `spawnSubagent`，由
+ *   AgentSession（B2）在构造 ToolContext 时提供；子 Agent（depth ≥ 1）里为 undefined。
+ * - `defineTool()` 是恒等函数，只为推断 `I`；放在契约文件里供 SDK 再导出。
+ * - `ToolRegistryApi` 是 Runtime 需要的最小接口，B3 的 `ToolRegistry` 实现它。
+ * - （W3-C0）`SubagentResult.cache` 可选：子会话的命中率与重计费 token。
+ */
+import type { ContentBlock, JsonSchema, ModelRef, ModelThinkingLevel, Usage } from "../ai/types.js";
+export type { JsonSchema } from "../ai/types.js";
+/** 权限管线的粗分类（§7）。 */
+export type ToolPermission = "read" | "write" | "execute";
+export type ToolExecutionMode = "sequential" | "parallel";
+export interface ToolAnnotations {
+    readOnly?: boolean;
+    destructive?: boolean;
+    openWorld?: boolean;
+}
+export interface ToolDefinition<I = unknown> {
+    /** `^[a-z][a-z0-9_]{1,63}$`；宿主工具建议前缀（canvas_*）。 */
+    readonly name: string;
+    /** TUI 标题。 */
+    readonly label?: string;
+    readonly description: string;
+    readonly parameters: JsonSchema;
+    readonly permission: ToolPermission;
+    /** 缺省：read → parallel；write / execute → sequential。 */
+    readonly executionMode?: ToolExecutionMode;
+    readonly annotations?: ToolAnnotations;
+    /** 系统提示 tools 节一行。 */
+    readonly promptSnippet?: string;
+    /** 系统提示 rules 节。 */
+    readonly promptGuidelines?: readonly string[];
+    execute(input: I, ctx: ToolContext): Promise<ToolResult>;
+    /** TUI 可选自定义渲染。 */
+    renderCall?(input: I, width: number): string[];
+    renderResult?(result: ToolResult, width: number, expanded: boolean): string[];
+}
+export interface ToolResult {
+    content: string | ContentBlock[];
+    isError?: boolean;
+    /** 落盘，不进上下文。 */
+    details?: unknown;
+    structured?: unknown;
+    /** 整批工具结果都为 true 才提前结束 run。 */
+    terminate?: boolean;
+}
+export interface SubagentRequest {
+    prompt: string;
+    description?: string;
+    /** 缺省 = 父活动集去掉 task。 */
+    tools?: string[];
+    /** `provider/model-id`；缺省继承父。 */
+    model?: string;
+    thinkingLevel?: ModelThinkingLevel;
+    /** 缺省 30。 */
+    maxTurns?: number;
+    /** 父 toolCallId（写入子会话的 custom{ama.task}）。 */
+    parentToolCallId: string;
+    signal: AbortSignal;
+    onUpdate?(partial: string): void;
+}
+export interface SubagentResult {
+    /** 子会话最后一条助手文本。 */
+    text: string;
+    sessionFile?: string;
+    usage: Usage;
+    stopReason: string;
+    isError: boolean;
+    /**
+     * [W3-C0] 子会话自己的缓存统计（第三波 §1.9），供 task 结果 details 与 `/session` 的
+     * 「子任务」行；子会话未接缓存控制器时缺省。
+     */
+    cache?: {
+        hitRate?: number;
+        reBilledTokens: number;
+    };
+}
+export interface ToolContext {
+    readonly toolCallId: string;
+    readonly cwd: string;
+    readonly sessionId: string;
+    readonly sessionFile?: string;
+    readonly signal: AbortSignal;
+    /** task 深度：主会话 0，子 Agent 1。 */
+    readonly depth: number;
+    readonly model?: ModelRef;
+    readonly thinkingLevel?: ModelThinkingLevel;
+    /** 截断全文的落盘目录（`<sessionDir>/outputs`）；内存会话为 undefined。 */
+    readonly outputDir?: string;
+    onUpdate(partial: string): void;
+    /** 本会话已 read 的绝对路径（write / edit 先读后写检查）。 */
+    readonly readFiles: ReadonlySet<string>;
+    markRead(absolutePath: string): void;
+    /**
+     * 嵌套调用其它工具（codemode 脚本、task），受同一管线；按全部未禁用工具查找（不限于活动集），
+     * 发带 `parentToolCallId` 的 tool_execution_* 事件。`signal`：与 ctx.signal 合并，用于提前取消
+     * 这一次嵌套调用（codemode 脚本结束时取消仍在跑的调用）。
+     */
+    readonly tools: {
+        executeTool(name: string, input: unknown, options?: {
+            signal?: AbortSignal;
+        }): Promise<ToolResult>;
+    };
+    readonly session: {
+        /** 追加 custom 条目（不进上下文）。 */
+        appendCustom(customType: string, data: unknown): void;
+        /** 活动分支上最近一条该类型 custom 条目的 data。 */
+        lastCustom(customType: string): unknown;
+    };
+    /** 仅 depth 0 且 task 可用时存在。 */
+    readonly spawnSubagent?: (request: SubagentRequest) => Promise<SubagentResult>;
+    log(level: "debug" | "info" | "warn", message: string): void;
+}
+export type ToolSource = "builtin" | "host" | "sdk";
+export interface ToolRegistryApi {
+    /** 同名已存在则抛 AmaError{code:"tool_exists"}。 */
+    register(tool: ToolDefinition, source: ToolSource): void;
+    disable(name: string): void;
+    get(name: string): ToolDefinition | undefined;
+    /** 已注册且未禁用的名字，按名排序。 */
+    list(): readonly string[];
+    /** 当前活动集（发给模型的工具），按名排序。 */
+    active(): readonly ToolDefinition[];
+    setActive(names: readonly string[]): void;
+}
+/** 恒等函数，帮助推断输入类型。 */
+export declare function defineTool<I>(tool: ToolDefinition<I>): ToolDefinition<I>;

package/dist/tools/types.js

@@ -0,0 +1,19 @@
+/**
+ * 工具契约（设计 §5.1）。[B0] 契约文件，实现归 B3；也从 `./host` 再导出。
+ *
+ * 补全与偏差：
+ * - `ToolContext.readFiles` 是只读集合，但 read 工具要「成功后加入」——增加 `markRead(path)`。
+ * - bash 要注入 `AMA_PROVIDER / AMA_MODEL / AMA_THINKING`（§5.2），增加 `model` 与 `thinkingLevel`。
+ * - 截断全文落 `<sessionDir>/outputs/<toolCallId>.txt`（§4.4），增加 `outputDir`
+ *   （内存会话为 undefined，实现自行落到临时目录）。
+ * - todo 工具要写 / 读 `custom` 条目，增加 `session.appendCustom / lastCustom`。
+ * - task 工具要开子会话，但 B3 不得 import B2 的实现——增加 `spawnSubagent`，由
+ *   AgentSession（B2）在构造 ToolContext 时提供；子 Agent（depth ≥ 1）里为 undefined。
+ * - `defineTool()` 是恒等函数，只为推断 `I`；放在契约文件里供 SDK 再导出。
+ * - `ToolRegistryApi` 是 Runtime 需要的最小接口，B3 的 `ToolRegistry` 实现它。
+ * - （W3-C0）`SubagentResult.cache` 可选：子会话的命中率与重计费 token。
+ */
+/** 恒等函数，帮助推断输入类型。 */
+export function defineTool(tool) {
+    return tool;
+}

package/dist/tools/write.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `write` 工具（设计 §5.2）。[B3]
+ *
+ * 整文件覆盖、自动建父目录；文件已存在且不在 `ctx.readFiles` → 错误「先 read」；若原文件有 BOM
+ * 或 CRLF，写回时保留（新内容自带 BOM / CRLF 时不重复加）。`details: { bytes, created }`。
+ */
+import type { ToolContext, ToolDefinition, ToolResult } from "./types.js";
+export interface WriteInput {
+    path: string;
+    content: string;
+}
+export interface WriteDetails {
+    path: string;
+    bytes: number;
+    created: boolean;
+}
+/** 按原文件的 BOM / 换行风格调整新内容。 */
+export declare function conformToOriginal(original: string, content: string): string;
+export declare function executeWrite(input: WriteInput, ctx: ToolContext): Promise<ToolResult>;
+export declare function createWriteTool(): ToolDefinition<WriteInput>;

package/dist/tools/write.js

@@ -0,0 +1,84 @@
+/**
+ * `write` 工具（设计 §5.2）。[B3]
+ *
+ * 整文件覆盖、自动建父目录；文件已存在且不在 `ctx.readFiles` → 错误「先 read」；若原文件有 BOM
+ * 或 CRLF，写回时保留（新内容自带 BOM / CRLF 时不重复加）。`details: { bytes, created }`。
+ */
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { displayPath, resolvePath } from "./paths.js";
+import { withFileMutex } from "./file-mutex.js";
+import { BOM, detectLineEnding, normalizeToLF, restoreLineEndings, splitBom, } from "./edit-fuzzy.js";
+async function exists(path) {
+    try {
+        const info = await stat(path);
+        return info.isDirectory() ? "dir" : "file";
+    }
+    catch {
+        return false;
+    }
+}
+/** 按原文件的 BOM / 换行风格调整新内容。 */
+export function conformToOriginal(original, content) {
+    const { bom, text } = splitBom(original);
+    const incoming = splitBom(content);
+    let body = incoming.text;
+    if (detectLineEnding(text) === "\r\n" && text.includes("\n")) {
+        body = restoreLineEndings(normalizeToLF(body), "\r\n");
+    }
+    return (bom !== "" || incoming.bom !== "" ? BOM : "") + body;
+}
+export async function executeWrite(input, ctx) {
+    const abs = resolvePath(input.path, ctx.cwd);
+    const shown = displayPath(abs, ctx.cwd);
+    if (typeof input.content !== "string") {
+        return { content: "content must be a string", isError: true };
+    }
+    return withFileMutex(abs, async () => {
+        const state = await exists(abs);
+        if (state === "dir")
+            return { content: `${shown} is a directory`, isError: true };
+        let output = input.content;
+        if (state === "file") {
+            if (!ctx.readFiles.has(abs)) {
+                return {
+                    content: `${shown} already exists. Read it with the read tool before overwriting it.`,
+                    isError: true,
+                };
+            }
+            output = conformToOriginal(await readFile(abs, "utf8"), input.content);
+        }
+        await mkdir(dirname(abs), { recursive: true });
+        await writeFile(abs, output, "utf8");
+        ctx.markRead(abs);
+        const details = {
+            path: abs,
+            bytes: Buffer.byteLength(output, "utf8"),
+            created: state === false,
+        };
+        const verb = details.created ? "Created" : "Overwrote";
+        return { content: `${verb} ${shown} (${details.bytes} bytes)`, details };
+    });
+}
+export function createWriteTool() {
+    return {
+        name: "write",
+        label: "Write",
+        description: "Write a file, replacing its entire content; parent directories are created. " +
+            "An existing file must be read first. Prefer the edit tool for partial changes.",
+        parameters: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "File path, absolute or relative to cwd" },
+                content: { type: "string", description: "Full new file content" },
+            },
+            required: ["path", "content"],
+            additionalProperties: false,
+        },
+        permission: "write",
+        executionMode: "sequential",
+        annotations: { destructive: true },
+        promptSnippet: "write: create or overwrite a whole file (read existing files first)",
+        execute: executeWrite,
+    };
+}

package/dist/tui/ansi.d.ts

@@ -0,0 +1,29 @@
+/**
+ * ANSI 与列宽工具（设计 §12.1、§12.2）。[B4]
+ *
+ * - 列宽按字素簇（grapheme）计：东亚宽字符与 emoji 占 2 列，组合字符 / 零宽字符占 0 列，
+ *   控制字符占 0 列；CSI / OSC / APC / DCS 等转义序列不占列。
+ * - 宽度表自写（零依赖）：东亚宽 / 全角区段 + Unicode 属性转义（`\p{Emoji_Presentation}` 等）。
+ * - 所有截断 / 切片在保留 SGR 样式的同时，于末尾补 `\x1b[0m`，保证「每行末尾重置样式」。
+ */
+export declare const SGR_RESET = "\u001B[0m";
+/** 单个码点的列宽（0 / 1 / 2）。 */
+export declare function codePointWidth(cp: number): 0 | 1 | 2;
+/** 一个字素簇的列宽：首码点决定基础宽度；VS16（U+FE0F）把文本型 emoji 升为 2 列。 */
+export declare function graphemeWidth(grapheme: string): number;
+/** 从 i 起的转义序列长度；不是转义序列返回 0。未终止的序列吃到字符串末尾。 */
+export declare function escapeLengthAt(s: string, i: number): number;
+export declare function stripAnsi(s: string): string;
+/** 可见列宽：跳过 ANSI 转义序列，按字素簇计宽。 */
+export declare function visibleWidth(s: string): number;
+/** 截断到不超过 width 列；超出时以 ellipsis 结尾；含样式时末尾补重置。 */
+export declare function truncateToWidth(s: string, width: number, ellipsis?: string): string;
+/**
+ * 取 [start, end) 列区间。开头补上 start 处生效的 SGR，末尾补重置；
+ * 被边界切开的宽字符用空格代替，保证结果恰好占 end - start 列（不足时按原内容）。
+ */
+export declare function sliceByColumn(s: string, start: number, end: number): string;
+/** 右侧补空格到 width 列（已超出则原样返回）。 */
+export declare function padToWidth(s: string, width: number): string;
+/** 自动换行：按空白断词，超长词按字素断开；样式跨行延续（行尾重置、下一行开头恢复）。 */
+export declare function wrapTextWithAnsi(text: string, width: number): string[];