@armadra/agent 0.0.0-stage → 0.3.0

package/dist/session/types.d.ts

@@ -0,0 +1,201 @@
+/**
+ * 会话 JSONL 树契约（设计 §8，格式沿用 v1 §5）。[B0] 契约文件，实现归 B2。
+ *
+ * 补全与偏差：
+ * - `message` 条目只装 LLM 消息（`Message`：system / user / assistant / toolResult），
+ *   这样 session 不必反向依赖 agent。
+ * - 投影（projection.ts）产出的上下文消息 `AgentMessage` = `Message` + 三种非 LLM 角色
+ *   （custom / compactionSummary / branchSummary），定义在这里，agent/types.ts 再导出；
+ *   `convertToLlm` 负责把三种扩展角色转成 user 消息。
+ * - `context_edit.reason` 在 v1 的 prune / abort / manual 之外加 `retry`（§3.6 失败尝试剔除）
+ *   与 `overflow`（§9 溢出恢复剔除）。
+ * - `compaction` / `branch_summary` 的 details 统一为 `FileOpsDetails`。
+ * - 补全 `SessionTreeNode`、`SessionListItem` 与 B6 / B7 需要的 `SessionManagerApi`。
+ *   `append()` 同步：返回带 id 的条目并把叶子移到它（落盘可延迟到首条提示，§11.1 第 16 步）。
+ * - （W3-C0）第三波 §1.7 / A7：新增 `usage` 条目（保温等不进上下文的请求用量，计入统计）与
+ *   非条目的 `leaf` 行（`/tree` 位置落盘）；都是 v1 可选行，格式版本不升。
+ */
+import type { ContentBlock, Message, ModelThinkingLevel, Usage } from "../ai/types.js";
+export declare const SESSION_FORMAT_VERSION: 1;
+export interface SessionHeader {
+    type: "session";
+    version: typeof SESSION_FORMAT_VERSION;
+    id: string;
+    /** ISO 8601。 */
+    timestamp: string;
+    cwd: string;
+    agent: {
+        name: "ama";
+        version: string;
+    };
+    /** fork / clone / task 的来源文件。 */
+    parentSession?: string;
+}
+export interface EntryBase {
+    id: string;
+    parentId: string | null;
+    /** ISO 8601。 */
+    timestamp: string;
+}
+export interface FileOpsDetails {
+    readFiles: string[];
+    modifiedFiles: string[];
+}
+export interface MessageEntry extends EntryBase {
+    type: "message";
+    message: Message;
+}
+export interface CompactionEntry extends EntryBase {
+    type: "compaction";
+    summary: string;
+    firstKeptEntryId: string;
+    tokensBefore: number;
+    usage?: Usage;
+    details?: FileOpsDetails;
+}
+export interface BranchSummaryEntry extends EntryBase {
+    type: "branch_summary";
+    fromId: string;
+    summary: string;
+    usage?: Usage;
+    details?: FileOpsDetails;
+}
+export type ContextEditReason = "prune" | "abort" | "retry" | "overflow" | "manual";
+/** 同一目标最新一条赢；replacement 为 null 表示从上下文剔除。 */
+export interface ContextEditEntry extends EntryBase {
+    type: "context_edit";
+    targetId: string;
+    replacement: string | null;
+    reason: ContextEditReason;
+}
+export interface ModelChangeEntry extends EntryBase {
+    type: "model_change";
+    provider: string;
+    modelId: string;
+    /** 所选渠道（多渠道供应商）；没有时走模型的首选渠道。 */
+    channel?: string;
+}
+export interface ThinkingLevelChangeEntry extends EntryBase {
+    type: "thinking_level_change";
+    thinkingLevel: ModelThinkingLevel;
+}
+/** 不进上下文（如 ama.todo、ama.task）。 */
+export interface CustomEntry extends EntryBase {
+    type: "custom";
+    customType: string;
+    data: unknown;
+}
+/** 进上下文（如 ama.aborted、Hook 的 additionalContext）。 */
+export interface CustomMessageEntry extends EntryBase {
+    type: "custom_message";
+    customType: string;
+    content: string | ContentBlock[];
+    display: boolean;
+    details?: unknown;
+}
+export interface LabelEntry extends EntryBase {
+    type: "label";
+    targetId: string;
+    /** 缺省 = 清除标签。 */
+    label?: string;
+}
+export interface SessionInfoEntry extends EntryBase {
+    type: "session_info";
+    name?: string;
+}
+/** 不进上下文的请求用量的来源；第一期只有缓存保温。 */
+export type UsageEntryKind = "cache_warm" | (string & {});
+/**
+ * [W3-C0] 不进上下文的请求用量（第三波 §1.7）：计入 `/session` 费用与 RPC 统计，投影跳过。
+ */
+export interface UsageEntry extends EntryBase {
+    type: "usage";
+    kind: UsageEntryKind;
+    provider: string;
+    /** 模型 id（不含 provider）。 */
+    model: string;
+    usage: Usage;
+}
+export type SessionEntry = MessageEntry | CompactionEntry | BranchSummaryEntry | ContextEditEntry | ModelChangeEntry | ThinkingLevelChangeEntry | CustomEntry | CustomMessageEntry | LabelEntry | SessionInfoEntry | UsageEntry;
+export type SessionEntryType = SessionEntry["type"];
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+/** `append()` 的入参：id / parentId / timestamp 由管理器填。 */
+export type SessionEntryInput = DistributiveOmit<SessionEntry, keyof EntryBase>;
+/**
+ * [W3-C0] `/tree` 换叶子的落盘记录（第三波 A7）：不是条目，`getEntries` / 树不返回它；
+ * 最后一条 `leaf` 行若晚于最后一条条目，打开文件时作为叶子。fork 不复制。
+ */
+export interface LeafLine {
+    type: "leaf";
+    /** 叶子条目 id；null = 回到根之前（空分支）。 */
+    id: string | null;
+    /** ISO 8601。 */
+    timestamp: string;
+}
+/** JSONL 一行：首行是头，其后是条目（以及可选的 `leaf` 行）。 */
+export type SessionLine = SessionHeader | SessionEntry | LeafLine;
+export interface CustomMessage {
+    role: "custom";
+    customType: string;
+    content: string | ContentBlock[];
+    display: boolean;
+    details?: unknown;
+    timestamp: number;
+}
+export interface CompactionSummaryMessage {
+    role: "compactionSummary";
+    summary: string;
+    tokensBefore: number;
+    timestamp: number;
+}
+export interface BranchSummaryMessage {
+    role: "branchSummary";
+    summary: string;
+    fromId: string;
+    timestamp: number;
+}
+export type AgentMessage = Message | CustomMessage | CompactionSummaryMessage | BranchSummaryMessage;
+export interface SessionTreeNode {
+    entry: SessionEntry;
+    children: SessionTreeNode[];
+    label?: string;
+}
+export interface SessionListItem {
+    id: string;
+    file: string;
+    cwd: string;
+    name?: string;
+    /** ISO 8601。 */
+    createdAt: string;
+    modifiedAt: string;
+    firstPrompt?: string;
+    messageCount: number;
+}
+export interface SessionManagerApi {
+    readonly id: string;
+    readonly cwd: string;
+    /** 未落盘（内存会话或首条提示前）为 undefined。 */
+    file(): string | undefined;
+    header(): SessionHeader;
+    /** 全部条目（文件顺序）。 */
+    entries(): readonly SessionEntry[];
+    getEntry(id: string): SessionEntry | undefined;
+    leafId(): string | null;
+    /** 追加到当前叶子之后并把叶子移到新条目。 */
+    append(input: SessionEntryInput): SessionEntry;
+    /** `/tree`：同文件换叶子。 */
+    setLeaf(id: string | null): void;
+    /** 根 → 叶子的活动分支。 */
+    branch(leafId?: string | null): SessionEntry[];
+    /** 以 entry id 为游标（不含 since 本身）。 */
+    getEntries(since?: string): {
+        entries: SessionEntry[];
+        leafId: string | null;
+    };
+    getTree(): SessionTreeNode[];
+    name(): string | undefined;
+    setName(name: string): void;
+    /** 复制 root → entryId 的分支到新文件（parentSession 指回）。 */
+    fork(entryId: string): SessionManagerApi;
+}
+export {};

