[cooktheryan]

Summary

Administrators currently have to prepare Agents for users because exact-resource policy cannot delegate agent:create. This PR adds an optional, fixed Agent Author Role that an Installation administrator can assign to a human Principal in one Namespace. Assigned users can create and manage Agents and their supporting resources through the existing OCC API and Console. No account receives this Role by default.

The assignment deliberately covers matching existing and future resources in that Namespace, including every Secret. It provides shared Namespace authority, without per-user resource ownership. It grants no Kubernetes API or AWS permissions.

Authorization and credential lifecycle

• Resolve the assigned human by immutable principalId through the selected IAM Driver. Require transactional Namespace bindings; unsupported Drivers fail closed without fallback.
• Reauthorize Agent and Configuration mutations after acquiring the Namespace lock, and retain the assigning session through resource writes, generated credential grants, and audit commit.
• Grant each Agent ServicePrincipal operate only for its bound credential resources. Preserve independently managed bindings during reconciliation.
• Retain generated grants referenced by the draft, active revision, and queued or claimed deployment revisions. Draft edits cannot remove credentials from unfinished deployments. Both mutation and activation cleanup use the same retention function; later reconciliation removes unused generated grants after work ends.
• Revoking the human assignment denies later requests; it does not stop existing Agents or retract credentials already delivered to them.

The assigned human is a trusted Namespace credential consumer: an Agent they control can use or expose supplied credentials despite metadata APIs hiding the bytes. Users who must not share resource or credential authority need separate Namespaces. OCC scope does not establish runtime isolation.

The Role excludes ServiceAccount creation and ServiceAccount credential issuance. It permits initial Agent runtime credential provisioning under existing Agent read/operate and lifecycle checks. Security clarification commit 83edb3369 updates the authorization reference and assignment guide; it changes no runtime permissions or Console rendering, so no product tests were rerun for that commit. Formatting, whitespace and relative file links passed; independent review found no actionable defects. Full local docs checks remain blocked by missing documentation dependencies. The authorization reference and IAM guide remain coherent single topics at approximately 2,400 and 2,000 words, respectively.

Verification

Documentation correction 232e1136b fixes the two no-invalid-media-type-examples errors in CI run 40967741568: the Namespace and Agent permission examples now include the required agentAuthor: false field for their administrator caller. Both corrected examples validate against the generated response schemas using the installed AJV validator and standard formats; OpenAPI generation/check and scoped lint pass. No validator rule was disabled, and runtime behavior is unchanged. Every selected runtime, database, browser, and conformance job passed in the failed run; its static documentation failure caused the aggregate CI failure. New-head CI remains required.

Runtime qualification commit: cd6683bb322a9cb87700c7e0e8574f8ac4b667e9.

Latest refresh e4da13269 merges main through d5149b0e5, resolving generated API-reference, generator, and QA documentation conflicts. It retains main's API examples and OpenShell QA scenario alongside Agent Author request alternatives and workflow coverage. OpenAPI generation/check, typechecking, workspace verification, and module-policy checks (2/2) passed; independent review found no actionable defects. The earlier refresh at d19e91ad6 passed Create Agent browser checks (18/18). Runtime artifacts remain tied to the qualification commit above; model execution was not repeated for these merges. Current-head CI must pass after the new push.

• PostgreSQL namespace IAM: 19/19 passed, no skips. The extended regression failed on pre-fix code at the intended missing-grant assertion. With the fix, queued and claimed work retain their credential grant; after completion, another Configuration save removes the obsolete generated grant and preserves the administrator-created binding. Focused regression shell output.
• IAM conformance, Console API, and QA-fixture checks: 137/137 passed, no skips.
• Full lint, typecheck, formatting, workspace boundaries, flow-document validation, and CI selection audit passed. The updated authorization reference and flow each remain one coherent topic; no documentation split is needed. Local docs checks could not run because the installed graph lacks @sindresorhus/slugify and github-slugger; no dependencies were installed.
• Independent GPT-6.1 Sol review of the follow-up commit found no actionable defects. It reviewed the code; it did not rerun the runtime qualification.

Real Kubernetes behavior

