@dsh-edge/dsh-edge-agent 0.0.0-stage → 0.1.1

package/lib/dsh-adapter/file-logger.d.ts

@@ -0,0 +1,294 @@
+/**
+ * file-logger — M6 durable file exporter for Cordis `ctx.logger`.
+ *
+ * DSH host does not ship a service logger (`dsh --help` has no `--log-file`),
+ * and Cordis's LoggerService only installs an in-memory ring buffer (1000
+ * entries). Without an external exporter every `ctx.logger.info(...)` call
+ * lands in that buffer and is lost on exit. We register a file exporter so
+ * every dsh-edge-agent plugin's log output is durably persisted to disk,
+ * rotated on size, and tail-able for offline troubleshooting.
+ *
+ * Cordis `export()` contract is **strictly synchronous** (see
+ * `@deepseek-ai/cordis@4.0.1/src/logger.ts:46`; the loop at `:154-159`
+ * does not await) — the only safe pattern is to synchronously push the
+ * formatted line into an in-memory queue, then let a background
+ * `setInterval().unref()` flush the queue to disk. The audit-log plugin
+ * uses the same pattern (`audit-log.ts:147-152`).
+ *
+ * Loop avoidance: `export()` must NEVER call `ctx.logger.error(...)` —
+ * audit-log's own diagnostics already do (`audit-log.ts:266/309`), and a
+ * failure here would re-enter our own `export()` and spin. Failures are
+ * swallowed silently and counted; a stderr notice is emitted on the first
+ * drop and every 1000th drop after that.
+ *
+ * Append-mode (`fs.open(path, 'a')`) means each process boot appends to
+ * the existing file instead of truncating it, so install.sh's truncate-on-
+ * restart semantics are no longer in play — dsh-edge-agent's own writer
+ * owns the file lifecycle.
+ *
+ * ═══════════════════════════════════════════════════════════════════════
+ * OPERATIONS / AUDIT CHANNEL DISCIPLINE  (2026-09-01)
+ * ═══════════════════════════════════════════════════════════════════════
+ * Two log channels. They serve different consumers. Do not blur them.
+ *
+ *  ┌─ OPERATIONS LOG ──────────────────────────────────────────────────┐
+ *  │ Path:   ~/.dsh-edge-agent/log/dsh-edge-agent.log (this file)      │
+ *  │ Source: every `ctx.logger.{info,warn,error,debug}` call           │
+ *  │ Rule:   **info / warn / error entries MUST NOT contain request    │
+ *  │         bodies, response bodies, tool arguments, prompt text,    │
+ *  │         or any user PII.** Only metadata (provider, model,        │
+ *  │         reqId, durationMs, counts) and error diagnostics.         │
+ *  │                                                                   │
+ *  │         **debug entries MAY carry LLM call bodies** (request     │
+ *  │         messages + response text) for offline triage — opt-in    │
+ *  │         via `DSH_EDGE_LOG_LEVEL=debug`. 2026-09-11 default       │
+ *  │         flipped from `debug` to `info` (users said log was too   │
+ *  │         noisy — every LLM call landed 4 body lines). Re-enable   │
+ *  │         with `DSH_EDGE_LOG_LEVEL=debug`. CLOUD prompts are       │
+ *  │         pre-sanitized by input-guard before egress, so the       │
+ *  │         captured prompt is already placeholder-text for         │
+ *  │         sensitive spans. CLOUD response text is NOT redacted.   │
+ *  │         Call sites: cloud-llm-adapter.ts, local-llm-adapter.ts.  │
+ *  │         Used by operators to triage service flow, failures, and  │
+ *  │         LLM call replay.                                         │
+ *  └───────────────────────────────────────────────────────────────────┘
+ *
+ *  ┌─ AUDIT LOG ───────────────────────────────────────────────────────┐
+ *  │ Path:   ~/.dsh-edge-agent/audit/audit.plain.jsonl                 │
+ *  │ Source: every `auditLog.log({...})` call — explicit, opt-in       │
+ *  │ Rule:   **Records the actual call content** (provider, model,     │
+ *  │         promptLen, messageCount, toolName, redacted args,         │
+ *  │         durationMs). Fields are PII-redacted via                  │
+ *  │         `pii-utils.redactObject()` before write. Used by          │
+ *  │         compliance / legal / security review.                     │
+ *  └───────────────────────────────────────────────────────────────────┘
+ *
+ * Concretely: every existing `ctx.logger.info(...)` call in dsh-edge-agent
+ * carries only metadata. **Before adding a new ctx.logger call**, confirm
+ * it does not embed any of: `messages`, `args` (tool args), `promptText`,
+ * response bodies, session content, or user-supplied strings. If you need
+ * to log that data, route it through `auditLog.log(...)` so it lands in
+ * the audit JSONL with field-level redaction, NOT here.
+ *
+ * Wiring (2026-09-01): file-logger is registered as a standalone Cordis
+ * plugin id (`profiles/dsh-edge-agent/cordis.patch.yml`) so its apply()
+ * runs at boot — before audit-log / http-api / etc. The disabled
+ * aggregator `dsh-edge-agent` (see cordis.patch.yml:26-29) means the
+ * internal `src/dsh-adapter/index.ts:apply()` is never invoked, so we
+ * can't rely on it to install the exporter. Each plugin id in the patch
+ * is loaded independently via its `name:` field.
+ *
+ * @module dsh-edge-agent/file-logger
+ */
+import type { Context, Message } from '@deepseek-ai/cordis';
+import { Service } from '@deepseek-ai/cordis';
+import Schema from '@deepseek-ai/schemastery';
+export declare const name = "file-logger";
+/**
+ * 无硬依赖（§7.169，2026-10-31）。
+ *
+ * 原来是 `inject = ['web']`，只为了一句 boot 诊断（web-diag）能读
+ * `ctx.web.searchProviders.size`。代价是**整个 ops log 通道被一个无关服务
+ * 卡住**：cordis 要等 `web` 服务就绪才让本插件 apply，而**注册文件导出器的
+ * 正是本插件** ⇒ 凡是比 file-logger 更早 apply 的插件，它的启动日志（乃至
+ * 拒绝行）会**静默丢失**。
+ *
+ * 实测（§7.169，headless `dsh-edge-agent` profile，探针实测）：
+ *   - 守卫 apply 那一刻 `ctx.logger` 还没有落盘导出器；
+ *   - 同一 ctx 上 `ctx.logger.info(...)` 在 t0 **丢失**，t300 / t1500 / t4000
+ *     才落盘 —— 即「闸门上膛」启动行与拒绝行都可能无处可落。
+ *
+ * 改法：`web` 从硬依赖降为**延迟注入**（`ctx.inject(['web'], cb)`，与
+ * edge-context-view / input-guard 同款纪律），本插件零静态依赖 ⇒ 导出器注册
+ * 不再被无关服务拖后。**注意**：实测同层插件的 apply 先后由模块解析速度
+ * 决定、不靠配置树顺序（§7.169），所以「通道就位」不能靠"谁先 apply"保证 ——
+ * 消费方要用 `ctx.inject(['fileLogger'], …)` 延迟注入，回调触发时导出器必已
+ * 注册（cordis `_updateState` 只在 providing fiber 变 ACTIVE 后 notify）。
+ *
+ * 注意：桌面版 ops log 的文件名（`dsh-edge-agent-desktop.log`）来自**行**
+ * 的 config，本插件行必须比裸包名聚合行先装载 —— 零依赖后这个顺序只会更稳。
+ */
+export declare const inject: readonly [];
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export interface Config {
+    /** Directory holding the log file. Created if missing. */
+    root: string;
+    /** Filename inside `root` for the persistent log. */
+    filename: string;
+    /** Background flush cadence in ms. */
+    flushIntervalMs: number;
+    /** In-memory queue cap; oldest entry is dropped on overflow. */
+    queueCapacity: number;
+    /** Rotate log when file exceeds this size (bytes). 0 = disabled. */
+    maxFileSizeBytes: number;
+    /**
+     * Calendar-day rotation: rotate when the file's last-write day is at
+     * least this many local calendar days before today. `1` = daily
+     * rotation (first flush after midnight moves the old file to `.1`).
+     * `0` = disabled.
+     *
+     * §7.56 (2026-09-15): previously this compared elapsed `now - mtime`,
+     * which NEVER fires for an active append-mode log — continuous writes
+     * keep mtime at "moments ago", so `ageDays ≈ 0` forever (the shipped
+     * `maxFileAgeDays: 0` masked the dead branch). Calendar-day diff works
+     * for continuously-written files: at the first flush of a new day the
+     * mtime's date is yesterday, so dayDiff ≥ 1 triggers the rotation.
+     */
+    maxFileAgeDays: number;
+    /** Maximum number of rotated files to keep. */
+    maxRotatedFiles: number;
+    /**
+     * Minimum logger level emitted to disk. 2026-09-11: default flipped
+     * from `debug` back to `info` (per user feedback "log 太冗余") so the
+     * LLM body debug calls in `cloud-llm-adapter.ts` /
+     * `local-llm-adapter.ts` (LLM_REQUEST / LLM_MESSAGES / LLM_RESPONSE
+     * / LLM_RESPONSE_TEXT) are filtered by Cordis and don't reach the
+     * ops log. Set `DSH_EDGE_LOG_LEVEL=debug` to re-enable body capture
+     * for offline triage. Previously flipped 2026-09-02 info→debug; see
+     * PROGRESS §7.23 for the original flip.
+     */
+    level: LogLevel;
+}
+export declare const Config: Schema<Config>;
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        fileLogger: FileLoggerServiceImpl;
+    }
+}
+/**
+ * Singleton service exposed on `ctx.fileLogger`. Owns the in-memory queue
+ * and the background flush loop. The Cordis exporter callback installed
+ * by `installFileLogger` simply forwards to `export()` on this service.
+ */
+export declare class FileLoggerServiceImpl extends Service {
+    private readonly filePath;
+    private readonly flushIntervalMs;
+    private readonly queueCapacity;
+    private readonly maxFileSizeBytes;
+    private readonly maxFileAgeDays;
+    private readonly maxRotatedFiles;
+    /** Formatted lines waiting to be flushed to disk. */
+    private queue;
+    /** Number of entries dropped because `queue` was full. */
+    private droppedCount;
+    /** Monotonically increasing serial so we can debug dropped-entry runs. */
+    private flushSerial;
+    private flushTimer;
+    private flushPromise;
+    constructor(ctx: Context, config: Config);
+    /** Test helper returning the resolved log file path. */
+    filePathForTests(): string;
+    /** Test helper: how many entries have been dropped because the queue was full. */
+    droppedCountForTests(): number;
+    /** Start the periodic flush; idempotent. Call once from `installFileLogger`. */
+    start(): void;
+    /** Stop the periodic flush; for tests and the dispose hook. */
+    stop(): void;
+    /**
+     * Cordis exporter callback. **Synchronous, no await**. Push the
+     * formatted line onto the queue; the background timer drains it.
+     *
+     * NEVER call `this.ctx.logger.*` from here — audit-log does that on
+     * its own errors (`audit-log.ts:266/309`), which would re-enter this
+     * method and spin the loop. We swallow everything silently and count
+     * drops; a one-shot stderr notice flags the first drop and every
+     * 1000th drop after.
+     */
+    export(message: Message): void;
+    /**
+     * Drain the queue to disk. Serialised through `flushPromise` so
+     * overlapping calls (timer + dispose) don't interleave writes.
+     *
+     * Uses `fs.open(path, 'a')` rather than audit-log's read-merge-write
+     * pattern — there is no upstream reader modifying the file, so
+     * append-at-the-tail is sufficient.
+     */
+    flush(): Promise<void>;
+    /**
+     * Size + age based rotation. Copied from audit-log's
+     * `checkAndRotate` (`audit-log.ts:278-311`) — the algorithm is the same
+     * but this exporter has no read-merge-write coupling, so we only rotate
+     * here (audit-log couples rotation with its write path).
+     */
+    private checkAndRotate;
+}
+/** Resolved config used by `installFileLogger`. Pure data, easy to mock. */
+export interface ResolvedLoggerConfig {
+    root: string;
+    filename: string;
+    flushIntervalMs: number;
+    queueCapacity: number;
+    maxFileSizeBytes: number;
+    maxFileAgeDays: number;
+    maxRotatedFiles: number;
+    level: LogLevel;
+}
+/**
+ * Resolve the file-logger config from env vars with sensible defaults.
+ * Centralised here so tests can call it directly and `installFileLogger`
+ * stays a one-liner.
+ *
+ * Path resolution: `DSH_EDGE_LOG_ROOT` wins, then `USERPROFILE` (Windows),
+ * then `HOME` (POSIX). File name is fixed (`dsh-edge-agent.log`) so
+ * operators always know what file to tail.
+ *
+ * Level resolution: `DSH_EDGE_LOG_LEVEL` wins, otherwise `info`. The
+ * `info` default (2026-09-11, flipped from `debug` per user feedback
+ * "log 太冗余") suppresses LLM body debug calls in
+ * `cloud-llm-adapter.ts` / `local-llm-adapter.ts` — set
+ * `DSH_EDGE_LOG_LEVEL=debug` to re-enable.
+ */
+export declare function resolveLoggerConfig(env?: NodeJS.ProcessEnv): ResolvedLoggerConfig;
+/**
+ * Install the file exporter on a fresh Cordis context. Called once at
+ * the very top of `apply()` (`src/dsh-adapter/index.ts`) before any
+ * other plugin can call `ctx.logger.*`.
+ *
+ * Gating:
+ *   - `DSH_EDGE_LOG_FILE=false` disables (tests opt out).
+ *   - `DSH_EDGE_LOG_FILE=force` 仍被接受（历史兼容），但已是默认行为。
+ *
+ * §7.118 (2026-10-26) — 守卫语义修正：
+ *
+ * 旧守卫是 `ctx.logger.exporters.size > 1 → return undefined`，理由是
+ * "宿主若已注册 file exporter，我们再写一份就是双写"。但这个 size 启发式
+ * **分不出控制台 exporter 和文件 exporter**：
+ *
+ *   - 桌面 App 的 dsh-desktop-host 注册的是**控制台** exporter（输出走
+ *     Electron 的 stdout，不落盘 —— `~/Library/Logs/DeepSeek Harness/`
+ *     实测是空目录）。size 变成 2 → 我们跳过 → **桌面 ops log 整份消失**，
+ *     最后一次写入停在 2026-10-25 19:47。
+ *   - CLI profile 同理（这正是 `DSH_EDGE_LOG_FILE=force` 逃逸口存在的原因，
+ *     见本文件下方的历史注释）。
+ *
+ * 也就是说，这个守卫防的是一个**不会发生**的碰撞（两个 exporter 写同一个
+ * 文件），代价却是让 ops log 在两种真实宿主里都从不落盘。而"会不会写坏
+ * 文件"根本不成立：我们的输出路径是 **edge 独占**的
+ * `~/.dsh-edge-agent/log/`，宿主没有任何理由往那儿写。
+ *
+ * 真正需要防的"我们自己被装载两次"由下面的重复 `provide` try/catch 负责，
+ * 不该由 size 启发式兜。
+ *
+ * 现在：除非显式 `false`，一律注册。
+ */
+export declare function installFileLogger(ctx: Context, resolved?: ResolvedLoggerConfig): FileLoggerServiceImpl | undefined;
+/**
+ * Stop the flush timer and drain the queue. Wired into the apply()
+ * dispose hook in `index.ts` so a clean shutdown loses at most one
+ * interval's worth of logs.
+ */
+export declare function shutdownFileLogger(service: FileLoggerServiceImpl | undefined): Promise<void>;
+/**
+ * Standard Cordis plugin apply — installs the file exporter on first
+ * load and returns a disposer that drains the queue on shutdown.
+ *
+ * Wired into repo-root `cordis.patch.yml` (per §7.25 + §7.31 — bundle is
+ * self-contained) as a standalone plugin id `file-logger` so this runs
+ * at boot, before any other dsh-edge-agent plugin (audit-log / http-api /
+ * etc.) emits log lines.
+ *
+ * Idempotency: `installFileLogger` already has a first-wins guard via
+ * `ctx.logger.exporters.size > 1`. Calling it twice is a no-op.
+ */
+export declare function apply(ctx: Context, config: Config): Promise<() => Promise<void>>;
+//# sourceMappingURL=file-logger.d.ts.map

package/lib/dsh-adapter/file-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-logger.d.ts","sourceRoot":"","sources":["../../src/dsh-adapter/file-logger.ts"],"names":[],"mappings":"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"}