chore(driver)!: remove the deprecated AgentDriver surface in the next major (extracted from agent-runtime#694)

[drewstone]

Extracted from tangle-network/agent-runtime#694. The legacy persona-driver surface is deprecated with a warn-once fence, not deleted. Removal is a breaking change and waits for the next major.

What remains on 0.145.15 (src/driver.ts)

• AgentDriver (class, line 49) — the second driver family; a driver profile whose directive is the persona supersedes it.
• buildDriverSystemPrompt (line 245) and decideNextUserTurn (line 323) — role-as-function; the knowledge moved to directive seed prompts.
• buildWorkerDriverSystemPrompt is already gone.
• src/deprecation.test.ts locks the warn-once behavior.

On removal

• The deprecation strings in src/driver.ts cite agent-runtime#694, which is closed. Repoint them at this issue on the next touch of that file; do not ship a release only for the pointer.
• Delete the class and both functions in the next major; keep what they know as registry prompt seeds where a consumer still needs it.

[drewstone]

Measured caller count

Method: git grep on the default branch of nine sibling repositories (agent-runtime main, agent-app main, agent-knowledge main, agent-sdk main, supervisor-lab main, tax-agent main, gtm-agent master, blueprint-agent develop, agent-dev-container develop), plus a tarball grep at current latest of every published npm package that declares a dependency on this one: agent-app@0.45.62, agent-bench@0.8.10, agent-knowledge@8.0.5, agent-provider-tangle@0.12.2, agent-runtime@0.137.0, browser-agent-driver@0.36.0, run-capsule@0.4.1, sandbox-cli@0.8.8, starter-foundry@0.13.5, traces@0.11.5.

Two classes of match are excluded because they are not these exports: unrelated identifiers (HostAgentDriver in agent-dev-container, RedTeamAgentDriver in starter-foundry) and the MultishotShape.buildDriverSystemPrompt callback field — a caller-supplied property that shares a name with the function and appears in agent-runtime, tax-agent and gtm-agent.

Symbol	Public?	Sibling-repo callers	Published-dependent callers	Disposition
AgentDriver	never on the barrel or any subpath	0	0	deleted, 0.145.22 (#626)
AgentDriverConfig	never	0	0	deleted, 0.145.22 (#626)
buildWorkerDriverSystemPrompt	never	0	0	already gone before this issue
buildDriverSystemPrompt	never on the barrel or any subpath	0	0	deleted in #628
decideNextUserTurn	barrel	1 — gtm-agent eval/kernel.ts:31,1083	0	migrated in tangle-network/gtm-agent#901, then deleted in #628
DecideNextUserTurnOpts	barrel	0	0	deleted in #628

The two class-level symbols could not be imported by any consumer at any released version. decideNextUserTurn had exactly one live caller, so it was migrated before it was deleted, not around.

Limbs the deletion orphaned

Each of these had AgentDriver as its only caller and never reached the export surface. They go with it rather than staying as dead internal surface:

MetricsCollector, TurnMetrics, DriverResult (0.145.22), ConvergenceTracker with src/convergence.ts (#628), PersonaConfig.feedbackPatterns with the FeedbackPattern type, and PersonaConfig.driverModel (#628). analyzeSeries in src/series-convergence.ts is a different thing and stays: it reads drift across runs, not progress within one.

What the migration needed from the substrate

decideNextUserTurn holds its transport to the model id it was asked for — a persona turn written by a substitute model is not the requested model's behaviour. That check is assertServedModel, and the barrel did not export it, so a consumer taking ownership of its conversation loop would have had to drop it. 0.145.22 publishes the family whole: assertServedModel, assertServedModels, assertCrossFamilyServed, checkServedModel, servedModelAcceptable, ModelSubstitutionError, ServedCrossFamilyError and their option types.

PersonaConfig and DriverState stay for the same reason: gtm-agent's migrated driver imports both rather than redefining them.

State

• 0.145.22 — released, live on npm and PyPI.
• tangle-network/gtm-agent#901 — the migration; open.
• refactor(driver)!: remove the persona-driver surface #628 — the remaining deletion at 0.146.0; open. This issue closes when it merges.

[drewstone]

The failure

The persona-driver retirement (#628) was built on a caller table that said decideNextUserTurn had one first-party caller. It had five. Three shipped products — legal-agent, insurance-agent, workcomp-agent — were absent from the repository list the sweep ran against. A fourth, creative-agent, was absent from every list used during the correction as well, including the one that found the first three.

Nothing was broken at the time, because all four pin a version below the deletion (0.145.3, 0.145.3, 0.143.0, 0.145.3). Each would have broken at its first bump past it — silently, in a product eval, at whatever future moment someone ran pnpm update.

The root cause is enumeration, not grep

The grep was fine. git grep -w decideNextUserTurn finds every call in a repository it is pointed at. The defect is that the set of repositories was hand-written. A hand-written list has no failure mode that announces itself: a repository that is missing produces zero matches, which is indistinguishable from a repository that genuinely has none.

This is why the correction pass also missed creative-agent. Correcting a hand-listed set by hand reproduces the original defect. The fix is not a better list. It is to stop writing lists.

The method that replaces it

Derive the set mechanically, and report what the derivation could not cover.

1. First-party callers — every canonical checkout, on its default branch.

# canonical checkout = .git is a DIRECTORY.
# A worktree clone's .git is a FILE, so this excludes *-wt*, adc-*, .worktrees/* by structure
# rather than by name pattern — no naming convention to keep in sync.
cd ~/code
for d in */; do d=${d%/}; [ -d "$d/.git" ] && echo "$d"; done > canonical.txt

Then grep each on its default branch ref, never the checked-out branch — repositories are alive and are usually sitting on someone's in-flight work:

ref=$(git -C "$repo" symbolic-ref -q --short refs/remotes/origin/HEAD) \
  || ref=$(for c in origin/main origin/master; do
       git -C "$repo" rev-parse -q --verify "$c" >/dev/null && echo "$c" && break; done)
git -C "$repo" grep -n -w -I -- "$SYMBOL" "$ref" -- ':(exclude)*/node_modules/*'

Word-boundary (-w) matching is what keeps HostAgentDriver and RedTeamAgentDriver from ever matching AgentDriver. Do not filter those out by hand afterwards; make the match incapable of producing them.

On this machine that is 106 repositories: 89 default to origin/main, 12 to origin/master, 3 to origin/develop. Any method that assumed main would have silently missed three repositories, and any method that grepped the working tree would have read whatever branch happened to be checked out.

2. Published dependents — every package at latest, by tarball.

The npm registry scope search is not a complete index. Searching scope:tangle-network returned 13 packages; the real set is 78, recovered by unioning the search with every non-private package.json name across those 106 repositories. Of the 78, 39 are published. Download each latest tarball and grep the built output — dist/ is what a consumer actually resolves, and a symbol can appear there without appearing in any source file you can read.

This step found braid and traces as dependents that the earlier ten-package list did not include.

3. Report the holes.

Two repositories (persona-labs-sdk, tinder-for-anything) have no remote default branch. Say so. A repository that cannot be covered must appear in the output as uncovered, never be dropped — that is the same silence that caused this failure.

The full working script is in the #628 PR description.

Before deleting any exported symbol

• Enumerate repositories structurally (.git is a directory), never from a written list.
• Grep the default branch ref of each, not the working tree.
• Use git grep -w so lookalike identifiers cannot match.
• Union the registry scope search with repo-derived package names; the search index alone is incomplete.
• Grep published tarballs at latest, including dist/.
• Read the from clause of every hit before calling it a caller. A property key, a local definition of the same name, and a JSDoc sentence all look like calls to a grep.
• List every repository that could not be covered.
• Record each caller's pinned version, and check what that pinned version's implementation actually did. It is not always the same as main — decideNextUserTurn did not call assertServedModel before the 0.145.x line, so the correct port for workcomp-agent (pinned 0.143.0) omits that guard, while the correct port for the other three includes it. A port copied from main into a repository pinned below it changes behaviour silently.

One more thing this exposed

A green pnpm typecheck does not mean the eval directory compiles. workcomp-agent's root tsconfig.json includes only src and tests; creative-agent's includes only src/**. Both have an eval/tsconfig.json that covers the code that actually imports this package — workcomp wires it as pnpm eval:typecheck, creative wires it to nothing, and creative's has drifted to 6 pre-existing errors nobody sees. When you verify a migration in a consumer repository, run the tsconfig that covers the changed file, not the one the typecheck script happens to name.

[drewstone]

Independent re-derivation, 2026-08-17 — after the removal shipped

The removal is correct and complete on npm. All six symbols are absent from @tangle-network/agent-eval@0.147.0.
Three first-party callers of decideNextUserTurn are still on their default branches. Each pins a version below the removal, and each has an open migration PR.

This comment re-derives the table from scratch. It does not read the earlier one. The post-mortem above says the defect was a hand-written repository list, so the set below is derived mechanically and its coverage is reported as a number.

Method

1. First-party set. Every directory under ~/code whose .git is a directory. A worktree clone's .git is a file, so worktrees are excluded by structure, not by a name pattern.
2. Branch. Each checkout is grepped on refs/remotes/origin/HEAD, never on the checked-out branch. Local branches are stale and give the wrong answer.
3. De-duplication. Checkouts are collapsed by remote URL. Two directories can be the same repository — tax-agent-capstable is tangle-network/tax-agent at the same commit 763fa6a.
4. Published set. npm search @tangle-network returns every published package. Each manifest is read for a dependency on this package. Every dependent's latest tarball is downloaded and grepped.
5. Freshness. Every repository with a hit was fetched before the count was taken.

Coverage

Stage	Count
Checkouts under ~/code with .git as a directory	106
Covered by their remote default-branch ref	104
Local-only, no origin remote, covered by HEAD	2 — persona-labs-sdk, tinder-for-anything, both 0 hits
Distinct repositories behind those checkouts	98
Published @tangle-network packages searched	250
Of those, declaring a dependency on this package	10
Of those 10, whose tarball references any removed symbol	0

The 10 dependents: agent-app@0.45.62, agent-bench@0.8.12, agent-knowledge@8.0.8, agent-provider-tangle@0.12.3, agent-runtime@0.140.0, browser-agent-driver@0.36.0, run-capsule@0.4.1, sandbox-cli@0.8.10, starter-foundry@0.13.5, traces@0.11.6.

Caller table

Symbol	First-party value callers	Published-dependent callers	State
AgentDriver	0	0	removed, 0.145.22 (#626)
AgentDriverConfig	0	0	removed, 0.145.22 (#626)
buildWorkerDriverSystemPrompt	0	0	removed before this issue; the knowledge is data in src/worker-driver-seed.ts
buildDriverSystemPrompt	0	0	removed, 0.147.0 (#628)
DecideNextUserTurnOpts	0	0	removed, 0.147.0 (#628)
decideNextUserTurn	5, of which 2 migrated and 3 open	0	removed, 0.147.0 (#628)

The five callers of decideNextUserTurn

Repo	Default branch	Import site	Pinned range	Migration
gtm-agent	origin/master	eval/kernel.ts	—	merged, gtm-agent#901
creative-agent	origin/master	eval/e2e/creative-product-harness.ts:5	0.145.22	merged, creative-agent#496 (895ff9c)
legal-agent	origin/main	tests/eval/canonical.ts:120	0.145.3	legal-agent#366 — OPEN, APPROVED, CLEAN
insurance-agent	origin/main	tests/eval/canonical.ts:112	0.145.3	insurance-agent#97 — OPEN, APPROVED, CLEAN
workcomp-agent	origin/master	eval/driver.ts:24	>=0.143.0 <0.144.0	workcomp-agent#28 — OPEN, CLEAN

creative-agent is the caller the correction pass missed. It is migrated. The mechanical set finds it because it finds every repository, not because anyone remembered it.

Nothing is broken now. All three open callers pin below 0.147.0. Each breaks at its first bump past it, so each migration must merge before its next substrate bump.

creative-agent pins 0.145.22 exactly. An exact first-party pin is refused fleet-wide; the range for that version is >=0.145.22 <0.146.0. That is a separate repository's hygiene item, recorded here because the sweep measured it.

Excluded matches

Four classes of match are not these exports.

Class	Where	Why
Different identifier	HostAgentDriver in agent-dev-container, RedTeamAgentDriver in starter-foundry	unrelated names
Caller-supplied property key	MultishotShape.buildDriverSystemPrompt in agent-runtime, gtm-agent, tax-agent, and this package's own tests	a field a caller supplies; it shares a name with the removed function
Local declaration	export interface AgentDriver in agent-lab projects/playproof/runner.mts:47; function buildDriverSystemPrompt in tuner-agent src/lib/eval-adversary.ts:106	declared in that repository, not imported from here
Prose	agent-runtime docs/research/rsi-atom-masterplan.md, agent-app src/eval/index.ts comment, redteam .evolve/progress.md, this package's CHANGELOG	comments and documents, not code

Published-artifact check

The source tree is not the artifact. @tangle-network/agent-eval@0.147.0 was installed into an empty project and read at runtime.

AgentDriver => absent
AgentDriverConfig => absent
buildDriverSystemPrompt => absent
buildWorkerDriverSystemPrompt => absent
decideNextUserTurn => absent
DecideNextUserTurnOpts => absent

Version lock on origin/main is consistent at 0.147.0 across package.json, clients/python/pyproject.toml, clients/python/src/agent_eval_rpc/__init__.py and clients/python/uv.lock. npm published 0.147.0 at 2026-08-17T01:30:59Z, after the last commit on main (e07a6a4, 2026-08-17T01:24:57Z), so the published tarball carries #626, #627, #628, #622 and #629.