---
brief: 2
convoy: ai-agent-studio
role: role-implementer
title: Versioned agent registry schema and contracts
status: ready
priority: P1
slice_dependencies: []
recommended_model: auto/coding
model_tier: standard
---

# Brief 2 — `Task-agent-registry-marketplace.md`

## Goal

Add durable workspace agent definitions and shared validation/permission contracts that later draft, marketplace, and builder APIs can consume.

## Files

Expected scope; confirm names against current exports.

- `packages/database/src/schema/` and a generated migration — template, agent, version, and installation/provenance records.
- `packages/shared/src/` — zod contracts for identity, configuration, policies, versions, permissions, and marketplace filters.
- Adjacent schema/contract/permission-policy tests.

## Required design

- Agents are not `users`, role IDs, provider aliases, harness aliases, or `agent_runs`. This is the single identity/version registry for AI Chat, Agents builder/library, mentions, installations and jobs; never add a second channel-agent registry.
- Separate lifecycle/tool approval roles from context delegation and per-conversation access. Installation/activation grants no channel/private-object access. Follow the parent plan's permission matrix; schemas/contracts must support reviewed, version-bound scoped grants without inventing project ACL tables.
- Workspace agents have immutable IDs, unique workspace handles, versioned configuration, lifecycle status, provenance, and creator/audit metadata.
- Configuration references model role and harness route aliases but contains no provider secrets.
- Schemas support global curated-template provenance and workspace-owned installations without storing provider secrets.
- Reusable policy contracts encode: members manage their own private drafts/use active agents; `admin`/`owner` manage template installation, shared lifecycle, and ordinary allowlisted grants; only `owner` approves mutating sandbox policy or sensitive workspace-wide tools.
- Contracts expose lifecycle, visibility, provenance, permissions, and update state for later APIs and UI.

## Follow-on boundaries

[Registry API](../../plans/Plan-workspace-communications/Epic-agent-participation/Task-agent-registry-api.md) owns catalog/private-draft procedures. [Install lifecycle](../../plans/Plan-workspace-communications/Epic-agent-participation/Task-agent-install-lifecycle.md) owns reviewed lifecycle transitions. These are not hidden deliverables of this schema brief; UI tasks consume them.

## Acceptance

- Tenant ownership, handle uniqueness, and supporting indexes/foreign keys are enforced at the schema/contract layer; workspace-scoped query enforcement is required in the follow-on CRUD APIs.
- Version/updated-at precondition contracts prevent silent last-write-wins behavior in later APIs.
- Contracts cover capabilities, requested/granted tools, context/invocation policy, model role, harness route, budget, provenance, permissions, and version changes without weakening private-draft boundaries.
- No schema or contract treats existing workflow role IDs as agent identities.
- `pnpm db:generate`, `pnpm lint`, `pnpm type-check`, and relevant tests pass.

## Prompt

Read existing model/harness registry schemas and settings UI, template CRUD/editor patterns, workspace authorization helpers, and schema exports. Keep this brief focused on registry/marketplace; do not implement channel participation or builder inference.