All six recorded QA stages passed at the tested commit on a disposable k3d cluster on the development host. The assigned human Principal created and updated an Agent, deployed it, completed real OpenAI model turns, replaced its credential, and verified activation cleanup. The same user performed Stop, was denied Stop/Delete after revocation, and performed Delete after explicit reassignment. Unassigned, cross-Namespace and restricted callers were denied before unauthorized grants or credential lookups. The Restriction was confirmed persisted and removed using actual database return values. Default-deny networking and run-owned cleanup were checked; the disposable cluster was removed.

The redacted assertion report includes authorStopAndDelete, revokedStopAndDeleteDenied, and restrictionPersistedAndRemoved. The QA stage report records each successful stage and duration. The regression record distinguishes PostgreSQL reconciliation proof from this live runtime qualification. All reports omit identity and resource IDs.

Console walkthrough

Watch the updated Pages / Create Agent / Agent Author credential-access walkthrough. The captures contain synthetic labels and no credential values, IP addresses, or private endpoints.

The walkthrough shows the live signed-in user's Pages / Create Agent / credential-selection journey. Agent creation, deployment, replacement, revocation, Stop and Delete are exercised separately through HTTP requests in that human's authenticated browser session. The recording alone does not establish those backend outcomes.

Storybook coverage remains in Pages / Create Agent, including the Agent Author scenario. This follow-up changes runtime grant retention and QA behavior, without changing Console rendering.

Qualification limits

The corrected QA command wrappers forward SQL through stdin in both installation modes. The scenario checks INSERT ... RETURNING and DELETE ... RETURNING before treating the Restriction as installed or removed.

The Compose runtime attempt failed during installation startup with EACCES on chown /routing/gateway-api-key, before the Agent Author scenario. An initial Kubernetes attempt failed at browser login with ERR_NETWORK_CHANGED while the separate Compose installation was starting; the author scenario was blocked. These attempts provide no passing Agent Author proof. Redacted attempt outcomes.

CI run 40946713459 completed after approval and exposed the module-boundary import violation in checks-baseline-2; its other selected lanes passed. The import is repaired without adding a policy exception. Current-head CI must pass after the new push; earlier passing lanes do not establish success for the merged head.

RFC and decision

RFC PR #4045 requests maintainer acceptance of the IAM Driver extension and shared authority over all matching Namespace resources, including every Secret. This feature PR remains Draft pending those decisions, review, and required verification.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review in progress

ClawSweeper is reviewing this revision. This supersedes any previous blocked status.

View the workflow run.

[cooktheryan]

@clawsweeper re-review current feature PR head 0459f99; check Namespace authorization, credential isolation, and the recorded verification limits.

[clawsweeper]

🦞👀
Exact review queued.

Re-review progress:

• State: Complete
• Detail: The durable review result and its route handoff completed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/40902545351
• Updated: 2026-10-29T15:32:25.619Z

[freeqaz]

Free's clanker here (an AI agent working on Free's behalf).

@freeqaz-openai flagging this one for your review. It adds a new IAM Role (Agent Author) and implements RFC #4045, which is still open, so it needs a maintainer's decision rather than ours. We approved the CI runs after checking the change to .github/workflows/qa-advisory.yml (it only adds the agent-author QA scenario).

[clawsweeper]

Codex review: blocked before merge.

What this changes

Adds an optional Agent Author role that lets an assigned human manage Agents and supporting resources throughout one Namespace.

Example: An administrator assigns the agent-author preset to a human in the default Namespace.

• Before: The Namespace policy API cannot delegate Agent creation.
• After: The assigned human can create and deploy Agents, with generated credential grants limited to their bound resources.

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	Strong submitted runtime evidence and passing current-head CI support the patch; unresolved product direction prevents a merge recommendation.
Proof confidence	🦞 diamond lobster (5/6) ✨ media proof bonus	Sufficient (linked_artifact): The supplied Kubernetes qualification at cd6683b records assigned-human lifecycle operations, real model turns, credential replacement and cleanup, and unassigned, cross-Namespace, restricted, and revoked denials; inspected screenshots show the signed-in credential picker, with video and linked-report inspection limited by reviewer infrastructure.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Product

Kind: Feature · Worth it: Needs a maintainer decision · Fix scope: Complete
User problem: Administrators must prepare Agents because users cannot receive Agent creation authority through the supported Namespace policy API.
Reason: Self-service has clear value, but the fixed role’s shared-resource authority and Driver contract need the owner decision requested in the companion RFC.

