@renxqoo/renx-code 0.0.4 → 0.0.6

package/vendor/agent-root/src/agent/app/sqlite-client.ts

@@ -0,0 +1,177 @@
+import * as fs from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import * as path from 'node:path';
+
+interface SqliteStatementLike {
+  run: (...params: unknown[]) => unknown;
+  get: (...params: unknown[]) => unknown;
+  all: (...params: unknown[]) => unknown[];
+}
+
+interface SqliteDatabaseLike {
+  exec: (sql: string) => void;
+  prepare: (sql: string) => SqliteStatementLike;
+  close: () => void;
+}
+
+interface BunSqliteStatementLike {
+  run: (...params: unknown[]) => unknown;
+  get: (...params: unknown[]) => unknown;
+  all: (...params: unknown[]) => unknown[];
+}
+
+interface BunSqliteDatabaseLike {
+  exec: (sql: string) => unknown;
+  query: (sql: string) => BunSqliteStatementLike;
+  close: () => unknown;
+}
+
+class BunSqliteDatabaseAdapter implements SqliteDatabaseLike {
+  constructor(private readonly db: BunSqliteDatabaseLike) {}
+
+  exec(sql: string): void {
+    this.db.exec(sql);
+  }
+
+  prepare(sql: string): SqliteStatementLike {
+    const statement = this.db.query(sql);
+    return {
+      run: (...params: unknown[]) => statement.run(...params),
+      get: (...params: unknown[]) => statement.get(...params),
+      all: (...params: unknown[]) => statement.all(...params),
+    };
+  }
+
+  close(): void {
+    this.db.close();
+  }
+}
+
+/**
+ * Agent-v4 app 专用 SQLite 客户端。
+ * 只负责连接与事务，不执行通用 storage 模块的旧迁移。
+ */
+export class AgentAppSqliteClient {
+  private static readonly require = createRequire(import.meta.url);
+  private db: SqliteDatabaseLike | null = null;
+  private initialized = false;
+  private initializePromise: Promise<void> | null = null;
+
+  constructor(private readonly dbPath: string) {}
+
+  async prepare(): Promise<void> {
+    if (this.initialized) {
+      return;
+    }
+    if (this.initializePromise) {
+      return this.initializePromise;
+    }
+    this.initializePromise = this.doPrepare();
+    try {
+      await this.initializePromise;
+    } finally {
+      this.initializePromise = null;
+    }
+  }
+
+  private async doPrepare(): Promise<void> {
+    await fs.mkdir(path.dirname(this.dbPath), { recursive: true });
+
+    this.db = this.tryCreateNodeSqlite() ?? this.tryCreateBunSqlite();
+    if (!this.db) {
+      throw new Error(
+        'Unable to initialize sqlite backend: neither "node:sqlite" nor "bun:sqlite" is available.'
+      );
+    }
+
+    this.db.exec('PRAGMA foreign_keys = ON;');
+    this.db.exec('PRAGMA journal_mode = WAL;');
+    this.db.exec('PRAGMA synchronous = NORMAL;');
+    this.db.exec('PRAGMA temp_store = MEMORY;');
+    this.db.exec('PRAGMA busy_timeout = 5000;');
+    this.initialized = true;
+  }
+
+  async exec(sql: string): Promise<void> {
+    this.requireDb().exec(sql);
+  }
+
+  async run(sql: string, params: unknown[] = []): Promise<void> {
+    this.requireDb()
+      .prepare(sql)
+      .run(...params);
+  }
+
+  async get<T>(sql: string, params: unknown[] = []): Promise<T | undefined> {
+    return this.requireDb()
+      .prepare(sql)
+      .get(...params) as T | undefined;
+  }
+
+  async all<T>(sql: string, params: unknown[] = []): Promise<T[]> {
+    return this.requireDb()
+      .prepare(sql)
+      .all(...params) as T[];
+  }
+
+  async transaction<T>(fn: () => Promise<T>): Promise<T> {
+    const db = this.requireDb();
+    db.exec('BEGIN IMMEDIATE;');
+    try {
+      const result = await fn();
+      db.exec('COMMIT;');
+      return result;
+    } catch (error) {
+      db.exec('ROLLBACK;');
+      throw error;
+    }
+  }
+
+  async close(): Promise<void> {
+    if (this.initializePromise) {
+      await this.initializePromise.catch(() => undefined);
+    }
+    if (this.db) {
+      try {
+        this.db.exec('PRAGMA wal_checkpoint(TRUNCATE);');
+      } catch {
+        // Ignore checkpoint errors during shutdown and still close the handle.
+      }
+      this.db.close();
+      this.db = null;
+    }
+    this.initialized = false;
+  }
+
+  private tryCreateNodeSqlite(): SqliteDatabaseLike | null {
+    try {
+      const sqliteModule = AgentAppSqliteClient.require('node:sqlite') as {
+        DatabaseSync: new (location: string) => SqliteDatabaseLike;
+      };
+      return new sqliteModule.DatabaseSync(this.dbPath);
+    } catch {
+      return null;
+    }
+  }
+
+  private tryCreateBunSqlite(): SqliteDatabaseLike | null {
+    try {
+      const sqliteModule = AgentAppSqliteClient.require('bun:sqlite') as {
+        Database: new (location: string, options?: { create?: boolean }) => BunSqliteDatabaseLike;
+      };
+      const db = new sqliteModule.Database(this.dbPath, { create: true });
+      return new BunSqliteDatabaseAdapter(db);
+    } catch {
+      return null;
+    }
+  }
+
+  private requireDb(): SqliteDatabaseLike {
+    if (!this.db) {
+      throw new Error('SQLite client not initialized. Call prepare() first.');
+    }
+    return this.db;
+  }
+}
+
+export const AGENT_APP_SQLITE_CLIENT_MODULE = 'renx-app-sqlite-client';

