Tianyi Cui
7234d41b91
Codex code-review round 5: agent()/parallel()/pipeline() returned HOST Promise
objects into the script realm — Object.getPrototypeOf(agent('x')) reached host
Promise.prototype, contradicting the realm contract (correctness containment,
not the accepted sandbox stance). The rejection channel had the same leak one
hop away: a caught hook failure was a host WorkflowError (host Error.prototype
chain), and phase()/log() threw host errors synchronously.
All three surfaces are realm-built now:
- hook promises: the realm's own Promise.resolve (bound at context setup)
assimilates the host promise, so the script-visible promise carries realm
prototypes; the realm promise gets the same no-op rejection consumer as the
host one (a script may drop it).
- hook failures: rejections and phase/log sync throws are translated at the
boundary into realm-built clones (name/code/message/fatal via an in-realm
factory); non-WorkflowError host failures become generic realm Errors
carrying their describeThrown rendering.
- the combinators recognize FATAL clones structurally
(isFatalWorkflowErrorClone: proxy-guarded descriptor reads), preserving the
fatal-vs-null discipline across the boundary; a script forging the shape
kills only its own run. drive() maps any post-cancel failure to 'cancelled'
by run state (a CANCELLED clone deliberately fails the host instanceof).
Tests: realm-promise identity for all three hooks + host Promise.prototype
pollution unreachable; clone shape (instanceof realm Error, name/code/fatal/
message) with prototype-chain mutation staying realm-side; a rejecting
provider result crossing as a generic clone; phase/log sync-throw clones;
combinator catch branches (string throw, proxy throw, shape-miss forgery →
null; forged fatal → kills own run); existing fatal-propagation, cancellation,
and unhandled-rejection tests as canaries.
RFCs
One kind of design doc lives here. An RFC records a decision or proposal that shapes this codebase — the why and what we gave up, the parts code and docs can't carry.
Layout and naming
Every RFC has two axes, both encoded in its path — {lifecycle}/{class}/yyyy-mm-dd-topic-title.md:
- Lifecycle (the top-level folder) is the RFC's status, and an RFC moves between folders as that status changes:
proposed/— proposals reviewed before implementation; not yet built (or only partly).implemented/— the decision shipped. The file records what was decided and what was rejected, and is kept current with what actually shipped: when the code later moves a file, renames a package, or changes a key/default, the RFC is updated in the same change to match (facts only — paths, names, structure — not the decision itself). See implemented/AGENTS.md.rejected/— the proposal was considered and declined. Kept for the record so the rejection isn't re-litigated.
- Class (the nested folder) is the kind of decision — see Classification below.
The date in the filename is when the topic was first proposed (per git history). Cross-references between RFCs use relative markdown links ([topic](../../implemented/architecture/2026-…-….md)) — never bare prose or numbers — so they are mechanically checkable and survive moves between folders.
Classification
Each RFC is filed under exactly one class — the kind of decision it records. The class is encoded in the path (the folder is the label, so a file's location declares its class) and the set is closed: scripts/rfc-index.ts owns the canonical set, scripts/verify-rfc-classification.ts rejects any folder outside it, and the index tables below are generated from the tree (pnpm run gen-rfc-index rewrites the marker-delimited regions from each RFC's path, H1 title, and filename date; the gate fails when they are stale). Adding a new class means amending that const and this section, not just dropping a new folder. See the classification RFC for why the taxonomy is path-encoded and gated, and the index-generation RFC for why the tables are generated while this prose stays curated.
| Class | What it covers |
|---|---|
feature |
A new user- or model-facing capability. |
bug-fix |
Corrects a defect or closes a gap a postmortem surfaced. |
simplification |
Removes code, behavior, or surface area without adding a capability. |
architecture |
A structural decision about the shipped source — how packages relate, what the runtime vocabulary is. |
process |
Tooling, policy, or workflow around the code — gates, the package manager, vendoring — not runtime behavior. |
testing |
Test infrastructure and strategy. |
The architecture / process line: architecture is about the source we ship; process is the surrounding tooling and workflow. (refactor is deliberately absent — it overlaps simplification, whose discriminator, "does observable behavior change?", already covers it.)
When to write one
Write an RFC when a decision is durable (it shapes the codebase beyond a single function or package), contested (there was a real alternative a reasonable engineer might have chosen), and surprising (a future reader would otherwise ask "why on earth is it done this way?"). A proposal for substantial future work starts in proposed/; a decision already made starts in implemented/. Pick the class folder that matches the decision (see Classification).
Do NOT write one for a mechanical or local choice (a variable name, a one-file refactor), for anything already enforced and explained by a gate or a convention in AGENTS.md, or for a still-provisional decision tagged TODO(...) in the code — record those as TODOs and promote to an RFC only once they settle. An RFC is never edited into a different decision: supersede it with a new one and cross-link. (Editing an implemented/ RFC to track where its already-made decision now lives — a moved file, a renamed package — is not a different decision and is required, not forbidden; see implemented/AGENTS.md.)
Proposed
Feature
| Title | First proposed |
|---|---|
| Agent Client Protocol (ACP) support — drive the coding agent from external editors | 2026-06-14 |
| Multiplex concurrent ACP sessions over one connection | 2026-06-14 |
| Optional Code Mode — model writes TypeScript against an SDK of all tools | 2026-06-15 |
| Pre-tool input rewrite — a consistent design | 2026-06-30 |
Simplification
| Title | First proposed |
|---|---|
| Unify the agent id and the session id | 2026-06-20 |
Prune dead core-spine surface — SurfaceManager.invalidate(), the loop-internal exports, ToolExecutionResult.callId |
2026-07-04 |
Architecture
| Title | First proposed |
|---|---|
| Runtime schemas for the event vocabulary (Zod vs the merge-extensible-map pattern) | 2026-06-16 |
| Extract a generic long-running tool runtime | 2026-06-20 |
Process
| Title | First proposed |
|---|---|
| API extractor reports | 2026-06-11 |
| Architectural conformance — dependency rules and the adapter kit | 2026-06-11 |
| Supply chain checks and vendor drift verification | 2026-06-11 |
| Discover package inventories instead of maintaining static lists | 2026-06-20 |
Testing
| Title | First proposed |
|---|---|
| Deterministic tests, the replay invariant fixture, and race stress | 2026-06-11 |
| Mutation testing as the coverage counterweight | 2026-06-11 |
Implemented
Feature
Simplification
Architecture
Process
| Title | First proposed |
|---|---|
| Doc-sync enforcement | 2026-06-11 |
| Mechanical quality gates over prose guidelines | 2026-06-11 |
| tsdown for JS bundling instead of dumble | 2026-06-11 |
| Vendor Cordis as source, not npm dependencies | 2026-06-11 |
| pnpm as the package manager instead of Yarn 4 | 2026-06-16 |
| TSC-first build and one tsconfig | 2026-06-17 |
| Markdown cross-link validity linting | 2026-06-18 |
Core-data-structures catalog and the ts type-equiv drift gate |
2026-06-20 |
| Generated cordis events + services catalog | 2026-06-20 |
| Classify RFCs by kind via path-encoded subdirectories | 2026-06-20 |
| Bilingual documentation via paired sibling files and a pairing gate | 2026-07-02 |
| Generated tool-schema catalog (boot-and-harvest) | 2026-07-02 |
| JSDoc completeness gate for the cordis surface | 2026-07-04 |
| Documentation tiers, budgets, and the ceiling gate | 2026-07-04 |
| Generate the RFC index tables | 2026-07-04 |
| Generated persistence log event catalog | 2026-07-04 |
Testing
| Title | First proposed |
|---|---|
| Property-based testing for protocol-shaped code | 2026-06-11 |
| ACP snapshot tests — record-once / replay-deterministic | 2026-06-19 |
| Real-API e2e in CI against the external DeepSeek API | 2026-06-19 |
Use session.jsonl as the only snapshot session-log artifact |
2026-06-20 |
| Persist the seed boundary so fork-child replay routes correctly | 2026-06-22 |
| Record fork and mixed spawn+fork snapshot scenarios | 2026-06-22 |
| Per-session snapshot replay for nested agents | 2026-06-22 |
| Hook snapshot matrix — end-to-end goldens for both bridges | 2026-07-04 |
| Single-source the acp-agent replay config | 2026-07-04 |
Rejected
Simplification
| Title | First proposed |
|---|---|
| Persist assembled assistant messages, not stream chunks | 2026-06-20 |
| Drop ACP session/load until resume has a product shape | 2026-06-20 |
Drop ACP terminal _meta rendering |
2026-06-20 |
| Drop bash full-output spill files | 2026-06-20 |
| Drop durable step boundary events | 2026-06-20 |
| Drop unused session lineage metadata | 2026-06-20 |
| Fold the persistence interface into dsh-session | 2026-06-20 |
| Collapse tool-owned UI presentation | 2026-06-20 |
| Retire mid-turn steering | 2026-06-20 |
| Return the ACP bridge to one live session per connection | 2026-06-20 |
| Truncate interrupted final turns on load | 2026-06-20 |
| Prune the unimplemented subagent seam vocabulary | 2026-07-04 |
Architecture
| Title | First proposed |
|---|---|
| Deep-readonly public surfaces | 2026-06-11 |
| Make the shared example base providerless | 2026-06-20 |