@armadra/agent 0.5.1 → 0.6.1

package/dist/trace/query-session.js

@@ -0,0 +1,38 @@
+/**
+ * 运行中会话的轨迹查询：RPC `get_trace` 与 SDK `session.trace()`（docs/wave6-plan.md §2.6、D29）。[W6-T2]
+ *
+ * 构建器输入取自会话（`traceInputOf`）；运行中时叠一层 `{ running: true }`（没有结果的工具算 running 而不是
+ * interrupted，不编造时长）；子会话读取按会话缓存（mtime + 大小没变就不重读）。
+ */
+import { queryTrace } from "./query.js";
+import { childLoader, traceInputOf } from "./session.js";
+const loaders = new WeakMap();
+function loaderOf(session) {
+    let loader = loaders.get(session);
+    if (loader === undefined) {
+        loader = childLoader();
+        loaders.set(session, loader);
+    }
+    return loader;
+}
+/** RPC `get_trace`。参数不合法抛 `invalid_arguments`，任务不存在抛 `task_not_found`。 */
+export function sessionTrace(session, params) {
+    return queryTrace(traceInputOf(session), params, {
+        loadChild: loaderOf(session),
+        live: { running: session.state.isStreaming },
+    });
+}
+/** SDK `session.trace(options?)`：缺省全部回合；`turnLimit` 取尾部若干回合；`taskId` 取子轨迹。 */
+export function sdkSessionTrace(session, options = {}) {
+    const { branch, turnLimit, taskId, now } = options;
+    return queryTrace(traceInputOf(session), {
+        ...(branch !== undefined ? { branch } : {}),
+        ...(turnLimit !== undefined ? { turnLimit } : {}),
+        ...(taskId !== undefined ? { taskId } : {}),
+    }, {
+        loadChild: loaderOf(session),
+        live: { running: session.state.isStreaming },
+        unlimited: turnLimit === undefined,
+        ...(now !== undefined ? { now } : {}),
+    }).trace;
+}

package/dist/trace/query.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 轨迹查询：RPC `get_trace`、SDK `session.trace()`、`ama sessions trace --json` 共用（docs/wave6-plan.md §2.6）。
+ * [W6-T2]
+ *
+ * - **窗口**：在 `Trace.turns` 上切。缺省尾部 `turnLimit`（50，上限 500）个回合；`before`（回合 id）向前翻页；
+ *   `since`（条目 id）只返回「受该条目之后的新条目影响」的回合起到末尾——含 `since` 所在回合，以及子树
+ *   `entryIds` 引用了新条目的更早回合（后台任务晚到的结束条目会改到旧回合）。`since` 不在所选分支上
+ *   （rewind 之后、或未知 id）时从第一个回合起全量返回，与 `get_entries.since` 一致。客户端合并规则：
+ *   从返回的第一个回合 id 起替换本地列表的尾部（找不到该 id 就整体替换）。
+ * - `totals` 与 `aux` 始终是整条分支的；`turns` 才是窗口。
+ * - **脱敏**：结果整棵过 `redactValue`；`content:"preview"` 时附 `previews`（`preview.ts`，先脱敏后截断）。
+ * - `taskId`：ama 子会话 → 子轨迹（游标与 `leafId` 都按子会话）；外部 Agent → 空回合的轨迹 + `task.external`
+ *   骨架。两种都在 `task` 里回子 Agent 节点本身（不含 `child`，避免重复）。
+ * - 错误：`task_not_found`、`invalid_arguments`（英文 message，界面层自己渲染）。
+ */
+import { type LiveOverlay, type TraceInput } from "./build.js";
+import { type TracePreview } from "./preview.js";
+import type { Trace, TraceSubagentNode } from "./types.js";
+export declare const TURN_LIMIT_DEFAULT = 50;
+export declare const TURN_LIMIT_MAX = 500;
+export interface TraceQuery {
+    branch?: "leaf" | "all";
+    turnLimit?: number;
+    before?: string;
+    since?: string;
+    taskId?: string;
+    content?: "none" | "preview";
+}
+export interface TraceQueryResult {
+    trace: Trace;
+    hasMoreBefore: boolean;
+    cursor: {
+        before?: string;
+        since: string;
+    };
+    leafId: string | null;
+    /** `taskId` 时：子 Agent 节点本身（不含 `child`）。 */
+    task?: TraceSubagentNode;
+    /** `content:"preview"` 时：`<kind>:<id>` → 预览（只含窗口内的节点）。 */
+    previews?: Record<string, TracePreview>;
+}
+export interface TraceQueryDeps {
+    /** 读子会话（`taskId` 用；缺省时任务的子轨迹标 childMissing）。 */
+    loadChild?: (sessionFile: string) => TraceInput | undefined;
+    /** 构建时就加载全部 ama 子会话（`sessions trace --json`；RPC 不加载，按 `taskId` 取）。 */
+    loadChildren?: boolean;
+    /** 不分页：返回全部回合（`sessions trace --json`）。 */
+    unlimited?: boolean;
+    live?: LiveOverlay;
+    now?: number;
+}
+/** 校验参数（RPC 的 JSON 可能是任意形状）。 */
+export declare function checkTraceQuery(q: TraceQuery): Required<Pick<TraceQuery, "branch" | "turnLimit" | "content">>;
+/** 构建 + 切窗口 + 脱敏。 */
+export declare function queryTrace(input: TraceInput, q?: TraceQuery, deps?: TraceQueryDeps): TraceQueryResult;

