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
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ All notable changes follow [Keep a Changelog](https://keepachangelog.com/en/1.1.

### Added

- Include the selected agent and all recursively related active/archived subagents in task Token and cost totals. Deduplicate logical agent IDs, retain per-agent model/Fast pricing and selected-agent turn details, refresh totals on child-only changes, and warn about incomplete subagent logs.
- Add current-task timing distribution with durations and percentages for local/tool execution, estimated model/token time, and unattributed time. Read only the selected task's complete history and reuse its loaded source/index; retain `get_codex_project_timing` for compatibility, preserve unknown timing, and report incomplete coverage.

### Removed
Expand Down
2 changes: 2 additions & 0 deletions PRIVACY.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

Codex Trajectory runs locally and reads Codex JSONL task logs from `CODEX_HOME/sessions` and, when requested for a target, `CODEX_HOME/archived_sessions`. Paginated targets may inherit earlier segments from either authorized root; copied parent context before a subagent's declared history boundary is excluded from that child trajectory.

Task token and cost totals also read recursively related subagent logs from both authorized roots, including archived children of an active target. Relations use explicit parent identities or structured agent activity references, never arbitrary message/tool content or working-directory matches. Descendant logs contribute numeric usage, estimated costs, and bounded completeness notices; their transcript content, raw metadata, and paths are not merged into the selected task's response. Bounded process-memory caches retain only validated signatures, normalized parent/child identifiers, usage counters, estimates, and warning flags. They persist no additional history and do not expand full-detail access. Missing or unreadable known subagent logs are reported as incomplete totals.

To avoid rebuilding every full session overview during historical search, the plugin maintains `CODEX_HOME/codex-trajectory/session-search-index-v1.json`. This private derived index contains only hashed physical file identities, hashed lineage identities with file metadata signatures, and the bounded session ID, title, display-safe working directory, and model used by `list_codex_sessions`; the title is a potentially sensitive excerpt of the first prompt (up to 100 characters), while no additional transcript bodies, tool input or output, reasoning, Git metadata, or absolute task-log paths are persisted. It is limited to 10,000 entries and 8 MiB, is merged under a cross-process lock and written atomically with mode 0600, refuses linked index files, and treats invalid or stale entries as cache misses. Any lineage-file change invalidates that session entry, and deleting the index is safe because it is rebuilt on demand.

The plugin does not edit task logs, persist a secondary copy of them, or add telemetry. Its Python runtime makes no application network requests. The UI uses the native MCP Apps host without a separate HTTP server. The `uv` launcher may provision a compatible Python and, on Python 3.10–3.13, the pinned `zstandard` decoder according to the user's own uv configuration. The trajectory tools accept session identifiers rather than paths and use descriptor-checked reads to exclude descendant symlinks/reparse points, file hardlinks, non-regular sources, and files outside the configured roots. Requested complete compressed rollouts are decompressed locally into a bounded spool and are never uploaded. Metadata and format probes stream bounded headers without creating decompression temporary files; unread bodies are validated only by complete trajectory reads. Safe summary mode is the default: tool inputs, tool outputs, raw record metadata, absolute log paths, Git remotes, base instructions, and encrypted reasoning are not returned. Full-detail mode requires an explicit session ID plus the full-detail parameter or confirmation in the viewer; it returns bounded tool inputs and outputs but still excludes base instructions and encrypted reasoning. All returned collections and text fields are bounded. The default target is the latest modified active session, not caller identity; archives are opt-in. `list_codex_sessions` does not modify source logs but updates its private derived index (its MCP read-only hint is therefore false). The native panel receives the calling task identifier on each tool request and does not persist that identifier separately. Missing or invalid native context requires explicit task selection. MCP startup does not discover, scan, or prewarm task history; logs are read only when requested by a viewer or tool. It starts no watcher and registers no lifecycle command hook. The plugin has no task interruption, Goal mutation, automatic stop, composer, or follow-up-message feature.
Expand Down
4 changes: 3 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,12 +21,14 @@ Codex Trajectory is a plugin that turns local Codex logs into a searchable event
- **Task history:** messages, saved reasoning summaries, tool calls, subagent activity, and context compaction.
- **Timing and failures:** event durations, execution status, and a timeline to locate slow calls.
- **Current task timing:** active time for the open task, split into local/tool execution, estimated model/token time, and unattributed time, with percentages.
- **Tokens and cost:** task and turn totals, cache usage, and estimated cost.
- **Tokens and cost:** task totals include the main agent and all descendant subagents, with cache usage and estimated cost; turn details show the selected agent's own usage.
- **Live activity:** a scrolling event stream, token totals, cost estimates, and the latest available local quota sample.
- **History browsing:** search, event filters, task switching, and earlier records, including compressed and paginated logs.

Steps are approximate, and reasoning summaries appear only when saved in the log. Cost figures are estimates based on bundled API prices, not a Codex subscription bill. Local quota samples may lag the account service.

Task token and cost totals recursively include related active and archived subagent logs, counting each agent once. Each agent uses its recorded model and Fast mode for pricing. Live totals refresh when a subagent changes, even if the main agent is idle. Missing or unreadable subagent logs produce a warning that totals are incomplete; an oversized related log requires a larger explicit read budget. The event ledger, turn details, timing distribution, context window, and quota sample remain scoped to the selected agent or account as labeled.

## Install

You need **Codex** and **[uv](https://docs.astral.sh/uv/getting-started/installation/)**. The plugin runs on macOS, Linux, and Windows.
Expand Down
4 changes: 3 additions & 1 deletion README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,12 +21,14 @@ Codex Trajectory 将本地 Codex 日志整理成可搜索的事件账本和交
- **任务过程:**消息、日志中保存的推理摘要、工具调用、子代理活动和上下文压缩。
- **耗时与失败:**事件耗时、执行状态,以及帮助定位慢调用的时间轴。
- **当前任务耗时分布:**统计当前打开任务的活跃耗时,展示本地/工具执行、模型/Token 估算、未归因时间及占比。
- **Token 与费用:**任务和各轮次的用量、缓存使用情况及估算费用。
- **Token 与费用:**任务总量包含主代理及所有层级子代理,展示缓存使用情况和估算费用;轮次明细保留当前代理自身的用量。
- **实时活动:**滚动事件流、Token 总量、估算费用,以及本地最新可用的额度采样。
- **历史浏览:**搜索、事件筛选、任务切换和更早记录,支持压缩日志与分页历史。

步骤划分是近似值,推理摘要仅在日志保存了摘要时显示。费用按内置 API 价格估算,不等于 Codex 订阅账单;本地额度采样也可能滞后于账户实际状态。

任务 Token 和费用会递归汇总有关联的活跃及已归档子代理日志,每个代理只计一次,分别按其记录的模型及 Fast 模式估算费用。子代理用量变化时,即使主代理空闲,实时总量也会更新。缺失或不可读的子代理日志会提示总量不完整;关联日志超过读取上限时,需要显式提高读取预算。事件账本、轮次明细、耗时分布、上下文窗口与额度采样继续按页面标注展示当前代理或账户的数据。

## 安装

需要 **Codex** 和 **[uv](https://docs.astral.sh/uv/getting-started/installation/)**,支持 macOS、Linux 和 Windows。
Expand Down
14 changes: 14 additions & 0 deletions docs/interface.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,20 @@ Discovery first resolves each configured session root, then accepts only regular

When `list_codex_sessions` receives a non-empty query, discovery filters title, identifier, display-safe working directory, and model through a private metadata index before building full overviews. An index miss scans the complete rollout but decodes only metadata-bearing JSONL records; matched candidates alone receive a full overview, and scanning stops at `limit`. The index at `CODEX_HOME/codex-trajectory/session-search-index-v1.json` stores hashed physical and lineage identities, lineage file metadata signatures, and those four bounded search fields. Its title is an excerpt of the first prompt (up to 100 characters), and therefore can be sensitive; it contains no additional transcript bodies, tool details, reasoning, Git metadata, or absolute log paths; it is capped at 10,000 entries and 8 MiB, merged under a cross-process lock with persisted LRU touches and written atomically with mode 0600, rejects linked/reparse files, and fails open to an uncached scan. Any lineage signature change invalidates the corresponding entry.

## Task token and cost totals

In trajectory responses, `stats.tokens` and `stats.cost` include the selected agent and every recursively related descendant subagent with available local logs. This applies to public reads, the native panel, history/full-detail pages, and live updates. Selecting a subagent includes its own descendants, never its ancestors or siblings. `list_codex_sessions` remains a list of individual-session metadata; its overview token counters describe that session alone.

Relations come from `session_meta.parent_thread_id`, `session_meta.source.subagent.thread_spawn.parent_thread_id`, and structured `sub_agent_activity.agent_thread_id` references (including canonical `SubAgentActivity` items). Activity references cannot override an explicit different parent. Arbitrary tool results, message text, working-directory matches, and agent-path prefixes never establish a relation. Both authorized active and archive roots are searched for descendants, independently of `includeArchived`, which controls selection of the target task. Each exact metadata task ID counts once, selecting its newest discovered rollout; cycles, repeated notifications, and alternate physical copies do not multiply usage. Existing per-segment subagent history boundaries exclude inherited model context.

Descendant accounting uses the same cumulative-counter delta/reset handling, per-call model pricing, cache rates, explicit Fast multiplier, and unknown-price coverage as the selected session. Unknown prices still contribute tokens and increase `unpricedModelCalls`; the known priced subtotal remains available with partial coverage. A child's recorded Fast multiplier also adds the existing `codex_fast_cost_multiplier` notice, preventing the viewer's manual task multiplier from applying it twice. `stats.cost.pricedModelCalls + stats.cost.unpricedModelCalls` counts recorded model requests across the task. The existing frozen trajectory schemas are unchanged.

`turns`, `records`, their usage/cost fields, other statistics, and current-task timing remain scoped to the selected session. Totals therefore need not equal the displayed turn subtotal. Child transcript content and raw metadata are never merged into the parent's response. Missing or unreadable known descendants, and child logs with read warnings, add a bounded `subagent_usage_incomplete` warning: totals then contain available usage only. Pricing coverage describes known usage samples, not completeness of local log availability. Related logs exceeding the selected read budget return the normal read-limit error bound to the selected task, rather than silently omitting their usage. The same byte budget applies to each related logical rollout; existing line, discovery, decompression, and filesystem limits continue to apply.

Own-agent usage summaries and minimal metadata links are cached in bounded process memory, keyed by validated source signatures and read budget. Unrelated metadata probes retain the default budget. Live/page revision hashes also include descendant membership and each descendant's full lineage signature, so child appends, new logs, and removed logs invalidate totals even when the parent file is unchanged. Child-only updates reuse the parent's existing summary/page index.

**中文:**轨迹响应的 `stats.tokens` 与 `stats.cost` 递归包含当前代理和所有层级子代理,已归档子代理也参与统计,按任务 ID 去重并分别按各代理实际模型及 Fast 模式计价。普通查看、完整详情、历史分页和实时小窗采用相同总量;子代理日志变化会触发实时更新。逐轮用量、事件、耗时等仍属于当前代理,任务列表的概览仍是单会话信息。关联日志缺失、不可读或有读取警告时,`subagent_usage_incomplete` 提示总量仅含可读部分;未知模型仍计入 Token 并标记费用覆盖不足。子代理日志内容不会合并到主任务响应中,现有公开数据结构保持不变。

## Rollout formats

Legacy single-file JSONL and Codex paginated history are both supported in plain `.jsonl` and Zstandard-compressed `.jsonl.zst` files. Python 3.14 uses `compression.zstd`; Python 3.10–3.13 use the pinned `zstandard==0.25.0` dependency. Decompression is materialized into an 8 MiB memory spool that spills to a private temporary file, with a 128 MiB window cap and a 512 MiB default decompressed limit (or the selected task's explicit `maxReadBytes` budget); concatenated frames are accepted, while truncation and trailing garbage fail closed. `history_base.end_byte_offset` always addresses the decompressed logical JSONL stream.
Expand Down
Loading
Loading