feat: let the engine run host agent classes, and teach SchemaTools about Rails enums

[TonsOfFun]

Four gaps a host hits when its agents live in Ruby and the dashboard mirrors them. Each was found by reading a real integration (support-hub) against the engine, and each is something the framework already has the information to do itself.

Based on release/1.6.3 (#457). No overlap with #460, which fixes the host-adapter / eval-catalog path (adapted-replay metering, ModelSpec validation, replace_scenarios! retention) — that host supplies a scenario_evaluation_adapter_resolver; this one supplies agent classes. Different seams, no shared files.

A Rails enum reached the model as a bare integer, and wrong values failed silently

SchemaTools builds filter properties from SchemaGenerator, which derives an enum constraint from inclusion validators. It never consulted model.defined_enums. So a status column backed by a Rails enum was offered as:

"status": {
  "anyOf": [
    { "type": "integer", "default": 0 },                       // no labels
    { "type": "object", "properties": { "gt": {…}, "lt": {…} } } // comparisons, on an enum
  ]
}

Two failure modes, both silent — measured against a host with 47 tickets, 2 open:

Call	Before	After
status: "pending" (not a real status)	{count: 0}	error naming draft, review, live
status: {gt: 1} (meaningless on an enum)	{count: 27}	rejected

{count: 0} is indistinguishable from "no tickets match", so an agent reports "nothing is under review" as fact and nothing errors anywhere.

The framework already had the right instinct one level up — an unknown column is rejected with `description` is not a filterable attribute. Allowed filters: … — and range_predicates! rejects an unknown operator with this reasoning stated in its own comment:

Rails silently turns where(col: { "before" => x }) into col = NULL, which matches nothing and reports zero rather than failing — the worst outcome for an agent, which reads it as a truthful empty answer.

This extends that same rule to enum values. Enums are now offered as {type: "string", enum: [names]} and excluded from the range form, so the prose mapping every host writes into its instructions ("status: open (0), in_progress (1)…") is no longer needed.

The engine could not run an agent that exists in code

AgentExecutionService builds an anonymous Class.new(ActiveAgent::Base) from the record's tools and instructions columns, overriding .name to impersonate the host class.

That is exactly right for a dashboard-authored agent — it is rows: a tool selection from AVAILABLE_TOOLS and instructions typed in the builder, with no Ruby class anywhere. That runtime is untouched here.

It is wrong for a mirrored agent. Its SchemaTools rosters, delegations and rendered instructions cannot be expressed as tools + instructions, so a host flattens its agents to sync them — and the dashboard then evaluates a lookalike rather than what production runs. One host's own docs record the consequence: "evals score the dashboard hub (flat roster), production runs the code hub (delegations)."

Both runtimes now coexist, chosen by whether the class resolves:

ActionAgent.run_host_agent_classes = true   # default: false

Default off, because it changes what a run of a mirrored agent executes. Agents naming no class are unaffected either way, and a name that no longer resolves — renamed, deleted, or not an agent at all — falls back to the dynamic runtime rather than taking the dashboard down.

AgentSync, so agent_class_name is the engine's job

AgentRelease already reads agent_class_name and documents that "whatever syncs its ActiveAgent classes into Agent records sets it" — but the engine never shipped that syncer, so each host writes ~90 generic lines. ActionAgent::AgentSync.call(RecordAgent.all, owner:) is that step, with the split that makes it safe on every deploy:

• The code owns what an agent is — name, description, instructions, tools. Rewritten each sync, so it cannot drift.
• The operator owns how it runs — provider, model, status. Set on create, never touched again, so a model picked in the dashboard survives the next deploy.

rendered_instructions

Two surfaces need an agent's instructions without running it: the dashboard mirror and tests. Both previously reached a private renderer via send. TicketAgent.rendered_instructions(topic: "tickets") is now public API — and gives release_digest a stronger thing to hash later (rendered text, not template file digests).

Testing

• 9 new tests: 5 in schema_tools_test.rb (enum schema, no range form, undefined value rejected, defined values still accepted, range predicate rejected), 3 in rendered_instructions_test.rb, 4 in agent_sync_test.rb, 5 in host_agent_class_execution_test.rb covering both runtimes and each fallback.
• One test caught a real bug pre-merge: namespaced classes produced billing/ticket-agent, which fails Agent's slug format. Now flattened to billing-ticket-agent.
• Full suite 2040 runs, 0 failures. 253 errors are pre-existing missing-API-key errors in docs/integration tests — baseline on the same checkout before these changes is 261, so this removes 8 and adds none.
• bin/lint: 555 files, no offenses.

Notes for review

• The chars/4 token estimator is untouched here, but it is worth a separate look: measured against a real trace it runs ~31% low (2.75 chars/token actual on JSON schema + markdown), so the context meter is a relative breakdown rather than a budget.
• provider_available? still ignores the provider ENV fallback, so a host with only OPENROUTER_API_KEY set sees the dashboard report the provider unconfigured while direct calls work. Related: openai is a development dependency but OpenRouterProvider requires it at runtime #416.

🤖 Generated with Claude Code