feat(mcp): add agent identities and issue runtime support

[yxr-2025]

What this changes

This is a Draft PR for early review of the Agent identity, data model, permission boundaries, and Issue runtime implementation. It is not ready to merge and does not claim to complete #215. Known Web integration gaps and remaining work are listed below.

Adds workspace Agent identities that can be assigned issues through MCP and appear as the actor for Issue mutations. The authorizing Human remains the permission principal, so Agent access is the intersection of the grant scopes, the Human's current permissions, and resource policy.

• Personal Agents are selected or created during OAuth consent, bound to the original client, and managed from MCP settings. Owners and admins can pause, revoke, or delete them while preserving historical attribution.
• The database, Core services, and MCP support Human or Agent creators and assignees. Agent assignments require a Human issue owner, and assignment policy permits only the Personal Agent's owner or that Agent to assign it. The Web Agent selection flow is not yet implemented.
• Access and refresh credentials bind to the exact rotating grant. Legacy unbound credentials are invalidated, and lifecycle changes cannot race past an issue mutation.
• Issue mutations, activity, audit, and Outbox writes commit together. A persistent Worker delivers events with retries; create_issue supports idempotency keys, and public events omit grant identifiers.
• Adds Agent queue discovery, canonical server-side readers and analytics, release documentation, and separate Writer-on/Writer-off HTTP E2E scheduling in CI. Web consumers do not yet retain and render the complete canonical Actor contract.

Why

MCP actions currently appear to come from the authorizing person, and Agents cannot own an assignment queue. This work establishes the runtime and permission boundaries needed to make Agent work visible and assignable without granting additional access. This draft requests upstream feedback before completing the remaining UI integration.

Refs #215

Feedback requested

• The original issue describes admin-created identities. This implementation lets members explicitly select or create Personal Agents during OAuth consent, while admins govern their lifecycle and connections. Is this MVP creation model acceptable?
• This MVP attributes Issue Aggregate mutations to Agents. Comments, attachments, documents, and other aggregates retain Human attribution. Is that scope acceptable for the first increment?
• Each member currently has a limit of two active Personal Agents per workspace. Should this identity limit remain, given the contribution guide's policy against usage limits?

Known gaps and remaining work before ready for review

• Retain canonical creator, assignee, owner, assigneeAgentId, and ownerId in the client Issue schema and update detail, list, and board consumers. Agent assignments currently render as Unassigned, and the Human Issue Owner has no display or transfer controls.
• Add an Owner-authorized Personal Agent selection flow to the Web detail and card Assignee controls. They currently list only Human workspace members.
• Render the Agent Creator's actual name, avatar, and Deleted state instead of only a generic Agent label.
• Support ownerUserId: null for policy-controlled Owner clearing when there is no Agent Assignee. The current validator and transfer path do not support that input.
• Add member-removal confirmation and preflight counts for affected Agents, connections, and open assignments, without leaking unreadable resources.
• Move remaining profile and lock-holder action authorization into Shared Policy. These checks currently run on the server in Core; the finding is incomplete policy centralization, not a demonstrated permission bypass.
• Add regressions that fail on these missing behaviors and rerun the affected verification before marking this PR ready for review. Align documentation with the agreed scope and completed surfaces.

How you know it works

Validated on 203a066dcba7c7ffc4adcb5a28e81749f3392e79, including upstream d133153ef077637324f0eb34b79fbc82f45b1212.

Check	Result
bun run verify	6,534 passed, 0 failed; all nine workspace packages executed on Linux
bun run test:e2e	57 passed, 0 failed, three existing skips; no added retries or exclusions
bun run test:e2e:agent-release	Writer-on and a fresh Writer-off process both passed
Isolated empty-database db:release, repeated release, and db:check-drift	Passed; 31 migrations applied, then zero pending; no required drift
bun run build, bun run docs:build, documentation navigation test	Passed
git diff --check	Passed

The regression coverage includes current-permission checks, identity lifecycle races, exact credential binding, Actor constraints and backfills, issue attribution, Agent queue access, idempotency, Outbox delivery and redaction, and real HTTP OAuth/MCP behavior with the Writer enabled and disabled.

The browser coverage also includes document access revoked during a reconnect, keyboard drag readiness and persistence, and Agent settings and Inbox behavior. The full verification includes real S3 round trips with signature validation enabled. The earlier persistent Worker image and recovery drill was not repeated for this merge candidate; it remains historical evidence, not a new result.

These passing results describe the current test suite, not complete coverage of #215. The existing MCP browser test checks the generic Agent Creator label and Activity badge, but does not assert Agent Assignee rendering, Human Owner controls, or Web Agent selection. Those gaps remain despite the green suite.

Screenshots

Before this change, MCP settings listed Human-authorized client connections without an Agent management surface, and MCP issue actions appeared to come from the Human.

After this change, settings show Agent identities, owners, lifecycle and connection state, locks, permissions, quota, and recent activity. Issue activity distinguishes the Agent actor from its Human principal.

Light and dark screenshots of Agent settings and issue attribution have been captured in the local review bundle. Uploading the four PNGs to this PR is pending. They use synthetic E2E data, not production records.

The screenshots cover existing Settings and Activity behavior only. They are not evidence that the Agent Assignee and Human Owner UI is complete.

Checklist

• bun run verify is green, all four checks
• Tests added or updated for the implemented runtime and lifecycle behavior
• Missing Web and Owner workflows have failing regressions and complete coverage
• No comments added to code, and no em-dash characters anywhere
• No any, no non-null assertions
• External input is parsed with a Zod schema from @orbit/shared
• All authorization is enforced on the server through packages/shared/src/policy, including the remaining lifecycle action checks
• Docs updated if behaviour, configuration or setup changed
• bun run db:release and bun run db:check-drift passed against the target database before this ships. The isolated acceptance target passed; the deployment target remains a release-time check.

Anything reviewers should know

• All four Agent feature gates default to off. Agent issue writes require all four gates and a separate persistent Outbox Worker; Cron provides recovery rather than the primary delivery process.
• 0030_green_shaman.sql appends to the official migration chain. Existing upstream migrations are unchanged. The abandoned local development migration lineage is not a supported upgrade path.
• Migrating invalidates legacy unbound MCP credentials even while feature gates are off. Existing clients must reconnect through consent.
• Personal Agents do not consume seats or membership roles. Each member can have two active Personal Agents per workspace; disconnected identities still count while active. A Human issue owner can differ from the Agent owner.
• me and list_my_issues keep their Human meanings; agent and list_agent_issues refer to the current Agent. Agent attribution covers issue mutations; comments, attachments, and documents retain Human attribution.
• Owner departure deletes the Personal Agent in product terms and clears open Agent assignments, while tombstones and closed history remain. Resume requires fresh consent and does not restore assignments.
• The three unchanged browser skips are rich-editor round-trip, synthetic mouse dragging, and notification conversations with their gate disabled. Hosted CI, production OAuth/S3, the public network entry point, and production deployment checks remain to be completed.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Thanks for your first pull request to Orbit.

Two things that will save you a review round: bun run verify runs the
same four checks CI does, and the repo has no comments in code by policy,
so bun run check-comments will flag any you added out of habit.

A maintainer will review this shortly. Ask anything on the thread.

[imshashank]

This can be something amazing; you are basically adding an agent directly to Orbit. Is there a design doc?
Also look at Yodu; it's a harness built on top of OpenClaw and uses existing claude/codex subscriptions.