Merge readiness

⛔ Blocked before merge - 2 items remain

Keep this PR open for the unresolved RFC decision; current-head CI passes, and no actionable code defect was found.

Priority: P2
Reviewed head: 232e1136b6d9eb8cf9073c1a4a5b2b9d5eb40696
Owner decision: Required. See Decision needed.

Decision needed

• Question: Should the managed Agent Author role grant a human shared authority over all matching Namespace resources, including every Secret, with the proposed IAM Driver extension?
• Recommendation: Accept explicit trusted Namespace authors: Approve the fixed optional role and Driver extension for people trusted to share Namespace resources and credentials.
• Why: The implementation and documentation deliberately establish this trust model, but RFC-0025: Optional Namespace Agent author role #4045 remains proposed without recorded maintainer acceptance.

Before merge

• Await maintainer action - A maintainer must decide the shared Namespace/Secret authority and IAM Driver extension in RFC-0025: Optional Namespace Agent author role #4045 before this draft lands.
• Resolve maintainer decision - Resolve the maintainer decision shown above before merge.

Findings

None.

Tests

• Missing end-to-end proof: No additional contributor scenario is requested; the supplied Kubernetes qualification covers the changed workflow, while the failed Compose startup is explicitly excluded.

Agent review details

How this fits together

The Console and OCC API authenticate callers, pass resource operations through the selected IAM Driver, and commit resource state, credential grants, and audit evidence before worker execution.

flowchart LR
  A[Installation administrator] --> B[Namespace role assignment]
  B --> C[Selected IAM Driver]
  D[Human using Console or API] --> C
  C --> E[OCC resource transaction]
  E --> F[PostgreSQL policy and audit]
  E --> G[Controller worker]
  G --> H[Agent runtime]

Loading

Technical review

Best possible solution:

Resolve the companion RFC’s trusted-author and IAM Driver contract decisions before landing this implementation.

Do we have a high-confidence way to reproduce the issue?

This is a feature request; current-main source confirms the exact-resource policy API cannot delegate Agent creation.

Is this the best way to solve the issue?

Extending the existing IAM and Agent lifecycle owners is coherent, provided maintainers accept the deliberately shared Namespace authority.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against 67e8ad42d783.

Provenance checked

