kandev/docs/decisions/0005-agent-model-unification.md

# 0005: Agent model unification — enrich `agent_profiles`, drop `office_agent_instances`

**Status:** proposed
**Date:** 2026-05-06
**Area:** backend, frontend

## Context

Two separate concepts describe "an agent" in the codebase today:

1. **`agent_profiles`** (singular table, defined at
   `apps/backend/internal/agent/settings/store/sqlite.go:56`). A
   profile is a *configured variant* of a CLI agent tool — it selects
   a `model`, a `mode` (e.g. ACP for Claude Code, plan for
   OpenCode), permission flags (`auto_approve`,
   `dangerously_skip_permissions`, `allow_indexing`, `cli_passthrough`),
   and an MCP configuration (in the sibling `agent_profile_mcp_configs`
   table). It belongs to a CLI tool via `agent_id`
   (`agents.id` — the CLI registration table). Profiles are global
   today; the kanban settings UI manages them at
   `/settings/agents/<agent>/profiles/<profile-id>`. Workflow steps,
   workflow_step_participants, kanban tasks, and task_sessions all
   reference profiles via `agent_profile_id`.

2. **`office_agent_instances`** (defined at
   `apps/backend/internal/office/repository/sqlite/agents.go`).
   Workspace-scoped. Carries the *organisational* and *runtime*
   identity of an agent: name (e.g. "Backend Engineer Alice"), role
   (`ceo` / `worker` / `qa_lead`), icon, status,
   pause_reason, skill_ids, custom_prompt, reports_to, budget,
   concurrency caps, failure tracking, etc. Each instance has an
   `agent_profile_id` foreign key pointing at concept (1).

The two-table model exists because office was added on top of an
already-shipped kanban concept. It produces real friction:

- **Workflow_step_participants is keyed by `agent_profile_id`.** For
  office reviewers we need the rich per-workspace identity (skills +
  prompt) but the participants table only references the profile tier.
  Two different reviewer instances sharing one CLI profile become
  indistinguishable in the workflow store. This is "Blocker 1" from the
  task-model-unification work.
- **Office tasks reference instances** via
  `tasks.assignee_agent_instance_id` while workflow steps reference
  profiles. Every launch path threads both ids and resolves the union.
- **Kanban can't use office-created agents.** A CEO with skills + a
  custom prompt is invisible to kanban workflow editors today, even
  though the underlying CLI configuration is exactly the same shape as
  any kanban profile.

The fix is to merge them: enrich `agent_profiles` with the office-only
columns, migrate every office_agent_instance into a profile, and rename
`agent_instance_id` → `agent_profile_id` everywhere in code and
schema. After the merge, `agent_profiles` is the single source of
truth for "an agent" — kanban-shallow agents (no skills, no role) and
office-rich agents (with skills + role + workspace scoping) live as
rows in the same table.

## Decision

**One `agent_profiles` table** that supports two richness levels:

- **Shallow profile** (kanban-style): just the existing columns. No
  workspace scope, no skills, no role. The kanban settings UI at
  `/settings/agents/<agent>/profiles/<profile-id>` continues to manage
  these as today.
- **Rich profile** (office-style): all of the above PLUS workspace
  scope, role, skills, custom_prompt, status, budget, concurrency
  caps, failure tracking, etc. The office agents page surfaces both
  the shallow fields (so the user can pick / change the underlying CLI
  client, model, mode, MCP config) AND the office-only enrichment
  fields.

`office_agent_instances` is dropped. Every `agent_instance_id` in
schema and code becomes `agent_profile_id` referencing the merged
table. Skill deployment moves into the runtime's launch-prep so every
launch (kanban or office) treats `skill_ids` + `custom_prompt`
uniformly — agents with empty values get a no-op deploy.

### Final schema

`agent_profiles` after this ADR:

```sql
CREATE TABLE agent_profiles (
    -- Existing columns (unchanged):
    id TEXT PRIMARY KEY,
    agent_id TEXT NOT NULL,                          -- FK → agents (CLI tool)
    name TEXT NOT NULL,
    agent_display_name TEXT NOT NULL,
    model TEXT NOT NULL DEFAULT '',
    mode TEXT DEFAULT NULL,
    migrated_from TEXT DEFAULT NULL,
    auto_approve INTEGER NOT NULL DEFAULT 0,
    dangerously_skip_permissions INTEGER NOT NULL DEFAULT 0,
    allow_indexing INTEGER NOT NULL DEFAULT 1,
    cli_passthrough INTEGER NOT NULL DEFAULT 0,
    user_modified INTEGER NOT NULL DEFAULT 0,
    plan TEXT DEFAULT '',
    cli_flags TEXT DEFAULT NULL,
    created_at TIMESTAMP NOT NULL,
    updated_at TIMESTAMP NOT NULL,
    deleted_at TIMESTAMP,

    -- NEW (workspace scoping):
    workspace_id TEXT NOT NULL DEFAULT '',           -- '' = global / kanban-legacy; set = workspace-scoped

    -- NEW (organisational identity):
    role TEXT NOT NULL DEFAULT '',                   -- '' | 'ceo' | 'worker' | 'qa_lead' | ...
    icon TEXT NOT NULL DEFAULT '',
    reports_to TEXT NOT NULL DEFAULT '',             -- agent_profiles.id (org chart)

    -- NEW (skills + prompt enrichment):
    skill_ids TEXT NOT NULL DEFAULT '[]',            -- JSON array
    desired_skills TEXT NOT NULL DEFAULT '[]',
    custom_prompt TEXT NOT NULL DEFAULT '',

    -- NEW (runtime state):
    status TEXT NOT NULL DEFAULT 'idle'
        CHECK (status IN ('idle','working','paused','stopped','pending_approval')),
    pause_reason TEXT NOT NULL DEFAULT '',
    last_run_finished_at TIMESTAMP,

    -- NEW (concurrency / scheduling):
    max_concurrent_sessions INTEGER NOT NULL DEFAULT 1,
    cooldown_sec INTEGER NOT NULL DEFAULT 0,
    skip_idle_runs INTEGER NOT NULL DEFAULT 0,

    -- NEW (failure tracking):
    consecutive_failures INTEGER NOT NULL DEFAULT 0,
    failure_threshold INTEGER NOT NULL DEFAULT 3,

    -- NEW (executor / cost):
    executor_preference TEXT NOT NULL DEFAULT '',
    cheap_agent_profile_id TEXT NOT NULL DEFAULT '', -- self-ref for low-priority work
    budget_monthly_cents INTEGER NOT NULL DEFAULT 0,

    -- NEW (catch-all for office fields not explicitly listed):
    settings TEXT NOT NULL DEFAULT '{}',

    FOREIGN KEY (agent_id) REFERENCES agents(id) ON DELETE CASCADE
);

CREATE INDEX idx_agent_profiles_workspace ON agent_profiles(workspace_id);
CREATE INDEX idx_agent_profiles_role ON agent_profiles(workspace_id, role) WHERE role != '';
CREATE INDEX idx_agent_profiles_reports_to ON agent_profiles(reports_to) WHERE reports_to != '';
```

**MCP config stays in the sibling `agent_profile_mcp_configs` table.**
That's already a 1:1 side table keyed by `profile_id`; it doesn't need
to fold in. Both shallow and rich profiles use it the same way.

### Tables that gain renamed columns

Every table that today references office's instance id by
`*_agent_instance_id` (or its variants) is renamed to
`*_agent_profile_id`, pointing at the merged `agent_profiles` table:

```
office_skills.created_by_agent_instance_id      → created_by_agent_profile_id
office_cost_events.agent_instance_id            → agent_profile_id
office_routines.assignee_agent_instance_id      → assignee_agent_profile_id
office_approvals.requested_by_agent_instance_id → requested_by_agent_profile_id
office_agent_memory.agent_instance_id           → agent_profile_id
office_channels.agent_instance_id               → agent_profile_id
office_agent_instructions.agent_instance_id     → agent_profile_id
office_inbox_dismissals.agent_instance_id       → agent_profile_id
office_workspace_settings.lead_agent_instance_id → lead_agent_profile_id
runs.agent_instance_id                          → agent_profile_id
tasks.assignee_agent_instance_id                → assignee_agent_profile_id
office_task_participants.agent_instance_id      → agent_profile_id
```

(After the merge, the `office_task_participants` table is itself
migrated into `workflow_step_participants` — see "Implementation
sequence" below.)

### Identity preservation in the migration

For each `office_agent_instances` row, we INSERT a new
`agent_profiles` row using the **instance's id as the new profile's
id**. That way every existing FK that today points at the instance id
(tasks, participants, decisions, runs, costs, etc.) continues to work
unchanged after the rename — the column name flips but the value is
preserved.

The instance's old `agent_profile_id` (which today points at a
shallow profile that the instance was configured against) gets its
columns *copied* into the new merged row (model, mode, auto_approve,
mcp_config, etc.). The original shallow profile keeps existing as a
distinct row — kanban tasks that referenced it continue to reference
it. After the migration we'll have:

- The original shallow row (kanban-flavour, workspace_id='').
- A new rich row using the old instance's id (office-flavour,
  workspace_id set, with the CLI fields copied from the original
  shallow row).

Same logical kanban behaviour; rich identity now first-class.

### Migration policy

Per the user's directive: **office tables can be wiped without
migrations** (greenfield — the office feature is in development, not
deployed). For non-office tables (`tasks`, `task_sessions`, `runs`,
`workflow_step_participants`) we write proper migrations because they
carry kanban data.

Concretely:

| Table | Migration policy |
|---|---|
| `office_agent_instances` | wipe + repopulate from migration insert |
| `office_skills`, `office_routines`, `office_approvals`, `office_agent_memory`, `office_channels`, `office_agent_instructions`, `office_inbox_dismissals`, `office_workspace_settings`, `office_cost_events`, `office_task_participants`, `office_task_approval_decisions` | recreate-table with renamed column; data preservation only when trivial — wiping is fine for office state |
| `tasks` | proper recreate-table migration: copy `assignee_agent_instance_id` → `assignee_agent_profile_id`, drop the old column |
| `task_sessions` | column rename if `agent_instance_id` exists (kanban data preserved via the rename) |
| `runs` | column rename, kanban + office data preserved |
| `workflow_step_participants` | already has `task_id` (wave 8 piece 1); no schema change |

For SQLite, the recreate-table pattern handles column renames where
`ALTER TABLE RENAME COLUMN` isn't available. Look at
`apps/backend/internal/task/repository/sqlite/base.go` for the existing
pattern.

### UX

**Kanban settings UI — unchanged.** The page at
`/settings/agents/<agent>/profiles/<profile-id>` continues to manage
just the existing fields (model, mode, MCP config, permission flags,
etc.). For shallow / kanban-style profiles, the office fields are not
exposed — the form looks identical to today.

**Office agents page — gains the full picture.** The office page
surfaces:

- The existing CLI fields: which CLI client (claude / codex /
  opencode-acp / amp / etc.), model, mode, MCP config, permissions.
  Today these fields are configured in kanban settings; on the office
  page they become inline so the user doesn't have to context-switch.
- The office enrichment fields: name, role, icon, reports_to,
  skill_ids, custom_prompt, max_concurrent_sessions, cooldown_sec,
  budget, etc.

A profile created in the office page is a rich profile
(workspace_id set, office fields populated). A profile created in
kanban settings is a shallow profile (workspace_id='', office fields
empty). Either way, the same row in the same table.

The office agents page becomes the recommended place to create an
agent that you intend to use for office work. Existing kanban profiles
continue to work and can be enriched into office agents by setting
their workspace + office fields.

**Office onboarding — adds CLI configuration step.** Today's
onboarding creates a CEO agent with hardcoded defaults. After this
ADR, onboarding asks the user to pick:

- Which CLI client (claude / codex / opencode-acp / amp / ...).
- Which model (claude-sonnet / opus / o3-mini / etc.).
- Which mode (ACP / plan mode / etc.).
- Optionally MCP servers + permission flags (or accept defaults).

These were previously handled by reading the user's existing kanban
settings for an inferred default; making them explicit at onboarding
time matches the "office can configure agents end-to-end" model.

### Skill deployment in runtime

Today: office's launch path materialises `skill_ids` + `custom_prompt`
into the worktree before the agent starts (symlink deploy + prompt
file). After this ADR: that step lives in `internal/agent/runtime/`'s
launch-prep — every launch reads the agent profile, looks at
`skill_ids` and `custom_prompt`, and deploys. Empty values → no-op
fast path. Kanban launches that don't use these fields are unaffected;
kanban profiles that the user later enriches with skills get them on
the next launch.

`runtime.LaunchSpec.AgentProfileID` already exists from Phase 1 of
task-model-unification. The runtime resolves the agent record (now
including office enrichment) from the profiles repo.

### Code-level rename

Across backend (~593 lines, ~131 files) and frontend (~164 lines):

| Old | New |
|---|---|
| `agent_instance_id` (column / JSON / param) | `agent_profile_id` |
| `AgentInstanceID` (Go field) | `AgentProfileID` |
| `agentInstanceId` (TS field) | `agentProfileId` |
| `models.AgentInstance` (Go struct) | merge with `models.AgentProfile` (the existing struct gains office fields) |
| `OfficeAgentInstance` (TS type) | merge with `AgentProfile` |
| `office_agent_instances` (table refs in code) | `agent_profiles` |

Most of this is mechanical rename + recompile. A subset of files have
both `AgentProfileID` and `AgentInstanceID` as separate fields on the
same struct (those collapse — needs hand-judgement per case to ensure
no callsite depended on the two values being different).

## Consequences

### Positive

- **Blocker 1 dissolved.** `workflow_step_participants.agent_profile_id`
  carries skills + prompt for office reviewers. Decision attribution
  is unambiguous because there's one identity per agent.
- **Office agents become available to kanban.** A CEO or Backend
  Engineer profile created in the office page is selectable in any
  workflow editor. Kanban profiles are eligible as office reviewers.
- **One settings model.** Skills + custom prompt + role are first-class
  fields on a profile. The runtime treats every launch the same way.
- **Smaller refactor than the workspace_agents alternative.** ~600
  callsites instead of ~2,762. Tractable in 1–2 focused waves.

### Negative

- **`agent_profiles` becomes a fat table.** ~25 columns, many
  nullable for shallow profiles. Mitigated by clear documentation of
  which fields are kanban-relevant vs office-relevant; the kanban UI
  doesn't expose office columns.
- **Workspace scoping coexistence.** Some profiles are global
  (`workspace_id=''`), some are workspace-scoped. Every read that's
  scoped by workspace must filter by `workspace_id IN ('', $ws)` to
  see both. Acceptable cost; encoded in the repo helpers.
- **Office onboarding gains complexity.** Users now have to make CLI
  choices upfront. Mitigated by sensible defaults (preselect the
  user's current kanban-default profile).

### Risks

- **Field-name collisions on existing structs.** `OfficeAgentInstance`
  has both `ID` and `AgentProfileID` today; merging makes them
  potentially the same value. Each callsite needs case-by-case review.
  Mitigated by mechanical sed for the 80% case + careful review of
  conflicts.
- **Frontend type churn.** `AgentProfile` is referenced in many
  components; adding office fields means TypeScript types widen.
  Mitigated by making office fields optional on the type so existing
  consumers don't break.

## Alternatives considered

### Alternative A: Keep two tables, add a bridge

Reject. Preserves Blocker 1.

### Alternative B: This proposal — enrich `agent_profiles`, drop `office_agent_instances`

Chosen. Smallest viable refactor that solves the impedance mismatch.
Keeps the existing table and its FK relationships. Office becomes a
richer view of the same row.

### Alternative C: New `workspace_agents` table, drop both old tables, full rename

Originally proposed in the first draft of this ADR. Rejected as
disproportionately large (~2,762 callsites for a name change). The
user's directive: "i don't want to move away from agent profiles for
now, its a much bigger change."

## Implementation sequence

Three waves, each shippable on its own:

### Wave A — Foundation (schema + migration only, no callsite changes)

1. Add the new columns to `agent_profiles` (idempotent ALTER TABLE
   migrations).
2. Update the `AgentProfile` Go model to carry the new fields.
3. Update the repo to round-trip them.
4. Migration: insert one `agent_profiles` row per
   `office_agent_instances` row, preserving the instance's id.
5. Skill deployment moves into `internal/agent/runtime/`'s launch-prep
   (no-op if `skill_ids` empty).

After Wave A: `agent_profiles` is the canonical store, both shallow
and rich rows live in it. `office_agent_instances` still exists but is
no longer the source of truth — it becomes a redundant copy until
Wave B.

### Wave B — Callsite rename

1. Rename `agent_instance_id` → `agent_profile_id` columns in all
   non-office tables (`tasks`, `runs`, `task_sessions`,
   `workflow_step_participants`, etc.) — proper migrations.
2. Recreate office tables with renamed columns (no data preservation
   needed; greenfield).
3. Rename `AgentInstanceID` → `AgentProfileID` Go fields, code
   references, frontend types, payloads.
4. Drop `office_agent_instances` table.

After Wave B: `office_agent_instances` is gone; everything references
`agent_profile_id` against the unified `agent_profiles` table.

### Wave C — Dashboard reviewer/approver migration

1. Migrate `office_task_participants` → `workflow_step_participants`
   (using the dual-scope `task_id` from wave 8 piece 1).
2. Migrate `office_task_approval_decisions` → `workflow_step_decisions`.
3. Drop the two legacy office tables.
4. Drop `tasks.assignee_agent_profile_id` entirely. Per-task assignee
   resolves through the workflow step's `primary_agent_profile_id`
   (or `workflow_step_participants` for multi-agent stages). The
   per-task snapshot was redundant.
5. Update office UI to surface the new agent fields (Office Agents
   page changes).
6. Update office onboarding to ask for CLI client + model + mode.

After Wave C: the dashboard reviewer/approver flow uses the unified
participants/decisions tables. The Phase 4 deferred items from
ADR 0004 are resolved.

## Out of scope

- Cross-workspace agent sharing (workspace_id is the boundary).
- Agent versioning beyond `updated_at`.
- Per-tool MCP overrides at the office level (use the existing
  `agent_profile_mcp_configs` for now).
- Renaming `agent_profiles` → `agents` or anything else. Keep the
  current name; it fits.

## References

- ADR 0004 — task-model-unification.
- `docs/specs/task-model-unification/plan.md` Phase 4 deferred items.
- Wave-9 / Wave-10 agent scope surveys (in PR commit messages).