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 @@ -14,6 +14,7 @@ All notable changes follow [Keep a Changelog](https://keepachangelog.com/en/1.1.

### Fixed

- Eliminate startup history prewarming and stream bounded compressed metadata/format probes without disk spools. Preserve full compressed-history validation, pagination, filesystem checks, and task-local read budgets for requested trajectory reads.
- Load task timing with the MCP dispatcher so in-place updates cannot lazily mix new timing code with an older parser. Detect incompatible running modules before task reads, preserve host error codes, and show plugin reload guidance for timing failures after updates.
- Distinguish missing, invalid, zero, and sub-millisecond tool timing in task attribution. Keep uncertainty within each tool's possible execution window instead of suppressing model estimates for an entire turn; preserve precision evidence through cached pages and late results and show separate coverage counts without changing public trajectory records.

Expand Down
2 changes: 1 addition & 1 deletion PRIVACY.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Codex Trajectory runs locally and reads Codex JSONL task logs from `CODEX_HOME/s

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. Compressed rollouts are decompressed locally into a bounded spool and are never uploaded. 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 only prewarms bounded read-only caches; 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.
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.

When a user invokes the plugin through Codex, structured results may become part of the active Codex conversation and may therefore be processed according to the user's Codex service configuration. Users should review task contents before enabling full details.

Expand Down
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,8 @@ codex plugin add codex-trajectory@icesixgod

Open a new Codex task to load the plugin. After updating an existing installation, fully quit and reopen Codex.

Startup does not scan or prewarm task history. Logs are loaded when a viewer or tool requests them. Metadata discovery streams only bounded headers from compressed archives without creating decompression temporary files; viewing a selected compressed task still validates its complete history within the chosen read budget.

## Use

1. Select **+ → More tools… → Plugins and MCPs → Codex Trajectory** in the task's right panel, or ask Codex to show the task trajectory using `show_codex_trajectory`.
Expand Down
2 changes: 2 additions & 0 deletions README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,8 @@ codex plugin add codex-trajectory@icesixgod

安装后新建一个 Codex 任务以加载插件。更新已有安装后,请完整退出并重新打开 Codex。

启动时不扫描或预热任务历史,打开查看器或调用工具后才加载日志。查找任务元数据时,压缩归档仅读取有上限的头部,不创建解压临时文件;查看选定压缩任务时,仍在所选读取预算内完整校验其历史。

## 使用

1. 在任务右侧面板中选择 **+ → More tools… → Plugins and MCPs → Codex Trajectory**,或让 Codex 使用 `show_codex_trajectory` 展示任务轨迹。
Expand Down
2 changes: 2 additions & 0 deletions docs/interface.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

Codex Trajectory exposes four user-facing MCP tools, four app-only helpers, and one `text/html;profile=mcp-app` resource at `ui://codex-trajectory/trajectory-v2.html`. The viewer uses the native MCP Apps host and exposes no task-control actions. `list_codex_sessions` updates a private derived index and advertises `readOnlyHint: false`; it never edits source task logs.

MCP startup performs no task discovery, projection, or history prewarming. Compressed metadata and format probes stream only the bounded header (at most 10 physical lines / 16 MiB, also subject to the request's read budget), without seeking to EOF or creating a disk spool. These probes do not validate an unread compressed body. Requested complete trajectory reads retain full frame/tail validation, decompressed byte limits, filesystem checks, logical source offsets, and paginated summary indexes. A verified matching compressed header can therefore identify an oversized native task and offer the existing read-budget retry without decompressing the body during discovery; unavailable or conflicting header identities still require explicit task selection.

## Current task timing

`get_codex_project_timing` keeps its original name for compatibility but now reads only the explicitly selected task. It requires `sessionId` (no omitted/latest selection), accepts `includeArchived` (default `true`, allowing the selected task to be archived), and optional `maxReadBytes`. A project directory is not required.
Expand Down
2 changes: 2 additions & 0 deletions docs/native-viewer.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,8 @@ After **Load full details**, leave **Default to full details for all tasks on th

The runtime contains no debugging-port client, DOM injector, watcher, loopback HTTP viewer, or task-control RPC. The portable Windows no-console launcher remains because MCP still needs inherited stdio.

MCP startup serves the protocol without scanning or prewarming any task. Metadata discovery streams bounded compressed headers without creating decompression temporary files. Complete selected-history reads retain their validated, bounded decompression spool and summary pagination index. After installing this fix, fully quit and reopen Codex so existing MCP processes stop using the old startup and metadata readers.

## Client compatibility

The integration was developed against macOS Codex desktop **26.928.20755** and its bundled CLI **0.159.0**. That client declares conversation entrypoints from tool `_meta["openai/ui"]` and forwards the calling task through `_meta.thread_id` and `_meta.threadId`. These client metadata aliases are validated per request; anonymized `openai/session` and process environment are not task bindings. Older clients without the native extension can still use `show_codex_trajectory` with an explicit session ID.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2727,12 +2727,6 @@ def session_timing_summary(path: Path) -> dict[str, Any]:
index.close()


def prewarm_caches() -> None:
"""Warm the bounded session and latest-summary caches after MCP startup."""
path = resolve_session(None, include_archived=False)
cached_trajectory(path, DEFAULT_MAX_RECORDS, "summary")


def _read_limit_task_id(path: Path) -> str | None:
try:
metadata = first_session_metadata(path)
Expand Down
50 changes: 48 additions & 2 deletions plugins/codex-trajectory/scripts/codex_trajectory/sessions.py
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@

import errno
import importlib
import io
import json
import os
import re
Expand Down Expand Up @@ -450,6 +451,42 @@ def _open_rollout_binary(path: Path) -> BinaryIO:
source.close()


@contextmanager
def _open_rollout_probe(path: Path) -> Iterator[BinaryIO]:
"""Stream a compressed header without spooling or validating its unread body.

Only bounded format/metadata probes use this reader. Complete trajectory reads
still use _open_rollout_binary to validate every frame and logical byte offset.
"""
with _open_regular_binary(path) as source:
try:
try:
zstd = importlib.import_module("compression.zstd")
except ModuleNotFoundError:
try:
zstd = importlib.import_module("zstandard")
except ModuleNotFoundError:
raise ValueError(
"Compressed Codex rollouts require compression.zstd or zstandard."
) from None
raw = zstd.ZstdDecompressor(max_window_size=ZSTD_MAX_WINDOW_BYTES).stream_reader(
source,
read_size=ZSTD_COMPRESSED_CHUNK_BYTES,
read_across_frames=True,
closefd=False,
)
reader = cast(BinaryIO, io.BufferedReader(raw))
else:
options = {zstd.DecompressionParameter.window_log_max: 27}
reader = cast(BinaryIO, zstd.open(source, "rb", options=options))
with reader:
yield reader
except (OSError, ValueError):
raise
except Exception as error:
raise ValueError("Compressed Codex rollout is not a valid zstd stream.") from error


def _rollout_stream_size(handle: BinaryIO, path: Path) -> int:
if not _is_compressed_rollout(path):
return os.fstat(handle.fileno()).st_size
Expand Down Expand Up @@ -635,8 +672,17 @@ def iter_jsonl(
or end_byte_offset < 0
):
raise ValueError("Invalid paginated history byte boundary.")
with _open_rollout_binary(path) as handle:
opened_size = _rollout_stream_size(handle, path)
compressed_probe = (
_scan_byte_limit is not None and end_byte_offset is None and _is_compressed_rollout(path)
)
stream = _open_rollout_probe(path) if compressed_probe else _open_rollout_binary(path)
with stream as handle:
if compressed_probe and _scan_byte_limit is not None:
# A header probe must not seek to EOF, which would decode the whole log.
# One extra byte lets the existing probe checks reject an overlong line.
opened_size = min(_scan_byte_limit, jsonl_byte_limit()) + 1
else:
opened_size = _rollout_stream_size(handle, path)
if end_byte_offset is not None and end_byte_offset > opened_size:
raise ValueError("Paginated history byte boundary is past the source rollout.")
read_end = opened_size if end_byte_offset is None else end_byte_offset
Expand Down
31 changes: 2 additions & 29 deletions plugins/codex-trajectory/scripts/codex_trajectory_mcp.py
Original file line number Diff line number Diff line change
Expand Up @@ -5,39 +5,12 @@
# ///
"""Start the Codex Trajectory MCP server."""

import threading
from contextlib import suppress

from codex_trajectory.projection import prewarm_caches
from codex_trajectory.protocol import main as protocol_main


def _initialize_in_background() -> None:
"""Warm bounded read-only caches without delaying MCP."""
with suppress(OSError, RuntimeError, ValueError):
prewarm_caches()


def _start_background_initialization() -> threading.Thread:
"""Start one bounded daemon worker for optional cold-start work."""
worker = threading.Thread(
target=_initialize_in_background,
name="codex-trajectory-initialize",
daemon=True,
)
worker.start()
return worker


def main() -> None:
"""Serve MCP immediately while optional cold-start work runs in parallel."""
worker = _start_background_initialization()
try:
protocol_main()
finally:
# Background parsing may still use SQLite when stdin closes. Finish it
# before interpreter finalizers close handles and delete page indexes.
worker.join()
"""Serve MCP without reading task history until a tool requests it."""
protocol_main()


if __name__ == "__main__":
Expand Down
54 changes: 14 additions & 40 deletions plugins/codex-trajectory/tests/test_mcp_entrypoint.py
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,10 @@

import json
from pathlib import Path
from types import SimpleNamespace

import codex_trajectory_mcp
import pytest
from codex_trajectory import projection, sessions


def test_mcp_config_uses_the_portable_windowless_launcher() -> None:
Expand All @@ -27,18 +27,20 @@ def test_mcp_config_uses_the_portable_windowless_launcher() -> None:
assert launcher.with_suffix(".exe").is_file()


def test_mcp_starts_optional_initialization_before_serving(
def test_mcp_serves_without_reading_or_indexing_history(
monkeypatch: pytest.MonkeyPatch,
) -> None:
calls: list[str] = []
monkeypatch.setattr(
codex_trajectory_mcp,
"_start_background_initialization",
lambda: (
calls.append("initialize"),
SimpleNamespace(join=lambda: calls.append("join")),
)[1],
)

def unexpected(*args: object, **kwargs: object) -> None:
calls.append("history")
pytest.fail("MCP startup must not discover, decompress, or index task history")

monkeypatch.setattr(sessions, "session_files", unexpected)
monkeypatch.setattr(sessions, "_decompress_rollout", unexpected)
monkeypatch.setattr(projection, "resolve_session", unexpected)
monkeypatch.setattr(projection, "cached_trajectory", unexpected)
monkeypatch.setattr(projection, "PageIndex", unexpected)
monkeypatch.setattr(
codex_trajectory_mcp,
"protocol_main",
Expand All @@ -47,43 +49,15 @@ def test_mcp_starts_optional_initialization_before_serving(

codex_trajectory_mcp.main()

assert calls == ["initialize", "serve", "join"]
assert calls == ["serve"]


def test_mcp_joins_initialization_when_protocol_exits_with_error(
def test_mcp_propagates_protocol_errors(
monkeypatch: pytest.MonkeyPatch,
) -> None:
joined: list[bool] = []
monkeypatch.setattr(
codex_trajectory_mcp,
"_start_background_initialization",
lambda: SimpleNamespace(join=lambda: joined.append(True)),
)

def fail() -> None:
raise RuntimeError("disconnected")

monkeypatch.setattr(codex_trajectory_mcp, "protocol_main", fail)
with pytest.raises(RuntimeError, match="disconnected"):
codex_trajectory_mcp.main()
assert joined == [True]


def test_background_initialization_only_prewarms(monkeypatch: pytest.MonkeyPatch) -> None:
calls: list[str] = []
monkeypatch.setattr(codex_trajectory_mcp, "prewarm_caches", lambda: calls.append("prewarm"))
codex_trajectory_mcp._initialize_in_background()
assert calls == ["prewarm"]


@pytest.mark.parametrize(
"error", [OSError("unavailable"), RuntimeError("busy"), ValueError("no logs")]
)
def test_background_prewarm_failure_does_not_break_stdio(
monkeypatch: pytest.MonkeyPatch, error: Exception
) -> None:
def fail() -> None:
raise error

monkeypatch.setattr(codex_trajectory_mcp, "prewarm_caches", fail)
codex_trajectory_mcp._initialize_in_background()
31 changes: 0 additions & 31 deletions plugins/codex-trajectory/tests/test_projection.py
Original file line number Diff line number Diff line change
Expand Up @@ -1174,37 +1174,6 @@ def counted_parse(*args: object, **kwargs: object) -> dict[str, object]:
assert refreshed["stats"]["turns"] == first["stats"]["turns"] + 1


def test_prewarm_only_loads_latest_active_summary(
monkeypatch: pytest.MonkeyPatch, tmp_path: Path
) -> None:
path = tmp_path / "latest.jsonl"
calls: list[tuple[object, ...]] = []
monkeypatch.setattr(
projection,
"list_session_overviews",
lambda **kwargs: calls.append(("list", kwargs)) or [],
)
monkeypatch.setattr(
projection,
"resolve_session",
lambda session_id, include_archived: (
calls.append(("resolve", session_id, include_archived)) or path
),
)
monkeypatch.setattr(
projection,
"cached_trajectory",
lambda *args: calls.append(("trajectory", *args)) or {},
)

projection.prewarm_caches()

assert calls == [
("resolve", None, False),
("trajectory", path, projection.DEFAULT_MAX_RECORDS, "summary"),
]


@pytest.mark.parametrize(
("value", "expected"),
[
Expand Down
Loading
Loading