billion-context-pi 0.1.27 → 0.1.29

package/README.md

@@ -154,7 +154,7 @@ Create `~/.pi/acp.json` (global) and/or `<project>/.pi/acp.json` (project-local,
 
 | Key | Default | Description |
 |-----|---------|-------------|
-| `debug` | `false` | Write diagnostic events to `~/.pi/acp-debug.log`. Also enabled by env `ACP_DEBUG=1`. |
+| `debug` | `false` | Enable verbose **debug-level** events in the log. The always-on log (lifecycle events, errors, warnings) is written regardless; `debug` only adds extra diagnostics. Also enabled by env `ACP_DEBUG=1`. |
 | `autoUpdate` | `true` | On Pi startup, check npm for a newer version and auto-install it (throttled to one check per 3 minutes). Disable to avoid all startup network calls. |
 | `modelContextLimit` | *(auto)* | Override the context limit (in tokens). Defaults to the model's `contextWindow`. |
 | `delegate` | `true` | Enable the `acp_delegate` tools (delegate/wait/cancel) and their system-prompt section. Set `false` to skip registering them (e.g. you use a different sub-agent extension, or run headless where async injection adds no value). |
@@ -169,7 +169,22 @@ Create `~/.pi/acp.json` (global) and/or `<project>/.pi/acp.json` (project-local,
 |----------|--------|
 | `ACP_AUTO_UPDATE` | Set to `0` / `false` / `no` / `off` (case-insensitive) to disable auto-update, overriding the config. |
 | `ACP_MODEL_CONTEXT_LIMIT` | Override the context limit. Takes precedence over the config value. |
-| `ACP_DEBUG` | Set to `1` or `true` to enable debug logging. |
+| `ACP_DEBUG` | Set to `1` or `true` to enable debug-level logging (always-on events are written regardless). |
+| `ACP_LOG_FILE` | Override the log file path (default `~/.pi/acp.log`). |
+
+### Logging
+
+billion-context-pi writes a structured, always-on log to `~/.pi/acp.log` (override with `ACP_LOG_FILE`). It covers the model's whole working session and is useful for diagnosing problems:
+
+- **Always written** (even with `debug: false`): `error`, `warn`, `info` levels — session start, every context turn (token usage / nudge decision), compress/decompress, delegate spawn/done, and **all errors and warnings** (config/state/tool failures, delegate errors, guardrail caps, update failures). Error lines include the message and stack trace.
+- **Written only when `debug: true`**: verbose `debug`-level diagnostics (full field dumps, per-turn internals).
+
+Each line: `<ISO timestamp> [<level>] [<scope>] key=value key=value`. The file rotates to `~/.pi/acp.log.old` at 10 MB.
+
+```sh
+tail -f ~/.pi/acp.log                 # watch the session live
+grep '\[error\]' ~/.pi/acp.log        # surface every recorded failure
+```
 
 ### Compression philosophy
 

package/README.zh-CN.md

@@ -153,7 +153,7 @@ billion-context-pi 开箱即用,无需任何配置。可以在 JSON 配置文件
 
 | Key | 默认值 | 说明 |
 |-----|--------|------|
-| `debug` | `false` | 将诊断事件写入 `~/.pi/acp-debug.log`。也可用环境变量 `ACP_DEBUG=1` 启用。 |
+| `debug` | `false` | 启用诊断日志(`error`/`warn`/`info` 始终写入 `~/.pi/acp.log`,此开关仅额外打开详细 `debug` 事件)。也可用环境变量 `ACP_DEBUG=1` 启用。 |
 | `autoUpdate` | `true` | Pi 启动时检查 npm 是否有更新版本并自动安装(限频:每 3 分钟最多一次检查)。禁用以避免所有启动时的网络请求。 |
 | `modelContextLimit` | *(自动)* | 覆盖上下文上限(token 数)。默认为模型的 `contextWindow`。 |
 | `delegate` | `true` | 启用 `acp_delegate` 工具(delegate/wait/cancel)及其系统提示词段落。设为 `false` 则不注册这些工具(例如你用了别的子代理扩展,或跑 headless 场景异步注入没有意义)。 |
@@ -168,7 +168,24 @@ billion-context-pi 开箱即用,无需任何配置。可以在 JSON 配置文件
 |------|------|
 | `ACP_AUTO_UPDATE` | 设为 `0` / `false` / `no` / `off`(不区分大小写)以禁用自动更新,覆盖配置值。 |
 | `ACP_MODEL_CONTEXT_LIMIT` | 覆盖上下文上限。优先级高于配置值。 |
-| `ACP_DEBUG` | 设为 `1` 或 `true` 启用 debug 日志。 |
+| `ACP_DEBUG` | 设为 `1` 或 `true` 启用 debug 日志(`error`/`warn`/`info` 始终写入,无需此开关)。 |
+| `ACP_LOG_FILE` | 覆盖日志文件路径(默认 `~/.pi/acp.log`)。 |
+
+### 日志
+
+billion-context-pi 会向 `~/.pi/acp.log`(可用 `ACP_LOG_FILE` 覆盖)写入结构化的**始终开启**日志,覆盖模型工作的整个会话,便于排查问题:
+
+- `error` — 详细记录所有报错(含 `message` 与 `stack`):上下文变换、压缩/解压/搜索执行失败、delegate 子进程错误、状态读写失败、子代理工具注册失败等。原本被静默吞掉的异常现在一律落盘。
+- `warn` — 值得注意的非致命情况:紧急 nudge 注入、配置加载失败、自动更新网络错误、工具输出被截断、委派结果注入被跳过。
+- `info` — 生命周期事件:会话启动、每轮上下文变换摘要(消息数/token/压缩比/活跃块数)、压缩/解压、delegate 派发与完成、自动更新检查。
+- `debug` —— 仅在 `debug: true` 时额外写入(细粒度的字段级事件)。
+
+每行格式:`<ISO 时间戳> [<级别>] [<范围>] key=value key=value`。文件达到 10 MB 时轮转为 `~/.pi/acp.log.old`。
+
+```bash
+tail -f ~/.pi/acp.log                 # 实时观察会话
+grep '\[error\]' ~/.pi/acp.log        # 汇总所有记录的失败
+```
 
 ### 压缩策略
 

package/dist/config.d.ts

@@ -13,7 +13,9 @@ export interface AdapterConfig {
      *  Disable via `autoUpdate: false` or env `ACP_AUTO_UPDATE=0` to avoid all
      *  network calls on startup. */
     autoUpdate?: boolean;
-    /** Write ACP debug events to the debug log file (default ~/.pi/acp-debug.log).
+    /** Enable debug-level events in the ACP log file (default ~/.pi/acp.log).
+     *  Always-on events (session/turn/compress/delegate lifecycle, all errors and
+     *  warnings) are written regardless; `debug` only adds verbose diagnostics.
      *  Default: false (or env ACP_DEBUG=1/true). */
     debug?: boolean;
     /** Enable acp_delegate tools (delegate/wait/cancel) and their system-prompt

package/dist/delegate-events.d.ts

@@ -0,0 +1,69 @@
+export interface ToolStartEvent {
+    kind: "tool-start";
+    toolName: string;
+    argsText: string;
+}
+export interface ToolUpdateEvent {
+    kind: "tool-update";
+    toolCallId: string;
+    text: string;
+}
+export interface ToolEndEvent {
+    kind: "tool-end";
+    toolName: string;
+    isError: boolean;
+}
+export interface ReplyDeltaEvent {
+    kind: "reply-delta";
+    delta: string;
+}
+export interface ReplyCompleteEvent {
+    kind: "reply-complete";
+    content: string;
+}
+export interface ThinkingDeltaEvent {
+    kind: "thinking-delta";
+    delta: string;
+}
+export type ParsedEvent = ToolStartEvent | ToolUpdateEvent | ToolEndEvent | ReplyDeltaEvent | ReplyCompleteEvent | ThinkingDeltaEvent | ThinkingEndEvent | RetryStartEvent | RetryEndEvent;
+export interface ThinkingEndEvent {
+    kind: "thinking-end";
+}
+/**
+ * Accumulates thinking_delta tokens and emits one human-readable line per
+ * thinking segment (a segment ends at thinking_end / text_start). Nothing is
+ * emitted when showThinking is off.
+ */
+export declare class ThinkingCollector {
+    private readonly showThinking;
+    private buf;
+    constructor(showThinking: boolean);
+    push(delta: string): void;
+    /** Return the segment line to write ("" when empty or disabled), resetting. */
+    flush(): string;
+}
+export interface RetryStartEvent {
+    kind: "retry-start";
+    attempt: number;
+    maxAttempts: number;
+    delayMs: number;
+    errorMessage: string;
+}
+export interface RetryEndEvent {
+    kind: "retry-end";
+    success: boolean;
+    attempt: number;
+}
+export declare function parseEventLine(line: string): ParsedEvent | null;
+/** Join `content[].text` blocks from a tool result / partialResult payload. */
+export declare function extractContentText(payload: unknown): string;
+/** Format a parsed event as human-readable activity file lines (each with a
+ *  trailing newline; empty when none). */
+export declare function activityLines(ev: ParsedEvent, opts: {
+    showThinking: boolean;
+}): string[];
+/**
+ * partialResult is an accumulated snapshot (not a delta), so each update
+ * carries everything so far. Return only the newly-appended portion.
+ */
+export declare function newPortion(text: string, prev: string): string;

package/dist/delegate-tool.d.ts

@@ -13,6 +13,7 @@ declare const DelegateParams: Type.TObject<{
     cwd: Type.TOptional<Type.TString>;
     model: Type.TOptional<Type.TString>;
     async: Type.TOptional<Type.TBoolean>;
+    showThinking: Type.TOptional<Type.TBoolean>;
 }>;
 type DelegateArgs = Static<typeof DelegateParams>;
 declare const CancelParams: Type.TObject<{
@@ -40,5 +41,7 @@ export declare function makeDelegateCancelTool(_pi: ExtensionAPI): ToolDefinitio
 export declare function buildChildArgs(args: DelegateArgs, rolePrompt: string, ctx: ExtensionContext): Promise<{
     cliArgs: string[];
     tmpDir: string;
+    isAsync: boolean;
+    useJsonStream: boolean;
 }>;
 export {};

package/dist/delegate-watchdog.d.ts

@@ -0,0 +1,31 @@
+import type { Readable } from "node:stream";
+export interface WatchdogOptions {
+    eofGraceMs: number;
+    idleMs: number;
+    timeoutMs: number;
+    killGraceMs: number;
+}
+export interface WatchdogHooks {
+    /** True once the run is finalized; watchdogs stop firing. */
+    isSettled(): boolean;
+    /** The child is about to be killed (SIGTERM). reason explains why. */
+    onKill(reason: string): void;
+    /** stdout EOF passed without the process exiting; force-finalize now. */
+    onEofGrace(): void;
+}
+export interface WatchdogHandle {
+    /** Re-arm the idle timer (call on every stdout data). */
+    poke(): void;
+    /** Stop all timers (call on finalize). */
+    dispose(): void;
+}
+/**
+ * Guarantees a hung child process gets killed. A stuck child holds its stdout
+ * fd open, so stdout EOF never fires — hence the idle timer (no output for
+ * idleMs) is the main defense; the hard time limit and the EOF grace period
+ * cover the rest. Kill is SIGTERM, escalated to SIGKILL after killGraceMs.
+ */
+export declare function attachWatchdogs(child: {
+    kill(signal: NodeJS.Signals): boolean;
+    stdout: Readable | null;
+}, hooks: WatchdogHooks, opts: WatchdogOptions): WatchdogHandle;