package/dist/session/types.js

@@ -0,0 +1,18 @@
+/**
+ * 会话 JSONL 树契约（设计 §8，格式沿用 v1 §5）。[B0] 契约文件，实现归 B2。
+ *
+ * 补全与偏差：
+ * - `message` 条目只装 LLM 消息（`Message`：system / user / assistant / toolResult），
+ *   这样 session 不必反向依赖 agent。
+ * - 投影（projection.ts）产出的上下文消息 `AgentMessage` = `Message` + 三种非 LLM 角色
+ *   （custom / compactionSummary / branchSummary），定义在这里，agent/types.ts 再导出；
+ *   `convertToLlm` 负责把三种扩展角色转成 user 消息。
+ * - `context_edit.reason` 在 v1 的 prune / abort / manual 之外加 `retry`（§3.6 失败尝试剔除）
+ *   与 `overflow`（§9 溢出恢复剔除）。
+ * - `compaction` / `branch_summary` 的 details 统一为 `FileOpsDetails`。
+ * - 补全 `SessionTreeNode`、`SessionListItem` 与 B6 / B7 需要的 `SessionManagerApi`。
+ *   `append()` 同步：返回带 id 的条目并把叶子移到它（落盘可延迟到首条提示，§11.1 第 16 步）。
+ * - （W3-C0）第三波 §1.7 / A7：新增 `usage` 条目（保温等不进上下文的请求用量，计入统计）与
+ *   非条目的 `leaf` 行（`/tree` 位置落盘）；都是 v1 可选行，格式版本不升。
+ */
+export const SESSION_FORMAT_VERSION = 1;