package/vendor/agent-root/src/agent/docs/cli-app-layer/00-README.md

@@ -0,0 +1,36 @@
+# Agent-V4 CLI 应用层技术文档总览
+
+本目录用于沉淀 `agent-v4` 的应用层实现设计，目标是让 `StatelessAgent` 内核可稳定服务 CLI 场景，并保持无状态架构原则。
+
+## 文档清单（按编号）
+
+- `01-scope-and-goals.md`：目标、范围、非目标、约束
+- `02-architecture-overview.md`：总体分层架构与依赖方向
+- `03-domain-model-and-contracts.md`：领域模型与核心数据契约
+- `04-ports-and-interfaces.md`：应用层 Port 接口定义
+- `05-run-orchestration-and-state-machine.md`：执行编排、状态机与时序
+- `06-cli-commands-and-ux.md`：CLI 命令与交互规范
+- `07-storage-design-local.md`：Phase 1 本地存储设计
+- `08-error-and-observability.md`：错误策略、日志、指标、追踪
+- `09-security-and-policy-boundary.md`：安全边界与策略层职责
+- `10-test-plan-and-acceptance.md`：测试计划与验收标准
+- `11-implementation-phases.md`：分阶段实施计划
+- `12-open-questions-and-risks.md`：开放问题与风险登记
+- `13-sqlite-schema-fields-and-rationale.md`：SQLite 表结构、字段释义与存储理由
+- `14-project-flow-mermaid.md`：项目级详细流程图（Mermaid）
+
+## 使用方式
+
+1. 先阅读 `01` 到 `05`，统一架构和执行语义。
+2. 再阅读 `06` 到 `09`，明确 CLI 落地方式与运维安全边界。
+3. 使用 `10` 和 `11` 驱动开发计划与验收。
+4. `12` 用于实现前对齐决策，避免反复返工。
+
+## 当前状态
+
+- 文档为“可实现级别”的设计稿。
+- 默认不改动 `agent-v4` 内核契约。
+- 应用层实现应以 Port + Adapter 方式扩展，避免反向侵入内核。
+## 补充文档
+
+- `15-openclaw-style-project-blueprint.md`：说明如何在 `agent-v4` 之上实现一个类似 OpenClaw 的网关化、多渠道、插件化系统。

package/vendor/agent-root/src/agent/docs/cli-app-layer/01-scope-and-goals.md

