waggle-os/docs/ux-refactor/gap-cards/S18-agent-builder.md

Gap Card — S18 Agent Builder

UX-refactor planning artifact. Execution model: in-place incremental refactor of apps/web + targeted backend extensions. Every claim is grounded in a real file. PRD = docs/Waggle_OS_UX_Refactor_Master_Handoff_Package/Waggle_OS_UX_Refactor_PRD.md (§12.9 + §16.7). Mockup (directional only) = Waggle_OS_Handoff_Assets/screens_18_21_builders_and_marketplace.png.

---

1. Screen & purpose

Create an agent as an explicit work actor through a guided stepper, with no hidden memory/tool access. PRD §12.9: "Manage agents as explicit work actors… User can explain what an agent can see and do before enabling it." Blueprint Screen 18 (_blueprint_extracted.txt:410-416): "Create an agent with goal, model, autonomy, memory, skills and permissions. Configure, test, review, create. States: Draft; validation; approval needed; created. Acceptance: No agent has hidden memory/tool access."

The Agent Builder is the create-flow companion to the Agent Center (Screen 9, a separate gap card). S18 is one of four builder/marketplace screens grouped in the same mockup (18 Agent Builder, 19 Skill Builder, 20 Automation Builder, 21 Marketplace).

PRD §16.7 names the agent CRUD/run/traces API surface this builder writes to.

---

2. Required states (PRD / Blueprint)

Builder steps (PRD §12.9, line 589): Basic Info → Capabilities → Memory & Tools → Permissions → Review & Create (5-step stepper).

Agent fields the builder must collect (PRD §12.9 line 590 + §15.5 lines 1015-1036): name, goal, description, persona/avatar, model, autonomyLevel (manual|guided|medium|high, PRD §15.2), type (personal|workspace|team|autonomous), memoryScopes, skillIds, connectorIds, mcpIds, permissions, status, workspaceIds, createdBy, lastRunAt, successRate.

Per-screen states (blueprint :413-414 + :461-463):

• Draft — partially-filled builder, save without activating.
• Validation — required-field gating (goal, model, memory scope, skills/tools/MCPs, autonomy per blueprint :134).
• Approval needed — elevated permission selections require an approval prompt before create (PRD §12.9 "all elevated access is reviewed"; §17.3 "elevated actions require human approval").
• Created — agent appears in Agent Center + target workspace (Journey 10, PRD lines 746-753).
• Plus global states (PRD §14.1): Loading, Error, Offline/local-only, Permission denied.

Hard acceptance gate (blueprint :415-416, :134): "No agent has hidden memory/tool access" and "Agent Builder must require model, goal, memory scope, skills/tools/MCPs and autonomy level." The Review step must render the full effective permission/memory/tool surface before the user confirms.

