@armadra/agent 0.0.0-stage → 0.3.0

package/dist/skills/frontmatter.js

@@ -0,0 +1,157 @@
+/**
+ * YAML 头**子集**解析（设计 §5.3、§2「YAML 只支持 frontmatter 子集自写」）。[B3]
+ *
+ * 支持：首行 `---` 到下一个 `---` / `...` 之间的
+ * - `key: value`（值为裸字串、单 / 双引号字串、`true/false`、整数 / 小数、`null` / `~`）；
+ * - 行内数组 `key: [a, "b", 3]`；块数组（`key:` 后跟 `- item` 行）；
+ * - `#` 注释（引号外）与空行。
+ * 不支持：嵌套映射、多行块标量（`|` / `>`）、锚点——遇到时记一条错误并跳过该键。
+ */
+function stripComment(text) {
+    let quote;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (quote) {
+            if (ch === "\\" && quote === '"')
+                i++;
+            else if (ch === quote)
+                quote = undefined;
+        }
+        else if (ch === '"' || ch === "'") {
+            quote = ch;
+        }
+        else if (ch === "#" && (i === 0 || /\s/.test(text[i - 1] ?? ""))) {
+            return text.slice(0, i).trimEnd();
+        }
+    }
+    return text.trimEnd();
+}
+function unquote(text) {
+    if (text.length >= 2 && text.startsWith('"') && text.endsWith('"')) {
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text.slice(1, -1);
+        }
+    }
+    if (text.length >= 2 && text.startsWith("'") && text.endsWith("'")) {
+        return text.slice(1, -1).replace(/''/g, "'");
+    }
+    return undefined;
+}
+export function parseScalar(raw) {
+    const text = raw.trim();
+    const quoted = unquote(text);
+    if (quoted !== undefined)
+        return quoted;
+    if (text === "" || text === "null" || text === "~")
+        return null;
+    if (text === "true" || text === "True" || text === "TRUE")
+        return true;
+    if (text === "false" || text === "False" || text === "FALSE")
+        return false;
+    if (/^-?\d+(\.\d+)?$/.test(text))
+        return Number(text);
+    return text;
+}
+function splitInlineArray(inner) {
+    const out = [];
+    let current = "";
+    let quote;
+    for (const ch of inner) {
+        if (quote) {
+            if (ch === quote)
+                quote = undefined;
+            current += ch;
+        }
+        else if (ch === '"' || ch === "'") {
+            quote = ch;
+            current += ch;
+        }
+        else if (ch === ",") {
+            out.push(current);
+            current = "";
+        }
+        else
+            current += ch;
+    }
+    if (current.trim() !== "")
+        out.push(current);
+    return out;
+}
+/** 拆出头与正文；不以 `---` 开头视为无头。 */
+export function splitFrontmatter(text) {
+    const normalized = text.replace(/^\uFEFF/, "").replace(/\r\n/g, "\n");
+    const lines = normalized.split("\n");
+    if (lines[0]?.trim() !== "---")
+        return { header: undefined, body: normalized };
+    for (let i = 1; i < lines.length; i++) {
+        const t = lines[i]?.trim();
+        if (t === "---" || t === "...") {
+            return { header: lines.slice(1, i), body: lines.slice(i + 1).join("\n") };
+        }
+    }
+    return { header: undefined, body: normalized };
+}
+export function parseFrontmatter(text) {
+    const { header, body } = splitFrontmatter(text);
+    const result = {
+        data: {},
+        body,
+        hasFrontmatter: header !== undefined,
+        errors: [],
+    };
+    if (!header)
+        return result;
+    let listKey;
+    const emptyKeys = new Set();
+    header.forEach((rawLine, index) => {
+        const lineNo = index + 2;
+        const line = stripComment(rawLine);
+        if (line.trim() === "")
+            return;
+        const item = /^\s+-\s*(.*)$|^-\s+(.*)$/.exec(line);
+        if (item && listKey !== undefined) {
+            const arr = result.data[listKey];
+            if (Array.isArray(arr))
+                arr.push(parseScalar(item[1] ?? item[2] ?? ""));
+            emptyKeys.delete(listKey);
+            return;
+        }
+        if (/^\s/.test(line)) {
+            result.errors.push(`line ${lineNo}: nested values are not supported`);
+            return;
+        }
+        const m = /^([A-Za-z0-9_][A-Za-z0-9_.-]*)\s*:(?:\s+(.*)|\s*)$/.exec(line);
+        if (!m) {
+            result.errors.push(`line ${lineNo}: expected "key: value"`);
+            listKey = undefined;
+            return;
+        }
+        const key = m[1];
+        const value = (m[2] ?? "").trim();
+        listKey = undefined;
+        if (value === "") {
+            result.data[key] = [];
+            listKey = key;
+            emptyKeys.add(key);
+        }
+        else if (value === "|" || value === ">" || /^[|>][+-]?$/.test(value)) {
+            result.errors.push(`line ${lineNo}: block scalars are not supported (key "${key}")`);
+        }
+        else if (value.startsWith("[") && value.endsWith("]")) {
+            result.data[key] = splitInlineArray(value.slice(1, -1)).map(parseScalar);
+        }
+        else if (value.startsWith("{")) {
+            result.errors.push(`line ${lineNo}: inline mappings are not supported (key "${key}")`);
+        }
+        else {
+            result.data[key] = parseScalar(value);
+        }
+    });
+    // `key:` 后没有列表项 → null。
+    for (const key of emptyKeys)
+        result.data[key] = null;
+    return result;
+}