@@ -0,0 +1,33 @@
+# 01. 范围与目标
+
+## 1. 背景
+
+`agent-v4` 已具备内核执行能力（LLM 调用、工具执行、流式事件、错误契约、超时预算）。当前缺口是可被 CLI 直接使用的应用层。
+
+## 2. 目标
+
+- 提供可复用的应用层入口，将内核能力组装为 CLI 可用服务。
+- 保持无状态原则：执行真相进入存储，不依赖进程内全局状态。
+- 支持前台流式执行（Phase 1），并为后续后台化与恢复预留接口。
+- 提供清晰的执行生命周期：创建、运行、完成、失败、取消。
+
+## 3. 范围（In Scope）
+
+- 应用层服务接口：`runForeground/getRun/listRuns`。
+- 事件桥接：`runStream` 流事件 + `onMessage/onCheckpoint/onCompaction/onError` 回调统一落库与发布。
+- 本地存储实现（Phase 1 统一采用 SQLite，文件存储仅作历史兼容方案）。
+- CLI 命令协议与输出事件模型。
+- 测试与验收规范。
+
+## 4. 非目标（Out of Scope）
+
+- P0 级安全策略重构（如 `bash` 重写）
+- 分布式任务队列与多 Worker 编排
+- 跨主机高可用部署方案
+- Redis/DB 幂等账本生产实现（仅保留接口）
+
+## 5. 关键约束
+
+- 不破坏 `StatelessAgent` 核心接口。
+- 应用层必须依赖抽象 Port，不直接耦合具体存储细节。
+- CLI 层仅做解析与展示，不承载业务编排逻辑。

package/vendor/agent-root/src/agent/docs/cli-app-layer/02-architecture-overview.md

@@ -0,0 +1,40 @@
+# 02. 总体架构
+
+## 1. 分层
+
+- Kernel Layer：`StatelessAgent` 与工具内核。
+- Application Layer：执行编排、状态流转、回调桥接。
+- Port Layer：存储、上下文、事件、账本抽象。
+- Adapter Layer：本地文件/SQLite、CLI 事件输出实现。
+- Interface Layer：CLI 命令。
+
+## 2. 依赖方向
+
+仅允许：`CLI -> App -> Port -> Adapter`，以及 `App -> Kernel`。
+
+禁止：
+- CLI 直接依赖 Kernel 内部模块。
+- Adapter 直接调用 Kernel。
+- Kernel 反向依赖 App/Adapter。
+
+## 3. 核心设计原则
+
+- 单一职责：内核只执行，应用层只编排。
+- 无状态优先：跨执行状态一律外置到存储。
+- 事件源优先：`runStream` 事件作为事实源，读模型可重建。
+- 双通道桥接：`runStream` + `tool_chunk`（桥接为 `tool_stream`）。
+- 事件驱动：统一 `CliEvent`，屏蔽内核事件差异。
+- 可替换：所有外部依赖通过 Port 注入。
+
+## 4. 逻辑结构图
+
+- `AgentAppService`：外部 Facade。
+- `RunOrchestrator`：单次执行调度器。
+- `ExecutionStorePort`：执行状态持久化。
+- `ExecutionStepStorePort`：步骤级状态持久化。
+- `EventStorePort`：事件事实源持久化。
+- `MessageProjectionStorePort`：消息读模型投影。
+- `CheckpointStorePort`：检查点持久化。
+- `ConversationStorePort`：会话存在性与元信息读取。
+- `EventSinkPort`：事件发布。
+- `ContextProviderPort`：上下文加载。

package/vendor/agent-root/src/agent/docs/cli-app-layer/03-domain-model-and-contracts.md