package/dist/trace/query.js

@@ -0,0 +1,188 @@
+/**
+ * 轨迹查询：RPC `get_trace`、SDK `session.trace()`、`ama sessions trace --json` 共用（docs/wave6-plan.md §2.6）。
+ * [W6-T2]
+ *
+ * - **窗口**：在 `Trace.turns` 上切。缺省尾部 `turnLimit`（50，上限 500）个回合；`before`（回合 id）向前翻页；
+ *   `since`（条目 id）只返回「受该条目之后的新条目影响」的回合起到末尾——含 `since` 所在回合，以及子树
+ *   `entryIds` 引用了新条目的更早回合（后台任务晚到的结束条目会改到旧回合）。`since` 不在所选分支上
+ *   （rewind 之后、或未知 id）时从第一个回合起全量返回，与 `get_entries.since` 一致。客户端合并规则：
+ *   从返回的第一个回合 id 起替换本地列表的尾部（找不到该 id 就整体替换）。
+ * - `totals` 与 `aux` 始终是整条分支的；`turns` 才是窗口。
+ * - **脱敏**：结果整棵过 `redactValue`；`content:"preview"` 时附 `previews`（`preview.ts`，先脱敏后截断）。
+ * - `taskId`：ama 子会话 → 子轨迹（游标与 `leafId` 都按子会话）；外部 Agent → 空回合的轨迹 + `task.external`
+ *   骨架。两种都在 `task` 里回子 Agent 节点本身（不含 `child`，避免重复）。
+ * - 错误：`task_not_found`、`invalid_arguments`（英文 message，界面层自己渲染）。
+ */
+import { AmaError } from "../errors.js";
+import { redactValue } from "../session/redact.js";
+import { buildTrace, findSubagent, loadSubagentTrace, selectTraceEntries, } from "./build.js";
+import { entryLookup } from "./detail.js";
+import { childrenOf } from "./flatten.js";
+import { previewKey, previewOf } from "./preview.js";
+export const TURN_LIMIT_DEFAULT = 50;
+export const TURN_LIMIT_MAX = 500;
+function invalid(message) {
+    throw new AmaError("invalid_arguments", message);
+}
+/** 校验参数（RPC 的 JSON 可能是任意形状）。 */
+export function checkTraceQuery(q) {
+    const branch = q.branch ?? "leaf";
+    if (branch !== "leaf" && branch !== "all")
+        invalid("branch must be leaf | all");
+    const content = q.content ?? "none";
+    if (content !== "none" && content !== "preview")
+        invalid("content must be none | preview");
+    const turnLimit = q.turnLimit ?? TURN_LIMIT_DEFAULT;
+    if (!Number.isInteger(turnLimit) || turnLimit < 1 || turnLimit > TURN_LIMIT_MAX)
+        invalid(`turnLimit must be an integer in 1..${TURN_LIMIT_MAX}`);
+    for (const key of ["before", "since", "taskId"]) {
+        const value = q[key];
+        if (value !== undefined && (typeof value !== "string" || value === ""))
+            invalid(`${key} must be a non-empty string`);
+    }
+    if (q.before !== undefined && q.since !== undefined)
+        invalid("before and since are exclusive");
+    return { branch, turnLimit, content };
+}
+/** 回合子树引用的条目 id（不进子 Agent 的子轨迹：那是另一个会话的条目）。 */
+function subtreeEntryIds(node, out) {
+    for (const id of node.entryIds)
+        out.add(id);
+    if (node.kind === "subagent")
+        return;
+    for (const child of childrenOf(node))
+        subtreeEntryIds(child, out);
+}
+/** `since` 的起始回合下标。 */
+function sinceStart(turns, entries, since) {
+    const at = entries.findIndex((e) => e.id === since);
+    if (at < 0)
+        return 0;
+    const position = new Map(entries.map((e, i) => [e.id, i]));
+    const fresh = new Set(entries.slice(at + 1).map((e) => e.id));
+    let start = turns.length;
+    turns.forEach((turn, i) => {
+        if ((position.get(turn.id) ?? Infinity) <= at)
+            start = i;
+    });
+    if (start === turns.length)
+        start = 0;
+    if (fresh.size === 0)
+        return start;
+    for (let i = 0; i < start; i++) {
+        const ids = new Set();
+        subtreeEntryIds(turns[i], ids);
+        if ([...ids].some((id) => fresh.has(id)))
+            return i;
+    }
+    return start;
+}
+function windowOf(trace, entries, q, turnLimit) {
+    const n = trace.turns.length;
+    if (q.since !== undefined)
+        return { start: sinceStart(trace.turns, entries, q.since), end: n };
+    let end = n;
+    if (q.before !== undefined) {
+        end = trace.turns.findIndex((t) => t.id === q.before);
+        if (end < 0)
+            invalid(`before ${q.before} is not a turn id on this branch`);
+    }
+    return { start: Math.max(0, end - turnLimit), end };
+}
+function emptyTrace(parent, node) {
+    const trace = {
+        version: 1,
+        sessionId: node.childRef?.sessionId ?? node.taskId,
+        cwd: parent.cwd,
+        startedAt: node.startedAt ?? parent.startedAt,
+        totals: {
+            requests: 0,
+            input: node.usage?.input ?? 0,
+            output: node.usage?.output ?? 0,
+            cacheRead: node.usage?.cacheRead ?? 0,
+            cacheWrite: node.usage?.cacheWrite ?? 0,
+            toolCalls: (node.external ?? []).reduce((n, t) => n + t.toolCount, 0),
+            ...(node.costUsd !== undefined ? { cost: node.costUsd } : {}),
+        },
+        turns: [],
+        aux: [],
+        partial: node.status === "running",
+    };
+    if (node.endedAt !== undefined)
+        trace.endedAt = node.endedAt;
+    return trace;
+}
+function collectPreviews(nodes, lookup) {
+    const out = {};
+    const visit = (node) => {
+        const p = previewOf(node, lookup);
+        if (p !== undefined)
+            out[previewKey(node)] = p;
+        if (node.kind === "subagent")
+            return;
+        for (const child of childrenOf(node))
+            visit(child);
+    };
+    for (const node of nodes)
+        visit(node);
+    return out;
+}
+/** 构建 + 切窗口 + 脱敏。 */
+export function queryTrace(input, q = {}, deps = {}) {
+    const { branch, turnLimit, content } = checkTraceQuery(q);
+    const base = {
+        ...(deps.live !== undefined ? { live: deps.live } : {}),
+        ...(deps.now !== undefined ? { now: deps.now } : {}),
+    };
+    const eager = deps.loadChildren === true && deps.loadChild !== undefined;
+    let trace = buildTrace(input, {
+        branch,
+        ...base,
+        ...(eager ? { loadChild: deps.loadChild } : {}),
+    });
+    let source = input;
+    let sourceBranch = branch;
+    let task;
+    if (q.taskId !== undefined) {
+        const node = findSubagent(trace, q.taskId);
+        if (node === undefined)
+            throw new AmaError("task_not_found", `no task ${q.taskId} in this session`);
+        const loadChild = deps.loadChild ?? (() => undefined);
+        const child = loadSubagentTrace(node, loadChild, deps.now);
+        const file = node.childRef?.sessionFile;
+        const childInput = child !== undefined && file !== undefined ? loadChild(file) : undefined;
+        const { child: _omit, ...rest } = node;
+        task = rest;
+        if (child !== undefined && childInput !== undefined) {
+            trace = child;
+            source = childInput;
+            sourceBranch = "leaf";
+        }
+        else {
+            trace = emptyTrace(trace, node);
+            source = { ...input, entries: [] };
+        }
+    }
+    const entries = selectTraceEntries(source, sourceBranch);
+    const { start, end } = windowOf(trace, entries, q, deps.unlimited === true ? Infinity : turnLimit);
+    const turns = trace.turns.slice(start, end);
+    const leafId = source.entries.length === 0
+        ? null
+        : source.leaf === undefined
+            ? (source.entries.at(-1)?.id ?? null)
+            : source.leaf;
+    const result = {
+        trace: { ...trace, turns },
+        hasMoreBefore: start > 0,
+        cursor: {
+            ...(start > 0 && turns[0] !== undefined ? { before: turns[0].id } : {}),
+            since: entries.at(-1)?.id ?? "",
+        },
+        leafId,
+    };
+    if (task !== undefined)
+        result.task = task;
+    if (content === "preview")
+        result.previews = collectPreviews(turns, entryLookup(source.entries, source.header.cwd));
+    return redactValue(result);
+}

