@armadra/agent 0.5.1 → 0.6.0

package/dist/trace/build-nodes.js

@@ -0,0 +1,279 @@
+/**
+ * 轨迹构建器的节点构造（`build.ts` 用）：step / tool / subcall / compaction / retry_wait / subagent /
+ * external_turn。精确时间来自 `ama.trace`，缺失时按条目时间推算并标 `approx`。[W6-T1]
+ */
+import { cacheHitRatio, isObject, num, putNum, splitRef, zeroUsage, } from "./build-index.js";
+import { statusOfTask } from "./build-util.js";
+import {} from "./types.js";
+export function stepStatus(message, retried, data) {
+    if (retried)
+        return "retried";
+    if (data?.status === "aborted" || message.stopReason === "aborted")
+        return "aborted";
+    if (message.stopReason === "error")
+        return "error";
+    return "ok";
+}
+export function pushUsage(state, turnId, usage) {
+    const list = state.extraUsage.get(turnId) ?? [];
+    list.push(usage);
+    state.extraUsage.set(turnId, list);
+}
+export function assistantStep(entryId, m, at, turn, state, index) {
+    const trace = index.stepByAssistant.get(entryId);
+    const data = trace?.data;
+    const previous = [...turn.steps].reverse().find((s) => s.kind === "step");
+    const failedBefore = previous !== undefined && (previous.status === "retried" || previous.status === "error");
+    const ref = `${m.provider}/${m.model}`;
+    const step = {
+        id: entryId,
+        kind: "step",
+        status: stepStatus(m, index.retried.has(entryId), data),
+        entryIds: trace === undefined ? [entryId] : [entryId, trace.entryId],
+        provider: m.provider,
+        model: m.model,
+        attempt: num(data?.attempt) ?? (failedBefore ? (previous?.attempt ?? 0) + 1 : 1),
+        usage: m.usage ?? zeroUsage(),
+        stopReason: m.stopReason,
+        tools: [],
+    };
+    const fallbackFrom = data !== undefined
+        ? data.fallbackFrom
+        : failedBefore && state.turnModel !== undefined && state.turnModel !== ref
+            ? state.turnModel
+            : undefined;
+    if (fallbackFrom !== undefined)
+        step.fallbackFrom = fallbackFrom;
+    if (m.errorMessage !== undefined)
+        step.errorMessage = m.errorMessage;
+    if (m.thinkingLevel !== undefined)
+        step.thinkingLevel = m.thinkingLevel;
+    const hit = cacheHitRatio(step.usage);
+    if (hit !== undefined)
+        step.cacheHitRatio = hit;
+    const requestAt = num(data?.requestAt);
+    if (data !== undefined && requestAt !== undefined) {
+        step.requestAt = requestAt;
+        step.startedAt = requestAt;
+        const first = num(data.firstTokenAt);
+        const done = num(data.doneAt);
+        if (first !== undefined) {
+            step.firstTokenAt = first;
+            step.ttftMs = Math.max(0, first - requestAt);
+        }
+        if (done !== undefined) {
+            step.doneAt = done;
+            step.endedAt = done;
+        }
+        const tps = num(data.tps);
+        if (tps !== undefined)
+            step.tps = tps;
+    }
+    else {
+        // 回退推算：assistant.timestamp ≈ 请求发出，条目时间 ≈ 请求结束
+        const start = num(m.timestamp) ?? at;
+        const end = at ?? start;
+        if (start !== undefined) {
+            step.requestAt = start;
+            step.startedAt = start;
+        }
+        if (end !== undefined) {
+            step.doneAt = end;
+            step.endedAt = end;
+        }
+        step.approx = true;
+    }
+    for (const block of m.content ?? []) {
+        if (block.type !== "toolCall")
+            continue;
+        const tool = toolNode(block.id, block.name, entryId, step, index);
+        step.tools.push(tool);
+        state.tools.set(tool.id, tool);
+    }
+    return step;
+}
+export function toolNode(id, name, assistantEntryId, step, index) {
+    const timing = index.toolTiming.get(id);
+    const tool = {
+        id,
+        kind: "tool",
+        name,
+        status: "running",
+        isError: false,
+        entryIds: [assistantEntryId],
+        children: [],
+    };
+    if (timing !== undefined && num(timing.startedAt) !== undefined) {
+        tool.startedAt = timing.startedAt;
+        putNum(tool, "endedAt", timing.endedAt);
+        putNum(tool, "approvalMs", timing.approvalMs);
+        if (timing.denied === true) {
+            tool.denied = true;
+            tool.status = "denied";
+        }
+    }
+    else {
+        if (step.doneAt !== undefined)
+            tool.startedAt = step.doneAt;
+        tool.approx = true;
+    }
+    for (const { data, entryId } of index.subcalls.get(id) ?? []) {
+        const sub = {
+            id: data.id,
+            kind: "subcall",
+            name: typeof data.name === "string" ? data.name : "",
+            parentToolCallId: id,
+            isError: data.isError === true,
+            status: data.isError === true ? "error" : "ok",
+            entryIds: [entryId],
+        };
+        putNum(sub, "startedAt", data.startedAt);
+        putNum(sub, "endedAt", data.endedAt);
+        if (sub.endedAt === undefined && data.isError !== true)
+            sub.status = "running";
+        tool.children.push(sub);
+    }
+    return tool;
+}
+export function compactionNode(id, at, trace) {
+    const node = {
+        id,
+        kind: "compaction",
+        status: trace?.data.aborted === true ? "aborted" : "ok",
+        entryIds: trace === undefined || trace.entryId === id ? [id] : [id, trace.entryId],
+    };
+    const started = num(trace?.data.startedAt);
+    const ended = num(trace?.data.endedAt);
+    if (trace !== undefined && started !== undefined && ended !== undefined) {
+        node.startedAt = started;
+        node.endedAt = ended;
+    }
+    else if (at !== undefined) {
+        node.startedAt = at;
+        node.endedAt = at;
+        node.approx = true;
+    }
+    const trigger = trace?.data.trigger;
+    if (trigger === "threshold" || trigger === "overflow" || trigger === "manual")
+        node.trigger = trigger;
+    return node;
+}
+export function compactionAsAux(node, usage) {
+    const aux = {
+        id: node.id,
+        kind: "aux",
+        purpose: "compaction",
+        status: node.status,
+        entryIds: node.entryIds,
+    };
+    if (node.startedAt !== undefined)
+        aux.startedAt = node.startedAt;
+    if (node.endedAt !== undefined)
+        aux.endedAt = node.endedAt;
+    if (node.approx === true)
+        aux.approx = true;
+    if (usage !== undefined)
+        aux.usage = usage;
+    return aux;
+}
+export function retryNode(id, data) {
+    const d = data;
+    const delayMs = num(d.delayMs) ?? 0;
+    const node = {
+        id,
+        kind: "retry_wait",
+        status: "ok",
+        entryIds: [id],
+        attempt: num(d.attempt) ?? 0,
+        delayMs,
+    };
+    const started = num(d.startedAt);
+    if (started !== undefined) {
+        node.startedAt = started;
+        node.endedAt = started + delayMs;
+    }
+    if (typeof d.reason === "string")
+        node.reason = d.reason;
+    return node;
+}
+/** 中断兜底的 step（没有 assistant 条目）：请求在途时补一个 aborted 的 step。 */
+export function abortedRequest(entryId, data, state) {
+    const requestAt = num(data.requestAt);
+    if (requestAt === undefined || state.turn === undefined)
+        return;
+    const { provider, model } = splitRef(state.model);
+    const step = {
+        id: entryId,
+        kind: "step",
+        status: "aborted",
+        entryIds: [entryId],
+        provider,
+        model,
+        attempt: num(data.attempt) ?? 1,
+        usage: zeroUsage(),
+        stopReason: "aborted",
+        requestAt,
+        startedAt: requestAt,
+        tools: [],
+    };
+    const first = num(data.firstTokenAt);
+    if (first !== undefined) {
+        step.firstTokenAt = first;
+        step.ttftMs = Math.max(0, first - requestAt);
+    }
+    const done = num(data.doneAt);
+    if (done !== undefined) {
+        step.doneAt = done;
+        step.endedAt = done;
+    }
+    if (data.fallbackFrom !== undefined)
+        step.fallbackFrom = data.fallbackFrom;
+    state.turn.steps.push(step);
+}
+export function externalNodes(taskId, list) {
+    return list.map(({ data, entryId }) => {
+        const node = {
+            id: `${taskId}#${num(data.turn) ?? 0}`,
+            kind: "external_turn",
+            status: /error|fail/i.test(String(data.stopReason))
+                ? "error"
+                : /abort|cancel/i.test(String(data.stopReason))
+                    ? "aborted"
+                    : "ok",
+            entryIds: [entryId],
+            turn: num(data.turn) ?? 0,
+            stopReason: String(data.stopReason ?? ""),
+            tools: Array.isArray(data.tools) ? data.tools : [],
+            toolCount: num(data.toolCount) ?? 0,
+            filesTouched: num(data.filesTouched) ?? 0,
+        };
+        putNum(node, "startedAt", data.startedAt);
+        putNum(node, "endedAt", data.endedAt);
+        return node;
+    });
+}
+export function subagentNode(data, entryId, live) {
+    const node = {
+        id: data.taskId,
+        kind: "subagent",
+        taskId: data.taskId,
+        agent: typeof data.agent === "string" ? data.agent : "",
+        runner: typeof data.runner === "string" ? data.runner : "ama",
+        background: data.background === true,
+        status: statusOfTask(data.status, live),
+        entryIds: [entryId],
+    };
+    putNum(node, "startedAt", data.startedAt);
+    putNum(node, "endedAt", data.endedAt);
+    if (isObject(data.usage))
+        node.usage = data.usage;
+    putNum(node, "costUsd", data.costUsd);
+    putNum(node, "turns", data.turns);
+    const ref = data.sessionRef;
+    if (isObject(ref) && typeof ref.sessionId === "string") {
+        node.childRef = { sessionId: ref.sessionId };
+        if (typeof ref.sessionFile === "string")
+            node.childRef.sessionFile = ref.sessionFile;
+    }
+    return node;
+}