package/dist/skills/discover.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Skill 发现（设计 §5.3、§7.3）。[B3]
+ *
+ * 顺序：`--skill-dir`（可重复）→ profile `skillDirs` → config `skills.dirs` → `<configDir>/skills/`
+ * → `<cwd>/.ama/skills/`（需信任）→ 祖先目录的 `.agents/skills/`（需信任；从 cwd 向上到仓库根，
+ * 近者在前）。每个含 `SKILL.md` 的子目录是一个技能（递归查找，技能目录内部不再下钻）；重名保留
+ * 先发现者并 warning。信任结果由调用方（B5 的 trust 决策）作为参数传入；未信任时需信任的来源被
+ * 跳过并记入 `skippedUntrusted`。
+ *
+ * frontmatter：`name`（≤ 64，`^[a-z0-9-]+$`，缺省取目录名）、`description`（必填，≤ 1024）、
+ * `disable-model-invocation`、`allowed-tools`（只做提示）。
+ */
+export type SkillScope = "cli" | "profile" | "config" | "user" | "project" | "ancestor";
+export interface SkillSource {
+    dir: string;
+    scope: SkillScope;
+    requiresTrust: boolean;
+}
+export interface Skill {
+    name: string;
+    description: string;
+    /** SKILL.md 绝对路径。 */
+    location: string;
+    /** SKILL.md 所在目录。 */
+    baseDir: string;
+    disableModelInvocation: boolean;
+    allowedTools?: string[];
+    scope: SkillScope;
+}
+export interface DiscoverResult {
+    skills: Skill[];
+    warnings: string[];
+    /** 因未信任而跳过的目录（存在的才列出）。 */
+    skippedUntrusted: string[];
+}
+export declare const SKILL_FILE = "SKILL.md";
+export declare const SKILL_NAME_RE: RegExp;
+export declare const MAX_SKILL_NAME = 64;
+export declare const MAX_SKILL_DESCRIPTION = 1024;
+export interface SkillSourceOptions {
+    cwd: string;
+    /** 用户级配置目录（`~/.config/ama`）。 */
+    configDir: string;
+    cliDirs?: readonly string[];
+    profileDirs?: readonly string[];
+    configDirs?: readonly string[];
+}
+/** 从 cwd 向上到仓库根（含 `.git` 的目录，含其本身）；无仓库则到文件系统根。近者在前。 */
+export declare function ancestorDirs(cwd: string): string[];
+export declare function skillSources(options: SkillSourceOptions): SkillSource[];
+/** 解析一份 SKILL.md；不合格返回 warning。 */
+export declare function parseSkill(text: string, location: string, scope: SkillScope): {
+    skill?: Skill;
+    warnings: string[];
+};
+/** 一个来源目录下全部 SKILL.md（排序、递归；含 SKILL.md 的目录本身是技能，不再下钻）。 */
+export declare function findSkillFiles(dir: string, depth?: number): Promise<string[]>;
+export declare function discoverSkills(sources: readonly SkillSource[], options: {
+    trusted: boolean;
+}): Promise<DiscoverResult>;

