@armadra/agent 0.3.0 → 0.5.0

package/dist/agent/session-telemetry.js

@@ -0,0 +1,231 @@
+/**
+ * 会话遥测：输出速率与首 token 延迟（docs/wave5-plan.md §1.3，D2）。[W5-A]
+ *
+ * 以 `SessionExtension.wrapStream` 包一层流，只观察不改事件：
+ * - 只统计 `purpose: "turn"`（缺省即 turn）；summary / warm / probe / classify 原样透传、不计入；
+ * - 首 token = 首个 `text_delta` / `thinking_delta` / `toolcall_start`（`ttftMs = firstTokenAt − requestAt`）；
+ * - 流式中按增量字符估算输出 token（CJK / 假名 / 谚文每字 1，其余 / 4，与 `compaction/estimate.ts`
+ *   同口径，不逐块取整），瞬时速率取最近 2 s 滑动窗口；请求结束改用 `usage.output`（含 reasoning）；
+ * - `tps = outputTokens / (doneAt − firstTokenAt)`；会话均速 = Σoutput / Σ(done − firstToken)，只计有首
+ *   token、非 error 且生成时长 ≥ 250 ms 的请求（更短的整块到达，速率无意义，`tps` 留空）；
+ * - 流式中经 `emit` 发 `telemetry_tick`：首个在首 token 后 ≥ 500 ms，之后两次间隔 ≥ 500 ms（≤ 2 Hz，
+ *   只由增量驱动、不起计时器）；
+ *   `ticks: false`（`ui.animation: false`）时不发，界面在 message_end 时刷新。
+ *
+ * 数据从 `getStats().telemetry` 取（`contributeStats`）：进行中的请求出了首 token 后 `last` 即指向它（只有
+ * `requestAt / firstTokenAt / ttftMs`），结束后补齐 `doneAt / outputTokens / tps`；`sessionStartedAt` 是扩展创建（本进程打开会话）的时刻。
+ */
+export const TELEMETRY_TICK_MS = 500;
+export const TELEMETRY_WINDOW_MS = 2000;
+/** 不足这么长（自首 token 起）不算速率：开头几块或整块到达的回复会把速率放大到无意义。 */
+const MIN_SPAN_MS = 250;
+/** 一段增量文本的 token 估算（不取整，逐块累加不放大）。 */
+export function deltaTokens(text) {
+    let wide = 0;
+    let narrow = 0;
+    for (let i = 0; i < text.length; i++) {
+        const code = text.charCodeAt(i);
+        if (code < 0x1100)
+            narrow++;
+        else if (code >= 0xd840 && code <= 0xd87f) {
+            wide++;
+            i++;
+        }
+        else if ((code >= 0x1100 && code <= 0x11ff) ||
+            (code >= 0x3000 && code <= 0x30ff) ||
+            (code >= 0x3130 && code <= 0x318f) ||
+            (code >= 0x31f0 && code <= 0x31ff) ||
+            (code >= 0x3400 && code <= 0x4dbf) ||
+            (code >= 0x4e00 && code <= 0x9fff) ||
+            (code >= 0xac00 && code <= 0xd7af) ||
+            (code >= 0xf900 && code <= 0xfaff) ||
+            (code >= 0xff00 && code <= 0xffef))
+            wide++;
+        else
+            narrow++;
+    }
+    return wide + narrow / 4;
+}
+function deltaText(event) {
+    switch (event.type) {
+        case "text_delta":
+        case "thinking_delta":
+        case "toolcall_delta":
+            return event.delta;
+        case "toolcall_start":
+            return event.name;
+        default:
+            return undefined;
+    }
+}
+/** 一次 turn 请求的进行中记录。 */
+class RequestTracker {
+    record;
+    estimate = 0;
+    samples = [];
+    finished = false;
+    constructor(requestAt) {
+        this.record = { requestAt };
+    }
+    observe(event, at) {
+        if (this.finished)
+            return false;
+        const first = event.type === "text_delta" ||
+            event.type === "thinking_delta" ||
+            event.type === "toolcall_start";
+        if (first && this.record.firstTokenAt === undefined) {
+            this.record.firstTokenAt = at;
+            this.record.ttftMs = at - this.record.requestAt;
+        }
+        const text = deltaText(event);
+        if (text === undefined || text === "")
+            return false;
+        const tokens = deltaTokens(text);
+        this.estimate += tokens;
+        this.samples.push({ at, tokens });
+        while (this.samples.length > 0 && at - this.samples[0].at > TELEMETRY_WINDOW_MS)
+            this.samples.shift();
+        return true;
+    }
+    live(now) {
+        const first = this.record.firstTokenAt;
+        if (this.finished || first === undefined)
+            return undefined;
+        const elapsedMs = Math.max(0, now - first);
+        const recent = this.samples.filter((s) => now - s.at <= TELEMETRY_WINDOW_MS);
+        const windowTokens = recent.reduce((sum, s) => sum + s.tokens, 0);
+        const span = Math.min(TELEMETRY_WINDOW_MS, elapsedMs);
+        const tps = span < MIN_SPAN_MS ? 0 : windowTokens / (span / 1000);
+        return { tps, outputTokens: Math.round(this.estimate), elapsedMs };
+    }
+    finish(message, at) {
+        if (this.finished)
+            return;
+        this.finished = true;
+        const record = this.record;
+        record.doneAt = at;
+        const reported = message?.usage?.output;
+        const output = reported !== undefined && reported > 0 ? reported : Math.round(this.estimate);
+        record.outputTokens = output;
+        // 太短（整块到达）的请求不算速率，免得显示成上万 tok/s
+        if (record.firstTokenAt !== undefined && at - record.firstTokenAt >= MIN_SPAN_MS) {
+            record.tps = output / ((at - record.firstTokenAt) / 1000);
+        }
+    }
+}
+export function createTelemetryExtension(deps = {}) {
+    const now = deps.now ?? Date.now;
+    const ticks = deps.ticks !== false && deps.emit !== undefined;
+    const sessionStartedAt = now();
+    let last;
+    let current;
+    let sumOutput = 0;
+    let sumMs = 0;
+    let lastTickAt = Number.NEGATIVE_INFINITY;
+    const finish = (tracker, message) => {
+        if (tracker.finished)
+            return;
+        tracker.finish(message, now());
+        if (current === tracker)
+            current = undefined;
+        const r = tracker.record;
+        last = { ...r };
+        const failed = message === undefined || message.stopReason === "error";
+        if (!failed && r.firstTokenAt !== undefined && r.doneAt !== undefined) {
+            const ms = r.doneAt - r.firstTokenAt;
+            if (ms >= MIN_SPAN_MS) {
+                sumOutput += r.outputTokens ?? 0;
+                sumMs += ms;
+            }
+        }
+    };
+    const wrap = (inner, tracker) => {
+        let iterating = false;
+        let final;
+        // 只等 result() 的消费者：结果到了就结束记录；在迭代的消费者以读到终止事件为准（事件可能还在队列里）
+        void inner.result().then((message) => {
+            final = message;
+            if (!iterating)
+                finish(tracker, message);
+        }, () => finish(tracker, undefined));
+        const observe = (event) => {
+            const at = now();
+            if (event.type === "done" || event.type === "error") {
+                finish(tracker, event.message);
+                return;
+            }
+            if (!tracker.observe(event, at) || !ticks)
+                return;
+            // 首个 tick 在首 token 之后 500 ms：瞬时完成的短回复不发（RPC 事件序列不变）
+            const since = Math.max(lastTickAt, tracker.record.firstTokenAt ?? at);
+            if (at - since >= TELEMETRY_TICK_MS) {
+                lastTickAt = at;
+                deps.emit?.({ type: "telemetry_tick" });
+            }
+        };
+        return {
+            result: () => inner.result(),
+            [Symbol.asyncIterator]() {
+                iterating = true;
+                const it = inner[Symbol.asyncIterator]();
+                const iterator = {
+                    async next() {
+                        const step = await it.next();
+                        if (step.done === true)
+                            finish(tracker, final);
+                        else
+                            observe(step.value);
+                        return step;
+                    },
+                    // 提前退出（break / return）：按已有结果结束记录
+                    async return(value) {
+                        finish(tracker, final);
+                        return it.return !== undefined
+                            ? it.return(value)
+                            : { done: true, value: undefined };
+                    },
+                };
+                return iterator;
+            },
+        };
+    };
+    const snapshot = () => {
+        const out = { sessionStartedAt };
+        // 进行中的请求有了首 token 就算「最近一次」（没有 doneAt / tps），之前仍显示上一次
+        const recent = current?.record.firstTokenAt !== undefined ? current.record : last;
+        if (recent !== undefined)
+            out.last = { ...recent };
+        const live = current?.live(now());
+        if (live !== undefined)
+            out.live = live;
+        if (sumMs > 0)
+            out.avgTps = sumOutput / (sumMs / 1000);
+        return out;
+    };
+    return {
+        id: "telemetry",
+        wrapStream(stream) {
+            return (model, context, options) => {
+                const inner = stream(model, context, options);
+                if ((options.purpose ?? "turn") !== "turn")
+                    return inner;
+                const tracker = new RequestTracker(now());
+                current = tracker;
+                return wrap(inner, tracker);
+            };
+        },
+        contributeStats(stats) {
+            stats.telemetry = snapshot();
+        },
+        snapshot,
+    };
+}
+/** 组装表用的工厂：只装主会话（depth 0）；`ui.animation: false` 不发 tick。 */
+export function telemetryFactory(ui) {
+    return ({ core }) => core.depth > 0
+        ? undefined
+        : createTelemetryExtension({
+            emit: (event) => core.emit(event),
+            ticks: ui?.animation !== false,
+        });
+}

