@armadra/agent 0.2.1 → 0.4.0

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;

package/dist/session/stats-scan.js

@@ -0,0 +1,236 @@
+/**
+ * `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。
+ */
+import { forEachLine, lineType } from "./scan.js";
+const SKIP_TYPES = new Set([
+    "custom",
+    "custom_message",
+    "label",
+    "leaf",
+    "session_info",
+    "thinking_level_change",
+]);
+function pad(n) {
+    return n < 10 ? `0${n}` : String(n);
+}
+/** ISO → 本地日期；不可解析 → undefined。 */
+export function localDay(iso) {
+    if (typeof iso !== "string")
+        return undefined;
+    const ms = Date.parse(iso);
+    if (!Number.isFinite(ms))
+        return undefined;
+    const d = new Date(ms);
+    return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+}
+const isRec = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : 0);
+export function summarizeSessionFile(file) {
+    let header;
+    const buckets = new Map();
+    const tools = new Map();
+    let badLines = 0;
+    let channel;
+    let lastAssistant;
+    let lastBucket;
+    let turn;
+    const bucketOf = (day, kind, ref) => {
+        const key = `${day}\u0000${kind}\u0000${ref.provider}\u0000${ref.model}\u0000${ref.channel ?? ""}`;
+        let bucket = buckets.get(key);
+        if (bucket === undefined) {
+            bucket = {
+                day,
+                kind,
+                provider: ref.provider,
+                model: ref.model,
+                requests: 0,
+                input: 0,
+                output: 0,
+                cacheRead: 0,
+                cacheWrite: 0,
+                cost: 0,
+                costed: 0,
+                cacheSeen: false,
+                errors: 0,
+                retries: 0,
+                turns: 0,
+                turnMs: 0,
+                timedTurns: 0,
+            };
+            if (ref.channel !== undefined)
+                bucket.channel = ref.channel;
+            buckets.set(key, bucket);
+        }
+        return bucket;
+    };
+    const addUsage = (bucket, usage) => {
+        bucket.requests++;
+        if (!isRec(usage))
+            return;
+        const u = usage;
+        bucket.input += num(u.input);
+        bucket.output += num(u.output);
+        bucket.cacheRead += num(u.cacheRead);
+        bucket.cacheWrite += num(u.cacheWrite);
+        if (num(u.cacheRead) > 0 || num(u.cacheWrite) > 0)
+            bucket.cacheSeen = true;
+        if (isRec(u.cost) && typeof u.cost["total"] === "number") {
+            bucket.cost += num(u.cost["total"]);
+            bucket.costed++;
+        }
+    };
+    const refFor = (provider, model) => {
+        const ref = { provider, model };
+        if (channel?.channel !== undefined &&
+            channel.provider === provider &&
+            channel.model === model) {
+            ref.channel = channel.channel;
+        }
+        return ref;
+    };
+    const closeTurn = () => {
+        if (turn?.bucket !== undefined) {
+            turn.bucket.turns++;
+            if (turn.end !== undefined && turn.end >= turn.start) {
+                turn.bucket.turnMs += turn.end - turn.start;
+                turn.bucket.timedTurns++;
+            }
+        }
+        turn = undefined;
+    };
+    try {
+        forEachLine(file, (line, index, last) => {
+            if (index > 0) {
+                const quick = lineType(line);
+                if (quick !== undefined) {
+                    if (SKIP_TYPES.has(quick.type))
+                        return;
+                    if (quick.type === "message" && quick.role === "toolResult")
+                        return;
+                    if (quick.type === "message" && quick.role === "system")
+                        return;
+                }
+            }
+            let value;
+            try {
+                value = JSON.parse(line);
+            }
+            catch {
+                if (!last)
+                    badLines++;
+                return;
+            }
+            if (!isRec(value))
+                return;
+            if (index === 0) {
+                if (value["type"] !== "session" || typeof value["cwd"] !== "string")
+                    return false;
+                header = value;
+                return;
+            }
+            const ts = value["timestamp"];
+            const day = localDay(ts);
+            if (day === undefined)
+                return;
+            switch (value["type"]) {
+                case "model_change": {
+                    const ref = {
+                        provider: String(value["provider"]),
+                        model: String(value["modelId"]),
+                    };
+                    if (typeof value["channel"] === "string")
+                        ref.channel = value["channel"];
+                    channel = ref;
+                    return;
+                }
+                case "message": {
+                    const message = value["message"];
+                    if (!isRec(message))
+                        return;
+                    if (message["role"] === "user") {
+                        if (message["origin"] === "steer" && turn !== undefined)
+                            return;
+                        closeTurn();
+                        turn = { start: Date.parse(ts), day };
+                        return;
+                    }
+                    if (message["role"] !== "assistant")
+                        return;
+                    const ref = refFor(String(message["provider"]), String(message["model"]));
+                    lastAssistant = ref;
+                    const bucket = bucketOf(day, "turn", ref);
+                    lastBucket = bucket;
+                    addUsage(bucket, message["usage"]);
+                    if (message["stopReason"] === "error")
+                        bucket.errors++;
+                    const content = message["content"];
+                    if (Array.isArray(content)) {
+                        for (const block of content) {
+                            if (isRec(block) &&
+                                block["type"] === "toolCall" &&
+                                typeof block["name"] === "string") {
+                                const key = `${day}\u0000${block["name"]}`;
+                                tools.set(key, (tools.get(key) ?? 0) + 1);
+                            }
+                        }
+                    }
+                    if (turn !== undefined) {
+                        if (turn.bucket === undefined)
+                            turn.bucket = bucketOf(turn.day, "turn", ref);
+                        turn.end = Date.parse(ts);
+                    }
+                    return;
+                }
+                case "usage": {
+                    const ref = refFor(String(value["provider"]), String(value["model"]));
+                    addUsage(bucketOf(day, String(value["kind"] ?? "usage"), ref), value["usage"]);
+                    return;
+                }
+                case "compaction":
+                case "branch_summary": {
+                    if (value["usage"] === undefined)
+                        return;
+                    const ref = lastAssistant ?? { provider: "?", model: "?" };
+                    addUsage(bucketOf(day, value["type"], ref), value["usage"]);
+                    return;
+                }
+                case "context_edit":
+                    if (value["reason"] === "retry" && lastBucket !== undefined)
+                        lastBucket.retries++;
+                    return;
+                default:
+                    return;
+            }
+        });
+    }
+    catch {
+        return undefined;
+    }
+    closeTurn();
+    if (header === undefined)
+        return undefined;
+    return {
+        id: String(header["id"]),
+        cwd: String(header["cwd"]),
+        buckets: [...buckets.values()],
+        tools: [...tools].map(([key, count]) => {
+            const [day = "", name = ""] = key.split("\u0000");
+            return [day, name, count];
+        }),
+        badLines,
+    };
+}

