Console Agent sharing and removal

Overview

Trace how Agent detail shares one Agent with an existing Principal and removes one explicit Agent binding. The trace starts when Agent detail mounts the sharing panel and stops at policy configuration; native gateway admission and runtime readiness belong to the native admin flow. See the parent flow and the sharing reference.

Entry Points

• apps/controller/src/console/agents/access.mjs:renderAgentAccess renders the sharing panel inside Agent detail.
• apps/controller/src/console/agents/detail.mjs:renderAgentDetail mounts it.
• Assumptions: a signed-in Installation administrator, an existing Principal ID, and the Namespace IAM policy endpoints.

Flow

graph TD
  A["Agent detail mounts sharing panel"] --> B["Read Namespace Roles and bindings"]
  B -->|policy denied| K["Keep other Agent panels available"]
  B --> C["Submit share for an existing Principal"]
  C --> D["Reread policy; find or create Namespace read Role"]
  D --> E["Bind Namespace read to the exact Namespace"]
  E --> F["Find or create Agent read/administer Role"]
  F --> G["Bind it to the selected Agent"]
  G -->|confirmed steps| H["Show progress and direct grants"]
  C -->|uncertain| Q["Block writes until policy refresh"]
  H --> R["Remove one selected Agent binding"]

Execution Trace

1. Mount the panel and read policy

apps/controller/src/console/agents/access.mjs:renderAgentAccess

Agent detail mounts sharing independently of revision/configuration reads and native admission. The panel reads the selected Namespace's existing /iam/roles and /iam/access-bindings endpoints. A policy 403 leaves the other panels usable; a current 401 retains global session expiry.

2. Serialize Role and binding writes

apps/controller/src/console/agents/access.mjs:matchesRole

Submission rereads policy, finds or creates an immutable Role by exact Namespace and permissions, then binds Namespace read to the exact Namespace. Only after that response does it find or create the exact Agent read/administer Role and bind it to the selected Agent. The server validates the supplied subject and resource on each write. Confirmed progress survives later failure; unknown results disable mutations until an explicit current-policy refresh. Readback is configuration evidence, not a historical receipt, and never triggers a write.

3. Remove one explicit binding

apps/controller/src/console/agents/access.mjs:renderAgentAccess

Removal addresses only the selected Agent binding. The request client's existing success envelope handling also accepts the API's empty 204 deletion response. The panel retains discovery grants and explains other possible access sources.

Debugging and Verification

• A 403 on the policy reads affects only the sharing panel; check Installation administration before treating it as a console fault.
• After an uncertain write, select Refresh sharing and inspect the direct grants before submitting again. A present binding does not prove an earlier request's outcome.
• The real-runtime sharing case is described in gateway routing tests.

Related docs

• Return to the parent flow
• Agent editing flow
• Namespace IAM policy flow
• Sharing procedure