package/dist/agent/session-tools.js

@@ -13,6 +13,8 @@
 import { randomUUID } from "node:crypto";
 import { DEFAULT_APPROVAL_TIMEOUT_MS } from "../permissions/broker.js";
 import { previewAction } from "../permissions/preview.js";
+import { PermissionPipeline } from "../permissions/pipeline.js";
+import { classifierRequest } from "./session-classifier.js";
 import { runSingleToolCall } from "./tool-runner.js";
 /** 外层是这个工具时，嵌套调用的 Hook 输入带 `viaCodemode: true`。 */
 const CODEMODE_TOOL_NAME = "codemode";
@@ -21,6 +23,35 @@ function textOf(content) {
         return content;
     return content.map((block) => (block.type === "text" ? block.text : "")).join("");
 }
+/**
+ * [W5-EG] `permission_request.context`：子 Agent（depth、taskId）与外部 Agent（origin）的来源，供
+ * RPC 客户端与对话框标注。ama 子会话的请求没带 taskId 时取子会话首条 `custom{ama.task}`；
+ * 主会话自己的调用返回 undefined（事件形状不变）。
+ */
+function requestContext(core, request) {
+    const source = request.context;
+    const depth = Math.max(source?.depth ?? 0, core.depth);
+    let taskId = source?.taskId;
+    if (taskId === undefined && core.depth > 0) {
+        const head = core.manager
+            .branch()
+            .find((e) => e.type === "custom" && e.customType === "ama.task");
+        const data = head?.type === "custom" ? head.data : undefined;
+        if (typeof data?.taskId === "string")
+            taskId = data.taskId;
+    }
+    const origin = source?.origin;
+    if (depth === 0 && taskId === undefined && origin === undefined)
+        return undefined;
+    const context = {};
+    if (depth > 0)
+        context.depth = depth;
+    if (taskId !== undefined)
+        context.taskId = taskId;
+    if (origin !== undefined)
+        context.origin = origin;
+    return context;
+}
 /** 审批链：依次问每个 broker，第一个给出决定的为准；全部弃权 → deny。 */
 export async function requestApproval(core, request, signal) {
     const timeoutMs = core.options.approvalTimeoutMs ?? DEFAULT_APPROVAL_TIMEOUT_MS;
@@ -36,6 +67,11 @@ export async function requestApproval(core, request, signal) {
         event.hookReason = request.hookReason;
     if (request.preview !== undefined)
         event.preview = request.preview;
+    if (request.autoDecision !== undefined)
+        event.autoDecision = request.autoDecision;
+    const context = requestContext(core, request);
+    if (context !== undefined)
+        event.context = context;
     core.emit(event);
     void core.runHook("Notification", {
         notification: { kind: "approval", message: `approval requested for ${request.toolName}` },
@@ -117,6 +153,7 @@ export async function gateToolCall(core, call, ctx) {
     let decision = hookDecision === "ask" ? "ask" : "allow";
     let approvalReason = "hook";
     let denyMessage;
+    let autoDecision;
     if (permission !== undefined) {
         const checkInput = {
             toolName: call.name,
@@ -132,12 +169,29 @@ export async function gateToolCall(core, call, ctx) {
         decision = verdict.decision;
         approvalReason = verdict.approvalReason ?? "mode";
         denyMessage = verdict.message;
+        autoDecision = verdict.auto;
+        if (verdict.classify === true) {
+            // auto 第 3 层：规则层与静态判定都没决定，问一次独立的模型分类器（只能变 allow）
+            const judged = await core
+                .autoClassifier()
+                .classify(classifierRequest(core, call.name, input, permission.projectRoot, verdict.sandboxed === true && permission instanceof PermissionPipeline
+                ? { network: permission.bashSandbox?.network ?? "deny" }
+                : undefined), ctx.signal);
+            autoDecision = { layer: "classifier", decision: judged.decision, reason: judged.reason };
+            if (judged.cached)
+                autoDecision.cached = true;
+            if (judged.decision === "allow")
+                decision = "allow";
+        }
+        if (autoDecision !== undefined)
+            permission.recordAutoDecision?.(call.name, input, autoDecision);
     }
     else if (decision === "ask" && core.options.unattended === true) {
         decision = "deny";
     }
+    const withAuto = (gate) => autoDecision === undefined ? gate : { ...gate, autoDecision };
     if (decision === "deny") {
-        return { block: true, reason: denyMessage ?? `Permission denied for ${call.name}` };
+        return withAuto({ block: true, reason: denyMessage ?? `Permission denied for ${call.name}` });
     }
     if (decision === "ask") {
         const request = {
@@ -149,16 +203,18 @@ export async function gateToolCall(core, call, ctx) {
         };
         if (hookReason !== undefined)
             request.hookReason = hookReason;
+        if (autoDecision !== undefined)
+            request.autoDecision = autoDecision;
         const preview = safePreview(core, request);
         if (preview !== undefined)
             request.preview = preview;
         const answer = await requestApproval(core, request, ctx.signal);
         if (answer === "deny")
-            return { block: true, reason: `The user denied ${call.name}` };
+            return withAuto({ block: true, reason: `The user denied ${call.name}` });
         if (answer === "allow_session")
             permission?.rememberForSession(call.name, input);
     }
-    return replaced ? { input } : {};
+    return withAuto(replaced ? { input } : {});
 }
 export async function afterToolCall(core, call, result, parent) {
     if (core.options.hooks?.has("PostToolUse", call.name) !== true)
@@ -250,6 +306,10 @@ export function createToolContext(core, runner, call, signal, onUpdate) {
     const extra = {};
     if (file !== undefined)
         extra.sessionFile = file;
+    // [RW-B] 检查点钩子：主会话有后端时为它，task 子会话为父会话的（记到父会话当前回合）
+    const checkpoint = core.checkpointHooks?.();
+    if (checkpoint !== undefined)
+        extra.checkpoint = checkpoint;
     if (outputDir !== undefined)
         extra.outputDir = outputDir;
     if (core.depth === 0 && core.options.subagents !== false) {

package/dist/agent/session.d.ts

@@ -1,17 +1,16 @@
 /**
  * AgentSessionImpl（设计 §4.2–§4.3、§9、§11.1 第 16 步、§13.1）。[B2]
  *
- * 会话 = SessionManager（JSONL 树，事实来源）+ Agent（上下文消息、队列、run）+ 压缩 / 重试 / Hook 调度。
- * - 每条 message_end 落盘为条目；Agent 的上下文 = 活动分支的投影（压缩 / context_edit 后重建）。
- * - 首次模型请求前把系统提示 + 工具表作为首条 `system` 消息落盘并 `flush()`（此时才创建文件）；
- *   之后节或工具表变化落 system 补丁。
- * - `prompt()`：运行中且无 streamingBehavior → `AmaError{code:"busy"}`；否则展开（expandPrompt）→
- *   UserPromptSubmit Hook → 阈值压缩检查 → 会话周期（session-run.ts）；周期结束后 resolve。
- * - `steer()` / `followUp()`：运行中入队（返回 "queued"）；空闲时直接以该消息开始一个周期（"handled"）。
- * - `abort()`：中断供应商流、工具、重试等待与压缩；回到 idle 后 resolve；不清队列。
+ * 会话 = SessionManager（JSONL 树，事实来源）+ Agent（上下文、队列、run）+ 压缩 / 重试 / Hook / 回滚调度。
+ * 每条 message_end 落盘；首次请求前落 system + 工具表并 flush。`prompt()` 运行中且无
+ * streamingBehavior → busy；`steer / followUp` 运行中入队、空闲时直接开周期；`abort()` 不清队列。
+ * [W5-C0] 设置类方法在 session-settings.ts；扩展点（session-extensions.ts）的调用点：构造时
+ * wrapStream、emit 后 onEvent、runPrompt 的 beforePrompts、agent_settled 后 onAgentSettled、
+ * getStats 末尾 contributeStats、dispose。
  */
 import type { Model, ModelThinkingLevel } from "../ai/types.js";
 import type { HookEvent, HookEventPayload, HookOutcome } from "../hooks/types.js";
+import type { PermissionClassifier } from "../permissions/classifier.js";
 import type { PermissionMode } from "../permissions/types.js";
 import type { SessionManager } from "../session/manager.js";
 import type { AgentMessage, BranchSummaryEntry, SessionEntry, SessionEntryInput } from "../session/types.js";
@@ -20,7 +19,9 @@ import { Agent } from "./agent.js";
 import type { StreamFn } from "./loop.js";
 import type { AgentSessionOptions, SessionCore } from "./session-core.js";
 import { SessionCacheController } from "./session-cache.js";
-import type { SystemPromptInput } from "./system-prompt.js";
+import { type StaticSystemInput } from "./session-settings.js";
+import { type RewindDraft, type SummarizeFromResult } from "./session-rewind.js";
+import type * as CP from "../checkpoints/types.js";
 import type { AgentSession, CompactionResult, EnqueueOptions, PromptDisposition, PromptOptions, SessionEvent, SessionState, SessionStats } from "./types.js";
 export type { AgentSessionOptions } from "./session-core.js";
 export declare class AgentSessionImpl implements AgentSession, SessionCore {
@@ -32,10 +33,8 @@ export declare class AgentSessionImpl implements AgentSession, SessionCore {
     readonly readFiles: Set<string>;
     readonly stream: StreamFn;
     readonly cache: SessionCacheController;
-    private currentModel;
-    private currentThinking;
-    private readonly allTools;
-    private activeNames;
+    private readonly settings;
+    private readonly extensions;
     private readonly listeners;
     private readonly compaction;
     private retrySettings;
@@ -44,11 +43,12 @@ export declare class AgentSessionImpl implements AgentSession, SessionCore {
     private stopReason;
     private stopFlag;
     private turns;
-    private systemInput;
     private readonly subagentPool;
     private disposed;
+    private classifier;
     /** 已入队、尚未投递的消息（投递时发 queue_update）。 */
     private readonly queuedMessages;
+    private readonly rewinder;
     constructor(options: AgentSessionOptions);
     model(): Model;
     thinkingLevel(): ModelThinkingLevel;
@@ -81,29 +81,32 @@ export declare class AgentSessionImpl implements AgentSession, SessionCore {
         followUp: string[];
     };
     subscribe(listener: (event: SessionEvent) => void): () => void;
-    /** 手动压缩；运行中 → busy。 */
-    compact(instructions?: string): Promise<CompactionResult>;
+    /** 手动压缩；运行中 → busy。`cutAt`：以该条目为切点（「摘要到这里」）。 */
+    compact(instructions?: string, cutAt?: string): Promise<CompactionResult>;
+    readonly rewindPoints: () => CP.RewindPoint[];
+    readonly rewind: (request: CP.RewindRequest) => Promise<CP.RewindResult>;
+    readonly summarizeFrom: (entryId: string, instructions?: string) => Promise<SummarizeFromResult>;
+    readonly summarizeUpTo: (entryId: string, instructions?: string) => Promise<CompactionResult>;
+    readonly canUndoAbortedTurn: () => boolean;
+    readonly undoAbortedTurn: () => Promise<RewindDraft | undefined>;
+    readonly checkpointHooks: () => CP.CheckpointHooks | undefined;
     fork(entryId: string): Promise<AgentSessionImpl>;
-    /**
-     * `/tree`：同文件换叶子；`summarize` 时为离开的分支写 branch_summary（挂在新叶子下）。
-     */
+    /** `/tree`：同文件换叶子；`summarize` 时为离开的分支写 branch_summary（挂在新叶子下）。 */
     navigate(targetId: string | null, options?: {
         summarize?: boolean;
         instructions?: string;
     }): Promise<BranchSummaryEntry | undefined>;
-    setModel(ref: string): Promise<void>;
-    setThinkingLevel(level: ModelThinkingLevel): void;
-    setPermissionMode(mode: PermissionMode): void;
-    setActiveTools(names: string[]): void;
+    readonly setModel: (ref: string) => Promise<void>;
+    readonly setThinkingLevel: (level: ModelThinkingLevel) => void;
+    readonly setPermissionMode: (mode: PermissionMode) => void;
+    readonly setActiveTools: (names: string[]) => void;
     /** 宿主 / SDK 在会话创建后追加工具（下次请求前以 system 补丁声明）。 */
-    addTool(tool: ToolDefinition, active?: boolean): void;
-    /** 更新系统提示的静态部分（SessionStart Hook 的 hookContext、宿主 instructions 等）。 */
-    updateSystem(patch: Partial<Omit<SystemPromptInput, "tools" | "cwd">>): void;
+    readonly addTool: (tool: ToolDefinition, active?: boolean) => void;
+    readonly updateSystem: (patch: Partial<StaticSystemInput>) => void;
+    readonly getTools: () => readonly ToolDefinition[];
+    readonly announceStart: (reason: "startup" | "resume" | "new" | "fork") => void;
     setAutoCompaction(enabled: boolean): void;
     setAutoRetry(enabled: boolean): void;
-    getTools(): readonly ToolDefinition[];
-    /** 发 session_start（bootstrap / SDK 在会话就绪后调用一次）。 */
-    announceStart(reason: "startup" | "resume" | "new" | "fork"): void;
     get state(): SessionState;
     get messages(): readonly AgentMessage[];
     get entries(): readonly SessionEntry[];
@@ -113,5 +116,6 @@ export declare class AgentSessionImpl implements AgentSession, SessionCore {
     getStats(): SessionStats;
     dispose(): Promise<void>;
     childBase(): Pick<AgentSessionOptions, "model" | "thinkingLevel" | "activeTools" | "system">;
+    autoClassifier(): PermissionClassifier;
     spawnSubagent(request: SubagentRequest): Promise<SubagentResult>;
 }