Skip to content

fix: render Codex file citations as Markdown links, parsed the way Codex does - #698

Merged
EugeneTheDev merged 3 commits into
mainfrom
eugenethedev/ijai-5057-codex-file-citation
Oct 29, 2026
Merged

EugeneTheDev merged 3 commits into
mainfrom
eugenethedev/ijai-5057-codex-file-citation

Conversation

@EugeneTheDev

@EugeneTheDev EugeneTheDev commented Oct 28, 2026 •

Copy link
Copy Markdown
Collaborator

Codex models may cite a file with :codex-file-citation{path="policy.txt" purpose="source"}. The Codex TUI renders this as a link to the file. The adapter passed it through as plain text, so AIR showed the raw directive at the end of an answer.

Codex has no setting to turn the directive off: neither the Codex instructions nor the feature flags mention it, so the model emits it on its own.

This change:

  • turns each citation into a Markdown link, e.g. [docs/policy.txt](/workspace/docs/policy.txt). Relative paths resolve against the session cwd. Absolute paths, Windows drive paths, and URLs stay as cited
  • parses the directive with a port of Codex's own parser (codex-rs/tui/src/assistant_directives.rs), not regexes, so it accepts the syntax Codex renders: " or ' quotes, spaces around =, one to three colons, and backslashes kept literally in paths
  • holds back a citation split across streamed deltas until it is complete, and sends any held-back text when the message completes
  • applies the same rewrite to history replay
  • leaves citations inside code spans and fences, and escaped ones (\:), as written

The port differs from Codex only where the adapter needs it: it parses citations alone, reports an unfinished directive for streaming, and caps a directive at 4096 characters instead of sharing a scan budget. The cap keeps the scan linear on malformed input. Link labels and targets escape a backslash before punctuation, so Markdown does not read it as an escape.

Reproduced on main with a test that streams the directive across deltas: the raw text reached the client unchanged.

Tests cover streaming on v1 and v2, replay on v1 and v2, and the edge cases: the Codex syntax variants, Windows paths, every split point of a streamed message, and linear time on malformed input. standard-subagent-live.test.ts > keeps command rendering across parent attachment changes fails locally, the same way on main.

IJAI-5057

Codex models may cite files with `:codex-file-citation{path="..."}`. The
Codex TUI renders it as a file link, but the adapter passed it through, so
ACP clients showed the raw directive. Live messages and history replay now
turn it into a Markdown link to the file.

IJAI-5057
Comment thread src/CodexFileCitations.ts Fixed
Comment thread src/CodexFileCitations.ts Fixed
Replace the citation regexes with a port of Codex's directive parser
(codex-rs/tui/src/assistant_directives.rs): single quotes, spaces around
`=`, attributes without separating spaces, one to three colons, and the
backslash-quote fallback now match Codex. A length limit bounds the scan,
and Markdown escaping is a plain loop.
@EugeneTheDev EugeneTheDev changed the title fix: render Codex file citations as Markdown file links fix: render Codex file citations as Markdown links, parsed the way Codex does Oct 28, 2026
@EugeneTheDev
EugeneTheDev merged commit 3f6d371 into main Oct 29, 2026
7 checks passed
@EugeneTheDev
EugeneTheDev deleted the eugenethedev/ijai-5057-codex-file-citation branch October 29, 2026 00:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants