{"key":"haip_webui_agent_create_edit_handoff_2026_04_05","title":"HAIP Web UI Handoff — Add Create/Edit Agent Management","content":"Detailed implementation handoff for a follow-on coding model, specifically targeted at a smaller local coding model such as Qwen2.5-Coder 9B. Goal: add Create Agent and Edit Agent functionality to the HAIP Web Control UI without breaking the existing deployed service.\n\nContext\n- Deployable HAIP Web UI lives at `/home/svc-admin/appstack/haip-ui` on `svc-apps`.\n- The architecture repo at `/home/svc-admin/ai-projects/projects/homelab_ai_platform_architecture` is read-only reference only and must not be modified.\n- Live UI URL: `http://192.168.4.114:3010`\n- Stack: FastAPI + Jinja2 + direct PostgreSQL access.\n- Existing UI already supports rooms, room detail, roster management, room creation, preset loading, sessions, agent catalog, memory inspection, health, and invocations.\n- The `/agents` page currently appears to be read-only/listing oriented. The next slice is to add agent creation and editing in the Web UI.\n\nImportant scope\n- Do not redesign the UI broadly.\n- Preserve the existing visual language and route structure in `/home/svc-admin/appstack/haip-ui/app`.\n- Add a create-agent workflow and an edit-agent workflow.\n- Do not modify architecture docs.\n- Keep the implementation straightforward and low-risk.\n\nRelevant codebase locations\n- Main app entry: `/home/svc-admin/appstack/haip-ui/app/main.py`\n- Existing agents router: likely under `/home/svc-admin/appstack/haip-ui/app/routers/agents.py`\n- Templates: `/home/svc-admin/appstack/haip-ui/app/templates/agents/`\n- Shared DB helpers / connection code: inspect `/home/svc-admin/appstack/haip-ui/app` for whichever module currently handles DB access.\n- Existing rooms CRUD patterns are the best template for new POST form handlers. Compare with room creation and preset load handlers in the rooms router.\n\nLive HAIP database facts\nDatabase connection details are already wired into the deployed UI environment. Reuse the existing UI service DB config pattern; do not invent a second DB config path.\n\nThe `agents` table shape in the live HAIP database is:\n- `id bigint primary key`\n- `agent_key text unique not null`\n- `display_name text not null`\n- `nick text not null`\n- `provider_family_id bigint not null`\n- `persona_id bigint not null`\n- `runtime_adapter_key text not null`\n- `private_memory_namespace text not null`\n- `default_response_policy text not null`\n- `default_cooldown_policy text not null`\n- `enabled boolean not null default true`\n- `created_at timestamptz not null`\n- `updated_at timestamptz not null`\n\nRelated tables that matter for create/edit flows\n- `provider_families`\n- `personas`\n- `agent_aliases`\n- `memory_namespaces`\n- `room_roster_memberships` (editing an agent should not automatically change room membership)\n\nCurrent live provider families known in HAIP\n- `codex_cli`\n- `claude_cli`\n- `gemini_cli`\n- `opencode_cli`\n\nCurrent known enabled agents include examples such as:\n- `arena-builder`\n- `arena-skeptic`\n- `arena-synthesizer`\n- `claude`\n- `codex`\n- `gemini`\n- `opencode`\n- multiple Genealogy / Ohio History / Stoned agents\n\nExpected behavior to add\n1. `/agents` page should include a Create Agent form.\n2. Add an agent detail or edit page, likely `/agents/{agent_key}` or `/agents/{agent_id}`.\n3. Support editing at least these fields:\n- `display_name`\n- `nick`\n- `provider_family_id`\n- `persona_id`\n- `runtime_adapter_key`\n- `private_memory_namespace`\n- `default_response_policy`\n- `default_cooldown_policy`\n- `enabled`\n4. Creation should require at minimum:\n- `agent_key`\n- `display_name`\n- `nick`\n- `provider_family_id`\n- `persona_id`\n- `runtime_adapter_key`\n- `private_memory_namespace`\n- `default_response_policy`\n- `default_cooldown_policy`\n5. Do not automatically create room memberships when creating an agent.\n6. Do not automatically create aliases unless you intentionally add a small alias input section.\n7. If persona creation is not already exposed in the UI, assume personas are selected from existing rows only.\n\nRecommended minimal implementation approach\nPhase 1: Create + Edit existing agents using existing personas and provider families.\n- This is the correct first slice.\n- Do not try to add persona CRUD in the same pass.\n- Do not try to add alias management unless it is trivial.\n\nUI recommendations\n- On `/agents`, add a compact create form above or beside the existing list.\n- Add an `Edit` link/button per agent row.\n- Create an agent detail/edit template with a standard HTML form.\n- Use server-rendered forms and redirects, matching the current rooms workflow style.\n- Show validation errors clearly but simply.\n\nRouting recommendations\nAdd or extend routes in the agents router along these lines:\n- `GET /agents` -> existing listing page, now also loads form select options\n- `POST /agents/create` -> create a new agent, then redirect to `/agents/{agent_key}` or `/agents`\n- `GET /agents/{agent_key}` -> render edit page for a single agent\n- `POST /agents/{agent_key}/update` -> update the agent, then redirect back to detail page\n\nData-loading required for forms\nFor both create and edit forms, load:\n- provider families: id + provider_key + display label if available\n- personas: id + persona_key or display title/name if present\n\nImportant caution: inspect the live `personas` schema before rendering labels.\nDo not assume exact persona columns until confirmed in the code or DB.\nUse the same DB inspection/query style already used elsewhere in the UI.\n\nValidation rules\n- `agent_key` should be unique and stable; reject duplicates.\n- `nick` should be unique enough for IRC use; at minimum, reject exact duplicates already in `agents.nick`.\n- `runtime_adapter_key` should be consistent with the selected provider family.\n- `private_memory_namespace` should not be empty.\n- `default_response_policy` and `default_cooldown_policy` should not be empty.\n- `enabled` should map cleanly from checkbox -> boolean.\n\nLow-risk handling for `runtime_adapter_key`\nBecause this is a local-model handoff, prefer a simple rule:\n- When creating a new agent, default `runtime_adapter_key` to the selected provider family’s `provider_key` if that matches current HAIP conventions.\n- But first inspect current live agent rows and existing UI data loading to confirm how runtime adapter keys are represented.\n- If the existing UI already knows the correct adapter keys, reuse that exact source.\n- Do not hardcode a complicated mapping unless necessary.\n\nWhat to inspect before coding\n1. `/home/svc-admin/appstack/haip-ui/app/routers/agents.py`\n2. `/home/svc-admin/appstack/haip-ui/app/templates/agents/`\n3. existing DB helper functions used by rooms and presets\n4. live DB schema for `personas` and `provider_families`\n5. how existing forms are posted and redirected in rooms routes\n\nRecommended SQL shape\nAgent list query should likely include joins for readability:\n- `agents a`\n- `provider_families pf on pf.id = a.provider_family_id`\n- `personas p on p.id = a.persona_id`\n\nSuggested create query:\n- `INSERT INTO agents (...) VALUES (...) RETURNING id, agent_key`\n\nSuggested update query:\n- `UPDATE agents SET ... , updated_at = CURRENT_TIMESTAMP WHERE agent_key = $1`\n\nSuggested uniqueness checks before write:\n- `SELECT 1 FROM agents WHERE agent_key = $1`\n- `SELECT 1 FROM agents WHERE nick = $1 AND agent_key <> $2`\n\nSafer field strategy for smaller models\nBecause Qwen2.5-Coder 9B is smaller, keep the work narrow:\n- build create/edit around core fields only\n- avoid fancy abstractions\n- prefer explicit SQL in the router if the codebase already does that elsewhere\n- reuse template patterns from rooms rather than inventing a new form framework\n\nTesting / verification checklist\nAfter implementing:\n1. restart or rebuild the HAIP UI service on `svc-apps`\n2. confirm these endpoints return `200`:\n- `/agents`\n- new agent detail/edit route\n3. create a non-destructive test agent in the UI\n4. verify it appears on `/agents`\n5. edit one safe field such as `display_name` or `enabled`\n6. verify the update persists in the DB and in the UI\n7. if the test agent is only for validation, delete it manually via SQL only if a delete UI was not added\n8. ensure existing `/rooms`, `/presets`, `/sessions`, `/memory`, `/health`, `/invocations` still return `200`\n\nOperational constraints\n- The HAIP IRC gateway is now live and roster-driven. New agents should not appear in IRC rooms unless explicitly added to room rosters.\n- Do not break existing rooms, rosters, or provider-family sync behavior.\n- The service is already deployed live, so treat this as an in-place enhancement to an active app.\n\nDefinition of done\n- Operator can create a new agent from the Web UI.\n- Operator can open an existing agent and edit its core fields from the Web UI.\n- Provider family and persona are selected from live DB-backed lists.\n- Validation prevents duplicate `agent_key` and duplicate `nick`.\n- Changes persist correctly in PostgreSQL.\n- Existing pages remain functional.\n\nNice-to-have but not required in first pass\n- alias management\n- persona preview on edit page\n- delete/deactivate workflow beyond `enabled=false`\n- inline success/error flash messaging if current UI does not already have a pattern\n\nFinal implementation advice for the next model\n- Do not over-engineer.\n- Follow the rooms CRUD style already in this codebase.\n- Reuse server-rendered forms and redirects.\n- Verify schema before assuming persona/provider field names.\n- Keep the patch small, explicit, and easy to review.","summary":"Detailed implementation handoff for a follow-on coding model, specifically targeted at a smaller local coding model such as Qwen2.5-Coder 9B. Goal: add Create Agent and Edit Agent functionality to the HAIP Web Control UI without breaking the existing deployed service.\n\nContext\n- Deployable HAIP Web UI lives at `/home/svc-admin/appstack/haip-ui` on `svc-apps`.\n- The architecture repo at `/home/svc-admin/ai-projects/projects/homelab_ai_platform_architecture` is read-only reference only and must not be modified.\n- Live UI URL: `http://192.168.4.114:3010`\n- Stack: FastAPI + Jinja2 + direct PostgreSQL access.\n- Existing UI already supports rooms, room detail, roster management, room creation, preset loading, sessions, agent catalog, memory inspection, health, and invocations.\n- The `/agents` page currently appears to be read-only/listing oriented. The next slice is to add agent creation and editing in the Web UI.\n\nImportant scope\n- Do not redesign the UI broadly.\n- Preserve the existing visual language and route structure in `/home/svc-admin/appstack/haip-ui/app`.\n- Add a create-agent workflow and an edit-agent workflow.\n- Do not modify architecture docs.\n- Keep the implementation straightforward and low-risk.\n\nRelevant codebase locations\n- Main app entry: `/home/svc-admin/appstack/haip-ui/app/main.py`\n- Existing agents router: likely under `/home/svc-admin/appstack/haip-ui/app/routers/agents.py`\n- Templates: `/home/svc-admin/appstack/haip-ui/app/templates/agents/`\n- Shared DB helpers / connection code: inspect `/home/svc-admin/appstack/haip-ui/app` for whichever module currently handles DB access.\n- Existing rooms CRUD patterns are the best template for new POST form handlers. Compare with room creation and preset load handlers in the rooms router.\n\nLive HAIP database facts\nDatabase connection details are already wired into the deployed UI environment. Reuse the existing UI service DB config pattern; do not invent a second DB config path.\n\nThe `agents` table shape in the live HAIP database is:\n- `id bigint primary key`\n- `agent_key text unique not null`\n- `display_name text not null`\n- `nick text not null`\n- `provider_family_id bigint not null`\n- `persona_id bigint not null`\n- `runtime_adapter_key text not null`\n- `private_memory_namespace text not null`\n- `default_response_policy text not null`\n- `default_cooldown_policy text not null`\n- `enabled boolean not null default true`\n- `created_at timestamptz not null`\n- `updated_at timestamptz not null`\n\nRelated tables that matter for create/edit flows\n- `provider_families`\n- `personas`\n- `agent_aliases`\n- `memory_namespaces`\n- `room_roster_memberships` (editing an agent should not automatically change room membership)\n\nCurrent live provider families known in HAIP\n- `codex_cli`\n- `claude_cli`\n- `gemini_cli`\n- `opencode_cli`\n\nCurrent known enabled agents include examples such as:\n- `arena-builder`\n- `arena-skeptic`\n- `arena-synthesizer`\n- `claude`\n- `codex`\n- `gemini`\n- `opencode`\n- multiple Genealogy / Ohio History / Stoned agents\n\nExpected behavior to add\n1. `/agents` page should include a Create Agent form.\n2. Add an agent detail or edit page, likely `/agents/{agent_key}` or `/agents/{agent_id}`.\n3. Support editing at least these fields:\n- `display_name`\n- `nick`\n- `provider_family_id`\n- `persona_id`\n- `runtime_adapter_key`\n- `private_memory_namespace`\n- `default_response_policy`\n- `default_cooldown_policy`\n- `enabled`\n4. Creation should require at minimum:\n- `agent_key`\n- `display_name`\n- `nick`\n- `provider_family_id`\n- `persona_id`\n- `runtime_adapter_key`\n- `private_memory_namespace`\n- `default_response_policy`\n- `default_cooldown_policy`\n5. Do not automatically create room memberships when creating an agent.\n6. Do not automatically create aliases unless you intentionally add a small alias input section.\n7. If persona creation is not already exposed in the UI, assume personas are selected from existing rows only.\n\nRecommended minimal implementation approach\nPhase 1: Create + Edit existing agents using existing personas and provider families.\n- This is the correct first slice.\n- Do not try to add persona CRUD in the same pass.\n- Do not try to add alias management unless it is trivial.\n\nUI recommendations\n- On `/agents`, add a compact create form above or beside the existing list.\n- Add an `Edit` link/button per agent row.\n- Create an agent detail/edit template with a standard HTML form.\n- Use server-rendered forms and redirects, matching the current rooms workflow style.\n- Show validation errors clearly but simply.\n\nRouting recommendations\nAdd or extend routes in the agents router along these lines:\n- `GET /agents` -> existing listing page, now also loads form select options\n- `POST /agents/create` -> create a new agent, then redirect to `/agents/{agent_key}` or `/agents`\n- `GET /agents/{agent_key}` -> render edit page for a single agent\n- `POST /agents/{agent_key}/update` -> update the agent, then redirect back to detail page\n\nData-loading required for forms\nFor both create and edit forms, load:\n- provider families: id + provider_key + display label if available\n- personas: id + persona_key or display title/name if present\n\nImportant caution: inspect the live `personas` schema before rendering labels.\nDo not assume exact persona columns until confirmed in the code or DB.\nUse the same DB inspection/query style already used elsewhere in the UI.\n\nValidation rules\n- `agent_key` should be unique and stable; reject duplicates.\n- `nick` should be unique enough for IRC use; at minimum, reject exact duplicates already in `agents.nick`.\n- `runtime_adapter_key` should be consistent with the selected provider family.\n- `private_memory_namespace` should not be empty.\n- `default_response_policy` and `default_cooldown_policy` should not be empty.\n- `enabled` should map cleanly from checkbox -> boolean.\n\nLow-risk handling for `runtime_adapter_key`\nBecause this is a local-model handoff, prefer a simple rule:\n- When creating a new agent, default `runtime_adapter_key` to the selected provider family’s `provider_key` if that matches current HAIP conventions.\n- But first inspect current live agent rows and existing UI data loading to confirm how runtime adapter keys are represented.\n- If the existing UI already knows the correct adapter keys, reuse that exact source.\n- Do not hardcode a complicated mapping unless necessary.\n\nWhat to inspect before coding\n1. `/home/svc-admin/appstack/haip-ui/app/routers/agents.py`\n2. `/home/svc-admin/appstack/haip-ui/app/templates/agents/`\n3. existing DB helper functions used by rooms and presets\n4. live DB schema for `personas` and `provider_families`\n5. how existing forms are posted and redirected in rooms routes\n\nRecommended SQL shape\nAgent list query should likely include joins for readability:\n- `agents a`\n- `provider_families pf on pf.id = a.provider_family_id`\n- `personas p on p.id = a.persona_id`\n\nSuggested create query:\n- `INSERT INTO agents (...) VALUES (...) RETURNING id, agent_key`\n\nSuggested update query:\n- `UPDATE agents SET ... , updated_at = CURRENT_TIMESTAMP WHERE agent_key = $1`\n\nSuggested uniqueness checks before write:\n- `SELECT 1 FROM agents WHERE agent_key = $1`\n- `SELECT 1 FROM agents WHERE nick = $1 AND agent_key <> $2`\n\nSafer field strategy for smaller models\nBecause Qwen2.5-Coder 9B is smaller, keep the work narrow:\n- build create/edit around core fields only\n- avoid fancy abstractions\n- prefer explicit SQL in the router if the codebase already does that elsewhere\n- reuse template patterns from rooms rather than inventing a new form framework\n\nTesting / verification checklist\nAfter implementing:\n1. restart or rebuild the HAIP UI service on `svc-apps`\n2. confirm these endpoints return `200`:\n- `/agents`\n- new agent detail/edit route\n3. create a non-destructive test agent in the UI\n4. verify it appears on `/agents`\n5. edit one safe field such as `display_name` or `enabled`\n6. verify the update persists in the DB and in the UI\n7. if the test agent is only for validation, delete it manually via SQL only if a delete UI was not added\n8. ensure existing `/rooms`, `/presets`, `/sessions`, `/memory`, `/health`, `/invocations` still return `200`\n\nOperational constraints\n- The HAIP IRC gateway is now live and roster-driven. New agents should not appear in IRC rooms unless explicitly added to room rosters.\n- Do not break existing rooms, rosters, or provider-family sync behavior.\n- The service is already deployed live, so treat this as an in-place enhancement to an active app.\n\nDefinition of done\n- Operator can create a new agent from the Web UI.\n- Operator can open an existing agent and edit its core fields from the Web UI.\n- Provider family and persona are selected from live DB-backed lists.\n- Validation prevents duplicate `agent_key` and duplicate `nick`.\n- Changes persist correctly in PostgreSQL.\n- Existing pages remain functional.\n\nNice-to-have but not required in first pass\n- alias management\n- persona preview on edit page\n- delete/deactivate workflow beyond `enabled=false`\n- inline success/error flash messaging if current UI does not already have a pattern\n\nFinal implementation advice for the next model\n- Do not over-engineer.\n- Follow the rooms CRUD style already in this codebase.\n- Reuse server-rendered forms and redirects.\n- Verify schema before assuming persona/provider field names.\n- Keep the patch small, explicit, and easy to review.","status":"active","namespace":"shared:platform","namespace_name":"shared","namespace_tier":"platform","tags":[]}