package/dist/skills/discover.js

@@ -0,0 +1,160 @@
+/**
+ * Skill 发现（设计 §5.3、§7.3）。[B3]
+ *
+ * 顺序：`--skill-dir`（可重复）→ profile `skillDirs` → config `skills.dirs` → `<configDir>/skills/`
+ * → `<cwd>/.ama/skills/`（需信任）→ 祖先目录的 `.agents/skills/`（需信任；从 cwd 向上到仓库根，
+ * 近者在前）。每个含 `SKILL.md` 的子目录是一个技能（递归查找，技能目录内部不再下钻）；重名保留
+ * 先发现者并 warning。信任结果由调用方（B5 的 trust 决策）作为参数传入；未信任时需信任的来源被
+ * 跳过并记入 `skippedUntrusted`。
+ *
+ * frontmatter：`name`（≤ 64，`^[a-z0-9-]+$`，缺省取目录名）、`description`（必填，≤ 1024）、
+ * `disable-model-invocation`、`allowed-tools`（只做提示）。
+ */
+import { existsSync } from "node:fs";
+import { readdir, readFile, stat } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { parseFrontmatter } from "./frontmatter.js";
+export const SKILL_FILE = "SKILL.md";
+export const SKILL_NAME_RE = /^[a-z0-9-]+$/;
+export const MAX_SKILL_NAME = 64;
+export const MAX_SKILL_DESCRIPTION = 1024;
+const MAX_DEPTH = 6;
+const SKIP_DIRS = new Set(["node_modules", ".git"]);
+/** 从 cwd 向上到仓库根（含 `.git` 的目录，含其本身）；无仓库则到文件系统根。近者在前。 */
+export function ancestorDirs(cwd) {
+    const out = [];
+    let dir = resolve(cwd);
+    for (;;) {
+        out.push(dir);
+        if (existsSync(join(dir, ".git")))
+            return out;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return out;
+        dir = parent;
+    }
+}
+export function skillSources(options) {
+    const sources = [];
+    const add = (dir, scope, requiresTrust) => sources.push({ dir: resolve(options.cwd, dir), scope, requiresTrust });
+    for (const d of options.cliDirs ?? [])
+        add(d, "cli", false);
+    for (const d of options.profileDirs ?? [])
+        add(d, "profile", false);
+    for (const d of options.configDirs ?? [])
+        add(d, "config", false);
+    add(join(options.configDir, "skills"), "user", false);
+    add(join(options.cwd, ".ama", "skills"), "project", true);
+    for (const d of ancestorDirs(options.cwd))
+        add(join(d, ".agents", "skills"), "ancestor", true);
+    return sources;
+}
+/** 解析一份 SKILL.md；不合格返回 warning。 */
+export function parseSkill(text, location, scope) {
+    const warnings = [];
+    const fm = parseFrontmatter(text);
+    for (const e of fm.errors)
+        warnings.push(`${location}: ${e}`);
+    const baseDir = dirname(location);
+    const rawName = fm.data["name"];
+    const name = typeof rawName === "string" && rawName !== "" ? rawName : basename(baseDir);
+    if (name.length > MAX_SKILL_NAME || !SKILL_NAME_RE.test(name)) {
+        warnings.push(`${location}: invalid skill name "${name}" (lowercase letters, digits, -)`);
+        return { warnings };
+    }
+    const description = fm.data["description"];
+    if (typeof description !== "string" || description.trim() === "") {
+        warnings.push(`${location}: missing description; skill "${name}" not loaded`);
+        return { warnings };
+    }
+    if (description.length > MAX_SKILL_DESCRIPTION) {
+        warnings.push(`${location}: description longer than ${MAX_SKILL_DESCRIPTION} characters`);
+        return { warnings };
+    }
+    const skill = {
+        name,
+        description: description.trim(),
+        location,
+        baseDir,
+        disableModelInvocation: fm.data["disable-model-invocation"] === true,
+        scope,
+    };
+    const allowed = fm.data["allowed-tools"];
+    if (Array.isArray(allowed))
+        skill.allowedTools = allowed.map(String);
+    else if (typeof allowed === "string" && allowed !== "") {
+        skill.allowedTools = allowed.split(/[\s,]+/).filter((t) => t !== "");
+    }
+    return { skill, warnings };
+}
+async function isDir(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** 一个来源目录下全部 SKILL.md（排序、递归；含 SKILL.md 的目录本身是技能，不再下钻）。 */
+export async function findSkillFiles(dir, depth = 0) {
+    if (depth > MAX_DEPTH)
+        return [];
+    const own = join(dir, SKILL_FILE);
+    if (existsSync(own))
+        return [own];
+    let names;
+    try {
+        names = await readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    names.sort();
+    const out = [];
+    for (const name of names) {
+        if (SKIP_DIRS.has(name))
+            continue;
+        const child = join(dir, name);
+        if (await isDir(child))
+            out.push(...(await findSkillFiles(child, depth + 1)));
+    }
+    return out;
+}
+export async function discoverSkills(sources, options) {
+    const result = { skills: [], warnings: [], skippedUntrusted: [] };
+    const byName = new Map();
+    const seenDirs = new Set();
+    for (const source of sources) {
+        if (seenDirs.has(source.dir))
+            continue;
+        seenDirs.add(source.dir);
+        if (!(await isDir(source.dir)))
+            continue;
+        if (source.requiresTrust && !options.trusted) {
+            result.skippedUntrusted.push(source.dir);
+            continue;
+        }
+        for (const file of await findSkillFiles(source.dir)) {
+            let text;
+            try {
+                text = await readFile(file, "utf8");
+            }
+            catch (err) {
+                result.warnings.push(`${file}: ${err.message}`);
+                continue;
+            }
+            const parsed = parseSkill(text, file, source.scope);
+            result.warnings.push(...parsed.warnings);
+            if (!parsed.skill)
+                continue;
+            const existing = byName.get(parsed.skill.name);
+            if (existing) {
+                result.warnings.push(`${file}: skill "${parsed.skill.name}" already defined at ${existing.location}; ignored`);
+                continue;
+            }
+            byName.set(parsed.skill.name, parsed.skill);
+            result.skills.push(parsed.skill);
+        }
+    }
+    return result;
+}

package/dist/skills/expand.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `/skill:<name> [args]` 展开（设计 §5.3）。[B3]
+ *
+ * 展开格式：
+ *   <skill name="…" location="…">
+ *   References are relative to <dir>.
+ *
+ *   <正文（去掉 frontmatter）>
+ *   </skill>
+ *
+ *   <args>          ← 有参数时才有
+ * 用户手打的 `/skill:` 不受 `disable-model-invocation` 限制（那只约束模型调用）。
+ */
+import type { Skill } from "./discover.js";
+export declare const SKILL_COMMAND_PREFIX = "/skill:";
+export interface SkillCommand {
+    name: string;
+    args: string;
+}
+export declare function parseSkillCommand(text: string): SkillCommand | undefined;
+export declare function skillBody(fileText: string): string;
+/** `<skill …>` 块（skill 工具与 `/skill:` 共用）。 */
+export declare function formatSkillBlock(skill: Pick<Skill, "name" | "location" | "baseDir">, body: string): string;
+export declare function formatSkillInvocation(skill: Pick<Skill, "name" | "location" | "baseDir">, body: string, args: string): string;
+export type SkillExpansion = {
+    kind: "expanded";
+    text: string;
+    skill: Skill;
+} | {
+    kind: "unknown";
+    name: string;
+    available: string[];
+};
+/** 不是 `/skill:` 命令返回 undefined。 */
+export declare function expandSkillCommand(text: string, skills: readonly Skill[], read?: (path: string) => Promise<string>): Promise<SkillExpansion | undefined>;

package/dist/skills/expand.js

@@ -0,0 +1,46 @@
+/**
+ * `/skill:<name> [args]` 展开（设计 §5.3）。[B3]
+ *
+ * 展开格式：
+ *   <skill name="…" location="…">
+ *   References are relative to <dir>.
+ *
+ *   <正文（去掉 frontmatter）>
+ *   </skill>
+ *
+ *   <args>          ← 有参数时才有
+ * 用户手打的 `/skill:` 不受 `disable-model-invocation` 限制（那只约束模型调用）。
+ */
+import { readFile } from "node:fs/promises";
+import { splitFrontmatter } from "./frontmatter.js";
+import { escapeXml } from "./index-prompt.js";
+export const SKILL_COMMAND_PREFIX = "/skill:";
+export function parseSkillCommand(text) {
+    const m = /^\/skill:([a-z0-9-]+)(?:[ \t]+([\s\S]*))?$/.exec(text.trim());
+    if (!m)
+        return undefined;
+    return { name: m[1], args: (m[2] ?? "").trim() };
+}
+export function skillBody(fileText) {
+    return splitFrontmatter(fileText).body.replace(/^\n+/, "").replace(/\s+$/, "");
+}
+/** `<skill …>` 块（skill 工具与 `/skill:` 共用）。 */
+export function formatSkillBlock(skill, body) {
+    return (`<skill name="${escapeXml(skill.name)}" location="${escapeXml(skill.location)}">\n` +
+        `References are relative to ${skill.baseDir}.\n\n${body}\n</skill>`);
+}
+export function formatSkillInvocation(skill, body, args) {
+    const block = formatSkillBlock(skill, body);
+    return args === "" ? block : `${block}\n\n${args}`;
+}
+/** 不是 `/skill:` 命令返回 undefined。 */
+export async function expandSkillCommand(text, skills, read = (p) => readFile(p, "utf8")) {
+    const cmd = parseSkillCommand(text);
+    if (!cmd)
+        return undefined;
+    const skill = skills.find((s) => s.name === cmd.name);
+    if (!skill)
+        return { kind: "unknown", name: cmd.name, available: skills.map((s) => s.name) };
+    const body = skillBody(await read(skill.location));
+    return { kind: "expanded", text: formatSkillInvocation(skill, body, cmd.args), skill };
+}

package/dist/skills/frontmatter.d.ts

@@ -0,0 +1,27 @@
+/**
+ * YAML 头**子集**解析（设计 §5.3、§2「YAML 只支持 frontmatter 子集自写」）。[B3]
+ *
+ * 支持：首行 `---` 到下一个 `---` / `...` 之间的
+ * - `key: value`（值为裸字串、单 / 双引号字串、`true/false`、整数 / 小数、`null` / `~`）；
+ * - 行内数组 `key: [a, "b", 3]`；块数组（`key:` 后跟 `- item` 行）；
+ * - `#` 注释（引号外）与空行。
+ * 不支持：嵌套映射、多行块标量（`|` / `>`）、锚点——遇到时记一条错误并跳过该键。
+ */
+export type FrontmatterValue = string | number | boolean | null | FrontmatterScalar[];
+type FrontmatterScalar = string | number | boolean | null;
+export interface FrontmatterResult {
+    data: Record<string, FrontmatterValue>;
+    /** 头之后的正文（无头时为全文）。 */
+    body: string;
+    /** 是否有头。 */
+    hasFrontmatter: boolean;
+    errors: string[];
+}
+export declare function parseScalar(raw: string): FrontmatterScalar;
+/** 拆出头与正文；不以 `---` 开头视为无头。 */
+export declare function splitFrontmatter(text: string): {
+    header: string[] | undefined;
+    body: string;
+};
+export declare function parseFrontmatter(text: string): FrontmatterResult;
+export {};