chore: add agent principal domain support

[danielkov]

Linear: AIM-183

Summary

Adds canonical agent:<uuid> typed principals plus a small internal/agents domain and SQLC persistence package. Agent principals now resolve by organization and ID through the existing strict grant-target validator, and lifecycle state is derived from authoritative timestamps.

Motivation

Gram needs a durable organization-scoped agent identity that remains distinct from users, roles, Assistants, and generic credential records. Resolution must fail closed for malformed, missing, deleted, and cross-tenant identities without an unscoped lookup.

Impact

This application change is blocked by the expand-only schema migration in #6038 and must merge and deploy after it. Existing user, role, and email principal behavior remains unchanged.

Technical details

Tenant-scoped resolution

The lookup always constrains both organization_id and agent UUID and excludes deleted rows. Suspended, revoked, and owner-latched rows still resolve as durable identities; admission gates for those states remain in dependent work.

Minimal persistence surface

The new package exposes only create and tenant-scoped get queries plus pure lifecycle derivation. Management endpoints, transition orchestration, audit, credential policy, and owner-loss transactions remain outside this foundation.

---

Summary by cubic

Adds agent:<uuid> as a typed principal so agents can be granted and resolved like users, roles, and emails. Gram previously had no durable organization-scoped agent identity; now agent principals resolve tenant-scoped through the existing strict grant-target validator, with lifecycle state derived from timestamps instead of stored.

This PR is blocked by the expand-only schema migration in #6038 and must merge after it. Existing user, role, and email principal behavior is unchanged.

Persistence and resolution

• New internal/agents package exposes only create and tenant-scoped get queries.
• Lookups always constrain both organization_id and agent ID and exclude deleted rows.
• Missing, deleted, and cross-organization agents fail closed with the same not-found error.

Principal support

• urn parsing now accepts agent:<uuid> and requires canonical UUIDs.
• ValidatePrincipal resolves agent principals; suspended and revoked agents still resolve as durable identities.
• Plugin assignments reject agent: URNs with a bad request since agent assignments are not yet supported there.

^{Written for commit ac0d232. Summary will update on new commits.}

[linear-code]

AIM-183

[changeset-bot]

⚠️ No Changeset found

Latest commit: ac0d232

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

[cubic-dev-ai]

Running ultrareview automatically — This adds a new agent principal type to the strict grant-target validator with a new SQLC persistence layer and tenant-scoped resolution; a subtle bug here could break authorization or allow cross-tenant principal resolution.. I'll post findings when complete.

[cubic-dev-ai]

Ultrareview completed in 7m 29s

All reported issues were addressed across 15 files

Linked issue analysis

Linked issue: AIM-183: feat: add tenant-bound agent principals and lifecycle

Status	Acceptance criteria	Notes
✅	Parse canonical agent: principals and reject malformed, unsupported, and non-canonical forms without changing existing principal behavior.	Agent parsing and canonical UUID validation were added, with table-driven coverage for valid, malformed, uppercase, compact, braced, bare, and unsupported forms. Existing principal tests remain covered.
✅	Resolve agents using both organization ID and agent ID, failing closed for missing, deleted, and cross-organization agents.	The query constrains organization_id and id and excludes deleted rows. Tests cover successful resolution, missing agents, deleted agents, and cross-tenant lookup with the same not-found result.
✅	Persist a dedicated agent with exactly one tenant-pinned human owner and prevent organization-user deletion from cascading into agent deletion or orphaning the owner.	The persistence tests reject a missing owner, reject an owner from another organization, and reject physical deletion of the organization-user relationship while preserving the agent owner.
✅	Enforce case-insensitive per-organization name uniqueness, reserving names for suspended and revoked agents and releasing them after deletion.	Database tests cover active, suspended, and revoked name conflicts, reuse after deletion, and reuse in a different organization.
✅	Derive lifecycle as deleted, revoked, suspended, or active in that precedence order, while preventing suspension and revocation from coexisting.	DeriveLifecycle implements the required precedence, unit tests cover precedence, and persistence tests reject simultaneous suspension and revocation.
✅	Store owner-reassignment timestamp and reason as an all-or-nothing pair, allowing the pair in any lifecycle state.	Persistence tests reject timestamp-only and reason-only values and accept both fields together for active, suspended, revoked, and deleted agents.
✅	Keep the agent persistence model limited to authoritative fields without stored status, principal URN, generation, reconciliation, or ownership-history fields.	The generated model exposes the expected authoritative columns, and the schema test asserts the exact agent column set.

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

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