@@ -0,0 +1,91 @@
+# 03. 领域模型与数据契约
+
+## 1. 核心实体
+
+### RunRecord
+- `executionId: string`
+- `runId: string`（持久化层别名，默认与 `executionId` 一致）
+- `conversationId: string`
+- `status: CREATED | QUEUED | RUNNING | COMPLETED | FAILED | CANCELLED`（Phase 1 可不启用 `QUEUED`）
+- `createdAt: number`
+- `updatedAt: number`
+- `stepIndex: number`
+- `lastCheckpointSeq?: number`
+- `terminalReason?: stop | max_steps | error | aborted | timeout | rate_limit | max_retries`
+- `errorCode?: string`
+- `errorCategory?: string`
+- `errorMessage?: string`
+
+### RunRequest
+- `conversationId: string`
+- `userInput: string`
+- `executionId?: string`
+- `maxSteps?: number`
+
+### ExecutionStepRecord
+- `executionId: string`
+- `stepIndex: number`
+- `status: pending | executing | completed | failed | skipped`
+- `stage?: llm | tool | checkpoint`
+- `errorCode?: string`
+- `startedAt?: number`
+- `completedAt?: number`
+
+### ConversationRecord
+- `conversationId: string`
+- `title?: string`
+- `status: active | archived`
+- `workspacePath?: string`
+- `createdAt: number`
+- `updatedAt: number`
+
+### CliEvent（内核 `StreamEvent` + 应用层扩展）
+- `user_message`（应用层扩展）
+- `assistant_message`（应用层扩展）
+- `chunk`
+- `reasoning_chunk`
+- `tool_call`
+- `tool_result`
+- `tool_stream`（应用层由 `agent.on('tool_chunk')` 归一化桥接）
+- `progress`
+- `checkpoint`
+- `compaction`
+- `done`
+- `error`
+
+### CliEventEnvelope
+- `conversationId: string`
+- `executionId: string`
+- `seq: number`（会话内单调递增）
+- `eventType: CliEvent['type']`
+- `data: unknown`
+- `createdAt: number`
+
+## 2. 终止语义与状态映射
+
+- `done.finishReason=stop|max_steps` -> `RunRecord.status=COMPLETED`
+- `error.errorCode=AGENT_ABORTED` -> `RunRecord.status=CANCELLED`，`terminalReason=aborted`
+- `error.errorCode=AGENT_TIMEOUT_BUDGET_EXCEEDED` -> `RunRecord.status=FAILED`，`terminalReason=timeout`
+- `error.errorCode=AGENT_UPSTREAM_TIMEOUT` -> `RunRecord.status=FAILED`，`terminalReason=timeout`
+- `error.errorCode=AGENT_UPSTREAM_RATE_LIMIT` -> `RunRecord.status=FAILED`，`terminalReason=rate_limit`
+- `error.errorCode=AGENT_MAX_RETRIES_REACHED` -> `RunRecord.status=FAILED`，`terminalReason=max_retries`
+- 其他 `error` -> `RunRecord.status=FAILED`，`terminalReason=error`
+
+## 3. 状态变更约束
+
+- `createdAt` 不可变。
+- `updatedAt` 每次状态更新必须刷新。
+- `stepIndex` 只能增长。
+- `COMPLETED/FAILED/CANCELLED` 为终态，不允许再切回 `RUNNING`。
+
+## 4. ID 约束
+
+- `executionId` 全局唯一（可采用 `trace_` 风格时间戳+随机串）。
+- `conversationId` 由上层会话管理系统提供。
+- `runId` 是存储层主键名；对外 CLI/API 统一使用 `executionId`。
+
+## 5. 兼容性约束
+
+- 应用层事件必须保留内核错误包：`errorCode/category/httpStatus/retryable`。
+- 对外事件字段采用增量扩展，不删除既有字段。
+- 应用层的持久化事实源以 `events` 为准，`messages` 为投影视图。

package/vendor/agent-root/src/agent/docs/cli-app-layer/04-ports-and-interfaces.md