package/dist/trace/build-util.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 轨迹构建器的汇总小工具（`build.ts` 用；单独成文件以守住 600 行上限）。[W6-T1]
+ */
+import type { Usage } from "../ai/types.js";
+import type { TraceNodeStatus, TraceTotals } from "./types.js";
+/** 汇总累加器：`finishTotals` 转成 `TraceTotals`。 */
+export interface TotalsAcc {
+    requests: number;
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    toolCalls: number;
+    costSum: number;
+    costed: number;
+    /** 精确 step 的 ttft 样本。 */
+    ttfts: number[];
+    /** 精确 step 的 Σoutput 与 Σ(doneAt − firstTokenAt)。 */
+    tpsOutput: number;
+    tpsMs: number;
+    durationMs?: number;
+}
+export declare function emptyTotals(): TotalsAcc;
+/** 计一次请求（进行中的 step 不计：用量还没有）。 */
+export declare function accumulate(acc: TotalsAcc, node: {
+    usage?: Usage | undefined;
+    status?: TraceNodeStatus;
+    approx?: boolean;
+    ttftMs?: number;
+    firstTokenAt?: number;
+    doneAt?: number;
+}): void;
+/** 最近秩分位（确定性；空样本 undefined）。 */
+export declare function percentile(sorted: readonly number[], p: number): number | undefined;
+export declare function finishTotals(acc: TotalsAcc): TraceTotals;
+export declare function maxDefined(a: number | undefined, b: number | undefined): number | undefined;
+/**
+ * `ama.task` 的 status → 节点状态。文件里的 `running`：有 live 叠加（会话在本进程运行）时仍是 running，
+ * 否则视为 `interrupted`（与 resume 重建任务表同一口径）。
+ */
+export declare function statusOfTask(status: unknown, live: boolean): TraceNodeStatus;
+/** 把 `from` 的计数并进 `into`（含 ttft 样本）。 */
+export declare function mergeTotals(into: TotalsAcc, from: TotalsAcc): void;

package/dist/trace/build-util.js

@@ -0,0 +1,120 @@
+/**
+ * 轨迹构建器的汇总小工具（`build.ts` 用；单独成文件以守住 600 行上限）。[W6-T1]
+ */
+export function emptyTotals() {
+    return {
+        requests: 0,
+        input: 0,
+        output: 0,
+        cacheRead: 0,
+        cacheWrite: 0,
+        toolCalls: 0,
+        costSum: 0,
+        costed: 0,
+        ttfts: [],
+        tpsOutput: 0,
+        tpsMs: 0,
+    };
+}
+/** 计一次请求（进行中的 step 不计：用量还没有）。 */
+export function accumulate(acc, node) {
+    const usage = node.usage;
+    if (usage === undefined || node.status === "running")
+        return;
+    acc.requests++;
+    acc.input += usage.input;
+    acc.output += usage.output;
+    acc.cacheRead += usage.cacheRead;
+    acc.cacheWrite += usage.cacheWrite;
+    if (usage.cost !== undefined) {
+        acc.costSum += usage.cost.total;
+        acc.costed++;
+    }
+    if (node.approx === true)
+        return;
+    if (node.ttftMs !== undefined)
+        acc.ttfts.push(node.ttftMs);
+    if (node.firstTokenAt !== undefined &&
+        node.doneAt !== undefined &&
+        node.doneAt > node.firstTokenAt &&
+        usage.output > 0) {
+        acc.tpsOutput += usage.output;
+        acc.tpsMs += node.doneAt - node.firstTokenAt;
+    }
+}
+/** 最近秩分位（确定性；空样本 undefined）。 */
+export function percentile(sorted, p) {
+    if (sorted.length === 0)
+        return undefined;
+    const rank = Math.max(1, Math.ceil(p * sorted.length));
+    return sorted[Math.min(sorted.length, rank) - 1];
+}
+export function finishTotals(acc) {
+    const totals = {
+        requests: acc.requests,
+        input: acc.input,
+        output: acc.output,
+        cacheRead: acc.cacheRead,
+        cacheWrite: acc.cacheWrite,
+        toolCalls: acc.toolCalls,
+    };
+    if (acc.costed > 0)
+        totals.cost = acc.costSum;
+    if (acc.durationMs !== undefined)
+        totals.durationMs = acc.durationMs;
+    const sorted = [...acc.ttfts].sort((a, b) => a - b);
+    const p50 = percentile(sorted, 0.5);
+    const p90 = percentile(sorted, 0.9);
+    if (p50 !== undefined)
+        totals.ttftP50 = p50;
+    if (p90 !== undefined)
+        totals.ttftP90 = p90;
+    if (acc.tpsMs > 0)
+        totals.avgTps = Math.round((acc.tpsOutput / (acc.tpsMs / 1000)) * 10) / 10;
+    const prompt = acc.input + acc.cacheRead + acc.cacheWrite;
+    if (prompt > 0)
+        totals.cacheHitRatio = acc.cacheRead / prompt;
+    return totals;
+}
+export function maxDefined(a, b) {
+    if (a === undefined)
+        return b;
+    if (b === undefined)
+        return a;
+    return Math.max(a, b);
+}
+/**
+ * `ama.task` 的 status → 节点状态。文件里的 `running`：有 live 叠加（会话在本进程运行）时仍是 running，
+ * 否则视为 `interrupted`（与 resume 重建任务表同一口径）。
+ */
+export function statusOfTask(status, live) {
+    switch (status) {
+        case "completed":
+            return "ok";
+        case "failed":
+        case "max_turns":
+            return "error";
+        case "aborted":
+            return "aborted";
+        case "interrupted":
+            return "interrupted";
+        case "running":
+            return live ? "running" : "interrupted";
+        default:
+            return "ok";
+    }
+}
+/** 把 `from` 的计数并进 `into`（含 ttft 样本）。 */
+export function mergeTotals(into, from) {
+    into.requests += from.requests;
+    into.input += from.input;
+    into.output += from.output;
+    into.cacheRead += from.cacheRead;
+    into.cacheWrite += from.cacheWrite;
+    into.toolCalls += from.toolCalls;
+    into.costSum += from.costSum;
+    into.costed += from.costed;
+    into.ttfts.push(...from.ttfts);
+    into.tpsOutput += from.tpsOutput;
+    into.tpsMs += from.tpsMs;
+}