Test affordance: blueprint :413 "Configure, test, review, create" — a dry-run before create (analogous to Skill Builder's test). PRD §12.9 does not list test as a functional requirement; treat as optional (open question §9).

---

3. Current state in repo — disposition: create-new (builder) + partial (substrate reuse)

There is no Agent Builder and no first-class Agent entity today. The closest existing surface is a persona/agent-group model, which is a strict subset of the PRD Agent.

Existing frontend (the seed):

• apps/web/src/components/os/overlays/SpawnAgentDialog.tsx — a 2-step dialog (config → confirm, :29) that spawns a transient sub-agent (task + persona + model + parent workspace) via adapter.spawnAgent → POST /api/fleet/spawn. It collects only task/persona/model/workspaceMode (:37-44); it has model-fetch with 3-tier fallback (:50-99) and a cost-estimate review pane (:388-421). It does not persist an agent definition — it fires a one-shot fleet job. This is the seed named in the task, but it is a spawn dialog, not a builder.
• apps/web/src/components/os/apps/AgentsApp.tsx — titled "Personas" (:175), two tabs (agents/groups, :16). Lists personas via adapter.getPersonas() (:36) and agent-groups via adapter.getAgentGroups() (:38). "New Persona" → CreateAgentForm.
• apps/web/src/components/os/apps/agents/CreateAgentForm.tsx — a single-page form (not a stepper) collecting name/description/icon/systemPrompt/tools[] (:9), with an "Generate with AI" box (:58-81) → adapter.generatePersona. This is the closest existing "create-an-agent" UI, but it maps to a persona (no goal/autonomy/model/memoryScope/connectors/mcps/permissions).
• apps/web/src/components/os/apps/agents/AgentDetail.tsx — read view showing icon/name/description/tools/commands/affinity (:49-103). No goal/model/autonomy/permissions/successRate/status.

Existing backend (the substrate to reuse, not rebuild):

• packages/server/src/local/routes/personas.ts — GET/POST/PATCH/DELETE /api/personas + POST /api/personas/generate. POST persists a custom AgentPersona to disk (saveCustomPersona, :57); fields are id/name/description/icon/systemPrompt/modelPreference/tools/workspaceAffinity/suggestedCommands/defaultWorkflow (:45-56). No goal/autonomy/memoryScopes/connectorIds/mcpIds/permissions/status. PRO-tier gated (:32).
• AgentPersona interface (packages/agent/src/personas.ts; full field list in docs/backend-map/sections/05a-subsystem-agent-runtime.md:198-218) already carries suggestedSkills?/suggestedConnectors?/suggestedMcpServers?/disallowedTools?/isReadOnly? — useful seed columns for the richer Agent.
• packages/server/src/local/routes/agent-groups.ts — GET/POST/PATCH/DELETE /api/agent-groups + POST /api/agent-groups/:id/run (the run is a placeholder stub, :105-127 — returns a queued jobId, does not execute). Groups persist to {dataDir}/agent-groups.json (:29). This is the closest "agent persistence on disk via JSON file" precedent.
• packages/server/src/local/routes/fleet.ts — POST /api/fleet/spawn is the only real agent-execution path (:66-257): creates a session, emits Waggle signals, and fire-and-forgets runAgentLoop in the background (:142-245). POST /api/fleet/:workspaceId/pause|resume|kill (:260-290). This is what /api/agents/:id/run and /pause must wire onto.
• execution_traces table (packages/hive-mind-core/src/mind/schema.ts:199) is written from chat.ts and evolution.ts (grep-confirmed) but has no HTTP read route — /api/agents/:id/traces is net-new over this store.

Why create-new, not rework: the PRD Agent (§15.5) is a superset of persona — it adds goal, autonomy, type, memoryScopes, connectorIds, mcpIds, permissions, status, workspaceIds, lastRunAt, successRate. A persona is the behavioral template; a PRD Agent is an instantiated, scoped, governed actor. Bending CreateAgentForm/persona-POST to carry all of that would corrupt the persona contract (shared by the runtime prompt composer). The clean model: net-new Agent entity + 5-step builder, with a persona selected as one field of the agent. Heavy reuse of persona catalog, model picker, tool catalog, fleet-spawn, and execution-traces underneath.

---

4. Frontend work

Create new — apps/web/src/components/os/overlays/AgentBuilder.tsx (or components/os/apps/agents/AgentBuilder.tsx if hosted inside the Agents app shell). A 5-step stepper matching PRD §12.9:

1. Basic Info — name, goal (required), description, persona/avatar picker, type (AgentType).
2. Capabilities — model (required), autonomyLevel (required), defaultWorkflow.
3. Memory & Tools — memoryScopes (required), skillIds, tools[] (required-ish per blueprint :134).
4. Permissions — connectorIds, mcpIds, explicit permissions; surface elevated-access warnings here (drives the "approval needed" state).
5. Review & Create — full effective surface (the "no hidden access" gate), then create.

Reuse targets (do not rebuild):

• Stepper chrome: there is no shared BuilderStepper primitive yet (PRD §19.1 lists "Builder stepper" as a design-system component to create). S18/S19/S20 all need it — build it once as components/ui/builder-stepper.tsx and share. (Cross-screen dependency — flag to the Skill Builder & Automation Builder cards.)
• Model picker: reuse components/os/ModelSelector.tsx (already used by Spawn/Settings/onboarding) instead of SpawnAgentDialog's bespoke model-button grid (SpawnAgentDialog.tsx:328-344).
• Persona picker: reuse the persona grid pattern from SpawnAgentDialog.tsx:258-276 + PERSONAS from @/lib/personas; or fetch live via adapter.getPersonas() (as AgentsApp.tsx:36).
• Tool picker: reuse the searchable checkbox list from CreateAgentForm.tsx:104-145 (tools sourced from adapter.getCapabilityStatus() → flattened ToolDef[], AgentsApp.tsx:49-55).
• Skills/connectors/MCPs pickers: adapter.getSkills(), adapter.getConnectors(), and MCP list (see §5 — MCP list endpoint is itself partial). Persona's suggestedSkills/suggestedConnectors/suggestedMcpServers (05a :216-218) can pre-seed recommendations.
• Cost-estimate review pane: lift from SpawnAgentDialog.tsx:388-421 (adapter.getModelPricing()).
• Approval prompt: reuse the approvals pattern (ApprovalsApp / inline chat approvals) for the elevated-access gate; do not invent a new modal.

Adapter methods to add (apps/web/src/lib/adapter.ts — the single sidecar gateway, ~150 methods): getAgents(), createAgent(def), getAgent(id), patchAgent(id, partial), runAgent(id, {task?}), pauseAgent(id), getAgentTraces(id). (Today the adapter has getPersonas/createPersona/…, spawnAgent, getFleet/fleetAction, getAgentGroups/… — none of these is the PRD Agent CRUD.)

Wiring: register the builder open path through the existing waggle:open-app CustomEvent / overlay state (useOverlayState); add it as a "New Agent" entry in the Agents app (which should be renamed/retitled from "Personas" to host both — Agent Center card decides final IA). Reuse SpawnAgentDialog as the quick "run now without saving" path — keep it; it is a different verb (ephemeral spawn) from the builder (persisted definition).

---

5. Backend work (PRD §16.7 endpoints)

Naming collision (backend-routes inventory :486-492): the Cloud server has a Clerk-gated routes/agents.ts with /api/agents CRUD — but that is NOT the sidecar. The desktop frontend talks only to the local sidecar, where the sidecar agent surface is /api/agent/* (singular) + /api/agents/active + /api/agent-groups/* + /api/fleet/*. So in the desktop context every §16.7 row below is MISSING-or-PARTIAL locally.

PRD §16.7 endpoint	Status (sidecar)	Extend vs net-new + substrate
GET /api/agents	MISSING	Net-new route. Reads a net-new agent-definition store. Closest existing "definitions": GET /api/personas (personas.ts:15) + GET /api/agent-groups (agent-groups.ts:49) — neither is the PRD Agent.
POST /api/agents	MISSING	Net-new. Pattern to reuse: agent-groups JSON-file persistence (agent-groups.ts:29-43, {dataDir}/agent-groups.json) → store agents at {dataDir}/agents.json (no SQLite, mirrors persona/group precedent). Validate goal/model/memoryScopes/autonomy/permissions. PRO-tier gate like personas.ts:32.
GET /api/agents/:id	MISSING	Net-new read over the new store.
PATCH /api/agents/:id	MISSING	Net-new partial-update (mirror agent-groups.ts:74-90 PATCH shape).
POST /api/agents/:id/run	PARTIAL	Extend, do not build new execution. Resolve agent → call the real executor POST /api/fleet/spawn (fleet.ts:66, the only path that actually runs runAgentLoop :185). Map agent's persona/model/memoryScope/workspace onto the spawn body. (/api/agent-groups/:id/run is a stub — agent-groups.ts:105 — do NOT reuse it as the model.)
POST /api/agents/:id/pause	PARTIAL	Extend. Map agent's running session → POST /api/fleet/:workspaceId/pause (fleet.ts:260).
GET /api/agents/:id/traces	PARTIAL / net-new route	No HTTP route reads traces today. The execution_traces table exists (schema.ts:199) and is written by chat.ts/evolution.ts. Add a thin read route over the execution-trace store, filtered by agent/session. Fallback: session timeline GET /api/workspaces/:wid/sessions/:sid/timeline (sessions.ts).

Substrate touched: new {dataDir}/agents.json (file store — no DB migration); personas.ts (read for persona field); fleet.ts (run/pause delegation); execution_traces (read for traces); install_audit (write an audit entry on agent create when elevated connectors/MCPs are attached — InstallAuditStore, see §d of the substrate inventory; note the risk_level='critical' CHECK-constraint drift bug flagged there install-audit.ts:16 vs DDL :65).

.mind migration: NONE required. The agent definition lives in a JSON file (precedent: persona disk store + agent-groups.json), not in SQLite. lastRunAt/successRate are derived (successRate from execution_traces.outcome / procedures.success_rate schema.ts:147,206), not new columns. This matches the LOCKED in-place model and the backend-routes inventory verdict ("none require a new data store").

---

6. Shared types needed (PRD §15 vs lib/types.ts)

Per substrate inventory §(e): none of the PRD §15.2 unions exist in apps/web/src/lib/types.ts. S18 needs:

• AgentType = 'personal' | 'workspace' | 'team' | 'autonomous' (PRD §15.2) — MISSING.
• AutonomyLevel = 'manual' | 'guided' | 'medium' | 'high' (PRD §15.2) — MISSING in FE (note: a different AutonomyLevel exists in hooks/useWindowManager.ts for chat windows — Normal/Trusted/YOLO; do not reuse, they are different vocabularies — flag the collision).
• Scope = 'personal' | 'workspace' | 'team' | 'organization' (for memoryScopes) — MISSING.
• A full Agent interface (PRD §15.5 fields) — MISSING. Today packages/shared/src/types.ts has a thin AgentDef (:36-47: id/userId/teamId/name/role/systemPrompt/model/tools/config/createdAt) lacking goal/type/autonomy/memoryScopes/skillIds/connectorIds/mcpIds/permissions/status/lastRunAt/successRate. Decide: extend AgentDef (shared, cloud-aligned) vs add a desktop-local Agent in lib/types.ts. Given the sidecar-only execution model, a new Agent interface in lib/types.ts + a matching server-side type is cleanest; keep AgentDef for the cloud path.
• ExtensionType (for the connector/mcp/skill pickers' provenance) — MISSING but shared with S19/S21.

Keep types consistent with the new agents.json shape (PRD §22.2 "Frontend types are consistent with API contracts").

---

7. Dependencies (screens / phases first)

• Phase 3 (Intelligence layer) per PRD §8 / Sprint 6 — same phase as Agent Center (S9), Skill Builder (S19), Automation Builder (S20).
• Agent Center (Screen 9) — the builder's create result must land somewhere; the Agent Center list/card view + the new Agent type + GET /api/agents are a shared prerequisite. Sequence: define Agent type + agent store + GET/POST /api/agents with Agent Center, then layer the builder on top.
• Shared BuilderStepper primitive (PRD §19.1) — build once, shared by S18/S19/S20. Whichever builder ships first owns it.
• Connector Hub (S?) / MCP Hub (S?) — the Permissions step picks connectorIds/mcpIds; the MCP listing is itself PARTIAL (no GET /api/mcps; data lives in capabilities/status.mcpServers[] + @waggle/shared mcp-catalog.ts). The picker can read those existing surfaces without waiting for the full Hubs, but the canonical MCP list endpoint is a cross-card dependency.
• Approval prompt component (PRD §19.1) — reuse existing approvals plumbing; not a hard blocker.
• AppShell / IA (Phase 0/1) — the builder opens via the existing window-manager overlay path; no new routing (single-route windowed desktop, per frontend inventory §b).

---

8. Effort: L

Net-new 5-step builder UI + net-new Agent entity, store, and CRUD routes, plus run/pause delegation onto fleet and a net-new traces read route — but every backend piece reuses an existing substrate (persona catalog, agent-groups JSON-file precedent, fleet-spawn executor, execution-traces store; no .mind migration). The heavy reuse and absence of a DB migration keep it off XL; the breadth (4 new + 3 partial endpoints, a new shared entity/type, a shared stepper primitive, and the elevated-access approval gate) keeps it above M.

---

9. Open questions

1. Agent vs persona boundary. Confirm the model: persona = behavioral template (one field of an agent) vs agent = scoped governed instance. This card assumes that split. Should creating an agent ever auto-create a backing persona, or always reference one?
2. Store location. {dataDir}/agents.json (mirrors agent-groups.json) vs a new agents row in personal .mind. This card recommends the JSON file (no migration, matches precedent). Confirm.
3. /run semantics. Does Agent Builder's eventual run mean "fleet-spawn a one-shot in a chosen workspace" (current real path) or "persistent agent that keeps running"? PRD agent states include Running/Paused/Completed (§14.5) — confirm the lifecycle the sidecar must support beyond fleet's ephemeral sessions.
4. Test step. Blueprint says "configure, test, review, create" (:413); PRD §12.9 omits test. Include a dry-run (like Skill Builder's POST /api/skills/:id/test) or defer?
5. successRate source. Derive from execution_traces.outcome vs procedures.success_rate vs a new counter? (Both exist; pick one to avoid a third tally vocabulary.)
6. Autonomy vocabulary collision. PRD AutonomyLevel (manual/guided/medium/high) vs the chat-window AutonomyLevel (Normal/Trusted/YOLO in useWindowManager.ts) vs the agent-loop's tiered-autonomy. Which governs an agent's tool execution at run time?
7. Cloud vs sidecar /api/agents. The Cloud server already has Clerk-gated /api/agents CRUD. Should the desktop sidecar's new routes share a contract/shape with it for future sync, or stay independent?