Libra CodeHub

CedarCopilot/cedar-mail

Branch: staging

feat(agents): retire model and when_to_use as separate frontmatter concepts

merged#2707CedarCopilot

CedarCopilot wants to merge 4 commits into staging from feat/retire-model-and-when-to-use

Live on prod, no production signal yetTimeline and evidence
  1. Opened
    Sep 6, 2026, 7:03 PM
  2. Sep 6, 2026, 7:50 PM
  3. Merged
    Sep 6, 2026, 8:36 PM
  4. Live on prod
    Sep 6, 2026, 8:36 PM
  5. Observed 3 days
    Sep 6, 2026, 8:36 PM
  6. Pipelines steady after this deploy
    Sep 6, 2026, 8:36 PM
  7. Unobserved

    Live on prod, no production signal yet

    Sep 9, 2026, 8:23 PM

Behaviors Libra is checking

The `authorSubagentDoc` operation updates trigger guidance through `description` and no longer accepts a separate `whenToUse` field.Inconclusivehigh confidence

No production telemetry tied to authorSubagentDoc or admin.subagent.author was found since 2026-09-07T03:36:45Z: exact route/span query returned 0 requests, and CloudWatch returned no concrete author-operation success or error logs. The four matching log rows were unrelated.

prod, checked Sep 9, 2026, 8:22 PM
Agent creation and inspection no longer accept, expose, or display a configurable model value in the settings, service API, or `cedar-cli` commands.Inconclusivelow confidence

Unable to complete verification: telemetry identified `agent.list` activity, but the required direct create/show query was rejected by the telemetry service, and source reads were blocked by the source character budget. No verdict can be supported from the available evidence.

prod, checked Sep 9, 2026, 8:23 PM
Legacy `model:` frontmatter remains preserved as inert raw text but is no longer parsed into agent summaries, subagent descriptors, or editable header fields.Not checked
prod
The agent settings editor uses one Description field for both the agent's purpose and when the orchestrator should use it, without separate When to use or Model controls.Not checked
prod
The on-event orchestrator treats a subagent's description as informational context when deciding how to use a referenced subagent, rather than treating a separate `when_to_use` field as that context.Not checked
prod
Rendered playbook subagent references carry trigger guidance in the description and no longer render a separate `— when to use: ...` summary clause.Not checked
prod

Libra has verdicts on 0 of 10 tracked behaviors on prod; 10 are still being checked. Libra checks hourly for 3 days after each deploy.

Summary

Per explicit direction: model is ripped out entirely (backend and frontend), and when_to_use is retired as a separate concept , every current reader now reads description instead, which already carries the merged meaning going forward.

model , removed completely

Verified zero real customization exists in production (797/896 docs say model: sonnet, 2 say meaningless noise) and the hardcoded per-dispatch-tool model constants were always what actually ran. Removed: the Settings-form Model picker, SubagentFrontmatter.model and its parser case, EDITABLE_HEADER_KEYS/recomposeCustom, AgentHeaderFields.model/AgentSummary.model and every populator, model: sonnet from all 9 seeded templates and seed-playbook.ts's 5 legacy templates, and every authoring writer across both CLIs and 3 tRPC routes. No backfill needed , existing model: lines in customer docs go inert, same treatment permissions already got.

when_to_use , retired as a separate concept, replaced by description everywhere it's read

Flipped every live reader: the two production playbook renderers the orchestrator LLM reads on every live event (playbook-renderers.ts's renderSubagentRef, get-playbook-section.ts, plus resolve-playbook-context.ts's SubagentRef type feeding the first), reference-resolver.ts's formatSubagentSummary (a third rendering path found during implementation), review-triage.ts's reviewer-selection prompt, seed-playbook.ts's own separate hardcoded legacy templates (confirmed live, not dead code) and its dynamic custom-agent generator, and the Settings-form UI (folded into Description's hint text). Stopped every writer: the three authoring APIs no longer accept it as a parameter at all.

Deliberately still alive: SubagentFrontmatter.when_to_use and recomposeCustom's round-trip of it. The already-built, DRY_RUN-verified migrate-when-to-use-into-description.ts still needs to read and clear it on ~486 existing documents before the type can safely disappear. Running that migration for real, and the final cleanup pass removing the type once it has, are the next two steps , not in this PR.

