@armadra/agent 0.3.0 → 0.5.0

package/dist/session/search.js

@@ -0,0 +1,211 @@
+/**
+ * 跨会话全文检索（`ama sessions search`）。[W4-D]
+ *
+ * - 模式：普通关键词（不区分大小写的子串）或 `/正则/标志`；
+ * - 检索的文本：user = 文本块；assistant = 文本块 + 工具调用（`名字 参数 JSON`）；tool = 工具结果文本。
+ *   思考块、system、custom 不检索；
+ * - 关键词不含 `"`、`\` 与控制字符时，先在原始行上做子串预筛（JSON 只转义这些字符，中文原样），
+ *   不命中的行不解析；正则没法预筛，逐行解析消息行；
+ * - 每条命中带：会话 id、条目时间、项目（头的 cwd）、角色、条目序号（文件里第几条条目，1 起）、
+ *   user 的消息编号（同 `sessions show` / `--from`）、片段与命中区间（展示层负责高亮）。
+ * - 文件按创建时间倒序（最新在前），文件内按条目顺序；到 limit 停。
+ */
+import { lineType, forEachLine } from "./scan.js";
+import { contentText } from "./reuse.js";
+/** `/re/flags` → 正则；其它 → 不区分大小写的子串。非法正则抛 SyntaxError。 */
+export function compileQuery(pattern) {
+    const regex = /^\/(.+)\/([a-z]*)$/s.exec(pattern);
+    if (regex !== null) {
+        const flags = new Set((regex[2] ?? "").split(""));
+        flags.add("g");
+        const re = new RegExp(regex[1] ?? "", [...flags].join(""));
+        return {
+            match(text) {
+                const out = [];
+                re.lastIndex = 0;
+                for (const m of text.matchAll(re)) {
+                    if (m[0] === "")
+                        continue;
+                    out.push([m.index, m.index + m[0].length]);
+                    if (out.length >= 20)
+                        break;
+                }
+                return out;
+            },
+            mayContain: () => true,
+        };
+    }
+    const needle = pattern.toLowerCase();
+    // eslint-disable-next-line no-control-regex
+    const prefilter = !/["\\\u0000-\u001f]/.test(pattern);
+    return {
+        match(text) {
+            const out = [];
+            const hay = text.toLowerCase();
+            let at = hay.indexOf(needle);
+            while (at >= 0 && out.length < 20) {
+                out.push([at, at + needle.length]);
+                at = hay.indexOf(needle, at + needle.length);
+            }
+            return out;
+        },
+        mayContain: (line) => !prefilter || line.toLowerCase().includes(needle),
+    };
+}
+const isRec = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+function searchableText(message) {
+    switch (message["role"]) {
+        case "user":
+            return { role: "user", text: contentText(message["content"]) };
+        case "toolResult":
+            return { role: "tool", text: contentText(message["content"]) };
+        case "assistant": {
+            const parts = [];
+            const content = message["content"];
+            if (Array.isArray(content)) {
+                for (const block of content) {
+                    if (!isRec(block))
+                        continue;
+                    if (block["type"] === "text" && typeof block["text"] === "string")
+                        parts.push(block["text"]);
+                    if (block["type"] === "toolCall")
+                        parts.push(`${String(block["name"])} ${JSON.stringify(block["arguments"] ?? {})}`);
+                }
+            }
+            return { role: "assistant", text: parts.join("\n") };
+        }
+        default:
+            return undefined;
+    }
+}
+/** 命中附近的单行片段（空白压平），区间换算到片段坐标。 */
+export function makeSnippet(text, ranges, context = 50) {
+    const [first] = ranges;
+    if (first === undefined)
+        return { snippet: "", ranges: [] };
+    const start = Math.max(0, first[0] - context);
+    const end = Math.min(text.length, first[1] + context);
+    const prefix = start > 0 ? "…" : "";
+    const suffix = end < text.length ? "…" : "";
+    // 压平空白时逐字符换算，区间跟着移动。
+    let out = prefix;
+    const map = [];
+    let lastSpace = false;
+    for (let i = start; i < end; i++) {
+        const ch = text[i] ?? "";
+        map[i - start] = out.length;
+        if (/\s/.test(ch)) {
+            if (!lastSpace)
+                out += " ";
+            lastSpace = true;
+        }
+        else {
+            out += ch;
+            lastSpace = false;
+        }
+    }
+    map[end - start] = out.length;
+    const mapped = [];
+    for (const [a, b] of ranges) {
+        if (a < start || b > end)
+            continue;
+        mapped.push([map[a - start] ?? 0, map[b - start] ?? out.length]);
+    }
+    return { snippet: out + suffix, ranges: mapped };
+}
+/** 在一批文件里检索；返回命中（最多 limit 条）与是否到了上限（可能还有更多）。 */
+export function searchSessions(files, query, options) {
+    const hits = [];
+    let truncated = false;
+    for (const file of files) {
+        if (hits.length >= options.limit)
+            break;
+        let header;
+        let entryIndex = 0;
+        let userN = 0;
+        try {
+            forEachLine(file, (line, index) => {
+                if (index === 0) {
+                    try {
+                        const h = JSON.parse(line);
+                        if (h["type"] !== "session")
+                            return false;
+                        header = { id: String(h["id"]), cwd: String(h["cwd"]) };
+                    }
+                    catch {
+                        return false;
+                    }
+                    return;
+                }
+                const quick = lineType(line);
+                if (quick?.type === "leaf")
+                    return;
+                entryIndex++;
+                if (quick !== undefined && quick.type !== "message")
+                    return;
+                const isUser = quick?.role === "user";
+                if (isUser)
+                    userN++;
+                if (quick?.role === "system")
+                    return;
+                if (!query.mayContain(line))
+                    return;
+                let entry;
+                try {
+                    entry = JSON.parse(line);
+                }
+                catch {
+                    return;
+                }
+                if (quick === undefined) {
+                    // 非 ama 形状的行：解析后再判断
+                    if (entry["type"] === "leaf") {
+                        entryIndex--;
+                        return;
+                    }
+                    if (entry["type"] !== "message")
+                        return;
+                    if (isRec(entry["message"]) && entry["message"]["role"] === "user")
+                        userN++;
+                }
+                const message = entry["message"];
+                if (!isRec(message) || header === undefined)
+                    return;
+                const found = searchableText(message);
+                if (found === undefined)
+                    return;
+                if (options.roles !== undefined && !options.roles.has(found.role))
+                    return;
+                const timestamp = typeof entry["timestamp"] === "string" ? entry["timestamp"] : "";
+                if (options.sinceIso !== undefined && timestamp < options.sinceIso)
+                    return;
+                const ranges = query.match(found.text);
+                if (ranges.length === 0)
+                    return;
+                const snippet = makeSnippet(found.text, ranges);
+                const hit = {
+                    sessionId: header.id,
+                    file,
+                    cwd: header.cwd,
+                    timestamp,
+                    role: found.role,
+                    entryIndex,
+                    entryId: String(entry["id"]),
+                    snippet: snippet.snippet,
+                    ranges: snippet.ranges,
+                };
+                if (found.role === "user")
+                    hit.userN = userN;
+                hits.push(hit);
+                if (hits.length >= options.limit) {
+                    truncated = true;
+                    return false;
+                }
+            });
+        }
+        catch {
+            // 读不了的文件跳过
+        }
+    }
+    return { hits, truncated };
+}

package/dist/session/stats-aggregate.d.ts

@@ -0,0 +1,63 @@
+/**
+ * `ama stats` 的汇总（纯函数）：文件摘要 → 合计、分组、按来源的请求数、工具 Top N。[W4-D]
+ *
+ * 口径（与 `/session`、`get_session_stats` 一致）：
+ * - 请求 = 每次模型请求（回合里的 assistant、保温、权限分类、压缩摘要…），按 kind 分开计；
+ * - 命中率 = cacheRead /（input + cacheRead + cacheWrite），只算「报告缓存」的端点：同一
+ *   provider/model@channel 在扫描范围内出现过任何非零缓存读写才算；其余端点不进分母；
+ * - 费用只加有价请求；`unpriced` 是无价请求数（全无价时 cost 缺省，展示层只给 token）。
+ */
+import type { FileStatsSummary, StatsBucket } from "./stats-scan.js";
+export declare const STATS_GROUPS: readonly ["day", "week", "month", "provider", "channel", "model", "project"];
+export type StatsGroupBy = (typeof STATS_GROUPS)[number];
+export interface StatsTotals {
+    requests: number;
+    turns: number;
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    /** 有价请求的费用；没有任何有价请求时缺省。 */
+    cost?: number;
+    /** 无价请求数。 */
+    unpriced: number;
+    /** 0–1；报告缓存的端点没有输入时缺省。 */
+    hitRate?: number;
+    errors: number;
+    retries: number;
+    /** 平均回合耗时（毫秒）；没有可计时的回合时缺省。 */
+    avgTurnMs?: number;
+}
+export interface StatsGroup extends StatsTotals {
+    key: string;
+    sessions: number;
+}
+export interface StatsReport {
+    since?: string;
+    until?: string;
+    sessions: number;
+    totals: StatsTotals;
+    /** kind → 请求数。 */
+    byKind: Record<string, number>;
+    groups?: StatsGroup[];
+    tools: Array<{
+        name: string;
+        count: number;
+    }>;
+    endpoints: {
+        reported: number;
+        total: number;
+    };
+}
+export declare function endpointOf(b: Pick<StatsBucket, "provider" | "model" | "channel">): string;
+/** 本地日期 → ISO 周 `2026-W40`。 */
+export declare function isoWeek(day: string): string;
+export interface AggregateOptions {
+    /** 含当天，本地日期 YYYY-MM-DD。 */
+    since?: string;
+    until?: string;
+    by?: StatsGroupBy;
+    /** 工具 Top N（缺省 10）。 */
+    topTools?: number;
+}
+export declare function aggregateStats(summaries: readonly FileStatsSummary[], options?: AggregateOptions): StatsReport;

package/dist/session/stats-aggregate.js

@@ -0,0 +1,163 @@
+/**
+ * `ama stats` 的汇总（纯函数）：文件摘要 → 合计、分组、按来源的请求数、工具 Top N。[W4-D]
+ *
+ * 口径（与 `/session`、`get_session_stats` 一致）：
+ * - 请求 = 每次模型请求（回合里的 assistant、保温、权限分类、压缩摘要…），按 kind 分开计；
+ * - 命中率 = cacheRead /（input + cacheRead + cacheWrite），只算「报告缓存」的端点：同一
+ *   provider/model@channel 在扫描范围内出现过任何非零缓存读写才算；其余端点不进分母；
+ * - 费用只加有价请求；`unpriced` 是无价请求数（全无价时 cost 缺省，展示层只给 token）。
+ */
+export const STATS_GROUPS = [
+    "day",
+    "week",
+    "month",
+    "provider",
+    "channel",
+    "model",
+    "project",
+];
+const newAcc = () => ({
+    requests: 0,
+    turns: 0,
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    cost: 0,
+    costed: 0,
+    hitRead: 0,
+    hitPrompt: 0,
+    errors: 0,
+    retries: 0,
+    turnMs: 0,
+    timedTurns: 0,
+    sessions: new Set(),
+});
+export function endpointOf(b) {
+    return `${b.provider}/${b.model}${b.channel !== undefined ? `@${b.channel}` : ""}`;
+}
+function add(acc, b, reported, session) {
+    acc.requests += b.requests;
+    acc.turns += b.turns;
+    acc.input += b.input;
+    acc.output += b.output;
+    acc.cacheRead += b.cacheRead;
+    acc.cacheWrite += b.cacheWrite;
+    acc.cost += b.cost;
+    acc.costed += b.costed;
+    if (reported) {
+        acc.hitRead += b.cacheRead;
+        acc.hitPrompt += b.input + b.cacheRead + b.cacheWrite;
+    }
+    acc.errors += b.errors;
+    acc.retries += b.retries;
+    acc.turnMs += b.turnMs;
+    acc.timedTurns += b.timedTurns;
+    acc.sessions.add(session);
+}
+function totals(acc) {
+    const out = {
+        requests: acc.requests,
+        turns: acc.turns,
+        input: acc.input,
+        output: acc.output,
+        cacheRead: acc.cacheRead,
+        cacheWrite: acc.cacheWrite,
+        unpriced: acc.requests - acc.costed,
+        errors: acc.errors,
+        retries: acc.retries,
+    };
+    if (acc.costed > 0)
+        out.cost = acc.cost;
+    if (acc.hitPrompt > 0)
+        out.hitRate = acc.hitRead / acc.hitPrompt;
+    if (acc.timedTurns > 0)
+        out.avgTurnMs = acc.turnMs / acc.timedTurns;
+    return out;
+}
+/** 本地日期 → ISO 周 `2026-W40`。 */
+export function isoWeek(day) {
+    const [y = 0, m = 1, d = 1] = day.split("-").map(Number);
+    const date = new Date(Date.UTC(y, m - 1, d));
+    const weekday = date.getUTCDay() || 7;
+    date.setUTCDate(date.getUTCDate() + 4 - weekday);
+    const yearStart = Date.UTC(date.getUTCFullYear(), 0, 1);
+    const week = Math.ceil(((date.getTime() - yearStart) / 86_400_000 + 1) / 7);
+    return `${date.getUTCFullYear()}-W${week < 10 ? `0${week}` : week}`;
+}
+function groupKey(by, b, cwd) {
+    switch (by) {
+        case "day":
+            return b.day;
+        case "week":
+            return isoWeek(b.day);
+        case "month":
+            return b.day.slice(0, 7);
+        case "provider":
+            return b.provider;
+        case "channel":
+            return endpointOf(b);
+        case "model":
+            return `${b.provider}/${b.model}`;
+        case "project":
+            return cwd;
+    }
+}
+export function aggregateStats(summaries, options = {}) {
+    const inRange = (day) => (options.since === undefined || day >= options.since) &&
+        (options.until === undefined || day <= options.until);
+    const reported = new Set();
+    const endpoints = new Set();
+    for (const s of summaries)
+        for (const b of s.buckets) {
+            endpoints.add(endpointOf(b));
+            if (b.cacheSeen)
+                reported.add(endpointOf(b));
+        }
+    const all = newAcc();
+    const groups = new Map();
+    const byKind = {};
+    const tools = new Map();
+    for (const s of summaries) {
+        for (const b of s.buckets) {
+            if (!inRange(b.day))
+                continue;
+            const isReported = reported.has(endpointOf(b));
+            add(all, b, isReported, s.id);
+            byKind[b.kind] = (byKind[b.kind] ?? 0) + b.requests;
+            if (options.by !== undefined) {
+                const key = groupKey(options.by, b, s.cwd);
+                let acc = groups.get(key);
+                if (acc === undefined)
+                    groups.set(key, (acc = newAcc()));
+                add(acc, b, isReported, s.id);
+            }
+        }
+        for (const [day, name, count] of s.tools)
+            if (inRange(day))
+                tools.set(name, (tools.get(name) ?? 0) + count);
+    }
+    const report = {
+        sessions: all.sessions.size,
+        totals: totals(all),
+        byKind,
+        tools: [...tools]
+            .map(([name, count]) => ({ name, count }))
+            .sort((a, b) => b.count - a.count || a.name.localeCompare(b.name))
+            .slice(0, options.topTools ?? 10),
+        endpoints: { reported: reported.size, total: endpoints.size },
+    };
+    if (options.since !== undefined)
+        report.since = options.since;
+    if (options.until !== undefined)
+        report.until = options.until;
+    if (options.by !== undefined) {
+        const timeOrdered = options.by === "day" || options.by === "week" || options.by === "month";
+        report.groups = [...groups]
+            .map(([key, acc]) => ({ key, sessions: acc.sessions.size, ...totals(acc) }))
+            .sort((a, b) => timeOrdered
+            ? a.key.localeCompare(b.key)
+            : b.requests - a.requests || a.key.localeCompare(b.key));
+    }
+    return report;
+}

package/dist/session/stats-index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `ama stats` 的增量索引缓存：`<数据目录>/stats-index.json`。[W4-D]
+ *
+ * - 每个会话文件一条：`{ mtimeMs, size, summary }`；mtime 或 size 变了就重扫，否则直接用摘要。
+ * - 摘要里的日期是本地日期，所以索引记下时区（`Intl` 的 timeZone 与当前 UTC 偏移）；变了整份作废。
+ * - 只是缓存：读不到、版本不对、JSON 坏了都当没有；写入走临时文件 + rename，失败忽略。
+ * - 扫描全部目录时顺带删掉已不存在的文件的条目；只扫一个项目时保留别的条目。
+ */
+import { type FileStatsSummary } from "./stats-scan.js";
+export declare const STATS_INDEX_FILE = "stats-index.json";
+export declare function timeZoneKey(now?: Date): string;
+export interface CollectResult {
+    summaries: FileStatsSummary[];
+    /** 本次重扫的文件数（其余命中缓存）。 */
+    scanned: number;
+    cached: number;
+    /** 无效 / 不可读的文件数。 */
+    invalid: number;
+}
+/**
+ * 取一批文件的摘要。`indexFile` 为 undefined 时不用缓存；`prune` 为 true 时删掉不在 `files` 里的条目。
+ */
+export declare function collectSummaries(files: readonly string[], options?: {
+    indexFile?: string;
+    prune?: boolean;
+}): CollectResult;

package/dist/session/stats-index.js

@@ -0,0 +1,91 @@
+/**
+ * `ama stats` 的增量索引缓存：`<数据目录>/stats-index.json`。[W4-D]
+ *
+ * - 每个会话文件一条：`{ mtimeMs, size, summary }`；mtime 或 size 变了就重扫，否则直接用摘要。
+ * - 摘要里的日期是本地日期，所以索引记下时区（`Intl` 的 timeZone 与当前 UTC 偏移）；变了整份作废。
+ * - 只是缓存：读不到、版本不对、JSON 坏了都当没有；写入走临时文件 + rename，失败忽略。
+ * - 扫描全部目录时顺带删掉已不存在的文件的条目；只扫一个项目时保留别的条目。
+ */
+import { mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { summarizeSessionFile } from "./stats-scan.js";
+export const STATS_INDEX_FILE = "stats-index.json";
+const INDEX_VERSION = 1;
+export function timeZoneKey(now = new Date()) {
+    let zone = "";
+    try {
+        zone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    }
+    catch {
+        // 无 Intl 时只看偏移
+    }
+    return `${zone}|${now.getTimezoneOffset()}`;
+}
+/**
+ * 取一批文件的摘要。`indexFile` 为 undefined 时不用缓存；`prune` 为 true 时删掉不在 `files` 里的条目。
+ */
+export function collectSummaries(files, options = {}) {
+    const zone = timeZoneKey();
+    let index = { version: INDEX_VERSION, zone, files: {} };
+    if (options.indexFile !== undefined) {
+        try {
+            const loaded = JSON.parse(readFileSync(options.indexFile, "utf8"));
+            if (loaded.version === INDEX_VERSION &&
+                loaded.zone === zone &&
+                typeof loaded.files === "object")
+                index = loaded;
+        }
+        catch {
+            // 没有或坏了：重建
+        }
+    }
+    let dirty = false;
+    const result = { summaries: [], scanned: 0, cached: 0, invalid: 0 };
+    for (const file of files) {
+        let stat;
+        try {
+            stat = statSync(file);
+        }
+        catch {
+            result.invalid++;
+            continue;
+        }
+        const hit = index.files[file];
+        let summary;
+        if (hit !== undefined && hit.mtimeMs === stat.mtimeMs && hit.size === stat.size) {
+            summary = hit.summary;
+            result.cached++;
+        }
+        else {
+            summary = summarizeSessionFile(file) ?? null;
+            result.scanned++;
+            index.files[file] = { mtimeMs: stat.mtimeMs, size: stat.size, summary };
+            dirty = true;
+        }
+        if (summary === null)
+            result.invalid++;
+        else
+            result.summaries.push(summary);
+    }
+    if (options.prune === true) {
+        const keep = new Set(files);
+        for (const key of Object.keys(index.files)) {
+            if (!keep.has(key)) {
+                delete index.files[key];
+                dirty = true;
+            }
+        }
+    }
+    if (dirty && options.indexFile !== undefined) {
+        try {
+            mkdirSync(dirname(options.indexFile), { recursive: true, mode: 0o700 });
+            const tmp = `${options.indexFile}.${process.pid}.tmp`;
+            writeFileSync(tmp, JSON.stringify(index), { mode: 0o600 });
+            renameSync(tmp, options.indexFile);
+        }
+        catch {
+            // 缓存写不进去不影响结果
+        }
+    }
+    return result;
+}

package/dist/session/stats-scan.d.ts

@@ -0,0 +1,54 @@
+/**
+ * `ama stats` 的单文件摘要（只读、按行）。[W4-D]
+ *
+ * 一个会话文件 → 若干「桶」：按（本地日期、请求来源 kind、provider、model、channel）累加。
+ * - 请求来源：assistant 消息 = `turn`；`usage` 条目用自己的 `kind`（cache_warm、permission_classify…）；
+ *   `compaction` / `branch_summary` 带的 usage 记为同名 kind（模型取最近一条 assistant 的）。
+ * - token：input（不含缓存）/ output / cacheRead / cacheWrite；费用只累加有 `usage.cost` 的请求，
+ *   `costed` 记有价请求数，展示层据此区分「有价」「部分无价」「全无价」。
+ * - 缓存三态：桶记下是否出现过 cacheRead > 0 或 cacheWrite > 0（`cacheSeen`）；汇总时同一端点
+ *   （provider/model@channel）任一桶出现过即算报告缓存，其余端点不进命中率分母（同会话层三态）。
+ * - 回合：非 `steer` 的用户消息开始一个回合，到下一个回合开始为止；回合计入首条 assistant 的桶，
+ *   耗时 = 最后一条 assistant 条目时间 − 用户消息条目时间（都是落盘时间戳）。没有 assistant 的回合不计。
+ * - 工具调用：assistant 内容里的 toolCall 块按名字计（codemode 内层调用不展开）。
+ * - 重试：`context_edit{reason:"retry"}` 计入当时最近一条 assistant 的桶；`stopReason:"error"` 计错误。
+ * - toolResult、custom、label 等行按前缀跳过、不解析；末尾半行忽略；中间坏行跳过并计数。
+ * - channel：最近一条 `model_change` 与该请求同 provider / model 时取它的 channel。
+ */
+export interface StatsBucket {
+    /** 本地日期 YYYY-MM-DD。 */
+    day: string;
+    kind: string;
+    provider: string;
+    model: string;
+    channel?: string;
+    requests: number;
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    /** 有价请求的费用合计（美元）。 */
+    cost: number;
+    /** 有价请求数。 */
+    costed: number;
+    /** 出现过 cacheRead > 0 或 cacheWrite > 0。 */
+    cacheSeen: boolean;
+    errors: number;
+    retries: number;
+    turns: number;
+    /** 有耗时的回合的耗时合计与个数。 */
+    turnMs: number;
+    timedTurns: number;
+}
+export interface FileStatsSummary {
+    id: string;
+    cwd: string;
+    buckets: StatsBucket[];
+    /** `[日期, 工具名, 次数]`。 */
+    tools: Array<[string, string, number]>;
+    /** 跳过的坏行数。 */
+    badLines: number;
+}
+/** ISO → 本地日期；不可解析 → undefined。 */
+export declare function localDay(iso: unknown): string | undefined;
+export declare function summarizeSessionFile(file: string): FileStatsSummary | undefined;