Spec: Codex TypeScript MCP

Context

A Codex agent working in a TypeScript repository answers "where is this defined, who references it, what is its type" by reading text. The hi Baseline gives it formatting, lint and typecheck gates but no semantic reads. A local experiment proved that Typegraph MCP 0.9.56, with its bundled native TypeScript 7.0.2 compiler, answers those questions correctly for every source-bearing workspace in this repository, and that Codex can call it. The experiment also showed what breaks: the repository root tsconfig.json has no files, so one root server sees nothing; Typegraph's LSP hover returns stale types after a dependency edit; approval_policy = "never" refused the reads; and the eleven hand-written Codex entries later disappeared with no proven cause while the runtime and the SDK replay kept working. Today hi check reports the Registry as current although Codex has zero Typegraph entries.

The user restarted the requirements grill on 2026-09-28, answered Q10 to Q20, and confirmed shared understanding. The grill status records closure; the grill log is the decision trail (section "R5 — Accepted decisions"); the glossary records reused canonical terms and the parked working labels. The retained architecture is ARCHITECTURE.md at commit 3f0809e3dab6b25e476ff6c3feb523ed22b48a00 (blob https://github.com/wearedevpunks/harness-intelligence/blob/3f0809e3dab6b25e476ff6c3feb523ed22b48a00/apps/wiki/content/docs/project/specs/cli/codex-typescript-mcp/ARCHITECTURE.md). Source evidence: the Registry research report and the local runbook.

Terms: Compiler Project, Tool Runtime and Semantic Session are working labels parked under Glossary Q21, used here for clarity only. Pack, Baseline, Registry, Installed Record, Recorded Shape, Authored Artifact, Software Scope and Effective Lint Policy keep their canonical meanings.

Non-Goals

Other languages and harnesses; semantic mutations; Typegraph graph tools and Effect diagnostics; LSP hover (excluded until its stale-result behavior is fixed and separately accepted); an HI-owned router or wrapper MCP server (parked, Q13 alternative); automatic recovery after tsconfig, dependency or branch changes (parked with the router, Q17); pruning of old Tool Runtime versions (Q20); any change to the user's global Codex approval policy (Q15); a per-platform acceptance test matrix (Q19); a separate opt-in Pack or a second selection unit (Q10, C4); reopening the Typegraph-over-Serena choice (C1); converting a recipient project's own TypeScript version (Q16); implementation order and task breakdown (owned by create-plan).

Requirements and Outcomes

OUT-001: The TypeScript Pack carries the capability

A repository that selects the TypeScript Pack receives Typegraph provisioning, discovery, probing, Codex entries and health reporting through hi init and hi update. No other Pack, setting or selector is involved. A repository without the TypeScript Pack receives none of it. (Q10, C4)

OUT-002: One pinned Tool Runtime per machine, outside project dependencies

The CLI installs Typegraph as a versioned machine-level installation with an exact dependency lock bound to the installed Baseline. The tested tuple is Typegraph 0.9.56, TypeScript API 7.0.2, @effect/tsgo 0.36.5, MCP SDK 1.30.1 on Node 22.18 or newer. Project package manifests, lockfiles, compiler and lint dependencies are not changed. Supported platforms follow the pinned runtime's upstream package availability; there is no per-platform test matrix, and a platform or install failure surfaces as a recorded reason, never as a silent gap. The runtime stays installed when one repository stops using it. (Q11, Q19, Q20)

OUT-003: Compiler Projects are discovered, not listed by hand

The CLI discovers source-bearing tsconfig.json files in the current worktree and treats each as one Compiler Project. Wiki configs (by the configured wiki boundary) and solution-only configs with no source files are excluded by default. Ambiguous discovery is reported and resolved by an explicit override. Real compiler options, exclusions and import closure are preserved; no source or tsconfig is rewritten. (Q12, E1)

OUT-004: Activation is gated by a load probe, not a version string

Each discovered Compiler Project is loaded under the bundled TypeScript 7.0.2 at scaffold and update time. A project that loads is eligible for an entry. A project that fails is reported unavailable with the reason; its lint and typecheck keep working and its own compiler is never replaced. The project's declared TypeScript version does not decide activation. (Q16)

OUT-005: HI owns exactly its Typegraph entries inside the Codex file

For every eligible Compiler Project the CLI writes one [mcp_servers.<name>] table into the repository's Authored .codex/config.toml, restores those generated tables on every update after manual edits, and removes them when the repository deselects the TypeScript Pack. Every other table and byte in that file remains user-owned and untouched. Each entry binds the worktree root and one tsconfig at launch, so parallel worktrees answer about their own files. (Q13, Q14, Q20, E1)

OUT-006: The five reads are always approved and nothing else is exposed

Generated entries expose exactly ts_find_symbol, ts_definition, ts_references, ts_type_info and ts_module_exports, marked always approved so a call completes without a per-call prompt. Hover, graph, mutation and Effect diagnostics tools are not exposed. The user's global approval policy is not written. If a host still prompts or refuses, that is reported as a limitation, not silently accepted. (Q15, E3, E6)

OUT-007: hi check tells installed, registered and probe-passing apart

hi check reports three separate facts: the Tool Runtime is installed on this machine; this repository's generated entries are registered; each Compiler Project's load probe passes. Registry currency alone never implies any of them. (Q18)

OUT-008: A Codex session gets correct semantic answers

In a new Codex session started in the checkout, the agent can call the five reads on the server that owns a file and receive compiler-API answers that reflect the current on-disk sources, including ordinary edits to imported dependencies since the session started. (E1, E3, E4, E6)

OUT-009: Freshness beyond source edits is a documented limitation

After a tsconfig, dependency or branch change the operator starts a new Codex session. HI ships no wrapper, daemon or automatic restart. The runbook and generated guidance state this limitation. (Q17, E4)

OUT-010: Session cost is measured, not capped

Delivery records startup time, memory and exposed tool count for the per-project topology on this repository. No numeric threshold is enforced or promised. (Q13)

Acceptance Criteria

• AC-001: Running hi update in a repository whose Project settings select the TypeScript Pack provisions the Tool Runtime and writes Typegraph entries with no additional setting.
  • Covers: OUT-001
• AC-002: Running hi update in a repository without the TypeScript Pack installs no Tool Runtime and writes no mcp_servers table.
  • Covers: OUT-001
• AC-003: After hi update, a machine-level directory for the pinned Typegraph version exists with a lockfile whose resolved tuple is Typegraph 0.9.56, TypeScript API 7.0.2, @effect/tsgo 0.36.5 and MCP SDK 1.30.1 (or the tuple the installed Baseline pins).
  • Covers: OUT-002
• AC-004: Repository package.json, lockfiles and lint configuration are byte-identical before and after the Tool Runtime install.
  • Covers: OUT-002
• AC-005: On a machine where the install cannot complete (for example Node below 22.18 or a missing platform package) hi update records a reason, writes no Typegraph entries, and existing lint and typecheck commands still run.
  • Covers: OUT-002
• AC-006: A second hi update with a matching installed Tool Runtime performs no reinstall and leaves the runtime directory unchanged.
  • Covers: OUT-002
• AC-007: After the TypeScript Pack is deselected and hi update runs, the Tool Runtime directory still exists.
  • Covers: OUT-002
• AC-008: In this repository, discovery yields one Compiler Project per source-bearing workspace tsconfig (apps/api, apps/backoffice, apps/cli, apps/web, packages/auth, packages/contract, packages/db, packages/env, packages/scaffold, packages/ui) and none for the root tsconfig.json.
  • Covers: OUT-003
• AC-009: The apps/wiki tsconfig produces no Compiler Project and no entry by default.
  • Covers: OUT-003
• AC-010: When discovery is ambiguous, hi update reports the ambiguity and an explicit mapping in Project settings resolves it.
  • Covers: OUT-003
• AC-011: No tsconfig.json or source file changes as a result of discovery, probing or entry writing.
  • Covers: OUT-003
• AC-012: A Compiler Project whose tsconfig loads under the bundled TypeScript 7.0.2 receives a generated entry.
  • Covers: OUT-004
• AC-013: A Compiler Project whose tsconfig fails to load under the bundled compiler receives no entry, and hi update and hi check show the failure reason for that project.
  • Covers: OUT-004
• AC-014: A project whose own typescript dependency is not 7.0.2 but whose tsconfig loads is activated.
  • Covers: OUT-004
• AC-015: .codex/config.toml contains exactly one [mcp_servers.<name>] table per probe-passing Compiler Project after hi update.
  • Covers: OUT-005
• AC-016: Every byte of .codex/config.toml outside the generated Typegraph tables is identical before and after hi update.
  • Covers: OUT-005
• AC-017: After a manual edit to a generated Typegraph table, the next hi update restores the generated content and changes nothing else.
  • Covers: OUT-005
• AC-018: After the TypeScript Pack is deselected, hi update removes only the generated Typegraph tables and leaves every other table intact.
  • Covers: OUT-005
• AC-019: Two worktrees of the same repository, each with its own Codex session, each resolve ts_definition to paths inside their own worktree.
  • Covers: OUT-005
• AC-020: Each generated table's enabled_tools equals exactly the five read tools, and no hover, graph, mutation or diagnostics tool appears in the Codex tool list.
  • Covers: OUT-006
• AC-021: In a new Codex session under the host's default policy, a call to each of the five tools completes without an approval prompt.
  • Covers: OUT-006
• AC-022: hi update writes no top-level approval_policy and changes no ~/.codex/config.toml content.
  • Covers: OUT-006
• AC-023: If the host prompts or refuses despite the generated approval settings, hi check or the runbook reports it as a limitation rather than reporting the reads as unattended.
  • Covers: OUT-006
• AC-024: hi check --json reports, per repository, whether the Tool Runtime is installed, whether generated entries are registered, and per Compiler Project whether the probe passes.
  • Covers: OUT-007
• AC-025: With the runtime installed and zero Typegraph tables in .codex/config.toml, hi check reports installed true and registered false while its Registry status can still be current.
  • Covers: OUT-007
• AC-026: Human-readable hi check output shows the three facts as distinct lines or fields.
  • Covers: OUT-007
• AC-027: In a new Codex session in this repository, ts_definition for commandRegistry in apps/cli/src/index.ts on the CLI server resolves to apps/cli/src/cli/command-registry.ts.
  • Covers: OUT-008
• AC-028: ts_type_info for HarnessReportType in packages/contract/src/reports.ts returns "bug" | "docs" | "other" | "tooling" | "workflow" on both the contract and the CLI servers.
  • Covers: OUT-008
• AC-029: After changing an imported function's return type from string to number in a fixture, the next ts_type_info on the consumer returns the new type within the same session.
  • Covers: OUT-008
• AC-030: The runbook and generated Codex guidance state that a tsconfig, dependency or branch change requires a new Codex session.
  • Covers: OUT-009
• AC-031: hi update and hi check start no long-running process; every Typegraph process is spawned by Codex.
  • Covers: OUT-009
• AC-032: Implementation notes record measured session startup time, resident memory and exposed tool count for this repository's per-project topology, with no threshold applied.
  • Covers: OUT-010

Constraints

• C1: Typegraph is the chosen MCP; Serena is not reopened.
• C2: Existing HI format, lint and typecheck hooks remain authoritative; MCP output is never lint evidence and MCP mutations are not enabled.
• C3: Local proof first, Baseline integration later; this spec is the Baseline integration.
• C4: Pack is the only selection unit; detection proposes, never selects.
• Typegraph 0.9.56 requires Node 22.18 or newer (upstream constraint).
• .codex/config.toml is an Authored Artifact: the Registry writes it once when absent and preserves its bytes afterwards. HI's Typegraph tables are the only HI-managed content inside it.
• The CLI (apps/cli) owns provisioning, discovery, probing, entry writing and health facts; only stable shared contracts belong in packages/scaffold. No API or database service participates in this local stdio flow.
• Codex starts every enabled stdio server at session start and applies mcp_optional_startup_grace_ms (default 1000 ms) when building the initial tool catalog; HI does not own that host setting.
• Historical launch values (startup timeout 20 s, tool timeout 60 s) are evidence, not accepted limits.

Dependency Readiness

Ready.

• Registry Baseline (CLI 6.0.x, Authored Codex config, Pack selection): landed on origin/main at commit 1ca243d3ec5a2ce75d96ffd91a33d5257e31ae2f (CLI 6.0.1) and published as Registry 2026.09.28-1ca243d3 (https://api.harness-intelligence.devpunks.com/r/2026.09.28-1ca243d3/registry.json). Evidence: Registry research report, "Authority and research coverage".
• Typegraph MCP 0.9.56 with bundled TypeScript 7.0.2: exact tested lock SHA-256 3bcfab52d4ed1f320469cfe589e0e41392e655b17f45b7a7d676aebdf751d569; upstream latest remains 0.9.56 at the research readback.

Branch/Base Intent

Not applicable.

Accepted Technical Decisions

• Tool Runtime: versioned machine-level directory per pinned Typegraph version with an exact lock (npm ci reproduction); tested location ~/.local/share/hi-tools/typegraph-mcp/<version>; the final path is a planning choice, the isolation and exactness are not.
• Launch binding per entry: derive the worktree root with git rev-parse --show-toplevel into TYPEGRAPH_PROJECT_ROOT and set one TYPEGRAPH_TSCONFIG; run the isolated server.cjs with Node.
• Entry fields (Codex configuration reference, read 2026-09-28): command, args, env, enabled_tools (the five reads), default_tools_approval_mode or per-tool tools.<tool>.approval_mode set to the documented no-prompt value (documented values: auto, prompt, writes, approve; the exact value is verified during delivery), startup_timeout_sec, tool_timeout_sec.
• Topology: one server per Compiler Project; HI ships no MCP process.
• Activation gate: load each tsconfig under the bundled TypeScript 7.0.2 API from the Tool Runtime; no version-string match.
• Discovery input: source-bearing tsconfig.json files in the worktree, excluding the configured wiki boundary and solution-only configs; explicit override in Project settings for ambiguity; separate from lint Software Scopes and from Recorded Shape.
• Config ownership: generated tables are distinguishable from user tables; restore on update, remove on deselection; whole-file Authored ownership stays with the Registry.
• Health facts: hi check runs the same probe as scaffold/update and reads the runtime path and generated tables.

Accepted Testing Decisions

• No per-platform acceptance test matrix (Q19). Platform failures are proven by the runtime reasons in AC-005 and AC-013.
• Validation exercises: clean-machine install; unattended calls under the real Codex desktop policy; load probe across this repository's tsconfigs; discovery exclusions; two divergent worktrees; entry restore on update and removal on deselection; unrelated-config byte preservation; runtime retention; measured startup, memory and tool count.
• Semantic witnesses are the current-source ones (commandRegistry, HarnessReportType), not the retired ArtifactKind.
• Existing wiki content check and wiki tests remain the docs gates; existing CLI source tests remain the code gates.

Verification Seams

• hi check --json: the three health facts per repository and per Compiler Project (AC-024 to AC-026).
• .codex/config.toml generated [mcp_servers.<name>] tables and the bytes around them (AC-015 to AC-018, AC-020, AC-022).
• codex mcp get <name> --json and a new Codex session's tool list (AC-020, AC-021).
• Semantic calls through the configured servers (AC-019, AC-027 to AC-029).
• Tool Runtime directory and lockfile on the machine (AC-003, AC-006, AC-007).

Prototype Verdicts

• Local Typegraph setup, verified 2026-09-28: native TypeScript 7.0.2 definition, reference and type queries passed in all eleven workspace Compiler Projects through the exact shell launch; real Codex reviewed calls resolved commandRegistry and a contract type; a dependency edit refreshed the consumer type; LSP hover stayed stale and was excluded; approval-never refused the reads. Artifact: grill log entries E1 to E6 at commit 9975e1b6a8f04f5e1d42083d0ade956553a18b6b, path apps/wiki/content/docs/project/grilling/codex-typescript-mcp-grill-log.md; runtime lock SHA-256 3bcfab52d4ed…. Implications: OUT-002 exact lock, OUT-003 no root server, OUT-006 hover excluded, OUT-008 witnesses.
• Serena adapter with TypeScript 7.0.2 failed to initialize (expects tsserver.js); same artifact, entry E3. Implication: C1.

Parked Decisions

• Glossary Q21 (Compiler Project, Tool Runtime, Semantic Session as canonical terms). Owner: user. Resume: any later grill round on this capability.
• HI router server and automatic recovery. Owner: user. Resume: measured session cost or agent server-choice errors justify it.

Decision Log