Verified

  • pnpm --filter @zero/server run types AND @zero/mail run types , both clean.
  • 2500 server tests across every touched directory (playbook, agenda, aop, agent-workspace, trpc routes, subagent-admin, migrations) , pass.
  • 233 mail app tests (all of modules/agents) , pass.
  • oxlint --deny-warnings , clean on all 43 files.
  • deps:check , clean (1771 modules).
  • Every file independently re-read against the diff by the coordinating session, not just trusted from the implementing agent's report , the three live rendering paths, the frontend removal, the ordering-constraint fix (keeping the migration script compilable), and both API boundaries were each traced by hand.
  • One CI failure caught a real gap in the first review pass (a test asserting old literal description text that wasn't grepped for) , fixed in a prior commit on this same branch.

šŸ¤– Generated with Claude Code

https://claude.ai/code/session_01E3AhwqADAFeqe9wEhz6Mk7

Show production surfaces and changed-file mapping

Production surfaces

Libra has not measured any production surfaces for this change yet.

Changed files → surfaces

  • apps/mail/modules/agents/components/AgentSettingsSection.tsxno production surface mapped
  • apps/server/src/agent-admin/cli.tsno production surface mapped
  • apps/server/src/db/migrations/scripts/__tests__/migrate-when-to-use-into-description.test.tsno production surface mapped
  • apps/server/src/db/migrations/scripts/migrate-when-to-use-into-description.tsno production surface mapped
  • apps/server/src/mastra/agents/on-event-orchestrator-agent.tsno production surface mapped
  • apps/server/src/mastra/tools/agenda/__tests__/reviewConversationFanOut.test.tsno production surface mapped
  • apps/server/src/mastra/tools/event-execution/runSubagentTool.tsno production surface mapped
  • apps/server/src/scripts/agent-doc-type-smoke.tsno production surface mapped
  • apps/server/src/scripts/seed-coaching-agent.tsno production surface mapped
  • apps/server/src/services/agenda/review-triage.tsno production surface mapped
  • apps/server/src/services/agent-workspace/__tests__/agent-folders.test.tsno production surface mapped
  • apps/server/src/services/agent-workspace/__tests__/agent-header.test.tsno production surface mapped
  • apps/server/src/services/agent-workspace/agent-create.tsno production surface mapped
  • apps/server/src/services/agent-workspace/agent-header.tsno production surface mapped
  • apps/server/src/services/agent-workspace/agent-read.tsno production surface mapped
  • apps/server/src/services/agent-workspace/types.tsno production surface mapped
  • apps/server/src/services/aop/__tests__/subagent-frontmatter.test.tsno production surface mapped
  • apps/server/src/services/aop/aop-agents.tsno production surface mapped
  • apps/server/src/services/aop/subagent-frontmatter.tsno production surface mapped
  • apps/server/src/services/coaching/agent-template.tsno production surface mapped
  • apps/server/src/services/documents/__tests__/doc-type-registry.test.tsno production surface mapped
  • apps/server/src/services/documents/playbook-resource-seeds.tsno production surface mapped
  • apps/server/src/services/playbook/__tests__/author-subagent.test.tsno production surface mapped
  • apps/server/src/services/playbook/__tests__/curated-agenda-migration.test.tsno production surface mapped
  • apps/server/src/services/playbook/__tests__/drafter-seed.test.tsno production surface mapped
  • apps/server/src/services/playbook/__tests__/frontmatter-grants.test.tsno production surface mapped
  • apps/server/src/services/playbook/__tests__/golden-output-regression.test.tsno production surface mapped
  • apps/server/src/services/playbook/__tests__/playbook-renderers.test.tsno production surface mapped
  • apps/server/src/services/playbook/__tests__/reference-resolver.test.tsno production surface mapped
  • apps/server/src/services/playbook/__tests__/subagent-frontmatter.test.tsno production surface mapped
  • apps/server/src/services/playbook/__tests__/verify-subagent-doc.test.tsno production surface mapped
  • apps/server/src/services/playbook/agent-defaults/index.tsno production surface mapped
  • apps/server/src/services/playbook/author-subagent.tsno production surface mapped
  • apps/server/src/services/playbook/get-playbook-section.tsno production surface mapped
  • apps/server/src/services/playbook/playbook-execution-triggers.tsno production surface mapped
  • apps/server/src/services/playbook/playbook-renderers.tsno production surface mapped
  • apps/server/src/services/playbook/reference-resolver.tsno production surface mapped
  • apps/server/src/services/playbook/resolve-playbook-context.tsno production surface mapped
  • apps/server/src/services/playbook/seed-playbook.tsno production surface mapped
  • apps/server/src/services/playbook/subagent-frontmatter.tsno production surface mapped
  • apps/server/src/services/playbook/templates/__tests__/inbound-email-notifier.test.tsno production surface mapped
  • apps/server/src/services/playbook/templates/inbound-email-notifier.tsno production surface mapped
  • apps/server/src/services/playbook/verify-subagent-doc.tsno production surface mapped
  • apps/server/src/subagent-admin/cli.tsno production surface mapped
  • apps/server/src/trpc/routes/__tests__/agent-router-auth.test.tsno production surface mapped
  • apps/server/src/trpc/routes/admin-subagent.tsno production surface mapped
  • apps/server/src/trpc/routes/agent.tsno production surface mapped
  • apps/server/src/trpc/routes/aop.tsno production surface mapped