package/dist/skills/index-prompt.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `<available_skills>` 索引（设计 §5.3 三级披露第一级）。[B3]
+ *
+ * 放进系统提示 `skills` 节。`disable-model-invocation: true` 的技能不进索引；有 `skill` 工具时
+ * 引导用它，否则用 `read`，都没有时不生成索引（返回空串）。
+ */
+import type { Skill } from "./discover.js";
+export interface SkillIndexOptions {
+    hasSkillTool: boolean;
+    hasReadTool: boolean;
+}
+export declare function escapeXml(text: string): string;
+export declare function formatSkillIndex(skills: readonly Pick<Skill, "name" | "description" | "location" | "disableModelInvocation">[], options: SkillIndexOptions): string;

package/dist/skills/index-prompt.js

@@ -0,0 +1,42 @@
+/**
+ * `<available_skills>` 索引（设计 §5.3 三级披露第一级）。[B3]
+ *
+ * 放进系统提示 `skills` 节。`disable-model-invocation: true` 的技能不进索引；有 `skill` 工具时
+ * 引导用它，否则用 `read`，都没有时不生成索引（返回空串）。
+ */
+export function escapeXml(text) {
+    return text
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&apos;");
+}
+export function formatSkillIndex(skills, options) {
+    const visible = skills.filter((s) => !s.disableModelInvocation);
+    if (visible.length === 0)
+        return "";
+    let how;
+    if (options.hasSkillTool) {
+        how =
+            "Call the skill tool with a skill's name to load it when the task matches its description.";
+    }
+    else if (options.hasReadTool) {
+        how = "Use the read tool to load a skill's file when the task matches its description.";
+    }
+    else {
+        return "";
+    }
+    const lines = [
+        "The following skills provide specialized instructions for specific tasks.",
+        how,
+        "When a skill file references a relative path, resolve it against the skill's directory.",
+        "",
+        "<available_skills>",
+    ];
+    for (const s of visible) {
+        lines.push("  <skill>", `    <name>${escapeXml(s.name)}</name>`, `    <description>${escapeXml(s.description)}</description>`, `    <location>${escapeXml(s.location)}</location>`, "  </skill>");
+    }
+    lines.push("</available_skills>");
+    return lines.join("\n");
+}

package/dist/skills/templates.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 提示模板 `prompts/<cmd>.md`（设计 §5.3）。[B3]
+ *
+ * - 发现：profile `promptDirs` → `<configDir>/prompts/` → `<cwd>/.ama/prompts/`（需信任）；只取目录
+ *   的直接 `*.md` 子文件，文件名即命令名；重名保留先发现者并 warning。frontmatter 可给
+ *   `description`（缺省取正文首个非空行）与 `argument-hint`。
+ * - 参数按 shell 规则切分（空白分隔，单 / 双引号，反斜杠转义）。
+ * - 占位：`$1…$N`、`$@` / `$ARGUMENTS`（全部参数）、`${N}`、`${N:-默认}`、`${@:-默认}`、`${@:N}`、
+ *   `${@:N:L}`；`\$` 为字面 `$`。模板里没有任何占位而用户给了参数时，参数接在正文后（空一行）。
+ */
+export interface PromptTemplate {
+    name: string;
+    path: string;
+    description: string;
+    argumentHint?: string;
+    scope: PromptScope;
+}
+export type PromptScope = "cli" | "profile" | "user" | "project";
+export interface PromptSource {
+    dir: string;
+    scope: PromptScope;
+    requiresTrust: boolean;
+}
+export declare const TEMPLATE_NAME_RE: RegExp;
+export declare function promptSources(options: {
+    cwd: string;
+    configDir: string;
+    cliDirs?: readonly string[];
+    profileDirs?: readonly string[];
+}): PromptSource[];
+export declare function discoverPromptTemplates(sources: readonly PromptSource[], options: {
+    trusted: boolean;
+}): Promise<{
+    templates: PromptTemplate[];
+    warnings: string[];
+    skippedUntrusted: string[];
+}>;
+/** shell 风格切分。 */
+export declare function parseCommandArgs(text: string): string[];
+export declare function hasPlaceholders(body: string): boolean;
+export declare function expandTemplate(body: string, args: readonly string[]): string;
+export interface PromptCommand {
+    name: string;
+    args: string[];
+    rawArgs: string;
+}
+export declare function parsePromptCommand(text: string): PromptCommand | undefined;
+/** `/name args` 命中模板则返回展开文本；否则 undefined（交给斜杠命令表）。 */
+export declare function expandPromptCommand(text: string, templates: readonly PromptTemplate[], read?: (path: string) => Promise<string>): Promise<{
+    text: string;
+    template: PromptTemplate;
+} | undefined>;

package/dist/skills/templates.js