@@ -0,0 +1,116 @@
+# 04. Port 接口设计
+
+## 1. ExecutionStorePort
+
+职责：执行生命周期持久化。
+
+接口：
+- `create(run: RunRecord): Promise<void>`
+- `patch(executionId: string, patch: Partial<RunRecord>): Promise<void>`
+- `get(executionId: string): Promise<RunRecord | null>`
+- `listByConversation(conversationId: string, opts?: { statuses?: RunRecord['status'][]; limit?: number; cursor?: string }): Promise<{ items: RunRecord[]; nextCursor?: string }>`
+
+## 2. EventStorePort（事实源，必需）
+
+职责：持久化 `runStream` 与回调产生的原始事件。
+
+接口：
+- `appendAutoSeq(event: Omit<CliEventEnvelope, 'seq'>): Promise<CliEventEnvelope>`
+- `append(event: CliEventEnvelope): Promise<void>`（仅回放/导入使用）
+- `listByRun(executionId: string): Promise<CliEventEnvelope[]>`
+- `listByConversation(conversationId: string, opts?: { fromSeq?: number; limit?: number }): Promise<CliEventEnvelope[]>`
+
+约束：
+- append-only，不允许覆盖历史事件。
+- 会话内序号必须单调递增。
+- `appendAutoSeq` 必须在单事务内原子分配 `seq`（禁止先查后写）。
+
+## 3. MessageProjectionStorePort（投影层，可选但推荐）
+
+职责：维护消息读模型（由事件投影构建）。
+
+接口：
+- `upsertFromEvent(event: CliEventEnvelope): Promise<void>`
+- `list(conversationId: string): Promise<Message[]>`
+
+## 4. ExecutionStepStorePort（推荐）
+
+职责：步骤级状态明细（`run-status --verbose` 与调试）。
+
+接口：
+- `upsert(step: ExecutionStepRecord): Promise<void>`
+- `listByRun(executionId: string, opts?: { limit?: number }): Promise<ExecutionStepRecord[]>`
+- `listLatestByRuns(executionIds: string[]): Promise<Record<string, ExecutionStepRecord | undefined>>`
+
+## 5. CheckpointStorePort（可选）
+
+职责：断点恢复位置存储。
+
+接口：
+- `save(checkpoint: ExecutionCheckpoint): Promise<void>`
+- `getLatest(executionId: string): Promise<ExecutionCheckpoint | null>`
+- `clear(executionId: string): Promise<void>`
+
+说明：
+- 若不建独立 `checkpoints` 表，可从 `events(event_type=checkpoint)` 投影实现。
+
+## 6. ContextSnapshotStorePort（推荐）
+
+职责：存储每步实际喂给模型的上下文快照。
+
+接口：
+- `saveSnapshot(snapshot: ContextSnapshotRecord, items: ContextSnapshotItemRecord[]): Promise<void>`
+- `getByRun(executionId: string): Promise<ContextSnapshotRecord[]>`
+
+## 7. SummaryStorePort（推荐）
+
+职责：存储压缩摘要产物。
+
+接口：
+- `append(summary: SummaryRecord): Promise<void>`
+- `listByConversation(conversationId: string): Promise<SummaryRecord[]>`
+
+## 8. RunLogStorePort（可选）
+
+职责：存储运维技术日志（`warn/error` 为主）。
+
+接口：
+- `append(log: RunLogRecord): Promise<void>`
+- `listByRun(executionId: string, opts?: { level?: string; limit?: number }): Promise<RunLogRecord[]>`
+
+## 9. ConversationStorePort（推荐）
+
+职责：会话存在性与会话元信息读取。
+
+接口：
+- `exists(conversationId: string): Promise<boolean>`
+- `get(conversationId: string): Promise<ConversationRecord | null>`
+
+## 10. ContextProviderPort
+
+职责：加载会话上下文输入。
+
+接口：
+- `load(conversationId: string): Promise<{ messages: Message[]; systemPrompt?: string; tools?: Tool[] }>`
+
+## 11. EventSinkPort
+
+职责：发布应用层事件到 CLI。
+
+接口：
+- `publish(executionId: string, event: CliEvent): Promise<void>`
+- `publishToolStream(executionId: string, chunk: { toolCallId: string; chunkType: 'stdout' | 'stderr' | 'progress'; chunk: string }): Promise<void>`
+
+说明：
+- `tool_stream` 来自 `agent.on('tool_chunk')` 桥接，不是当前 `runStream` 直接产物。
+
+## 12. LedgerProviderPort（预留）
+
+职责：提供可选幂等账本实现。
+
+接口：
+- `getLedger(conversationId: string): ToolExecutionLedger`
+
+约束：
+- 默认返回 `NoopToolExecutionLedger`。
+- 生产环境可注入 Redis/DB 账本。

package/vendor/agent-root/src/agent/docs/cli-app-layer/05-run-orchestration-and-state-machine.md

