Land TS Mono

Landing coordinated ts-mono changes

A change in this repo sometimes requires a matching change in the ts-mono submodule — most commonly because a Python model feeding the type-generation pipeline changed, which regenerates a file inside the submodule. Landing then requires a cross-repo dance: a ts-mono PR, a gitlink bump here, and a specific merge order. This skill is the sanctioned exception to the AGENTS.md rule against changing the submodule gitlink.

Repo facts

<!-- Porting this skill to another repo (e.g. inspect_scout): swap this
     section's values; the procedure below is repo-agnostic. -->

• Submodule: src/inspect_ai/_view/ts-mono → https://github.com/meridianlabs-ai/ts-mono (branch main)
• Regeneration command: python src/inspect_ai/_view/schema.py (from repo root, venv activated; requires pnpm install done in the submodule)
• Generated artifacts:
  • src/inspect_ai/_view/inspect-openapi.json (this repo)
  • packages/inspect-common/src/types/generated.ts (inside the submodule)
• CI jobs (.github/workflows/log_viewer.yml):
  • check-schema-and-types — artifacts must match the Python source (docstring-only drift tolerated) and each other (exactly)
  • submodule-on-main — the gitlink SHA must be reachable from ts-mono main
  • dist-validation — the checked-in viewer bundle src/inspect_ai/_view/dist must match pnpm --filter @meridianlabs/log-viewer build run at the pinned submodule commit
• Submodule checks before pushing: pnpm typecheck and pnpm test from the ts-mono root (turbo), not per-package tsc
• Pipeline internals: design/type-generation-pipeline.md
• Sibling consumer: inspect_scout (also embeds ts-mono; its apps/scout/src/types/generated.ts duplicates the shared types). Its regen script scripts/export_openapi_schema.py regenerates its openapi.json from the installed inspect_ai and chains scout's types:generate.

Recognize the situation

• check-schema-and-types is red on your PR, or
• you changed a Python model that flows into the pipeline (Content, ChatMessage, Event, Citation, ToolChoice, EvalLog, or anything they reference), or
• your change requires editing code in the submodule directly.

Procedure

Your job is to reach the landed state from whatever state you find — you may be starting fresh or resuming mid-flight (possibly in a new session). First assess where things stand, then enter at the matching step:

Resumption relies on the PR cross-links (step 3) to find the paired PR, and any monitors/watches from a previous session are gone — re-arm them.

Finding the paired ts-mono branch: the submodule sits on a detached HEAD, so the work branch isn't announced. The authoritative probes work whatever the branch is named: git -C <submodule> branch -a --contains HEAD lists every branch containing the gitlink commit, and the PR cross-links (step 3) name the ts-mono PR's head branch. Branches are usually named the same as this repo's branch (step 1's convention), which makes a good first guess — but never a requirement. If nothing but main-ish refs contain HEAD, there's no branch yet — that's the fresh-start case (step 1). Before committing in the submodule, git checkout <branch> — a commit made on the detached HEAD lands on no branch. A local branch may also lag its remote; trust origin/<branch>, not the local ref.

1. Start submodule work from current main

In the submodule, git fetch origin and branch from origin/main — NOT the local main ref, which lags arbitrarily far behind (submodules live on detached HEADs; nothing routinely updates their local branches, and fetch moves only origin/main). You must be current with ts-mono origin/main before merging anyway, so get current before making changes. Name the new branch after this repo's branch — a convention that makes the pairing obvious at a glance (discovery doesn't depend on it; see "Finding the paired ts-mono branch" above).

2. Make the change / regenerate

Sync this repo's branch with its origin/main (fetch first) before regenerating — the schema that lands is generated from the merged Python, so regenerating against a stale branch bakes in a schema that drifts the moment you update the branch.

For type changes, run the regeneration command. It rewrites both generated artifacts — one in this repo, one in the submodule. Docstring-only changes do NOT require regeneration (CI tolerates description drift); only structural changes do.

Run the submodule checks (see repo facts) before pushing. Expect fixture fallout: adding a required field means test/e2e fixtures constructing literals of that type need the new field.

2a. If scout#typecheck breaks: sync the sibling's duplicated types

The sibling consumer's app in ts-mono carries its own generated duplicates of the shared types. TypeScript's structural typing keeps them interchangeable until the shape of an existing shared type changes incompatibly. Heuristic: would the change break a strict TS consumer or producer of the type?

• Noneable field added (optional) — breaks nobody; nothing to do (the common case)
• New type added — nothing to do
• Enum/literal union widened — breaks readers; sync needed
• Required (non-Noneable) field added — breaks producers; sync needed
• Rename/removal/type change — sync needed

When sync is needed, regenerate with the sibling's real tooling — do NOT hand-edit its generated file:

1. Push the ts-mono branch first.
2. Create a worktree of the sibling repo at its main; init its ts-mono submodule and check out your ts-mono branch in it.
3. Ephemeral venv: uv pip install -e <sibling worktree> -e <this repo checkout> (so the sibling's regen sees your unmerged Python change).
4. Run the sibling's regen script (see repo facts) with that venv's python.
5. Discard the sibling repo's own regenerated openapi.json (it can't land there until it upgrades this package); commit only the ts-mono generated.ts change to your ts-mono branch and push.
6. Eyeball the diff: if the sibling is behind on regens, unrelated drift rides along — fine for compatibility, but flag it in the PR.

3. Two-phase landing — phase 1: branch-pinned, reviewable

1. Commit on the ts-mono branch, push it, open a ts-mono PR.
2. In this repo, commit the gitlink pointing at the ts-mono branch head (plus any regenerated files here) and push.
3. Cross-link the two PRs in each other's descriptions.

Result: this repo's PR is green except submodule-on-main. That one red gate is the expected signal meaning "waiting on ts-mono merge" — do not try to fix it yet. Note: submodule-on-main is a job inside the "Validate Embedded Viewer" workflow, so that whole workflow shows as failing in rollup views — read job-level status before concluding anything else broke.

Why two-phase: once ts-mono merges, its main depends on Python changes that aren't merged yet, blocking anyone else who pulls ts-mono main. The goal is to make that window as short as possible: get everything else green on both PRs first, and only then merge ts-mono.