Submatter/plans/Plan-workspace-communications/Epic-agent-participation/Task-agent-registry-marketplace.md

kind	slug	title	plan_slug	epic_slug	status	priority	tenant_id	owner	cursor_todo_id	updated_at
task	agent-registry-marketplace	Define the versioned agent registry schema and contracts	workspace-communications	agent-participation	ready	P1	global	unassigned	null	2026-10-22

Task summary

Define first-class, versioned workspace agent persistence and shared validation contracts that later draft, marketplace, and builder APIs can consume.

Description

Agents are service identities, not fake users and not aliases for model providers. Add workspace-scoped agent definitions with immutable IDs and stable handles, versioned configuration, provenance, status, role/capability bindings, instructions, tool policy, invocation/context policy, harness route, model role, budget, and creator metadata. Add a curated global template catalog and workspace installation records. This task owns persistence, migration, shared contracts, and the permission-policy definitions consumed by later API tasks; CRUD, installation, lifecycle behavior, and marketplace presentation remain separate.

Subtasks

• Add agent_templates, agents, agent_versions, and workspace installation/provenance schemas with generated migration and indexes.
• Add shared zod contracts for identity, configuration, provenance, lifecycle, permissions, filters, and optimistic-concurrency inputs.
• Encode the explicit owner | admin | member permission matrix as reusable policy functions/contracts.
• Add schema/contract tests for tenant isolation, creator ownership, handle uniqueness, immutable versions, and invalid configurations.

Owner or assignee

unassigned

Status

ready

Estimation

L

Acceptance criteria

• Agent definitions are distinguishable from users, roles, model providers, harnesses, and runs.
• Contracts represent: members manage their private drafts/use active agents; admin/owner manage shared lifecycle and ordinary grants; only owner approves mutating sandbox or sensitive workspace-wide grants.
• Agent configurations can reference model roles, harness routes, and tools but cannot contain provider credentials.
• Schemas expose lifecycle, provenance, permission, and update metadata without weakening workspace/private-draft boundaries.
• Tenant-owned schemas require and index workspace_id; follow-on CRUD/query tasks remain responsible for workspace authorization and explicit workspace_id filters.
• pnpm lint && pnpm type-check && pnpm test pass.

Follow-on ownership and access contract

This task supplies the single workspace agent identity/version registry used by AI Chat, Agents builder/library, mention completion and durable jobs. Task-agent-registry-api.md owns catalog/private-draft procedures; Task-agent-install-lifecycle.md owns reviewed server lifecycle mutations. UI and execution tasks consume them. No installation/publication grants channel or private-object access. Permission contracts must distinguish workspace lifecycle/tool approval from context delegation and reviewed per-conversation membership; follow the parent plan's role matrix, with fail-closed context policy and no silent grants.

Links to related Epic / Plan

• Epic: ./Epic-agent-participation.md
• Plan: ../Plan-workspace-communications.md