@@ -0,0 +1,177 @@
+/**
+ * 提示模板 `prompts/<cmd>.md`（设计 §5.3）。[B3]
+ *
+ * - 发现：profile `promptDirs` → `<configDir>/prompts/` → `<cwd>/.ama/prompts/`（需信任）；只取目录
+ *   的直接 `*.md` 子文件，文件名即命令名；重名保留先发现者并 warning。frontmatter 可给
+ *   `description`（缺省取正文首个非空行）与 `argument-hint`。
+ * - 参数按 shell 规则切分（空白分隔，单 / 双引号，反斜杠转义）。
+ * - 占位：`$1…$N`、`$@` / `$ARGUMENTS`（全部参数）、`${N}`、`${N:-默认}`、`${@:-默认}`、`${@:N}`、
+ *   `${@:N:L}`；`\$` 为字面 `$`。模板里没有任何占位而用户给了参数时，参数接在正文后（空一行）。
+ */
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { parseFrontmatter } from "./frontmatter.js";
+export const TEMPLATE_NAME_RE = /^[a-z0-9][a-z0-9_-]*$/i;
+export function promptSources(options) {
+    const out = [];
+    for (const d of options.cliDirs ?? [])
+        out.push({ dir: resolve(options.cwd, d), scope: "cli", requiresTrust: false });
+    for (const d of options.profileDirs ?? []) {
+        out.push({ dir: resolve(options.cwd, d), scope: "profile", requiresTrust: false });
+    }
+    out.push({ dir: join(options.configDir, "prompts"), scope: "user", requiresTrust: false });
+    out.push({ dir: join(options.cwd, ".ama", "prompts"), scope: "project", requiresTrust: true });
+    return out;
+}
+export async function discoverPromptTemplates(sources, options) {
+    const templates = [];
+    const warnings = [];
+    const skippedUntrusted = [];
+    const seen = new Map();
+    for (const source of sources) {
+        let names;
+        try {
+            if (!(await stat(source.dir)).isDirectory())
+                continue;
+            names = await readdir(source.dir);
+        }
+        catch {
+            continue;
+        }
+        if (source.requiresTrust && !options.trusted) {
+            skippedUntrusted.push(source.dir);
+            continue;
+        }
+        for (const file of names.filter((n) => n.endsWith(".md")).sort()) {
+            const name = file.slice(0, -3);
+            const path = join(source.dir, file);
+            if (!TEMPLATE_NAME_RE.test(name)) {
+                warnings.push(`${path}: invalid command name "${name}"`);
+                continue;
+            }
+            const existing = seen.get(name);
+            if (existing) {
+                warnings.push(`${path}: prompt "/${name}" already defined at ${existing.path}; ignored`);
+                continue;
+            }
+            let text;
+            try {
+                if (!(await stat(path)).isFile())
+                    continue;
+                text = await readFile(path, "utf8");
+            }
+            catch {
+                continue;
+            }
+            const fm = parseFrontmatter(text);
+            const desc = fm.data["description"];
+            const firstLine = fm.body
+                .split("\n")
+                .find((l) => l.trim() !== "")
+                ?.trim() ?? "";
+            const template = {
+                name,
+                path,
+                description: typeof desc === "string" && desc !== "" ? desc : firstLine.slice(0, 80),
+                scope: source.scope,
+            };
+            const hint = fm.data["argument-hint"];
+            if (typeof hint === "string" && hint !== "")
+                template.argumentHint = hint;
+            seen.set(name, template);
+            templates.push(template);
+        }
+    }
+    return { templates, warnings, skippedUntrusted };
+}
+/** shell 风格切分。 */
+export function parseCommandArgs(text) {
+    const args = [];
+    let current = "";
+    let has = false;
+    let quote;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (quote === "'") {
+            if (ch === "'")
+                quote = undefined;
+            else
+                current += ch;
+        }
+        else if (quote === '"') {
+            if (ch === '"')
+                quote = undefined;
+            else if (ch === "\\" && (text[i + 1] === '"' || text[i + 1] === "\\"))
+                current += text[++i];
+            else
+                current += ch;
+        }
+        else if (ch === "'" || ch === '"') {
+            quote = ch;
+            has = true;
+        }
+        else if (ch === "\\" && i + 1 < text.length) {
+            current += text[++i];
+            has = true;
+        }
+        else if (/\s/.test(ch)) {
+            if (has || current !== "")
+                args.push(current);
+            current = "";
+            has = false;
+        }
+        else {
+            current += ch;
+        }
+    }
+    if (has || current !== "")
+        args.push(current);
+    return args;
+}
+const PLACEHOLDER = /\\\$|\$\{(@|\d+)(?::-([^}]*)|:(\d+)(?::(\d+))?)?\}|\$(ARGUMENTS|@|\d+)/g;
+export function hasPlaceholders(body) {
+    return [...body.matchAll(PLACEHOLDER)].some((m) => m[0] !== "\\$");
+}
+export function expandTemplate(body, args) {
+    const all = args.join(" ");
+    const expanded = body.replace(PLACEHOLDER, (whole, braced, def, start, len, bare) => {
+        if (whole === "\\$")
+            return "$";
+        const key = braced ?? bare;
+        if (key === "@" || key === "ARGUMENTS") {
+            if (start !== undefined) {
+                const from = Math.max(0, Number(start) - 1);
+                const slice = len !== undefined ? args.slice(from, from + Number(len)) : args.slice(from);
+                return slice.join(" ");
+            }
+            if (def !== undefined)
+                return args.length > 0 ? all : def;
+            return all;
+        }
+        const value = args[Number(key) - 1];
+        if (def !== undefined)
+            return value === undefined || value === "" ? def : value;
+        return value ?? "";
+    });
+    if (!hasPlaceholders(body) && args.length > 0)
+        return `${expanded.replace(/\s+$/, "")}\n\n${all}`;
+    return expanded;
+}
+export function parsePromptCommand(text) {
+    const m = /^\/([A-Za-z0-9][A-Za-z0-9_-]*)(?:[ \t]+([\s\S]*))?$/.exec(text.trim());
+    if (!m)
+        return undefined;
+    const rawArgs = (m[2] ?? "").trim();
+    return { name: m[1], args: parseCommandArgs(rawArgs), rawArgs };
+}
+/** `/name args` 命中模板则返回展开文本；否则 undefined（交给斜杠命令表）。 */
+export async function expandPromptCommand(text, templates, read = (p) => readFile(p, "utf8")) {
+    const cmd = parsePromptCommand(text);
+    if (!cmd)
+        return undefined;
+    const template = templates.find((t) => t.name === cmd.name);
+    if (!template)
+        return undefined;
+    const body = parseFrontmatter(await read(template.path)).body.replace(/^\n+/, "");
+    return { text: expandTemplate(body, cmd.args), template };
+}

