Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions .scratch/codex-execution-history/spec.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
# 按需读取 Codex 执行历史

Status: ready-for-agent

用户要求任务详情按需读取当前 Codex Thread,运行中接收实时消息。Agent Loop 不长期保存另一套执行轨迹,不处理旧 Thread 或旧历史兼容。

## 验收

- 新数据库没有 execution_events 表,运行中不向数据库或本地文件写入执行轨迹副本。
- 看板任务详情从 Codex 读取可见历史。读取不恢复 Thread、不启动轮次、不回答审批。
- 实时消息与历史按稳定消息身份合并,完成文字不重复。
- 实时游标在进程重启或缓存丢失后触发重新加载。
- Codex 不可用时仍能查看业务事实,飞书不以空历史覆盖现有内容。
- 飞书发布成功后,数据库只保存发布标识、摘要和状态,不保存已发布正文。待确认操作可保存准确的重试正文,确认后清除。
- 任务生命周期、业务输入输出、显式汇报、审批和项目记录继续持久保存。

## 范围

修改本地源码、测试和文档。生产实例重启、数据清理与旧历史迁移不在本次范围。

## Comments

2026-11-20:实现完成。删除执行轨迹持久化,按需读取当前 Codex Thread,飞书确认后清除待发正文。类型检查和构建通过,全量测试735项通过。默认并发下的一项原有子进程启动超时在独立重跑及限制并发的全套运行中通过。最终独立复查因模型连接故障未返回结论,不宣称最终审查通过。

最终浏览器验收14场景40断言通过,SQLite全表执行正文检查通过。真实只读探针通过,仅读取本次验证创建的Thread。
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -139,7 +139,7 @@ npm start -- run --config config.json

`documentBaseUrl` 中的 `https://example.feishu.cn` 是占位值,替换为企业实际的 HTTPS 飞书文档域名,不带文档路径、端口、查询参数或片段。文档由飞书托管,不依赖运行 Agent Loop 的电脑能否被手机访问。文档模式不会在失败时改发进度卡片。

`maxLines` 是文档展示的逻辑行数上限,按文本中的换行计算,包含状态、角色标签和空行;屏幕自动折行不另计。已有文档在恢复后从本地保存的输入和 AI 执行事件重建历史。文档显示附件名称,附件原件保留在任务材料中。
`maxLines` 是文档展示的逻辑行数上限,按文本中的换行计算,包含状态、角色标签和空行;屏幕自动折行不另计。文档从本地保存的业务输入、当前 Codex Thread 历史和实时执行消息生成。Agent Loop 不另存执行历史。文档显示附件名称,附件原件保留在任务材料中。

机器人需要以下应用身份权限:

Expand All @@ -165,7 +165,7 @@ npm start -- run --config config.json

默认直接在飞书卡片中查看进度,不显示网页按钮。需要完整可见文字入口时,可另加 `dashboardUrl`,填写飞书客户端能访问的 HTTP 或 HTTPS 地址。网络地址能否访问取决于运行主机的网络和防火墙配置。看板不提供登录或 token 鉴权。配置修改后按 [服务操作说明](docs/agents/operations.md) 重启执行服务。

机器人需要 `cardkit:card:write` 权限及已有的消息发送权限。每轮执行发送一张进度卡片,后续合并更新同一张卡片。卡片展示执行状态、最近执行事件时间、模型文字和有长度限制的工具调用状态;完整可见文字保留在调试台。没有新事件时,最近执行事件时间保持原值。最终答复继续作为独立普通消息发送。
机器人需要 `cardkit:card:write` 权限及已有的消息发送权限。每轮执行发送一张进度卡片,后续合并更新同一张卡片。卡片展示执行状态、最近执行事件时间、模型文字和有长度限制的工具调用状态。调试台按需从 Codex 读取当前 Thread 的可见历史,并接收实时更新。没有新事件时,最近执行事件时间保持原值。最终答复继续作为独立普通消息发送。

卡片身份和更新顺序持久化,服务恢复后继续更新原卡片。首次启用不补发已结束的历史轮次。进度投递失败记录到诊断,不触发任务重跑,也不阻断最终答复。飞书消息发送结果不明确时,先核对原群消息与已保存的卡片实体;找到原消息便继续更新,确认没有发送且仍在平台去重保证范围内才重试。无法完成核对时不会盲目补建卡片。

