@armadra/agent 0.7.3 → 0.7.5

package/dist/modes/acp/acp-server.js

@@ -19,9 +19,10 @@
 import { realpathSync } from "node:fs";
 import { resolve } from "node:path";
 import { stopReasonOf } from "../../ai/apis/shared.js";
-import { createSessionAlongside, currentSession, disposeSessionAlongside, setForegroundSession, } from "../../cli/compose-session.js";
+import { createSessionAlongside, currentSession, setForegroundSession, } from "../../cli/compose-session.js";
 import { listSessions } from "../../cli/compose-store.js";
 import { AgentSessionImpl } from "../../agent/session.js";
+import { taskControl } from "../../agents/task-control.js";
 import { RpcError } from "../../drivers/jsonrpc.js";
 import { ACP_METHODS, ACP_PROTOCOL_VERSION, RPC_ERRORS, } from "../../drivers/acp/types.js";
 import { isPermissionMode } from "../../permissions/modes.js";
@@ -31,7 +32,7 @@ import { AcpEventMapper, permissionModes, toolKind, toolLocations, toolTitle, }
 import { msg } from "../../i18n/index.js";
 import { CONFIG_IDS, applyConfigOption, availableCommands, buildConfigOptions, prepareConfigOptions, } from "./acp-config.js";
 import { clientCapabilitiesOf } from "./acp-connection.js";