package/dist/session/types.d.ts

@@ -72,6 +72,8 @@ export interface ModelChangeEntry extends EntryBase {
     type: "model_change";
     provider: string;
     modelId: string;
+    /** 所选渠道（多渠道供应商）；没有时走模型的首选渠道。 */
+    channel?: string;
 }
 export interface ThinkingLevelChangeEntry extends EntryBase {
     type: "thinking_level_change";

package/dist/tools/image-file.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 图片文件（`read` 工具、`ama -p --image`、界面里的 `@图片路径` 共用）：MIME 检测、尺寸、大小上限。
+ *
+ * - MIME 以文件头为准（PNG / JPEG / GIF / WebP），文件头认不出时退回扩展名；
+ * - 单张上限 5 MB（各家图片上限里最小的 Anthropic）；
+ * - 不解码像素，只读文件头取尺寸。
+ */
+import type { ImageBlock } from "../ai/types.js";
+export declare const MAX_IMAGE_BYTES: number;
+export declare const IMAGE_EXTENSIONS: Readonly<Record<string, string>>;
+/** 按扩展名（不分大小写）；不是图片返回 undefined。 */
+export declare function imageMimeFromPath(path: string): string | undefined;
+/** 按文件头识别；认不出返回 undefined。 */
+export declare function sniffImageMime(buf: Buffer): string | undefined;
+export interface ImageSize {
+    width: number;
+    height: number;
+}
+/** 只读文件头取尺寸；不认识返回 undefined。 */
+export declare function imageSize(buf: Buffer, mimeType: string): ImageSize | undefined;
+export interface LoadedImage {
+    block: ImageBlock;
+    path: string;
+    mimeType: string;
+    bytes: number;
+    size?: ImageSize;
+}
+/**
+ * 读一张图片作为附件。文件不存在、不是图片、超过上限 → AmaError（`invalid_arguments`），文案给用户看。
+ */
+export declare function loadImageFile(path: string): Promise<LoadedImage>;