Expand Down
2 changes: 2 additions & 0 deletions docs/adr/0016-project-dashboard-boundaries.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

Status: accepted

执行文字的持久化约定已由 [ADR 0022](0022-codex-owns-execution-history.md) 取代。以下保留原决策,其余看板边界继续有效。

项目看板首版采用项目总览和任务深钻两层只读视图。总览包含项目协调者、Worker、verifier、已路由 intake 以及已结束历史任务,只显示任务卡片和每个任务的最近活动,不建立跨 Worker 的项目总时间线。任务深钻显示 Codex CLI 风格的可见执行说明、任务生命周期、工具开始/结束元数据、错误和显式 report,并永久保留完整可见文字和报告历史;工具输出正文、隐藏模型推理和私有 textDelta 不进入看板持久化记录。看板监听网络地址,任何能连通端口的电脑都可以读取所有项目和任务数据,不要求登录、token 或项目级鉴权。

这样可以复用现有项目关系和任务执行事实,长期保留真正需要复盘的可见过程文字和报告,同时避免把高频工具输出写入数据库。
13 changes: 13 additions & 0 deletions docs/adr/0022-codex-owns-execution-history.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
---
status: accepted
---

# Codex 保存执行历史

2026-11-20,用户确认执行历史由 Codex 保存,Agent Loop 查看任务详情时读取当前 Thread,运行中的展示使用有界内存数据。此决策取代 ADR 0016 中由看板永久保存可见过程文字的约定,不迁移旧 Thread 或旧执行轨迹。

SQLite 继续保存任务、业务输入输出、显式汇报、审批和项目记录。飞书进度发布成功后只保留标识、摘要和发布状态。需要确认外部写入结果的正文仅作为待确认操作保存,确认后清除,不能归档为另一套执行历史。

历史读取不得恢复 Thread、启动 Turn 或处理原生请求。Codex 历史不可用时,看板明确显示读取失败并保留业务事实,飞书保留已发布内容等待重试。项目总览不逐个读取 Thread 历史。实时游标失效时,客户端重新读取当前历史。

历史快照与实时通知没有共同的增量偏移。没有收到消息起点时,增量只触发重新读取,不猜测文字重叠。未解决缺口的身份被内存上限淘汰后,运行中的历史保留重读提示,完整结束的历史可以恢复可用状态。此保守行为避免用缺字的轨迹冒充已同步结果。
4 changes: 4 additions & 0 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,10 @@ Runtime 状态为 `pending`、`running`、`idle`、`paused`、`failed`。原生

输出按稳定 AgentOutput ID 去重,只转发用户可见进展与最终答复。原始工具日志和内部推理不作为普通消息发送。旧版 `turn:<turnId>` 出站记录继续作为历史通知屏障,避免升级后重发已处理轮次。pending、sending、sent 和 uncertain 区分准备发送与实际确认。

执行历史由 Codex 保存。任务详情按需读取当前 Thread 的历史,实时执行消息只保存在有界内存中。SQLite 不保存执行轨迹,项目总览不批量读取 Thread 历史。历史读取与执行恢复分开,读取不会启动或恢复任务,也不处理原生请求。历史读取失败时,业务输入、汇报和任务状态仍可查看。实时游标在进程重启或缓存淘汰后失效,客户端重新加载详情。

飞书进度由当前 Thread 历史、实时消息和业务输入生成。发布记录保存远端标识、内容摘要、顺序和重试状态。待确认的写入正文在确认后清除,不长期保留已发布文字。历史不可用时保留远端现有内容。此边界见 [ADR 0022](adr/0022-codex-owns-execution-history.md)。

## 输入与来源