package/dist/trace/session.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 轨迹与运行中会话之间的胶水（TUI `/trace`、line 模式 `/trace`；W6-T2 的 RPC / SDK 可复用）。[W6-T1]
+ *
+ * - `traceInputOf(session)`：会话 → `TraceInput`（头、全部条目、当前叶子、会话文件）。
+ * - `childLoader()`：读 ama 子会话文件（只读、不加锁），按 mtime + 大小缓存；读不到返回 undefined
+ *   （构建器据此标 `childMissing`）。
+ * - `LiveTracker`：订阅会话事件，给出 `LiveOverlay`（在途请求、执行中的工具、是否运行中）。
+ * - `traceText(session, taskId?)`：line 模式的整表文本。
+ */
+import type { AgentSession, SessionEvent } from "../agent/types.js";
+import type { CommandHandler } from "../modes/commands-core.js";
+import { type LiveOverlay, type TraceInput } from "./build.js";
+import type { Trace } from "./types.js";
+/** 会话 → 构建器输入。非 `AgentSessionImpl`（测试替身）用 state 拼一个头，叶子取最后一条。 */
+export declare function traceInputOf(session: AgentSession): TraceInput;
+/** 只读读取一个会话文件为构建器输入；读不到或损坏返回 undefined。 */
+export declare function readTraceInput(file: string): TraceInput | undefined;
+export type ChildLoader = ((file: string) => TraceInput | undefined) & {
+    /** 已读过的子会话（详情预览取正文用）。 */
+    inputs(): TraceInput[];
+};
+/** 带缓存的子会话读取（文件没变就不重读）。 */
+export declare function childLoader(read?: (file: string) => TraceInput | undefined): ChildLoader;
+/** 订阅会话事件，维护 live 叠加层。 */
+export declare class LiveTracker {
+    private readonly session;
+    private readonly now;
+    private request;
+    private readonly tools;
+    constructor(session: () => AgentSession, now?: () => number);
+    /** 处理一个事件；返回它是否影响轨迹（调用方据此安排刷新）。 */
+    onEvent(event: SessionEvent): boolean;
+    overlay(): LiveOverlay;
+}
+/** 任务的根节点（ama 子会话就地加载子轨迹）。 */
+export declare function taskRoot(trace: Trace, taskId: string, loadChild: ChildLoader): import("./types.js").TraceSubagentNode | undefined;
+/** line 模式 `/trace [任务 id]` 的文本。 */
+export declare function traceText(session: AgentSession, taskId?: string): string;
+/** line 模式 `CommandContext.extra.trace`。 */
+export declare const lineTraceCommand: CommandHandler;