@@ -0,0 +1,52 @@
+# 05. 执行编排与状态机
+
+## 1. RunOrchestrator 职责
+
+- 构建单次执行 `AgentInput`。
+- 消费 `runStream` 事件并桥接到存储与 CLI。
+- 消费 `agent.on('tool_chunk')` 并桥接为 `tool_stream`。
+- 处理 `onMessage/onCheckpoint/onCompaction/onError` 回调。
+- 维护运行状态机并保证终态收敛。
+
+## 2. 执行主流程（事件源优先）
+
+1. 创建 `RunRecord(CREATED)`。
+2. 读取上下文与历史消息。
+3. 追加用户输入（写 `events`，并更新消息投影）。
+4. 更新状态为 `RUNNING`。
+5. 调用 `runStream`，逐条消费事件并写 `EventStore`。
+6. 并行消费 `tool_chunk`，归一化为 `tool_stream` 后写 `EventStore`。
+7. 对关键事件更新投影与状态：
+   - `progress`：更新 `stepIndex`
+   - `checkpoint`：保存 checkpoint
+   - `done/error`：先写 `events`，再收敛终态
+8. 终态后停止接收后续事件并发布最终结果。
+
+## 3. 桥接规则（按真实内核行为）
+
+- `runStream event=*`：`EventStore.append` + `EventSink.publish`（当前不含 `tool_stream`）
+- `agent.on('tool_chunk')`：归一化为 `tool_stream`，再 `EventStore.append` + `EventSink.publish`
+- `onMessage`：补充消息持久化（或校验事件投影一致性）
+- `onCheckpoint`：`CheckpointStore.save` + `ExecutionStore.patch(stepIndex)`
+- `onCompaction`：仅更新摘要/上下文快照派生层（不重复 append 事件）
+- `onError`：记录错误决策，不直接替代终态收敛逻辑
+
+说明：
+- `progress` 以 `runStream` 事件为准，不依赖 `callbacks.onProgress`。
+- 终态收敛遵循“`events` 先写，`runs` 后更新”。
+
+## 4. 状态机与终态映射
+
+- CREATED -> RUNNING
+- RUNNING -> COMPLETED（`done.finishReason=stop|max_steps`）
+- RUNNING -> FAILED（`error` 且非 `AGENT_ABORTED`）
+- RUNNING -> CANCELLED（`error.errorCode=AGENT_ABORTED`）
+
+非法转换应拒绝并记录告警日志。
+
+## 5. 并发与幂等
+
+- 同 `executionId` 并发启动应被拒绝或去重。
+- `toolExecutionLedger` 是否缓存由注入实现决定。
+- 应用层不得假定默认有跨进程幂等能力。
+- 事实层（`events`）必须可重放，投影层可重建。

package/vendor/agent-root/src/agent/docs/cli-app-layer/06-cli-commands-and-ux.md

@@ -0,0 +1,53 @@
+# 06. CLI 命令与交互规范
+
+## 1. 命令集合（Phase 1）
+
+- `agent run --conversation <id> --message "..."`
+- `agent run-status --execution <id>`
+- `agent run-list --conversation <id>`
+
+## 2. 输出策略
+
+- `chunk`：实时增量输出文本。
+- `reasoning_chunk`：默认隐藏，可通过 flag 打开。
+- `tool_stream`：工具 stdout/stderr/progress 流（由 `tool_chunk` 桥接，默认紧凑显示）。
+- `tool_call/tool_result`：结构化一行输出。
+- `progress`：紧凑模式刷新（可覆盖上行）。
+- `compaction`：输出压缩动作摘要（移除条数、stepIndex）。
+- `done/error`：尾部输出总结。
+
+## 3. 退出码规范
+
+- `0`：完成（含 `finishReason=max_steps`）。
+- `1`：运行失败。
+- `130`：用户中断（SIGINT）。
+
+终态映射建议：
+- `done.stop` -> `COMPLETED` + `0`
+- `done.max_steps` -> `COMPLETED` + `0`（提示可 `resume`）
+- `error.AGENT_ABORTED` -> `CANCELLED` + `130`
+- `error.AGENT_TIMEOUT_BUDGET_EXCEEDED` -> `FAILED(timeout)` + `1`
+- `error.AGENT_MAX_RETRIES_REACHED` -> `FAILED(max_retries)` + `1`
+- 其他 `error` -> `FAILED(error)` + `1`
+
+## 4. 可观测输出字段
+
+推荐统一打印：
+- `executionId`
+- `stepIndex`
+- `eventType`
+- `toolCallId`（可选）
+- `errorCode`（错误时）
+
+## 5. 查询命令输出约定（`run-status` / `run-list`）
+
+- `run-status` 默认输出：`status/terminalReason/stepIndex/createdAt/updatedAt/completedAt`。
+- `run-status --verbose` 追加：最近 `execution_steps` 与尾部 `events`。
+- `run-status --watch`：按固定间隔刷新，终态后自动退出。
+- `run-list` 默认输出：`executionId/status/terminalReason/stepIndex/updatedAt`（按 `updatedAt` 倒序）。
+- `run-list --cursor <token>`：分页读取下一页；无下一页时返回空 `next_cursor`。
+
+建议错误码：
+- 参数错误：`2`
+- 资源不存在（例如 execution 不存在）：`2`
+- 查询成功（含空列表）：`0`