所有者在项目协调群交办,CLI submit、answer 和机器人私聊不再接单。协调者评估后才通过内部工具派发 Worker。GitHub 收集与历史请求仍先进入项目协调,不自动启动执行。Worker 默认无群,直接交流或原生审批时才建立任务群。
Expand Down
11 changes: 5 additions & 6 deletions scripts/verify-project-coordinator.ts
Original file line number Diff line number Diff line change
Expand Up @@ -159,7 +159,7 @@ function newLoop(): AgentLoop {
function snapshot(current: AgentLoop): unknown {
return { project: current.projects.ledger.project(projectId), tasks: current.tasks().map(task => ({ task,
inputs: current.store.inputs(task.id), outputs: current.store.outputs(task.id),
approvals: current.store.approvals(task.id), events: current.store.executionEvents(task.id, 0, 100_000) })),
approvals: current.store.approvals(task.id), events: current.execution.current(task.id) })),
diagnostics: current.store.diagnostics(), fakeFeishu: { groups: [...feishu.groups], sent: feishu.sent,
approvals: feishu.approvals }, fakeGithub: { sources: github.sources, verifications: github.verifications } };
}
Expand All @@ -183,7 +183,6 @@ function readDatabase(): unknown {
inbox: 'SELECT * FROM inbox ORDER BY seq', outbox: 'SELECT * FROM outbox ORDER BY rowid',
operations: 'SELECT * FROM operations ORDER BY rowid',
projectMetadata: "SELECT * FROM meta WHERE key LIKE 'project:%' OR key LIKE 'project-generation:%' OR key LIKE 'project-archived-thread:%' ORDER BY key",
executionEvents: 'SELECT * FROM execution_events ORDER BY seq',
diagnostics: 'SELECT * FROM diagnostics ORDER BY id',
};
return Object.fromEntries(Object.entries(queries).map(([name, sql]) => [name, { sql, rows: db.prepare(sql).all() }]));
Expand Down Expand Up @@ -286,17 +285,17 @@ async function verify(): Promise<void> {
assert.ok(reportInput);
assert.equal(reportInput.provenance.kind, 'agent');
assert.equal(reportInput.status, 'delivered');
const receiptTurnStart = loop.store.executionEvents(coordinatorId, 0, 100_000).find(event => event.kind === 'turn_start' && event.turnId === recorded.request.turnId);
assert.ok(receiptTurnStart && receiptTurnStart.createdAt >= reportArrival.at, 'Receipt turn must start after the actual worker report');
const workerEvents = loop.store.executionEvents(worker.taskId, 0, 100_000);
const receiptTurnStart = loop.execution.current(coordinatorId).find(event => event.kind === 'turn_start' && event.turnId === recorded.request.turnId);
assert.ok(receiptTurnStart && (receiptTurnStart.createdAt ?? 0) >= reportArrival.at, 'Receipt turn must start after the actual worker report');
const workerEvents = loop.execution.current(worker.taskId);
assert.ok(workerEvents.some(event => ['tool_output', 'tool_end'].includes(event.kind)
&& event.text.includes(marker)), 'Marker must be observed in actual worker tool output');
const workerOutputs = loop.store.outputs(worker.taskId).map(output => output.text).join('\n');
assert.ok(workerOutputs.includes(marker));
const coordinatorOutputs = loop.store.outputs(coordinatorId).map(output => output.text).join('\n');
assert.match(coordinatorOutputs, /COORDINATOR_RECEIPT_RECORDED/);
assert.ok(coordinatorOutputs.includes(marker));
for (const task of tasks) for (const event of loop.store.executionEvents(task.id, 0, 100_000)) {
for (const task of tasks) for (const event of loop.execution.current(task.id)) {
if (event.kind === 'tool_start') assert.ok(event.label.startsWith('project_action') || event.text.startsWith('$ '), 'No external tool or nested agent may be used');
}
assert.deepEqual({ files: (await readdir(directory)).sort(),
Expand Down
32 changes: 31 additions & 1 deletion src/adapters/codex.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ import { setTimeout as delay } from 'node:timers/promises';
import { z } from 'zod';
import { RejectedInputError, TurnChangedError, UncertainOperationError, workspaceTargetSchema, type AgentInput, type AgentOutput, type ExecutionSnapshot, type PendingRequest, type WorkspaceRequest } from '../domain.js';
import { CodexProviderMismatchError, type Activity, type CodexPort, type TurnIdentity } from '../ports.js';
import { executionEvent, type ExecutionEvent } from '../execution-events.js';
import { executionEvent, executionKey, type ExecutionHistory, type ExecutionEvent } from '../execution-events.js';
import { projectActionSchema } from '../project.js';
import type { ReasoningEffort } from '../execution.js';
import { normalizeDaemonSettings, sharedDaemonConnector, type CodexConnection, type CodexConnector, type DaemonSettings } from './codex-daemon.js';
Expand Down Expand Up @@ -179,9 +179,38 @@ export class CodexAppServer implements CodexPort {
private projectHandler: Parameters<NonNullable<CodexPort['setProjectHandler']>>[0] | undefined;
private readonly outputs = new Map<string, AgentOutput>();
private sequence = 0;
private observationReset: (() => void) | undefined;
private eventHandler: ((event: ExecutionEvent) => void) | undefined;
private completionPolicy: { isCompleted(threadId: string): boolean } | undefined;

async readHistory(threadId: string): Promise<ExecutionHistory> {
await this.ready();
const epoch = this.epoch;
const historyTurn = turnSchema.extend({ itemsView: z.literal('full'), startedAt: z.number().nullable(), completedAt: z.number().nullable() });
const { thread } = z.object({ thread: z.object({ id: z.string(), turns: z.array(historyTurn) }) })
.parse(await this.rpc('thread/read', { threadId, includeTurns: true }));
if (thread.id !== threadId) throw new Error('Codex history Thread identity changed');
const entries: ExecutionHistory = [], turns = new Set<string>();
for (const turn of thread.turns) {
if (turns.has(turn.id)) throw new Error('Codex history repeated a turn');
turns.add(turn.id);
for (const item of turn.items) {
const event = executionEvent('item/completed', { threadId, turnId: turn.id, item });
if (!event) {
if (['agentMessage', 'commandExecution', 'fileChange', 'mcpToolCall', 'dynamicToolCall', 'webSearch'].includes(item.type)) throw new Error('Codex visible history item is incomplete');
continue;
}
const timing = z.object({ startedAtMs: z.number().nullish(), completedAtMs: z.number().nullish() }).parse(item);
entries.push({ ...event, kind: event.kind === 'agent_message' && turn.status === 'inProgress' && timing.completedAtMs == null ? 'agent_delta' : event.kind,
key: executionKey(event), createdAt: timing.startedAtMs ?? (turn.startedAt === null ? null : turn.startedAt * 1000) });
}
const event = executionEvent(turn.status === 'inProgress' ? 'turn/started' : 'turn/completed', { threadId, turn });
if (event) entries.push({ ...event, key: executionKey(event), createdAt: (turn.completedAt ?? turn.startedAt) === null ? null : (turn.completedAt ?? turn.startedAt)! * 1000 });
}
if (epoch !== this.epoch) throw new Error('Codex connection changed during history read');
return entries;
}
setObservationResetHandler(handler: () => void): void { this.observationReset = handler; }
setEventHandler(handler: (event: ExecutionEvent) => void): void { this.eventHandler = handler; }
setThreadCompletionPolicy(policy: { isCompleted(threadId: string): boolean }): void { this.completionPolicy = policy; }
assertThreadCompletionAllowed(threadId: string): void {
Expand Down Expand Up @@ -838,6 +867,7 @@ export class CodexAppServer implements CodexPort {
}

private async reconnect(): Promise<void> {
this.observationReset?.();
this.connection = undefined;
this.initialized = undefined;
this.failure = undefined;
Expand Down
2 changes: 1 addition & 1 deletion src/cli.ts
Original file line number Diff line number Diff line change
Expand Up @@ -135,7 +135,7 @@ async function main(): Promise<void> {
const stop = () => { void close(); };
process.on('SIGINT', stop); process.on('SIGTERM', stop);
try {
dashboardStart = startDashboard({ dataDir: config.dataDir, host: config.dashboard.host, port: config.dashboard.port });
dashboardStart = startDashboard({ execution: loop.execution, dataDir: config.dataDir, host: config.dashboard.host, port: config.dashboard.port });
const dashboard = await dashboardStart;
if (closing) { await closing; return; }
executionWatcher.start();
Expand Down
Loading