feat: add first-class agent management

[danielkov]

Summary

Adds human-only create, read, rename, suspend, resume, revoke, and delete APIs for first-class agent principals, including generated server and dashboard clients. Adds an ownership-aware setup page whose controls reflect exact agent permissions and whose shared-demo state remains intentionally read-only.

Impact

Agent owners can manage identity and lifecycle without materialized owner grants. Delegated callers can use independent, resource-scoped agent permissions, while support, impersonated, alternate-credential, inactive-membership, and scope-override access is rejected.

Technical details

Authorization and lifecycle

Management requires a validated ordinary Gram session and locks active organization membership for mutation authorization. Current owners receive intrinsic read, setup, authorize, and transfer predicates; nonowners are checked against the matching exact agent scope without disclosing whether a denied resource exists. Revocation is terminal, and deletion tombstones the principal so its name can be reused while audit history remains intact.

Audit and clients

Every successful lifecycle transition writes its before/after audit event in the same transaction as the agent mutation. Goa/OpenAPI output and the dashboard TypeScript SDK are regenerated from the new service contract.

Prerequisites

Targets main, which includes the merged schema (#6038), domain (#6040), and authorization-scope (#6041) prerequisites.

Linear: https://linear.app/speakeasy/issue/AIM-182

[linear-code]

AIM-182

[changeset-bot]

🦋 Changeset detected

Latest commit: b10d4bf

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
server	Minor
dashboard	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[cubic-dev-ai]

Running ultrareview automatically — This PR adds first-class agent management with new authorization, lifecycle (suspend/revoke/delete), and audit-trail logic across a large public API surface — a missed permission or state-transition bug could break data integrity and security, so it warrants deep multi-pass review.. I'll post findings when complete.

[danielkov]

Demo

What it shows:

1. An owner can create a first-class agent from the new setup page.
2. The resulting settings page exposes rename and reversible lifecycle controls.

[cubic-dev-ai]

Ultrareview completed in 11m 28s

All reported issues were addressed across 65 files

Linked issue analysis

Linked issue: AIM-182: feat: add human-only agent management APIs

Status	Acceptance criteria	Notes
✅	Provide create, read, rename, suspend, resume, terminal-revoke, and delete agent APIs.	The PR adds the agents service, all seven generated endpoints and clients, route registration, lifecycle repository operations, and service implementations.
⚠️	Require validated nonsupport human sessions and apply owner predicates or the exact corresponding agent scope for existing-agent operations.	The reusable authorization layer defines the four intrinsic owner predicates and the PR describes exact-scope checks, with authorization tests present; the supplied diff does not expose the complete caller matrix or every endpoint authorization path.
⚠️	Allow eligible humans to create agents for themselves, while requiring evaluated agent:write to create for another same-organization human.	The create form and human authorization seam support an optional owner, and lifecycle tests cover self-creation, but the supplied diff does not show the complete cross-owner authorization test evidence.
⚠️	Reject support, impersonated or alternate-credential callers, inactive memberships, scope overrides, anonymous callers, and cross-tenant access without disclosing denied-resource existence.	The PR explicitly claims these rejection behaviors and uses tenant-bound repository lookups, but the provided excerpts do not show the full negative caller matrix or endpoint-level nondisclosure tests.
⚠️	Expose setup UX controls based on server-returned exact permissions, with shared-demo state remaining read-only.	A new ownership-aware Agents page and permissions model are present, but the supplied UI excerpt is incomplete and does not show all disabled-state behavior.
✅	Emit audit events atomically for successful create, rename, suspend, resume, revoke, and delete mutations.	The PR adds agent audit actions and event registration, and service tests explicitly cover atomic lifecycle auditing.

<sub>Tip: instead of fixing issues one by one fix them all with cubic

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 12 files (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 9 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Fix all with cubic | Re-trigger cubic</sub>

[daviddanialy]

would like a gif/video demoing the whole UI flow

[danielkov]

Agent management — screen recording

Real browser capture against the rebased PR head (b10d4bfdfc), using a synthetic agent in an isolated local workspace.

1. Create Release assistant and rename it to Release coordinator.
2. Suspend and resume the agent, showing the lifecycle state update.
3. Confirm terminal revocation and show the revoked state.

demo-trimmed.webm