package/dist/trace/session.js

@@ -0,0 +1,168 @@
+/**
+ * 轨迹与运行中会话之间的胶水（TUI `/trace`、line 模式 `/trace`；W6-T2 的 RPC / SDK 可复用）。[W6-T1]
+ *
+ * - `traceInputOf(session)`：会话 → `TraceInput`（头、全部条目、当前叶子、会话文件）。
+ * - `childLoader()`：读 ama 子会话文件（只读、不加锁），按 mtime + 大小缓存；读不到返回 undefined
+ *   （构建器据此标 `childMissing`）。
+ * - `LiveTracker`：订阅会话事件，给出 `LiveOverlay`（在途请求、执行中的工具、是否运行中）。
+ * - `traceText(session, taskId?)`：line 模式的整表文本。
+ */
+import { statSync } from "node:fs";
+import { AgentSessionImpl } from "../agent/session.js";
+import { msg } from "../i18n/index.js";
+import { readSessionReadOnly } from "../session/scan.js";
+import { plainTheme } from "../tui/theme.js";
+import { buildTrace, findSubagent, loadSubagentTrace, } from "./build.js";
+import { describeNode, entryLookup } from "./detail.js";
+import { flattenNode } from "./flatten.js";
+import { expandAll, formatTraceText, summaryText } from "./format.js";
+/** 会话 → 构建器输入。非 `AgentSessionImpl`（测试替身）用 state 拼一个头，叶子取最后一条。 */
+export function traceInputOf(session) {
+    if (session instanceof AgentSessionImpl) {
+        const manager = session.manager;
+        const file = manager.file();
+        return {
+            header: manager.header(),
+            entries: manager.entries(),
+            leaf: manager.leafId(),
+            ...(file !== undefined ? { sessionFile: file } : {}),
+        };
+    }
+    const entries = session.entries;
+    const header = {
+        type: "session",
+        version: 1,
+        id: session.state.sessionId,
+        timestamp: entries[0]?.timestamp ?? new Date(0).toISOString(),
+        cwd: session.state.cwd,
+        agent: { name: "ama", version: "" },
+    };
+    const file = session.state.sessionFile;
+    return { header, entries, ...(file !== undefined ? { sessionFile: file } : {}) };
+}
+/** 只读读取一个会话文件为构建器输入；读不到或损坏返回 undefined。 */
+export function readTraceInput(file) {
+    try {
+        const read = readSessionReadOnly(file);
+        return { header: read.header, entries: read.entries, leaf: read.leaf, sessionFile: file };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** 带缓存的子会话读取（文件没变就不重读）。 */
+export function childLoader(read = readTraceInput) {
+    const cache = new Map();
+    const load = ((file) => {
+        let stamp = "";
+        try {
+            const st = statSync(file);
+            stamp = `${st.mtimeMs}:${st.size}`;
+        }
+        catch {
+            stamp = "missing";
+        }
+        const hit = cache.get(file);
+        if (hit !== undefined && hit.stamp === stamp)
+            return hit.input;
+        const input = stamp === "missing" ? undefined : read(file);
+        cache.set(file, { stamp, input });
+        return input;
+    });
+    load.inputs = () => [...cache.values()].flatMap((v) => (v.input === undefined ? [] : [v.input]));
+    return load;
+}
+/** 订阅会话事件，维护 live 叠加层。 */
+export class LiveTracker {
+    session;
+    now;
+    request;
+    tools = new Map();
+    constructor(session, now = Date.now) {
+        this.session = session;
+        this.now = now;
+    }
+    /** 处理一个事件；返回它是否影响轨迹（调用方据此安排刷新）。 */
+    onEvent(event) {
+        switch (event.type) {
+            case "message_start":
+                if (event.message.role !== "assistant")
+                    return false;
+                this.request = { requestAt: event.message.timestamp };
+                return true;
+            case "message_update":
+                if (this.request === undefined || this.request.firstTokenAt !== undefined)
+                    return false;
+                this.request.firstTokenAt = this.now();
+                this.request.provider = event.message.provider;
+                this.request.model = event.message.model;
+                return true;
+            case "message_end":
+                if (event.message.role !== "assistant")
+                    return false;
+                this.request = undefined;
+                return true;
+            case "tool_execution_start":
+                this.tools.set(event.toolCallId, {
+                    id: event.toolCallId,
+                    name: event.toolName,
+                    startedAt: this.now(),
+                    ...(event.parentToolCallId !== undefined ? { parentId: event.parentToolCallId } : {}),
+                });
+                return true;
+            case "tool_execution_end":
+                this.tools.delete(event.toolCallId);
+                return true;
+            case "agent_end":
+                this.request = undefined;
+                this.tools.clear();
+                return true;
+            case "entry_appended":
+            case "telemetry_tick":
+            case "agent_start":
+                return true;
+            default:
+                return false;
+        }
+    }
+    overlay() {
+        const live = { running: this.session().state.isStreaming };
+        if (this.request !== undefined)
+            live.request = { ...this.request };
+        if (this.tools.size > 0)
+            live.tools = [...this.tools.values()];
+        return live;
+    }
+}
+/** 任务的根节点（ama 子会话就地加载子轨迹）。 */
+export function taskRoot(trace, taskId, loadChild) {
+    const node = findSubagent(trace, taskId);
+    if (node !== undefined)
+        loadSubagentTrace(node, loadChild);
+    return node;
+}
+/** line 模式 `/trace [任务 id]` 的文本。 */
+export function traceText(session, taskId) {
+    const input = traceInputOf(session);
+    const loadChild = childLoader();
+    const trace = buildTrace(input, { loadChild });
+    const lookup = entryLookup([...input.entries, ...loadChild.inputs().flatMap((i) => i.entries)], input.header.cwd);
+    const ctx = {
+        theme: plainTheme(),
+        describe: (n) => describeNode(n, lookup),
+    };
+    if (taskId === undefined)
+        return formatTraceText(trace, ctx);
+    const node = taskRoot(trace, taskId, loadChild);
+    if (node === undefined)
+        return `${msg().trace.taskNotFound(taskId)}\n`;
+    const rows = expandAll((expanded) => flattenNode(node, { expanded }));
+    // 标题换成任务；汇总用子轨迹（外部任务没有子轨迹，只有标题与骨架行）
+    const summary = node.child !== undefined ? ` · ${summaryText(node.child, ctx.theme)}` : "";
+    return formatTraceText(trace, ctx, rows, `${msg().trace.taskTitle(node.taskId, node.agent)}${summary}`);
+}
+/** line 模式 `CommandContext.extra.trace`。 */
+export const lineTraceCommand = async (args, ctx) => {
+    const taskId = args.trim() === "" ? undefined : args.trim();
+    return { kind: "handled", message: traceText(ctx.session(), taskId).replace(/\n$/, "") };
+};