refactor(agent): separate tool surface from operation registry

[avabbbb]

Why

OfferU currently has a large Operation Registry because the Registry is the governed control plane for more than external Agents:

• Career-domain primitives
• product workflows
• UI route mutations
• compatibility/legacy routes
• diagnostics/data-safety operations
• integration lifecycle operations
• Agent helpers

On the current assisted-apply branch the raw Registry contains 263 Operations.

That number was easy to misread as "the Agent has 263 tools".

It does not.

Static Skill projection shows:

Operation Registry                       263
Referenced by any built-in Agent Skill   112
Referenced by featured Skills             76
Not referenced by any built-in Skill     151

The real defect is that some discovery paths — especially ops --group / manifest --group — still treated route-level CRUD, diagnostics and legacy compatibility Operations as peers of model-facing tools.

This PR creates an explicit Tool Surface V2 boundary and performs the first evidence-backed registry cleanup.

Architecture

Operation Registry
  └─ all governed execution capabilities
     └─ Agent Tool Surface
        └─ union of live Skill allowlists
           └─ Active Skill Surface
              └─ selected Skill only

The Registry stays the authority.

Discovery is only a projection.

Main change: Agent-filtered discovery

Adds agent_operation_names() to the Skill Registry.

ops --group <group> now means:

Agent-exposed tools in this capability group

rather than:

every Registry Operation whose implementation happens to use this group label.

The explicit developer/audit escape hatch remains:

ops --all
manifest --all

which still exposes the complete Registry.

Example reduction

Before this PR:

group	raw Registry	built-in Skill surface
resume	42	8
applications	40	17
agent_runtime	31	14
profile	26	3
memory	20	14
research	19	17
interview	18	14
jobs	16	5

The goal is not an arbitrary low number. The goal is to keep route-level CRUD and maintenance tools out of normal Agent choice.

Registry cleanup: 263 → 260

Three Operations are removed with direct evidence.

1. Remove get_agent_provider_health

The single-provider Operation had no product route or Skill caller.

The actual product/Agent path uses list_agent_provider_health.

The underlying provider-health service remains available to implementation code.

2. Remove get_synthetic_email_test_data_status

This was synthetic-fixture/test infrastructure published as a Registry Operation.

Its service function remains available to privacy-hygiene tests. It is no longer a product/Agent Operation.

3. Merge generate_legacy_cover_letter into canonical generate_cover_letter

Both accepted the same business input:

job_id + resume_id

and produced the same class of draft.

The legacy /applications/generate HTTP route now calls the canonical Operation, which reads the current structured Resume/ResumeSection model.

The duplicate legacy Operation, input model and implementation are removed.

After this slice:

Operation Registry       260
Agent Tool Surface       112
Featured Tool Surface     76
Internal-only Operations 148

CLI clarity

Manifest / ops output now exposes separate metrics:

• operation_registry_count
• agent_tool_count
• featured_tool_count
• internal_operation_count

The old operation_count remains a backwards-compatible alias for Registry count.

This prevents future docs/Evals from treating Registry size as the model-facing tool count.

What is intentionally NOT deleted

This PR does not delete the old 28-operation legacy family wholesale.

Static review shows many still back current HTTP/UI surfaces.

For example:

• application-table CRUD still backs Application Workspace routes;
• resume template/section/share/photo CRUD still backs Resume routes;
• create_legacy_application and canonical create_application write different state models (Application vs current ApplicationRecord);
• get_legacy_profile still backs current Profile routes.

Those require data/route migration, not aliases or blind deletion.

Deferred consolidation

The architecture note records Phase-2 candidates such as:

• internal progress classifiers/projections with no literal product caller;
• context-rich reads replacing repeated list/get chains;
• Skill allowlist reductions for larger Skills such as follow_up, company_research, tailor_resume, application_assistant, and reply_watch.

Those should be accepted only after before/after real-Agent Eval, not from line-count intuition.

Tests added

backend/tests/test_agent_tool_surface.py locks:

• Agent Tool Surface is a strict subset of Registry
• featured surface ⊂ Agent surface
• group discovery hides internal/legacy route CRUD
• --all still exactly exposes the full Registry
• manifest count semantics
• resume group excludes low-level route CRUD
• removed entries stay absent
• old cover-letter HTTP route uses the canonical Operation

Safety

Unchanged:

• Operation validation
• side-effect labels
• Proposal/HITL
• permissions
• Bridge grants
• OperationAuditLog
• Career Truth authority

A tool being hidden from Agent discovery does not change authorization for existing product routes.

External design basis

Current tool-design guidance points in the same direction:

• OpenAI Function Calling: reduce initially available functions, combine functions that are always called sequentially, and delay-load large catalogs.
• OpenAI Tool Search: group/defer large tool collections and load detailed definitions only when relevant.
• Anthropic tool design: avoid exposing every API endpoint; prefer a smaller set of distinct, high-impact/context-rich tools and evaluate consolidation against real Agent tasks.

See docs/architecture/2026-09-22-tool-surface-v2.md.

Review note

This is stacked on #14 because #14 adds one assisted-apply Operation and is the current tool inventory baseline.

It is intentionally independent of #16's OMP RPC Harness implementation. #16 is the appropriate before/after evaluator for the deferred Skill-level consolidation work.

Verification state

Focused regression tests are included, but this PR does not claim a local test run from this GitHub-only editing session.

Keep Draft until local/CI verification is available.