118 lines
8.7 KiB
Markdown
118 lines
8.7 KiB
Markdown
|
---
|
||
|
|
name: ai-agent-studio
|
||
|
|
classification: feature
|
||
|
|
success_metric: The existing AI rail destination provides accessible Chat and Agents modes, versioned agent foundations, and a provider-agnostic service that streams validated agent draft proposals.
|
||
|
|
skip: []
|
||
|
|
status: in-progress
|
||
|
|
created: 2026-09-25
|
||
|
|
model_policy:
|
||
|
|
roles:
|
||
|
|
role-conductor: claude-planning
|
||
|
|
role-architect: claude-planning
|
||
|
|
role-implementer: qwen-coder
|
||
|
|
role-reviewer: qwen-coder
|
||
|
|
escalate_to: claude-planning
|
||
|
|
---
|
||
|
|
|
||
|
|
# AI agent studio and marketplace
|
||
|
|
|
||
|
|
## Why
|
||
|
|
|
||
|
|
The existing AI rail destination is already the natural home for AI interaction, but it currently provides only one stateless full-page chat. Users should be able to chat with AI or switch modes and use AI itself to create, review, install, and manage reusable agents. This should feel like one coherent AI workspace rather than separate Chat, Settings, and marketplace products.
|
||
|
|
|
||
|
|
Canonical backlog: `plans/Plan-workspace-communications/Epic-agent-participation/Epic-agent-participation.md`.
|
||
|
|
|
||
|
|
## Scope
|
||
|
|
|
||
|
|
- Brief 1: refactor `/<workspaceSlug>/ai` into URL-backed Chat and Agents tabs with one shared composer shell.
|
||
|
|
- Brief 2: add first-class, versioned agent persistence and shared validation/permission contracts.
|
||
|
|
- Brief 3: turn Agents-mode prompts into validated clarification and structured draft-patch events; it does not implement the editor or persistence.
|
||
|
|
- Follow-on backlog tasks add the builder editor/private-draft persistence, marketplace library UI, permission review/sandbox/activation, durable jobs, direct saved-agent chat, channel membership, harness events, and chat delivery.
|
||
|
|
- Preserve the existing Sparkles `AI` rail entry; do not add a separate Agents rail item.
|
||
|
|
- Reuse model routing, harness routing, template UI patterns, and workspace authorization without conflating those records with agent identity.
|
||
|
|
|
||
|
|
Out of scope: channel participation/jobs, commercial marketplace billing/ratings, arbitrary public publishing, and autonomous channel access. Those follow after the agent registry exists.
|
||
|
|
|
||
|
|
## Role activity and kickoff — 2026-10-22
|
||
|
|
|
||
|
|
- User approved beginning the integrated chat/agent direction, not merge or release.
|
||
|
|
- This session performed conductor reconciliation and architect access/registry/dependency review. Existing IA/UX/architecture sections are design guidance, not evidence of historical role completion; independent IA, UX and reviewer completion is not asserted.
|
||
|
|
- Brief 1 and its canonical task are `in_progress`: an independent implementer owns the AI shell app changes. This planning session changes no app code. Brief 2 is ready; Brief 3 waits for its dependencies.
|
||
|
|
- `in-progress` is local README bookkeeping for the active brief. No DB registration, task claim, event logging or MCP transition occurred; those tools are unavailable here.
|
||
|
|
|
||
|
|
## Full product versus this foundation
|
||
|
|
|
||
|
|
These three briefs provide a shell, schema/contracts, and inert builder service—not a working marketplace, install API, contextual chat or agent execution. The [registry API task](../plans/Plan-workspace-communications/Epic-agent-participation/Task-agent-registry-api.md) and [install/lifecycle task](../plans/Plan-workspace-communications/Epic-agent-participation/Task-agent-install-lifecycle.md) now explicitly own the missing server boundaries. Library/editor/review tasks consume them rather than creating duplicate registries or lifecycle endpoints.
|
||
|
|
|
||
|
|
AI Chat, Agents creation/library, channel mentions and durable jobs use **one workspace agent registry**. Installation/activation does not grant conversation access. Follow the [plan's context and mention-to-add contracts](../plans/Plan-workspace-communications/Plan-workspace-communications.md): channel addition or expanded access needs authorized explicit confirmation, reviewed version/history/tool scope, idempotency, and revocation checks; workspace role alone cannot grant private-object access.
|
||
|
|
|
||
|
|
## Todos
|
||
|
|
|
||
|
|
- [x] User approved kickoff of the AI Chat/Agents direction on 2026-10-22; merge/release gates remain pending.
|
||
|
|
- [ ] Implement the Chat/Agents shell without regressing existing AI chat.
|
||
|
|
- [ ] Implement versioned agent persistence and shared registry contracts.
|
||
|
|
- [ ] Implement provider-agnostic conversational clarification and validated structured draft-patch streaming.
|
||
|
|
- [ ] Reviewer validates tenant isolation, permission safety, provider agnosticism, accessibility, and spec alignment.
|
||
|
|
- [ ] Human performs merge and release gates.
|
||
|
|
|
||
|
|
## IA
|
||
|
|
|
||
|
|
- Keep `/<workspaceSlug>/ai` as the canonical route and Sparkles rail destination.
|
||
|
|
- Use URL-backed top-level tabs: `Chat` and `Agents`; Chat remains the default for old links.
|
||
|
|
- The shared composer stays centered and visually stable across modes.
|
||
|
|
- Chat preserves current conversation behavior; saved-agent selection arrives in the direct-agent-chat follow-on, not the shell brief.
|
||
|
|
- Agents renders scaffolded library regions under/around the composer; the follow-on marketplace task populates Featured/Templates, Installed, Created by your workspace, and Drafts.
|
||
|
|
- This convoy provides placeholders for future agent cards/detail actions and focuses `Create new` on the builder composer.
|
||
|
|
- Brief 3 exposes testable builder service events; the follow-on editor wires them into Agents mode and turns them into editable, persisted drafts.
|
||
|
|
|
||
|
|
## UX
|
||
|
|
|
||
|
|
- Switching tabs changes intent, placeholder, suggestions, submit label, and result content—not the fundamental composer size or interaction language.
|
||
|
|
- Agents-mode examples include outcome-oriented prompts rather than raw configuration fields.
|
||
|
|
- Validated builder events expose what the proposed agent could read, requested tools, invocation policy, budget, and requested model role/harness route; the follow-on editor presents the full review experience.
|
||
|
|
- Draft proposal generation never persists, activates, publishes, grants tools, or joins channels automatically.
|
||
|
|
- Marketplace lifecycle/provenance visuals are owned by the follow-on library task; this convoy reserves compatible states in the shell.
|
||
|
|
- Keyboard focus survives tab switches where sensible; tabs, cards, dialogs, draft fields, and permission review are accessible.
|
||
|
|
|
||
|
|
## Architecture
|
||
|
|
|
||
|
|
### Product boundaries
|
||
|
|
|
||
|
|
- An agent definition is a stable service identity and versioned policy bundle.
|
||
|
|
- A role is a requested capability used by model/harness routing; it is not an agent identity.
|
||
|
|
- A model provider or OmniRoute profile performs/routes inference; it is not an agent.
|
||
|
|
- A harness executes a run; it is not an agent.
|
||
|
|
- An `agent_run` is execution history and references the pinned agent version where applicable.
|
||
|
|
|
||
|
|
### Builder flow
|
||
|
|
|
||
|
|
1. The Agents tab submits a workspace-authorized builder request through a dedicated typed streaming endpoint, not the normal chat endpoint.
|
||
|
|
2. The builder resolves a model role through existing routing and returns validated clarification or structured draft-patch events.
|
||
|
|
3. This convoy stops at the typed event stream; it does not edit or persist drafts.
|
||
|
|
4. A follow-on editor consumes those events and saves private draft versions owned by the current member.
|
||
|
|
5. A later review flow handles permission approval, sandbox tests, install, activation, and workspace publication.
|
||
|
|
|
||
|
|
### Marketplace model
|
||
|
|
|
||
|
|
- Schemas/contracts support global curated templates that are readable but not tenant-owned; catalog seeding and browse APIs are follow-on work.
|
||
|
|
- Workspace agents/installations, drafts, permissions, and versions are always scoped by `workspace_id`.
|
||
|
|
- Installation contracts require workspace-owned versioned configuration and prohibit copying secrets.
|
||
|
|
- First release supports curated templates and workspace sharing, not open public submissions, ratings, or payments.
|
||
|
|
|
||
|
|
### Security
|
||
|
|
|
||
|
|
- Generated output is untrusted and must pass zod validation plus server-side policy checks.
|
||
|
|
- Tool grants, channel access, budgets, and activation are never inferred as silent side effects.
|
||
|
|
- Provider credentials remain referenced through existing provider configuration and are never embedded in an agent definition or prompt transcript.
|
||
|
|
- Agent handles are unique per workspace; immutable IDs/version IDs drive references and audit history.
|
||
|
|
|
||
|
|
## Briefs
|
||
|
|
|
||
|
|
| Brief | Backlog task | Depends on |
|
||
|
|
| --- | --- | --- |
|
||
|
|
| 1 | `Task-ai-workspace-tabs.md` | none |
|
||
|
|
| 2 | `Task-agent-registry-marketplace.md` | none; may proceed in parallel with brief 1 |
|
||
|
|
| 3 | `Task-ai-assisted-agent-builder.md` | briefs 1 and 2 |
|
||
|
|
|
||
|
|
Follow-on scheduling: registry API → install/lifecycle → library and editor/review UI; durable jobs → direct-chat and reviewed channel membership; normalized harness → sandbox execution and run delivery. UI-only review scaffolding can precede the harness, but sandbox execution cannot. Contextual channel integration additionally waits for a verified object access policy. These are canonical backlog dependencies, not extra deliverables of the three foundation briefs.
|