package/vendor/agent-root/src/agent/docs/cli-app-layer/07-storage-design-local.md

@@ -0,0 +1,52 @@
+# 07. Phase 1 本地存储设计（SQLite 基线）
+
+## 1. 目标
+
+在不引入外部基础设施的前提下，让 CLI 应用层可落地并支持：
+
+- 事件级回放
+- 运行状态查询
+- 断点与上下文可追溯
+
+## 2. 存储位置
+
+`<workspace>/.agent-v4/agent.db`
+
+说明：
+- Phase 1 采用单库 SQLite。
+- JSON/JSONL 文件存储仅保留为迁移兼容，不作为默认主路径。
+
+## 3. 最小必需表（Phase 1）
+
+- `runs`：执行状态
+- `events`：事实事件流（真相源）
+- `messages`：消息读模型（投影）
+- `tool_ledger`：工具幂等账本（可选注入）
+- `checkpoints`：断点恢复索引（推荐独立表；可由 `events` 投影重建）
+
+建议同时落：
+- `meta`（schema/version/feature flags）
+
+## 4. 写入策略
+
+- 统一事务：`events` 先写，再更新投影表（`messages/runs/...`）。
+- append-only：`events` 不更新不删除（仅归档/TTL 清理）。
+- 状态更新幂等：重复写同一终态不报错。
+- 开启 SQLite 保护：
+  - `PRAGMA journal_mode=WAL;`
+  - `PRAGMA busy_timeout=5000;`
+  - `PRAGMA foreign_keys=ON;`
+
+## 5. 读取策略
+
+- `run-status`：查询 `runs`。
+- `run-list`：按 `conversationId + updatedAt` 查询 `runs`。
+- 会话重建：
+  - 优先读 `messages`（快）
+  - 需要严格审计时读 `events` 并重放（准）
+
+## 6. 兼容与升级
+
+- 使用 `meta` / `schema_migrations` 管理版本。
+- 投影可重建：当 `messages` 损坏时从 `events` 重算。
+- 后续切换 Redis/DB 时，Port 接口保持不变。

package/vendor/agent-root/src/agent/docs/cli-app-layer/08-error-and-observability.md

@@ -0,0 +1,40 @@
+# 08. 错误与可观测性设计
+
+## 1. 错误模型
+
+沿用 `agent-v4` 错误契约：
+- `errorCode`
+- `category`
+- `retryable`
+- `httpStatus`
+
+应用层新增：
+- `executionId`
+- `stage`（bootstrap/run/callback/persist）
+
+## 2. 错误处理原则
+
+- 内核错误：保留原始错误码，不做语义降级。
+- 存储错误：标记 `APP_STORAGE_*`，并尽量不中断 stdout 事件流。
+- 回调错误：不传播到用户主流程，但要记录日志。
+
+## 3. 日志规范
+
+每条日志最小字段：
+- `executionId`
+- `conversationId`
+- `stepIndex`
+- `event`
+- `latencyMs`
+- `errorCode`
+
+落库建议：
+- 业务事实进入 `events`（真相源）。
+- 运维技术日志进入 `run_logs`（可选，默认 `warn/error`）。
+
+## 4. 指标建议（后续）
+
+- `app.run.duration_ms`
+- `app.run.error.count`
+- `app.store.write.error.count`
+- `app.cli.render.delay_ms`