4.0 KiB
spec, decision, created, status
| spec | decision | created | status |
|---|---|---|---|
| docs/specs/office/requirements/routing.md | docs/decisions/2026-07-15-office-agent-execution-profile-routing.md | 2026-07-15 | completed |
Implementation Plan: Office Execution Profile Routing
Overview
Preserve the rich Office agent_profile_id as the durable role identity while resolving a complete execution_profile_id for every Office launch. Make provider-tier mappings reference profiles, persist the concrete selection through sessions and executors, and make cross-provider fallback start a fresh provider-native session in the same task/worktree with an explicit durable-state continuation prompt.
Contract
- Office identity owns role metadata, hierarchy, instructions, skills, Office permissions, budgets, status, executor preference, task/run ownership, costs, and capabilities.
- Execution profile owns provider CLI/account, model, mode, ACP config options, CLI flags and permission behavior, environment, passthrough, and MCP configuration.
- Tier profile resolution is always active.
enabled=falseselects only the first candidate;enabled=truepermits health-aware fallback. - Cross-profile fallback never reuses the previous profile's ACP/session token.
- Non-Office launches retain
execution_profile_id = agent_profile_idcompatibility.
Data And API
- Make
execution_profile_idsauthoritative inoffice_workspace_routing.provider_profiles; decode legacytier_profile_idsand migrate unambiguous model-only mappings. - Add concrete execution profile summaries to routing APIs and replace raw tier model/config editing with profile selection.
- Add
execution_profile_idtotask_sessions,executors_running,runs, andoffice_run_route_attemptsthrough replayable SQLite/Postgres migrations. - Include the execution profile in route previews, run details, route attempts, and diagnostics.
Runtime
- Carry stable Office ID and concrete execution ID from resolver through scheduler, orchestrator, executor, and lifecycle.
- Resolve process config, profile environment, CLI arguments, config options, passthrough, and MCP from the execution profile.
- Resolve skills, instructions, Office JWT/capabilities, budgets, and ownership from the Office identity.
- On profile change, clean up the previous process, suppress its resume token, retain task/worktree state, and launch with a continuation instruction.
Migration
- Accept and rewrite legacy
tier_profile_idsasexecution_profile_ids. - Match legacy model-only mappings to an active profile only when provider/model/mode identify exactly one profile.
- Surface missing or ambiguous profile mappings as actionable settings errors.
- Seed absent legacy workspace routing from existing Office configuration so upgrades do not silently change providers.
- Reconcile and supersede the current copy-on-select changes; preserve unrelated restart-name and session-assignee fixes.
Implementation Waves
Wave 1:
Wave 2:
Wave 3:
Wave 4:
Wave 5:
Verification
Run formatting before checks:
make -C apps/backend fmt
make -C apps/backend test
make -C apps/backend lint
cd apps/web && pnpm run typecheck
cd apps && pnpm --filter @kandev/web test
cd apps && pnpm --filter @kandev/web lint
cd apps/web && pnpm e2e --grep "Office routing"
Focused tests run within each task before the full commands. Container-backed Codex-to-Claude fallback E2E runs when the existing Office E2E fixture can inject classified provider limits; otherwise a lifecycle integration test must cover the real profile/config/token boundary and the browser E2E covers configuration and telemetry.