package/dist/trace/build.d.ts

@@ -0,0 +1,82 @@
+/**
+ * 轨迹构建器（docs/wave6-plan.md §2.3、D6）。[W6-T1]
+ *
+ * `buildTrace(input, opts)` 把会话条目重建成 `Trace`（Turn → Step → Tool → Subcall / Subagent）：
+ * TUI `/trace`、`ama sessions trace`、RPC `get_trace` 三方共用同一棵树。
+ *
+ * 性质：
+ * - **纯函数**：不读时钟、不做 I/O；子会话经 `opts.loadChild` 回调读取（深度 ≤ 1：子轨迹里不再展开孙任务）。
+ * - **确定性**：同样的输入（含 `opts.now` / `opts.live`）得到逐字节相同的 JSON；节点顺序 = 条目顺序。
+ * - **不改历史**：老会话没有 `ama.trace` 时按条目时间回退推算并标 `approx`；推算出的时间不写回文件。
+ * - **容忍**：未知条目、未知 customType、损坏的 data 一律跳过；子会话缺失或读取抛错标 `childMissing`。
+ * - **不含正文**：只有 id、时间、计数与用量；提示 / 参数 / 结果的预览由调用方按 `entryIds` 回条目取。
+ *
+ * 算法：选分支（leaf = 根 → 叶子；all = 文件顺序）→ 预建索引（`ama.trace` 按 assistant / toolCall /
+ * compaction / usage 条目 id，`ama.task` 按父 toolCallId，`external_turn` 按 taskId，`context_edit` 的
+ * retry / overflow 目标）→ 顺序扫描建节点 → 叠加 `live` → 汇总。推算规则：`requestAt = assistant.timestamp`、
+ * `doneAt = 条目时间`、工具 `startedAt = assistant 条目时间`、`endedAt = toolResult.timestamp`；ttft 分位与
+ * 平均吞吐只用精确（非 approx）的 step。
+ *
+ * 汇总口径：`requests` 与 token / 费用和 `usageTotals`（session/export.ts）一致（assistant + 压缩 / 分支摘要 +
+ * `usage` 条目；进行中的请求不计）；`durationMs` = 各回合耗时之和（不含回合之间的空闲）；回合的 `endedAt`
+ * 不被后台子 Agent 拉长；文件里 `status: "running"` 的任务在没有 `live` 时视为 `interrupted`。
+ */
+import type { SessionEntry, SessionHeader } from "../session/types.js";
+import { type Trace, type TraceSubagentNode } from "./types.js";
+/** `buildTrace` 的输入：与 `ExportInput`（session/export.ts）同形，另可带会话文件路径。 */
+export interface TraceInput {
+    header: SessionHeader;
+    entries: readonly SessionEntry[];
+    /** 当前叶子；`undefined` = 最后一条条目，`null` = 空分支。`branch: "all"` 时不用。 */
+    leaf?: string | null | undefined;
+    /** 写进 `Trace.sessionFile`。 */
+    sessionFile?: string;
+}
+/** 进行中的模型请求（还没有 assistant 条目）。 */
+export interface LiveRequest {
+    requestAt: number;
+    firstTokenAt?: number;
+    provider?: string;
+    model?: string;
+    /** 流式期间估算的输出 token。 */
+    outputTokens?: number;
+}
+/** 正在执行的工具；`parentId` = codemode 外层调用（内层调用）。 */
+export interface LiveTool {
+    id: string;
+    name: string;
+    startedAt: number;
+    parentId?: string;
+}
+/** 运行中的叠加层（TUI / RPC 进行中时给；CLI 读文件不给）。 */
+export interface LiveOverlay {
+    /** 会话正在运行：没有结果的工具算 `running`（否则算 `interrupted`），最后一个回合算进行中。 */
+    running: boolean;
+    request?: LiveRequest;
+    tools?: readonly LiveTool[];
+}
+export interface BuildTraceOptions {
+    /** 缺省 `leaf`。 */
+    branch?: "leaf" | "all";
+    /** 注入的当前时刻：只在会话头与条目都没有可用时间时作 `startedAt` 兜底；构建器不读时钟。 */
+    now?: number;
+    /**
+     * 读取 ama 子会话（`ama.task.sessionRef.sessionFile`）；返回 undefined 或抛错 → `childMissing`。
+     * 不给时子 Agent 只有 `childRef`（懒加载：调用方之后用 `loadSubagentTrace`）。
+     */
+    loadChild?: (sessionFile: string) => TraceInput | undefined;
+    live?: LiveOverlay;
+}
+/** 所选分支的条目。 */
+export declare function selectTraceEntries(input: TraceInput, branch?: "leaf" | "all"): SessionEntry[];
+/**
+ * 从会话条目构建轨迹树。见文件头的性质与算法；选项见 `BuildTraceOptions`。
+ */
+export declare function buildTrace(input: TraceInput, opts?: BuildTraceOptions): Trace;
+/**
+ * 懒加载 ama 子 Agent 的子轨迹（就地写 `node.child` / `node.childMissing`，返回子轨迹）。深度 ≤ 1：
+ * 子轨迹里的任务不再展开。外部 runner 或没有会话文件时返回 undefined 且不标缺失。
+ */
+export declare function loadSubagentTrace(node: TraceSubagentNode, loadChild: (sessionFile: string) => TraceInput | undefined, now?: number): Trace | undefined;
+/** 在轨迹里找任务（子 Agent 节点）；深度优先，先找到的为准。 */
+export declare function findSubagent(trace: Trace, taskId: string): TraceSubagentNode | undefined;