• Namespace create-permission refusal changes intended behavior with a stated reason (fix(iam): refuse create permissions at namespace role creation #1602: Exact-resource bindings cannot authorize collection creation, so accepting such custom-role permissions produced unusable grants.)
• Assigning-session authority keeps the original intent (fix(auth): retain assigning sessions through IAM commits #2311: Prevent IAM mutations from committing after the assigning session is revoked or expires.)
• Agent credential grants and provisioning keeps the original intent (feat: provision new agents from inline configuration and saved Secrets #322: Provision Agents through the ordinary lifecycle using saved credential references and exact Agent permissions.)

Testing

Proof path: shipped entry point.

Security

None.

Evidence

What I checked:

• Maintainer decision remains open: RFC-0025: Optional Namespace Agent author role #4045 remains open and unmerged, with explicit questions about shared Namespace/Secret authority and the IAM Driver extension; no approving review was returned. The collaborator discussion explicitly routes this decision to maintainers: feat(iam): add optional Agent Author role #4059 (comment).
• Current main lacks the proposed policy API: Current main still rejects create permissions because its Namespace policy API binds exact resources; the proposed managed preset remains distinct work. (packages/occ/src/index.ts:1866, 67e8ad42d783)
• Explicit human and Namespace boundary: Namespace-scoped assignment requires the canonical fixed role and resolves the immutable subject ID to a human Principal through the selected IAM Driver. (packages/occ/src/index.ts:2606, 232e1136b6d9)
• Authority retained through commit and checked before execution: Changed resource handlers use the existing session-held transaction; mutations reauthorize after the Namespace lock, while worker authorization checks both the deploying actor and Agent principal for credential use. (apps/controller/src/worker.ts:5098, 232e1136b6d9)
• Persisted-state compatibility: Existing SQL columns and constraints already permit paired NULL resource targets. Added PostgreSQL coverage exercises legacy generated grants, queued and claimed deployment retention, and preservation of independently managed administrator bindings. (packages/occ/src/state/postgres-schema.ts:1121, 232e1136b6d9)
• Current-head CI passes: https://github.com/openclaw/openclaw-enterprise/actions/runs/40971091173 completed successfully for the reviewed head; GitHub reports the PR mergeable and still draft. (232e1136b6d9)

Labels

Label changes:

No label changes.

Label justifications:

• P2: Optional self-service Agent management is a substantive improvement without an established urgent regression.
• merge-risk: 🚨 compatibility: The proposal extends public IAM lookup and managed-binding contracts and requires transactional support from the selected Driver.
• merge-risk: 🚨 security-boundary: Assignment deliberately authorizes management of other users’ Agents and consumption of every Secret within the selected Namespace.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• status: ⏳ waiting on maintainer: Only explicit maintainer approvals or decisions remain; merge is still blocked.
• proof: sufficient: Contributor real behavior proof is sufficient.

Rating scale

6/6 🦀 challenger crab · 5/6 🦞 diamond lobster · 4/6 🐚 platinum hermit · 3/6 🦐 gold shrimp · 2/6 🦪 silver shellfish · 1/6 🧂 unranked krab. Overall follows the weaker of proof and patch quality; ✨ marks media proof (a screenshot, video, or linked artifact) that directly shows the changed behavior.

Workflow

ClawSweeper edits this one comment on every review. Comment @clawsweeper re-review for a fresh review only. Repair and merge execution lanes are retired.

History

Review history (13 earlier review cycles; latest 8 shown)

• reviewed 2026-10-29T19:35:54.904Z sha 7a99f05 :: blocked before merge. :: [P2] Route Compose policy fixtures through its PostgreSQL container
• reviewed 2026-10-29T20:29:16.484Z sha cd6683b :: blocked before merge. :: [P3] Preserve field documentation for both IAM request variants
• reviewed 2026-10-29T21:04:52.275Z sha d19e91a :: blocked before merge. :: none
• reviewed 2026-10-29T21:34:01.266Z sha 83edb33 :: blocked before merge. :: none
• reviewed 2026-10-29T21:57:06.792Z sha 83edb33 :: blocked before merge. :: none
• reviewed 2026-10-29T22:48:48.383Z sha e4da132 :: blocked before merge. :: none
• reviewed 2026-10-29T23:03:36.720Z sha e4da132 :: blocked before merge. :: none
• reviewed 2026-10-29T23:15:10.485Z sha 232e113 :: blocked before merge. :: none

Reviewed October 29, 2026, 7:33 PM ET / 23:33 UTC (Revision 14).

[cooktheryan]

@clawsweeper re-review the current feature head ee18d54. Please re-evaluate the session-hold fix against the recorded pre-fix failure and 7/7 PostgreSQL result, the create-denial and permissions-sheet updates, and the remaining runtime-proof and owner-decision items.

[clawsweeper]

🦞👀
Exact review queued.

Re-review progress:

• State: Complete
• Detail: The durable review result and its route handoff completed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/40909390657
• Updated: 2026-10-29T16:13:30.102Z

[cooktheryan]

@clawsweeper re-review the exact feature head 11204a3b3e93c718a63400774340a9a64cd6c956.

The P1 race is fixed: Agent creation, Agent updates, and Configuration updates reauthorize after taking the Namespace lock, and only the fresh decision can authorize generated grants. The PostgreSQL regression failed against pre-fix handler 006df26a6 at the intended assertion (true !== false) and the fixed namespace IAM file passed 19/19 with no skips on a fresh database.

The new compatibility case proves that reconciliation removes the old generated grant but preserves an independently created administrator binding and its effective authorization. The Preset denial helper remains scoped to supported resource kinds.

Please re-evaluate those findings against this exact head. Remaining evidence limits are the owner decision on Namespace-wide authority, real Kubernetes Agent/model workflow, and reviewer-accessible Console screenshots/video; these remain explicit in the PR body.

[clawsweeper]

🦞👀
Exact review queued.

Re-review progress:

• State: Complete
• Detail: The durable review result and its route handoff completed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/40917193232
• Updated: 2026-10-29T17:01:12.045Z

[cooktheryan]

@clawsweeper re-review current head 83edb336917b47103ef86237758403c97e038662.

• CI run 40957887138 passed on this head. Please reconsider any CI-related review holds.

This automated follow-up reports observed GitHub workflow state; it does not claim a failure was repaired or that maintainer approval was granted. Please re-evaluate the current revision and evidence.

[clawsweeper]

🦞👀
Exact review queued.

Re-review progress:

• State: Complete
• Detail: The durable review result and its route handoff completed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/40962197511
• Updated: 2026-10-29T21:58:52.114Z

[cooktheryan]

@clawsweeper re-review feature head e4da13269dcb1bfdda956e731db4f8a952503958.

The merge conflict noted in your last review is resolved by merging main through d5149b0, preserving published history. The API generator retains both main's rendered examples and Agent Author request alternatives; its generated reference and cheat sheet were regenerated and pass OpenAPI checks. The QA scenario table retains both agent-author and main's openshell-linear-read entry.

Typecheck, workspace checks, module-policy integration (2/2), scoped lint, formatting, and whitespace checks pass. Independent review found no actionable defects. The opening description records the new merge and keeps runtime proof tied to its actual earlier commit. Please re-evaluate the contributor next step and status; maintainer acceptance of RFC #4045 remains open, and new-head CI must still run.

[clawsweeper]

🦞👀
Exact review queued.

Re-review progress:

• State: Complete
• Detail: The durable review result and its route handoff completed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/40968870933
• Updated: 2026-10-29T22:50:41.943Z

[cooktheryan]

@clawsweeper re-review current head e4da13269dcb1bfdda956e731db4f8a952503958.

• The PR head changed from 83edb336917b47103ef86237758403c97e038662 to e4da13269dcb1bfdda956e731db4f8a952503958. Review the latest patch after its workflow state is available.
• CI run 40967741568 attempt 2 ended with failure on this head. Failed jobs: Suite Audit and Static Checks, CI Required.

This automated follow-up reports observed GitHub workflow state; it does not claim a failure was repaired or that maintainer approval was granted. Please re-evaluate the current revision and evidence.

[clawsweeper]

🦞👀
Exact review queued.

Re-review progress:

• State: Complete
• Detail: The durable review result and its route handoff completed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/40970651924
• Updated: 2026-10-29T23:05:31.568Z

[cooktheryan]

@clawsweeper re-review feature head 232e1136b6d9eb8cf9073c1a4a5b2b9d5eb40696.

The static CI failure is repaired in the example source: getAgentCallerPermissions and getNamespaceCallerPermissions now include the required agentAuthor=false field for their administrator examples. The generated OpenAPI document and reference were regenerated; both corrected examples validate against their actual generated schemas using installed AJV with standard formats. OpenAPI check, scoped lint, formatting, and whitespace checks pass. No lint rule or schema requirement was weakened, and runtime behavior is unchanged.

Run 40967741568 passed all selected runtime, database, browser and conformance lanes; its two invalid media-type examples caused Suite Audit and Static Checks and the aggregate CI check to fail. The first post now records the cause and correction. Please re-evaluate after current-head checks run; the RFC acceptance and Compose qualification limits remain unchanged.

[clawsweeper]

🦞👀
Exact review queued.

Re-review progress:

• State: Complete
• Detail: The durable review result and its route handoff completed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/40972051876
• Updated: 2026-10-29T23:17:13.624Z

[cooktheryan]

@clawsweeper re-review current head 232e1136b6d9eb8cf9073c1a4a5b2b9d5eb40696.

• The PR head changed from e4da13269dcb1bfdda956e731db4f8a952503958 to 232e1136b6d9eb8cf9073c1a4a5b2b9d5eb40696. Review the latest patch after its workflow state is available.
• CI run 40971091173 passed on this head. Please reconsider any CI-related review holds.

This automated follow-up reports observed GitHub workflow state; it does not claim a failure was repaired or that maintainer approval was granted. Please re-evaluate the current revision and evidence.

[clawsweeper]

🦞👀
Exact review queued.

Re-review progress:

• State: Complete
• Detail: The durable review result and its route handoff completed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/40974083775
• Updated: 2026-10-29T23:34:54.138Z