package/dist/tools/bash.d.ts

@@ -0,0 +1,49 @@
+/**
+ * `bash` 工具（设计 §5.2、§4.2）。[B3]
+ *
+ * - `spawn(shell, args, { detached: !win, stdio: [ignore, pipe, pipe] })`，stdout / stderr 合流；
+ * - 超时（缺省 120 s，上限 600 s）与 abort 都走 `killProcessTree`：SIGTERM → 2 s → SIGKILL；
+ * - 滚动尾部节流后经 `ctx.onUpdate` 流出；超限（2000 行 / 50 KB）尾截断并落全文；
+ * - 结构化结果 `{ output, exit_code, truncated, full_output_path?, wall_time_seconds }`；
+ *   信号退出 `128 + signo`；非零退出码 → isError；
+ * - 注入 `AMA_*` 环境变量（shell.ts）。shell 退出后不等仍占着管道的后台进程。
+ */
+import type { ToolContext, ToolDefinition, ToolResult } from "./types.js";
+import { type ShellConfig } from "./shell.js";
+import { type ProcessDeps } from "./process-tree.js";
+export declare const DEFAULT_BASH_TIMEOUT_MS = 120000;
+export declare const MAX_BASH_TIMEOUT_MS = 600000;
+export interface BashInput {
+    command: string;
+    timeoutMs?: number;
+    cwd?: string;
+    description?: string;
+}
+export interface BashStructured {
+    output: string;
+    exit_code: number;
+    truncated: boolean;
+    full_output_path?: string;
+    wall_time_seconds: number;
+}
+export interface BashDetails extends BashStructured {
+    timedOut: boolean;
+    aborted: boolean;
+    killedWithSigkill: boolean;
+    totalLines: number;
+    totalBytes: number;
+    cwd: string;
+    description?: string;
+}
+export interface BashToolOptions {
+    /** config.tools.bashTimeoutMs；缺省 120 000。 */
+    defaultTimeoutMs?: number;
+    /** 测试注入：固定 shell 选择。 */
+    shell?(): ShellConfig;
+    /** 测试注入：杀树参数（宽限时间等）。 */
+    processDeps?: ProcessDeps;
+    /** 测试注入：基础环境，缺省 process.env。 */
+    baseEnv?(): NodeJS.ProcessEnv;
+}
+export declare function executeBash(input: BashInput, ctx: ToolContext, options?: BashToolOptions): Promise<ToolResult>;
+export declare function createBashTool(options?: BashToolOptions): ToolDefinition<BashInput>;