-import { PromptQueue, cancelledResult, pageSessions, sessionTitle, } from "./acp-sessions.js";
+import { PromptQueue, cancelledResult, disposeQuiet, pageSessions, promptWhenIdle, quiesce, sessionTitle, } from "./acp-sessions.js";
 export const ACP_AGENT_CAPABILITIES = {
     loadSession: true,
     promptCapabilities: { image: true, audio: false, embeddedContext: true },
@@ -157,8 +158,9 @@ export class AcpServer {
                 .abort()
                 .catch(() => undefined);
         await this.queue.settled();
-        for (const session of this.sessions())
-            await session.waitForIdle().catch(() => undefined);
+        for (const s of this.sessions())
+            if (s instanceof AgentSessionImpl)
+                await quiesce(s, taskControl(s.state.sessionId));
         const foreground = this.session();
         for (const entry of this.pool.values())
             entry.unsubscribe();
@@ -167,7 +169,7 @@ export class AcpServer {
                 continue;
             if (!(foreground instanceof AgentSessionImpl))
                 continue;
-            await disposeSessionAlongside(this.runtime, session, foreground).catch(() => undefined);
+            await disposeQuiet(this.runtime, session, foreground).catch(() => undefined);
         }
         this.pool.clear();
         this.standby = undefined;
@@ -311,12 +313,11 @@ export class AcpServer {
             return {};
         this.pool.delete(id);
         this.queue.cancelQueued(id);
-        const running = this.queue.running;
-        if (running?.sessionId === id) {
-            running.cancelRequested = true;
-            await entry.session.abort().catch(() => undefined);
-            await this.queue.settled(id);
-        }
+        // [#167] 通知回合不经队列：不论谁在跑都先安静下来（停后台任务、abort 到空闲）
+        if (this.queue.running?.sessionId === id)
+            this.queue.running.cancelRequested = true;
+        await quiesce(entry.session, taskControl(id));
+        await this.queue.settled(id);
         entry.unsubscribe();
         let fallback = this.session();
         if (fallback === entry.session) {
@@ -330,12 +331,13 @@ export class AcpServer {
             }
         }
         if (fallback instanceof AgentSessionImpl)
-            await disposeSessionAlongside(this.runtime, entry.session, fallback);
+            await disposeQuiet(this.runtime, entry.session, fallback, taskControl(id));
         return {};
     }
     async prompt(params, signal) {
         const entry = this.entryOf(params);
         const { text, images } = promptOf(params["prompt"]);
+        let onAbort;
         const result = new Promise((resolve, reject) => {
             const job = {
                 sessionId: entry.id,
@@ -347,13 +349,22 @@ export class AcpServer {
             };
             // 客户端以 $/cancel_request 撤回：等价 session/cancel，答复由对等端改成 -32800。
             // 连接关闭（stdin 结束）也会 abort 这个 signal——那时不算撤回，已开始的运行照常跑完。
-            signal?.addEventListener("abort", () => {
+            onAbort = () => {
                 if (this.peer.isOpen)
                     this.cancelJob(job);
-            }, { once: true });
+            };
+            signal?.addEventListener("abort", onAbort, { once: true });
             this.queue.push(job);
         });
-        const answer = await result;
+        let answer;
+        try {
+            answer = await result;
+        }
+        finally {
+            // 有监听的组合信号（AbortSignal.any）被运行时强持有：不摘掉，job → 会话随之常驻（D2 L1）
+            if (onAbort !== undefined)
+                signal?.removeEventListener("abort", onAbort);
+        }
         if (signal?.aborted === true && this.peer.isOpen)
             throw new RpcError(RPC_ERRORS.requestCancelled, "session/prompt: request cancelled");
         return answer;
@@ -367,16 +378,17 @@ export class AcpServer {
         setForegroundSession(this.runtime, session);
         if (this.runtime.permission.mode !== entry.mode)
             session.setPermissionMode(entry.mode);
-        const before = session.getStats().tokens;
+        let before = session.getStats().tokens;
         let failure;
         try {
-            await session.prompt(job.text, job.images.length > 0 ? { images: job.images } : {});
+            // [#166] 起点取在真正发起时：等待期间结束的通知回合不计入本次 usage
+            await promptWhenIdle(session, job, () => void (before = session.getStats().tokens));
         }
         catch (error) {
             failure = error;
         }
-        await this.peer.flush();
         const after = session.getStats().tokens;
+        await this.peer.flush();
         const usage = {
             inputTokens: after.input - before.input,
             outputTokens: after.output - before.output,

package/dist/modes/acp/acp-sessions.d.ts

@@ -8,6 +8,8 @@
  */
 import type { ImageBlock } from "../../ai/types.js";
 import type { AgentSessionImpl } from "../../agent/session.js";
+import type { TaskControl } from "../../agents/task-control.js";
+import type { Runtime } from "../../cli/runtime.js";
 import type { AgentMessage, SessionListItem } from "../../session/types.js";
 import { type AcpPromptResult, type AcpListSessionsResult } from "../../drivers/acp/types.js";
 import type { PermissionMode } from "../../permissions/types.js";
@@ -78,3 +80,23 @@ export declare function decodeCursor(cursor: unknown): {
 };
 /** 一页会话（`cursor` 缺省从头）。 */
 export declare function pageSessions(items: readonly SessionListItem[], cursor: unknown, pageSize?: number): AcpListSessionsResult;
+/**
+ * 跑一个出队的提示（docs/memory-plan.md D4、§2.2，Issue #139）。[M-A]
+ *
+ * 后台子 Agent 的完成通知以 `followUp` 在会话空闲时开回合，不经 {@link PromptQueue}；那一回合在跑时
+ * 直接 `prompt` 会报 busy。这里先等它结束；与通知器竞速输了（等到空闲后它抢先开了回合）再等一轮。
+ * 不用 `streamingBehavior: "followUp"` 入队：`abort()` 不清队列，等待期间的 `session/cancel`
+ * 会让这条提示在之后的周期里冒出来。`job.cancelRequested`（cancel / close / 撤回）→ 不再发，直接返回。
+ */
+export declare function promptWhenIdle(session: AgentSessionImpl, job: PromptJob, onStart?: () => void): Promise<void>;
+/**
+ * 关会话前把它安静下来（Issue #167）：先停在跑的后台任务（被停止的任务不发完成通知），再反复 abort，
+ * 直到隔一个宏任务仍然空闲——已完成任务排在投递链上的通知会在上一周期结算后的微任务里开新周期，
+ * 一次 abort 不够。超过 `rounds` 轮仍不空闲返回 false。被打断的通知回合与用户 cancel 同样留下中断标记。
+ */
+export declare function quiesce(session: AgentSessionImpl, control: TaskControl | undefined, rounds?: number): Promise<boolean>;
+/**
+ * `disposeSessionAlongside` 的安静版：撞上 busy（SessionEnd Hook 期间又开了通知回合）→ 再 quiesce 重试；
+ * dispose 之后若还有周期（与 dispose 同一时刻开出来的）再 abort 一次。
+ */
+export declare function disposeQuiet(runtime: Runtime, session: AgentSessionImpl, fallback: AgentSessionImpl, control?: TaskControl, retries?: number): Promise<void>;

package/dist/modes/acp/acp-sessions.js

@@ -6,8 +6,10 @@
  * - 同一时刻只跑一个回合，其它会话的 `session/prompt` 进 {@link PromptQueue}（FIFO），不再回 busy；
  * - `session/list`：按 `updatedAt` 降序、`sessionId` 次序分页，cursor 是 `updatedAt|sessionId` 的 base64。
  */
+import { disposeSessionAlongside } from "../../cli/compose-session.js";
 import { RPC_ERRORS, } from "../../drivers/acp/types.js";
 import { RpcError } from "../../drivers/jsonrpc.js";
+import { AmaError } from "../../errors.js";
 import { msg } from "../../i18n/index.js";
 /** `session/list` 每页条数。 */
 export const LIST_PAGE_SIZE = 50;
@@ -155,3 +157,69 @@ export function pageSessions(items, cursor, pageSize = LIST_PAGE_SIZE) {
         ? { sessions, nextCursor: encodeCursor(last.updatedAt, last.sessionId) }
         : { sessions };
 }
+/**
+ * 跑一个出队的提示（docs/memory-plan.md D4、§2.2，Issue #139）。[M-A]
+ *
+ * 后台子 Agent 的完成通知以 `followUp` 在会话空闲时开回合，不经 {@link PromptQueue}；那一回合在跑时
+ * 直接 `prompt` 会报 busy。这里先等它结束；与通知器竞速输了（等到空闲后它抢先开了回合）再等一轮。
+ * 不用 `streamingBehavior: "followUp"` 入队：`abort()` 不清队列，等待期间的 `session/cancel`
+ * 会让这条提示在之后的周期里冒出来。`job.cancelRequested`（cancel / close / 撤回）→ 不再发，直接返回。
+ */
+export async function promptWhenIdle(session, job, onStart) {
+    for (;;) {
+        // 等周期而不是看 `state.isStreaming`：busy 以周期为准，周期的收尾阶段 isStreaming 已是 false
+        await session.waitForIdle();
+        if (job.cancelRequested)
+            return;
+        // [#166] 每次真正发起前回调（busy 重试时再调，最后一次为准）：usage 的起点不含之前的通知回合
+        onStart?.();
+        try {
+            await session.prompt(job.text, job.images.length > 0 ? { images: job.images } : {});
+            return;
+        }
+        catch (error) {
+            if (!(error instanceof AmaError && error.code === "busy"))
+                throw error;
+        }
+    }
+}
+const BUSY = Symbol("busy");
+/** 当前没有周期（含收尾阶段）：`waitForIdle()` 已结算即空闲。 */
+async function idleNow(session) {
+    return (await Promise.race([session.waitForIdle(), Promise.resolve(BUSY)])) !== BUSY;
+}
+/**
+ * 关会话前把它安静下来（Issue #167）：先停在跑的后台任务（被停止的任务不发完成通知），再反复 abort，
+ * 直到隔一个宏任务仍然空闲——已完成任务排在投递链上的通知会在上一周期结算后的微任务里开新周期，
+ * 一次 abort 不够。超过 `rounds` 轮仍不空闲返回 false。被打断的通知回合与用户 cancel 同样留下中断标记。
+ */
+export async function quiesce(session, control, rounds = 50) {
+    for (const task of control?.list() ?? [])
+        if (task.status === "running")
+            await control?.stop(task.taskId).catch(() => undefined);
+    for (let i = 0; i < rounds; i++) {
+        await session.abort();
+        await new Promise((resolve) => setImmediate(resolve));
+        if (await idleNow(session))
+            return true;
+    }
+    return false;
+}
+/**
+ * `disposeSessionAlongside` 的安静版：撞上 busy（SessionEnd Hook 期间又开了通知回合）→ 再 quiesce 重试；
+ * dispose 之后若还有周期（与 dispose 同一时刻开出来的）再 abort 一次。
+ */
+export async function disposeQuiet(runtime, session, fallback, control, retries = 3) {
+    for (let i = 0;; i++) {
+        try {
+            await disposeSessionAlongside(runtime, session, fallback);
+            break;
+        }
+        catch (error) {
+            if (i >= retries || !(error instanceof AmaError && error.code === "busy"))
+                throw error;
+            await quiesce(session, control);
+        }
+    }
+    await session.abort();
+}

package/dist/modes/context-report.js

@@ -10,7 +10,7 @@
  * 统计只读：取活动分支的投影（与 `getStats().contextTokens` 同一口径），不改请求体、不写条目。
  */
 import { AgentSessionImpl } from "../agent/session.js";
-import { DEFAULT_COMPACTION_SETTINGS, pendingPrefixMessage } from "../agent/session-compaction.js";
+import { DEFAULT_COMPACTION_SETTINGS, effectiveWindow, pendingPrefixMessage, } from "../agent/session-compaction.js";
 import { breakdownMessages, largestToolResults, } from "../compaction/breakdown.js";
 import { estimateContextTokens, estimateProjectedTokens, } from "../compaction/estimate.js";
 import { prunePolicy } from "../compaction/prune-tier.js";
@@ -48,7 +48,8 @@ export function contextSnapshot(session) {
         estimate = { ...estimate, tokens: stats.contextTokens };
     const window = stats.contextWindow;
     const reserve = compaction.reserveTokens ?? DEFAULT_COMPACTION_SETTINGS.reserveTokens;
-    const budget = window === undefined ? undefined : Math.max(0, window - reserve);
+    const soft = effectiveWindow(window, compaction);
+    const budget = soft === undefined ? undefined : Math.max(0, soft - reserve);
     const percent = window === undefined || window <= 0
         ? undefined
         : Math.min(100, Math.round((estimate.tokens / window) * 1000) / 10);

package/dist/modes/print/json-event.d.ts

@@ -4,13 +4,24 @@
  * - `message_update` 变成纯增量：去掉累计消息与 `partial`，附最新 `usage`；`done / error`
  *   保留最终 `message`。`tool_execution_end` 去掉 `result.fileChange`（[ACP-C0] 改前 / 改后全文只给
  *   ACP 映射用，不上 RPC / stream-json 线）。其余 `SessionEvent` 原样。
+ * - [M-G] `compact`（RPC 客户端声明 `compact_events`，docs/memory-plan.md D9）：`compactEvent()` 去掉
+ *   重复的大正文——`turn_end.toolResults[]` 每项只留 `{ toolCallId, toolName, isError, timestamp,
+ *   contentOmitted }`；`message_start` 与 `entry_appended`（`message` 条目）里的 toolResult / 带图片的 user
+ *   消息 `content` 换成 `""` 并加 `contentOmitted: true`。`message_end` 与 `tool_execution_end` 保持全量。
+ *   `stream-json` 不传 compact，输出不变。
  * - `toJsonLine()`：一行 JSON；Error 序列化为 `{ name, message }`，bigint 转字符串，
  *   U+2028 / U+2029 转义（部分 JSONL 客户端会把它们当换行）；图片 base64 不截断。
  */
 import type { SessionEvent } from "../../agent/types.js";
 import type { AssistantEvent } from "../../ai/types.js";
 import type { RpcEvent, WireAssistantEvent } from "../../rpc.js";
+export interface WireOptions {
+    /** [M-G] 客户端声明了 `compact_events`。 */
+    compact?: boolean;
+}
 export declare function toWireAssistantEvent(event: AssistantEvent): WireAssistantEvent;
-export declare function toWireEvent(event: SessionEvent): RpcEvent;
+/** [M-G] 精简事件：只改 turn_end / message_start / entry_appended，其余（含 message_end）原样。 */
+export declare function compactEvent(event: SessionEvent): SessionEvent;
+export declare function toWireEvent(input: SessionEvent, options?: WireOptions): RpcEvent;
 /** 一行 JSON（不含换行符）。 */
 export declare function toJsonLine(value: unknown): string;

package/dist/modes/print/json-event.js

@@ -4,6 +4,11 @@
  * - `message_update` 变成纯增量：去掉累计消息与 `partial`，附最新 `usage`；`done / error`
  *   保留最终 `message`。`tool_execution_end` 去掉 `result.fileChange`（[ACP-C0] 改前 / 改后全文只给
  *   ACP 映射用，不上 RPC / stream-json 线）。其余 `SessionEvent` 原样。
+ * - [M-G] `compact`（RPC 客户端声明 `compact_events`，docs/memory-plan.md D9）：`compactEvent()` 去掉
+ *   重复的大正文——`turn_end.toolResults[]` 每项只留 `{ toolCallId, toolName, isError, timestamp,
+ *   contentOmitted }`；`message_start` 与 `entry_appended`（`message` 条目）里的 toolResult / 带图片的 user
+ *   消息 `content` 换成 `""` 并加 `contentOmitted: true`。`message_end` 与 `tool_execution_end` 保持全量。
+ *   `stream-json` 不传 compact，输出不变。
  * - `toJsonLine()`：一行 JSON；Error 序列化为 `{ name, message }`，bigint 转字符串，
  *   U+2028 / U+2029 转义（部分 JSONL 客户端会把它们当换行）；图片 base64 不截断。
  */
@@ -13,7 +18,49 @@ export function toWireAssistantEvent(event) {
     const { partial: _partial, ...rest } = event;
     return rest;
 }
-export function toWireEvent(event) {
+/** toolResult 与带图片的 user 消息：正文换成 `""` 并标 `contentOmitted`；其它消息原样。 */
+function omitContent(message) {
+    const omit = message.role === "toolResult" ||
+        (message.role === "user" &&
+            Array.isArray(message.content) &&
+            message.content.some((block) => block.type === "image"));
+    return omit ? { ...message, content: "", contentOmitted: true } : message;
+}
+/** [M-G] 精简事件：只改 turn_end / message_start / entry_appended，其余（含 message_end）原样。 */
+export function compactEvent(event) {
+    switch (event.type) {
+        case "turn_end":
+            if (event.toolResults.length === 0)
+                return event;
+            return {
+                ...event,
+                // 线上形状（docs/rpc.md）不是完整的 ToolResultMessage：正文与 details 都不带
+                toolResults: event.toolResults.map(({ toolCallId, toolName, isError, timestamp }) => ({
+                    toolCallId,
+                    toolName,
+                    isError,
+                    timestamp,
+                    contentOmitted: true,
+                })),
+            };
+        case "message_start": {
+            const message = omitContent(event.message);
+            return message === event.message ? event : { ...event, message };
+        }
+        case "entry_appended": {
+            if (event.entry.type !== "message")
+                return event;
+            const message = omitContent(event.entry.message);
+            return message === event.entry.message
+                ? event
+                : { ...event, entry: { ...event.entry, message } };
+        }
+        default:
+            return event;
+    }
+}
+export function toWireEvent(input, options = {}) {
+    const event = options.compact === true ? compactEvent(input) : input;
     if (event.type === "tool_execution_end" && event.result.fileChange !== undefined) {
         const { fileChange: _fileChange, ...result } = event.result;
         return { ...event, result };

package/dist/modes/rpc/rpc-mode.d.ts

@@ -6,6 +6,7 @@
  * - 审批：客户端 `set_client_capabilities{capabilities:["approvals"]}` 之后才挂 UI broker；
  *   之前的 ask 无人作答 → deny。`permission_request` 带 `timeoutMs`，超时由会话 deny 并发
  *   `permission_resolved`。
+ * - [M-G] 声明 `compact_events` 之后的事件经 `toWireEvent(event, { compact: true })` 精简（json-event.ts）。
  * - 宿主 `ui.notify` → `{type:"notification", level, message}` 一行（stderr 同时一份）。
  * - stdin 关闭：撤下审批（之后的 ask 无人作答 → deny）、等在途命令与已开始的运行结束、
  *   应答写完 → 退出 0（会话由 runCli dispose）。`printf '{…prompt…}' | ama --mode rpc` 因此能拿到

package/dist/modes/rpc/rpc-mode.js

@@ -6,6 +6,7 @@
  * - 审批：客户端 `set_client_capabilities{capabilities:["approvals"]}` 之后才挂 UI broker；
  *   之前的 ask 无人作答 → deny。`permission_request` 带 `timeoutMs`，超时由会话 deny 并发
  *   `permission_resolved`。
+ * - [M-G] 声明 `compact_events` 之后的事件经 `toWireEvent(event, { compact: true })` 精简（json-event.ts）。
  * - 宿主 `ui.notify` → `{type:"notification", level, message}` 一行（stderr 同时一份）。
  * - stdin 关闭：撤下审批（之后的 ask 无人作答 → deny）、等在途命令与已开始的运行结束、
  *   应答写完 → 退出 0（会话由 runCli dispose）。`printf '{…prompt…}' | ama --mode rpc` 因此能拿到
@@ -24,7 +25,13 @@ import { cachedAgentInfos } from "../../agents/external.js";
 import { RpcApprovals, handlers } from "./commands.js";
 import { createLineReader, writeChunked } from "./jsonl.js";
 import { msg } from "../../i18n/index.js";
-export const RPC_CAPABILITIES = ["approvals", "images", "hooks", "plans"];
+export const RPC_CAPABILITIES = [
+    "approvals",
+    "images",
+    "hooks",
+    "plans",
+    "compact_events",
+];
 export async function runRpcMode(runtime, context, options = {}) {
     const stdin = options.stdin ?? process.stdin;
     const stdout = options.stdout ?? process.stdout;
@@ -34,7 +41,7 @@ export async function runRpcMode(runtime, context, options = {}) {
         writing = writing.then(() => writeChunked(stdout, line)).catch(() => undefined);
         return writing;
     };
-    const subscribe = (s) => s.subscribe((event) => void write(toWireEvent(event)));
+    const subscribe = (s) => s.subscribe((event) => void write(toWireEvent(event, { compact: ctx.capabilities.has("compact_events") })));
     let session = currentSession(runtime);
     let unsubscribe = subscribe(session);
     const approvals = new RpcApprovals();

package/dist/modes/session-report.d.ts

@@ -72,5 +72,5 @@ export declare function subscriptionRows(session: AgentSession, now?: number): K
 export declare function renderRows(rows: readonly KeyValueRow[], indent?: string): string[];
 export declare function describeCache(session: AgentSession, now?: number): string;
 export declare function describeSession(session: AgentSession, now?: number): string;
-/** `/cache fingerprint`：最近一次真实请求的前缀指纹（system / tools 哈希与模型）。 */
+/** `/cache fingerprint`：最近一次真实请求的前缀指纹（system / tools 哈希与模型；[ME-B] 再逐节列哈希）。 */
 export declare function describeFingerprint(session: AgentSession): string;

package/dist/modes/session-report.js

@@ -80,11 +80,13 @@ export function missReasonText(miss) {
         case "model_changed":
             return m.missModel;
         case "prefix_changed":
-            return miss.detail === "tools"
-                ? m.missTools
-                : miss.detail === "system"
-                    ? m.missSystem
-                    : m.missPrefix;
+            if (miss.detail === "tools")
+                return m.missTools;
+            if (miss.detail === "system")
+                return m.missSystem;
+            if (miss.detail?.startsWith("system:") === true)
+                return m.missSystemSections(miss.detail.slice("system:".length).replaceAll(",", ", "));
+            return m.missPrefix;
         case "evicted":
             return m.missEvicted;
     }
@@ -325,7 +327,7 @@ export function describeSession(session, now = Date.now()) {
         ...(external.length > 0 ? [m.externalTitle, ...renderRows(external, "  ")] : []),
     ].join("\n");
 }
-/** `/cache fingerprint`：最近一次真实请求的前缀指纹（system / tools 哈希与模型）。 */
+/** `/cache fingerprint`：最近一次真实请求的前缀指纹（system / tools 哈希与模型；[ME-B] 再逐节列哈希）。 */
 export function describeFingerprint(session) {
     const m = msg().report.session;
     if (!(session instanceof AgentSessionImpl))
@@ -338,6 +340,10 @@ export function describeFingerprint(session) {
         m.fingerprintTitle,
         ...renderRows([
             { key: "system", value: f.system },
+            ...Object.entries(f.sections ?? {}).map(([name, hash]) => ({
+                key: `  ${name}`,
+                value: hash,
+            })),
             { key: "tools", value: f.tools },
             { key: "model", value: f.model },
         ], "  "),

package/dist/rpc.d.ts

@@ -33,8 +33,11 @@ import type { TracePreview } from "./trace/preview.js";
 import type { Trace, TraceSubagentNode } from "./trace/types.js";
 export type { SessionEvent } from "./agent/types.js";
 export declare const RPC_PROTOCOL_VERSION: 1;
-/** `plans`（W5-C0）：客户端声明后计划审批交给客户端（`plan_proposed` → `plan_response`）。 */
-export type RpcCapability = "approvals" | "images" | "hooks" | "plans";
+/**
+ * `plans`（W5-C0）：客户端声明后计划审批交给客户端（`plan_proposed` → `plan_response`）。
+ * `compact_events`（M-G）：客户端声明后 turn_end / message_start / entry_appended 不重复带工具结果与图片正文。
+ */
+export type RpcCapability = "approvals" | "images" | "hooks" | "plans" | "compact_events";
 export interface RpcHello {
     type: "hello";
     protocolVersion: typeof RPC_PROTOCOL_VERSION;

package/dist/session/line-reader.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 会话文件的字节级按行读取（docs/memory-plan.md D6、§2.4）。[M-C0] 实现与单测；调用方由 [M-C] 接入
+ * （`store.ts readSessionLines`、`scan.ts forEachLine`、`list.ts`）。
+ *
+ * - fd + 一块复用的缓冲（缺省 64 KiB）顺序 `readSync`，以 `indexOf(0x0a)` 切行；跨块的残片挪到缓冲
+ *   开头续读，一行比缓冲还长时缓冲翻倍——每行不再分配，不生成全文字符串，也不 split 出整个数组；
+ * - 回调拿到的 `line` 不含 `\n` 与行尾的一个 `\r`，**只在回调期间有效**（可能是复用块的视图），
+ *   需要保留时自行拷贝或解码；空行照样回调（是否跳过由调用方决定）；
+ * - `index` 是物理行号（0 起，含空行）；`byteOffset` 是该行首字节在文件中的偏移（修复半行时
+ *   直接 `truncateSync(file, byteOffset)`）；`last` 为 true 表示这是**没有以 `\n` 结尾**的末行；
+ *   文件以 `\n` 结尾时不会多回调一个空的末行；
+ * - 回调返回 `false` 立即停止读盘并关闭 fd。
+ */
+/** 缺省块大小。 */
+export declare const LINE_CHUNK_BYTES: number;
+export interface LineVisit {
+    (line: Buffer, index: number, last: boolean, byteOffset: number): boolean | void;
+}
+/** 逐行访问 `file`（同步）；打不开时抛 `fs` 的原始错误。 */
+export declare function forEachLineSync(file: string, visit: LineVisit, chunkBytes?: number): void;
+/**
+ * ama 写的行：不解析、只解码行首就取出 type（与消息的 role），口径同 `scan.ts lineType`；
+ * 不是这种形状（或行首不足以判断 role）时 undefined，调用方退回 `JSON.parse`。
+ */
+export declare function lineTypeOf(line: Buffer): {
+    type: string;
+    role?: string;
+} | undefined;

package/dist/session/line-reader.js

@@ -0,0 +1,82 @@
+/**
+ * 会话文件的字节级按行读取（docs/memory-plan.md D6、§2.4）。[M-C0] 实现与单测；调用方由 [M-C] 接入
+ * （`store.ts readSessionLines`、`scan.ts forEachLine`、`list.ts`）。
+ *
+ * - fd + 一块复用的缓冲（缺省 64 KiB）顺序 `readSync`，以 `indexOf(0x0a)` 切行；跨块的残片挪到缓冲
+ *   开头续读，一行比缓冲还长时缓冲翻倍——每行不再分配，不生成全文字符串，也不 split 出整个数组；
+ * - 回调拿到的 `line` 不含 `\n` 与行尾的一个 `\r`，**只在回调期间有效**（可能是复用块的视图），
+ *   需要保留时自行拷贝或解码；空行照样回调（是否跳过由调用方决定）；
+ * - `index` 是物理行号（0 起，含空行）；`byteOffset` 是该行首字节在文件中的偏移（修复半行时
+ *   直接 `truncateSync(file, byteOffset)`）；`last` 为 true 表示这是**没有以 `\n` 结尾**的末行；
+ *   文件以 `\n` 结尾时不会多回调一个空的末行；
+ * - 回调返回 `false` 立即停止读盘并关闭 fd。
+ */
+import { closeSync, openSync, readSync } from "node:fs";
+import { lineType } from "./scan.js";
+/** 缺省块大小。 */
+export const LINE_CHUNK_BYTES = 64 * 1024;
+const LF = 0x0a;
+const CR = 0x0d;
+function stripCr(line) {
+    return line.length > 0 && line[line.length - 1] === CR ? line.subarray(0, -1) : line;
+}
+/** 逐行访问 `file`（同步）；打不开时抛 `fs` 的原始错误。 */
+export function forEachLineSync(file, visit, chunkBytes = LINE_CHUNK_BYTES) {
+    const fd = openSync(file, "r");
+    try {
+        // 一块复用的缓冲：未成行的残片挪到开头再续读；一行比缓冲还长时才翻倍（之后沿用）
+        let buf = Buffer.allocUnsafe(Math.max(1, Math.floor(chunkBytes)));
+        let start = 0; // 未成行数据在 buf 中的起点
+        let end = 0; // 有效数据的终点
+        let index = 0;
+        let lineStart = 0; // `start` 处对应的文件偏移
+        let position = 0;
+        for (;;) {
+            if (start > 0) {
+                buf.copyWithin(0, start, end);
+                end -= start;
+                start = 0;
+            }
+            if (end === buf.length) {
+                const grown = Buffer.allocUnsafe(buf.length * 2);
+                buf.copy(grown, 0, 0, end);
+                buf = grown;
+            }
+            const scanFrom = end; // 残片里已确认没有 \n
+            const read = readSync(fd, buf, end, buf.length - end, position);
+            if (read === 0)
+                break;
+            position += read;
+            end += read;
+            const view = buf.subarray(0, end);
+            for (let nl = view.indexOf(LF, scanFrom); nl >= 0; nl = view.indexOf(LF, start)) {
+                const line = view.subarray(start, nl);
+                const offset = lineStart;
+                lineStart += nl + 1 - start;
+                start = nl + 1;
+                if (visit(stripCr(line), index++, false, offset) === false)
+                    return;
+            }
+        }
+        if (end > start)
+            visit(stripCr(buf.subarray(start, end)), index, true, lineStart);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** 只解码这么多字节来判断行类型（`{"type":"message","message":{"role":"toolResult"` 约 48 字节）。 */
+const TYPE_HEAD_BYTES = 96;
+/**
+ * ama 写的行：不解析、只解码行首就取出 type（与消息的 role），口径同 `scan.ts lineType`；
+ * 不是这种形状（或行首不足以判断 role）时 undefined，调用方退回 `JSON.parse`。
+ */
+export function lineTypeOf(line) {
+    if (line.length <= TYPE_HEAD_BYTES)
+        return lineType(line.toString("utf8"));
+    const found = lineType(line.subarray(0, TYPE_HEAD_BYTES).toString("utf8"));
+    // role 可能被截断：宁可让调用方完整解析，也不给出与 `lineType` 不同的答案
+    if (found?.type === "message" && found.role === undefined)
+        return undefined;
+    return found;
+}

package/dist/session/list.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 会话列表（`SessionManager.list` 的实现）。[M-C] 按块逐行读（docs/memory-plan.md D6、§2.4）：
+ * 只解析头、第一条条目、`leaf` / `session_info` 行、要取 `firstPrompt` 的那一条 user 消息与末行；
+ * 其余 ama 写的行只看行首的 type / role（`lineTypeOf`），不生成全文字符串、不留条目对象。
+ *
+ * 口径与「`migrateSessionLines(readSessionLines(file).lines)` 再统计」一致：空行跳过、末尾半行忽略、
+ * 头必须是 `type: "session"` / `version === SESSION_FORMAT_VERSION` / id 与 cwd 为字符串、`leaf` 行不算
+ * 条目、重复的头与解析失败的中间行让整个文件跳过。差别只有一处：不解析的 ama 行不再逐条检查
+ * `id`（ama 写入的条目总有 id）；行尾不是 `}` 的（写到一半又被追加的坏行）仍会退回完整解析。
+ * 不经 `migrateSessionLines`——格式升到 v2 时要同时改这里（R6，见 migrate.ts）。
+ */
+import { type SessionListItem } from "./types.js";
+/** 只读列出目录下的会话（最新在前）；损坏的文件跳过。 */
+export declare function listSessionItems(dir: string): SessionListItem[];