Aetherin Agent Studio — product blueprint
This document is the buildable specification for Aetherin Agent Studio ("the Studio"). It defines what the product is, how it differs from the separate aetherin-agent product, its scope, its surfaces and pages, its domain data model, and how it maps onto the shared contract (aetherin-stack/common/openapi.yaml, v0.2.0).
See also: `project-overview.md` (project-overview.md) for the ecosystem inventory, `roadmap.md` (roadmap.md) for the milestone plan, and `../README.md` for the vision.
1. Definition
Aetherin Agent Studio is a build-orchestration product: it turns a short brief, an optional Git repository, and uploaded assets into a planned, scaffolded, validated, and release-ready software project, driven by a coordinated team of specialized agents with explicit human approval gates.
The Studio is the orchestration layer that connects the other Aetherin surfaces (identity, models, tools, design, deployment) into one project lifecycle. It is not a chat product and not a model gateway; it composes them.
Stage: specification only. This repository is the canonical planning and product-spec layer. There is no deployed Studio runtime and no Studio entry in the platform surface registry yet. Registering the surface (see §4) is a prerequisite for shipping.
2. Agent Studio vs Aetherin Agent
The two products share a name stem and nothing else. Keeping them separate is a hard product boundary.
| Aetherin Agent | Aetherin Agent Studio | |
|---|---|---|
| Repo | AetherinLLM/aetherin-agent | AetherinLLM/aetherin-agent-studio (this repo) |
| Surface name / registry id | Agent / agent | none yet — proposed studio (see §4) |
| Host | agent.aetherin.app | proposed studio.aetherin.app |
| Registry status | live | not registered |
| Status board row | "Agent" | not listed (planning only) |
| Purpose | Revenue-focused chat agent with server-side tool calling | Brief → plan → scaffold → implement → validate → release orchestration |
| Primary user | Anyone chatting with Aetherin's assistant | Builders and teams turning an idea or a repo into a product |
| Shape | Single-page chat + /api/chat + /api/health | Multi-stage project workspace with agents, gates, and artifacts |
| Maturity | chat works end-to-end; single-page, no history/persistence | spec only |
| Depends on | Gateway/models, MCP hub tools | Gateway/models, MCP hub, Account center (identity/keys/usage), Agent (optional helper), Admin console, Portal, Design system, Preset studio, Plugins |
Consequences:
- Shipping the Studio does not modify the Agent surface; Agent work
(conversation persistence, streaming polish, MCP tool provider) is tracked separately on the status board.
- Where the Studio reuses chat capability, it calls the Gateway
(/v1/chat/completions) rather than embedding the Agent product.
- Naming in docs, issues, and registry entries must always disambiguate "Agent"
from "Agent Studio".
3. Scope
In scope
- Intake: brief, optional Git repo/branch, uploaded assets (images, designs,
specs, schemas), stack and deployment preferences.
- Context assembly: repo structure, design references, requirements, metrics,
environment needs, deployment targets.
- Planning: product spec, functional/technical architecture, milestones, tasks,
risk checks.
- Design: design direction, tokens, screens, interaction specs.
- Build: template scaffolding and phased implementation delivered on Git
branches as PRs, without overwriting protected work.
- Validation: orchestrated lint / build / test / audit gates.
- Release readiness: deploy targets, CI/CD setup, secrets handling, release
artifacts.
- Governance: explicit human approval gates, audit trail, visible artifacts.
Out of scope
- Acting as the model gateway (that is Gateway /
gateway-base). - Acting as the chat product (that is Agent).
- Owning billing rails or payment capture (that is Account center + Gateway
wallet).
- Owning platform operations (that is Admin console).
- Being a generic prompt playground or a no-code website builder.
4. Surfaces and pages
Surface names below are cross-checked against aetherin-portal/account/js/registry.js (canonical) and aetherin-stack/docs/stack-plan/docs/03-status.md. Only registry names are used for existing surfaces.
4.1 Surfaces the Studio consumes
| Surface | Registry id | Used by the Studio for |
|---|---|---|
| Account center | account | User identity/session, API keys, usage & billing, setup, org-admin self-service. |
| Gateway | gateway | Model list and OpenAI-compatible completions; provider routing and accounting. |
| MCP hub | mcp | Tool catalog (tools/list) and tool calls (tools/call) for agents. |
| Agent | agent | Optional helper surface; not modified by the Studio. |
| Preset studio | presets | Apply named setups (models, tools, agents) to a Studio project. |
| Plugins | plugins | Client entry points (TUI/IDE/web/mobile) into Studio-driven work. |
| Portal | portal | Front door, atlas, and setup finder that link into the Studio. |
| Admin console | admin | Platform operations view of Studio tenants, billing health, support. |
| Design system | design | Canonical tokens and components the Studio uses for generated UI. |
| Streamproof | streamproof | Budget-controlled model calls where predictability matters. |
4.2 Proposed Studio surface (not yet registered)
Proposed registry entry — must be added to registry.js and given a status board row in the same change that deploys it. Until then it is a proposal only.
- Registry id:
studio - Name: Agent Studio
- Host:
studio.aetherin.app(proposal) - Status:
planned
Proposed pages (hash-routed workspace, consistent with the Account center pattern):
| Path | Name | Functions |
|---|---|---|
/ | Projects | Project list, status, open/archive |
/#/new | New project | Brief intake, repo link, asset upload, stack/deploy prefs |
/#/projects/:id | Project overview | Summary, current stage, next gate |
/#/projects/:id/plan | Plan | Product spec, architecture, milestones, tasks |
/#/projects/:id/design | Design | Direction, tokens, screens, interaction specs |
/#/projects/:id/build | Build | Agent runs, branches, PRs, artifacts |
/#/projects/:id/validate | Validation | Lint/build/test/audit results, defects |
/#/projects/:id/release | Release | Deploy target, CI/CD, release artifacts, approvals |
/#/runs | Agent runs | Cross-project run log, status, token usage |
/#/artifacts | Artifacts | Plans, designs, code bundles, reports |
/api/* | Studio API | Server routes implementing the domain model (§6) |
5. Domain data model
Entities are split into contract-backed (already defined in aetherin-stack/common/openapi.yaml v0.2.0 and reused as-is) and Studio-defined (new; require a future contract revision, see §6). Field names follow the contract's snake_case convention.
5.1 Contract-backed entities (reused)
- User — `id, name, email, role {owner|admin|member|viewer}, plan
{free|payg|pro|business|enterprise}, status {active|suspended}, bio, created_at. The Studio project owner is a User.id`.
- Session —
user, token?, expires_in. Issued by/v1/account/*; the Studio
authenticates via the Account center session cookie.
- Key / KeyCreate / KeyWithSecret — `id, name, prefix, scopes, consumer,
created_at, revoked, last_used_at`. Studio integrations and CI use scoped keys.
- Model —
id, object, created, owned_by, enabled. Selectable per agent role. - ChatCompletionRequest —
model, messages, stream, temperature. The transport
for agent LLM calls.
- UsageSummary / ModelUsage / ProviderUsage / UsageDaily — token, request, and
failure accounting that backs the Studio's cost/usage views.
- Provider / ProviderPatch — `id, name, type, base_url, health, enabled,
model_mapping, metadata`. Routing metadata surfaced to operators.
- Error, HealthStatus — shared response shapes for the Studio API.
5.2 Studio-defined entities (proposed)
| Entity | Key fields | Notes |
|---|---|---|
| Project | id, owner_id (User.id), name, slug, status, repo_url, repo_provider, default_branch, created_at, updated_at | status ∈ {draft, intake, planning, designing, building, validating, releasing, shipped, archived}. |
| Brief | id, project_id, goal, audience, constraints[], success_metrics[], stack_prefs{}, deploy_target, created_at | One active brief per project revision. |
| ContextItem | id, project_id, kind, uri, mime, size, checksum, summary, created_at | kind ∈ {repo, file, image, design, spec, schema, url}. Uploaded assets and repo snapshots. |
| Plan | id, project_id, version, summary, status, approved_by (User.id), approved_at | Deterministic plan precedes implementation. |
| Milestone | id, plan_id, order, name, objective, status, due_at | Ordered deliverable groupings. |
| Task | id, milestone_id, role, status, depends_on[], artifact_ids[], pr_url | role references an AgentRole id. |
| AgentRole | id, name, description, tools[], model_tier, approval_policy | Internal roles (see §5.3). |
| AgentRun | id, project_id, task_id, role_id, status, model (Model.id), prompt_tokens, completion_tokens, started_at, finished_at, log_uri | status ∈ {queued, running, blocked, succeeded, failed, awaiting_approval}. |
| Artifact | id, project_id, task_id?, kind, uri, checksum, created_at | kind ∈ {plan, design, tokens, branch, pr, docs, report, bundle}. |
| Approval | id, project_id, subject_task_id, requested_by, decided_by (User.id), decision, reason, created_at | Human gate; decision ∈ {approved, rejected}. |
| Integration | id, project_id, provider, status, secret_ref | provider ∈ {github, vercel, railway, aws, azure, self-hosted}; secrets stay in the platform secret store, referenced not inlined. |
5.3 Agent roles
Canonical internal role ids (AgentRole.id), with common aliases in parentheses:
orchestrator— coordinates work, dependency order, and approval gates.product-analyst(product strategist) — turns vague briefs into concrete specs.researcher— studies repo, docs, and references before proposing direction.designer— visual language, tokens, screens, interaction patterns.architect— framework, modules, data model, integration patterns.engineer— implementation across frontend, backend, automation, tooling.qa— tests, flow validation, regression detection.security-reviewer— secrets, auth paths, data flows, common risks.devops— build/deploy workflows, environment management, monitoring hooks.release-manager— launch notes, release packages, operational readiness.
Do not confuse these with the registry catalogs.
registry.jsexports
AGENTS(assistant, coder, analyst, support),SKILLS, andMCP_SERVERSforthe Account center *setup generator*. Those are selectable product catalog
entries, not the Studio's internal orchestration roles. If the Studio exposes
user-selectable roles, they must be added to the registry catalog as well.
6. Contract mapping (v0.2.0)
Source of truth: aetherin-stack/common/openapi.yaml, version 0.2.0. Each operation carries x-aetherin-maturity (live or planned).
6.1 Operations the Studio consumes today
| Studio need | Contract operation | Maturity | |
|---|---|---|---|
| Sign up / in / out, current user | POST /v1/account/signup, POST /v1/account/login, POST /v1/account/logout, `GET | PATCH /v1/account/me` | planned |
| Org-admin user management | GET /v1/users, `PATCH | DELETE /v1/users/{id}` | planned |
| Scoped API keys for CI/integrations | `GET | POST /v1/keys, DELETE /v1/keys/{id}` | planned |
| Usage and cost views | GET /v1/usage, GET /v1/usage/daily, GET /v1/usage/providers | planned | |
| Provider routing / health | GET /v1/providers, `GET | PATCH /v1/providers/{id}` | planned |
| Model catalogue | GET /v1/models | live | |
| Agent LLM calls | POST /v1/chat/completions | live | |
| Programmatic consumer tokens | POST /v1/auth/login, POST /v1/auth/refresh | planned | |
| Health / readiness | GET /healthz, GET /readyz | live |
Implication: the Studio's identity, key, usage, and provider features depend on planned routes. Until the core implements them, the Studio must degrade gracefully (local-first) exactly as the Account center does behind window.AETHERIN_API_BASE.
6.2 Studio additions required (propose for a future contract revision)
The Studio-defined entities in §5.2 have no representation in v0.2.0. They require a new, additive contract revision (working name v0.3.0). Proposed route families — indicative, not yet agreed:
| Route family | Backs |
|---|---|
/v1/studio/projects, /v1/studio/projects/{id} | Project, Brief |
/v1/studio/projects/{id}/context | ContextItem |
/v1/studio/projects/{id}/plan, /plan/milestones, /plan/tasks | Plan, Milestone, Task |
/v1/studio/projects/{id}/runs, /runs/{runId} | AgentRun |
/v1/studio/projects/{id}/artifacts | Artifact |
/v1/studio/projects/{id}/approvals | Approval |
/v1/studio/projects/{id}/integrations | Integration |
Rules for the addition:
- Reuse existing schemas (
User,Key,Model,Usage*,Error) — do not
duplicate identity, key, or usage shapes.
- Keep the two auth worlds intact: Studio user calls use the
account/*session;
Studio machine integrations use consumer keys (auth/*).
- Nothing in v0.2.0 changes; the addition is purely additive.
7. Integration boundaries
- Git: greenfield and brownfield. Detect existing stack; propose changes on
branches/PRs; never overwrite protected work.
- Design: extract direction from uploaded assets and the Design system
tokens; keep generated UI on the shared ax-* base.
- Tools: agents use the MCP hub catalogue; capability is discoverable and
schema-driven.
- Deploy: target selected per project (Vercel, Railway, AWS, Azure,
self-hosted, or the self-hosted Aetherin box) via Integration records.
- Billing/usage: metered through Account center + Gateway; the Studio
reads usage, it does not bill.
8. Non-functional requirements
- Safety: branch-safe writes; explicit human approval gates for launch,
destructive, and cost-sensitive actions.
- Determinism: a reviewable plan is produced before heavy implementation.
- Auditability: every agent run and approval is logged and visible.
- Portability: degrade to local-first when backend routes are unavailable.
- Consistency: generated UI uses the shared Design system tokens and
components.
- Isolation: secret values are referenced by
secret_ref, never inlined into
artifacts or logs.
9. Open questions
- Exact Studio host (
studio.aetherin.app) and whether it lives in
aetherin-portal or a new runtime repo.
- Whether Studio internal roles are exposed as selectable registry
AGENTS
entries or stay internal.
- Sandbox/execution model for agent tool calls (MCP hub vs a dedicated runner).
- Contract revision number and ownership for the Studio route families in
§6.2.
- Multi-tenant boundaries and how they map onto
plan/seats in
Account center.