Skip to content

fix(occ): preserve omitted Configuration IDs in Agent topology checks - #3800

Merged
freeqaz merged 3 commits into
openclaw:mainfrom
ericcaiwx-star:codex/six-oct26-03-partial-agent-topology
Oct 27, 2026
Merged

freeqaz merged 3 commits into
openclaw:mainfrom
ericcaiwx-star:codex/six-oct26-03-partial-agent-topology

Conversation

@ericcaiwx-star

@ericcaiwx-star ericcaiwx-star commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

Problem

Mode-only Agent updates omit configurationId. After completed initial workspace setup and a later edit of the same Configuration, OCC treats the omitted ID as a topology change and rejects the update. Explicitly restating that unchanged ID succeeds. This blocks the supported managed-mode toggle while operators are repairing a draft.

Closes #3799.

Change

Compare the resolved Configuration ID with the saved ID when deciding whether completed workspace topology changed. Keep the execution-mode comparison, pending-setup admission and deployment validation. Add an owning regression covering omitted/restated IDs and actual incompatible topology changes; update the existing workspace-files flow. No Console, Driver contract, configuration option or schema changes.

Verification

Portable shipped CLI proof, parent/head transcripts and failing regression. Parent 46f6f41f4763335da2512d5127e7082987df77f8; head 94a62c287a902c7446166e07d03ad89dc2eae780. Fresh upstream 37a29dfb7 had no change in this owner. Node 26.7.0, Go 1.27.2, macOS arm64.

go build -trimpath -o <owned-dir>/occ ./cmd/occ
node proof.mjs <checkout> <owned-dir>/occ
occ agent update <agent-id> --file <owned-mode.json> --output json

The proof compiles the shipped CLI and invokes it independently against the real loopback Fastify, Better Auth service-key authentication, Native IAM, OCC and Configuration Driver. It uses synthetic in-memory state and seeds only the completed setup metadata that a prior successful deployment retains. It does not claim PostgreSQL, a worker, Kubernetes, Docker, Gateway execution, a live model or production durability. No API response or topology rule under test is replaced. Temporary keys are explicitly revoked via HTTP 200; key/input files and listener are cleaned up.

  • Parent: after editing the same Configuration's workspace, {"gatewayManagedMode":true} exits1 with HTTP 400/workspace admission. The variant restating the unchanged execution mode also exits1. Explicitly adding the unchanged Configuration ID exits0.
  • Exact head: both omitted-ID variants exit 0 and save the requested flag. Configuration/execution-mode identities and the edited Configuration remain unchanged.
  • On both revisions, a genuinely incompatible execution-mode change or different Configuration is still rejected. The baseline mode-only update before the Configuration edit still succeeds. All six checks match expectations on head; the parent harness exits1 for the two unexpected rejections. A final API readback and attributable update audit event are asserted.
node --test --test-name-pattern='partial Agent updates keep completed workspace topology' tests/conformance/configuration-occ.test.mjs
node --test tests/conformance/configuration-occ.test.mjs
node --test --test-name-pattern='Agent save and deployment refuse initial workspace files' tests/integration/workspace-setup-api.test.mjs
pnpm lint
pnpm typecheck
pnpm check:workspace
pnpm docs:check
python3 .agents/skills/local-dev/scripts/validate_flow_doc.py --kind flow-doc --doc docs/flows/workspace-files.md
pnpm format:check
git diff --check

The new regression fails on parent production code with ConfigurationHarnessError at the omitted-ID update. The owning suite passes 33/33 with no skips after repair; the selected existing topology API scenario passes 1/1 with no skips. Listed checks pass; documentation validation covers 304 pages and 4747 links, retaining 3 historical external links as unverified. Shared independent autoreview reports no accepted/actionable P0–P2 finding in the three-file scope; it did not independently execute the CLI proof.

CI Required passed on exact head 94a62c287. First Agent Smoke also passed on this head. The local proof, body and Required CI match this head. ClawSweeper's first verdict is pending; no proof-sufficiency verdict is claimed yet.

Risks

An unrelated flag edit remains possible while a later Configuration edit makes a future deployment incompatible. This preserves the existing completed-setup editing contract; actual Configuration/execution-mode changes and deployment retain their admission checks. The proof seeds completed setup metadata and does not exercise the worker that creates that state.

@clawsweeper

clawsweeper Bot commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

🦞👀
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.

@ericcaiwx-star
ericcaiwx-star marked this pull request as ready for review October 27, 2026 00:03
@ericcaiwx-star
ericcaiwx-star requested a review from a team as a code owner October 27, 2026 00:03
@clawsweeper clawsweeper Bot added the clawsweeper:intake:bug Preliminary submission classification; full source review pending. label Oct 27, 2026
@ericcaiwx-star

Copy link
Copy Markdown
Contributor Author

@clawsweeper re-review

The automatic exact review in run 40425080286 ended superseded, with publication skipped, after Verification was synchronized to the completed First Agent Smoke result. Head 94a62c287a902c7446166e07d03ad89dc2eae780 is unchanged; the body, actual CLI proof, CI Required and First Agent Smoke now match it. There is no newer active or queued exact review. This requests one review of the stable revision after the interrupted attempt.

@clawsweeper

clawsweeper Bot commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor

🦞👀
Exact review queued.

Re-review progress:

@freeqaz freeqaz left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Verdict: looks good on 94a62c287a. The one-line fix is correct, and the regression fails without it.

The bug. updateAgent already resolves const configurationId = input.configurationId ?? agent.configurationId (packages/occ/src/index.ts:9553). It uses that value for the read authorization, the Configuration lookup and the stored update. The completed-setup topology check (:9637) compared the raw input.configurationId instead. An update that omitted the field (undefined !== agent.configurationId) therefore counted as a topology change. With a completed workspace setup and a later edit to the same Configuration, a mode-only update ({"gatewayManagedMode": true}) was rechecked and refused. Restating the same ID passed. The fix makes the check match the comment above it ("An update that keeps both is not checked").

Callers. In production, the only caller of OpenClawController.updateAgent is the HTTP route (apps/controller/src/http/agents.ts:363). It passes the body through unchanged, and the CLI and Console both go through that route. :9518 still requires either a Configuration or gatewayManagedMode. With the fix, omitting the ID now means the same as naming the current ID in every case. A real change of Configuration or execution mode is still rechecked, pending setups are still checked on every update, and deployment still checks a completed setup. No caller relied on the old behavior.

Test (tests/conformance/configuration-occ.test.mjs:171):

  • It runs the real OCC and the Kubernetes compute Driver's workspace admission.
  • It marks the setup completed through workspaceSetups.complete, the same store method the worker calls (apps/controller/src/worker.ts:6456).
  • It covers the omitted ID, the restated ID, the restated execution mode, and a genuinely different Configuration (:246, still refused).

Verification (on a remote test VM, this head):

  • The whole file passes 33/33, with no skips.
  • Mutant: I restored input.configurationId !== agent.configurationId at :9637. Only the new test fails (32/33), with ConfigurationHarnessError: ... agents.defaults.workspace must be ... on the omitted-ID update.

Nit (optional): the Risks note is fair. A flag-only edit can still be saved while a Configuration edit has already made the next deployment invalid. That is the existing contract, and deployment refuses it.

CI Required and First Agent Smoke are green on this head.

# Conflicts:
#	docs/flows/workspace-files.md
@freeqaz

freeqaz commented Oct 27, 2026

Copy link
Copy Markdown
Collaborator

Free's clanker here (an AI agent working on Free's behalf). I merged current main into this branch (no rebase, no force-push) so it can land on a fresh base; the only conflict was the changelog and front matter in docs/flows/workspace-files.md, resolved by keeping both changelog entries. The review above stands; I'll land it once CI is green on the new head.

@clawsweeper clawsweeper Bot added P2 Normal priority bug or improvement with limited blast radius. proof: sufficient Contributor real behavior proof is sufficient. rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action. and removed clawsweeper:intake:bug Preliminary submission classification; full source review pending. labels Oct 27, 2026
@clawsweeper

clawsweeper Bot commented Oct 27, 2026

Copy link
Copy Markdown
Contributor

Codex review: needs changes before merge.

What this changes

This PR uses the resolved Configuration ID when deciding whether an Agent update must recheck completed workspace setup.

Example: After completed workspace setup, the same Configuration's workspace changes to /srv/experiment and an operator submits {"gatewayManagedMode":true}.

  • Before: Omitting configurationId incorrectly triggers topology admission and returns HTTP 400; restating the saved ID succeeds.
  • After: The omitted-ID update succeeds while incompatible Configuration or execution-mode changes remain rejected.

Review scores

Measure Result What it means
Overall readiness 🦐 gold shrimp (3/6) A narrow, well-supported runtime repair with one concrete documentation gate failure on the reviewed head.
Proof confidence 🦞 diamond lobster (5/6) Sufficient (terminal): Inspected CLI build metadata and parent/head transcripts exercise the shipped occ executable against real loopback Fastify, service-key authentication, Native IAM, and OCC, using in-memory platform and Configuration storage plus seeded completed-setup metadata. On 94a62c2 both omitted-ID variants succeed and incompatible topology changes remain rejected. The reviewed merge preserves the production and regression blobs. Evidence establishes this update path, without claiming worker execution, runtime deployment, or PostgreSQL durability.
Patch quality 🦐 gold shrimp (3/6) 1 actionable review finding remain.

Product

Kind: Bug fix · Worth it: Yes · Fix scope: Complete
User problem: A supported Gateway managed-mode update fails with an unrelated workspace error unless the caller repeats the unchanged Configuration ID.
Reason: The repair restores the established editing contract, and collaborator freeqaz explicitly approved its direction.

Regression provenance

Possible regression — probable (reviewed change; failure trace). No predecessor PR is attributed.

Merge readiness

⛔ Needs changes before merge - 1 item remains

Keep open: the focused runtime fix restores intended partial-update behavior, but the merged head exceeds the documentation word limit and fails its documentation check.

Priority: P2
Reviewed head: 9f653d7bd629486f438d47fc87e4e7ec5adc4c44

Before merge

  • Trim the flow page below the documentation word limit (P2) - On the reviewed merged head, this paragraph and the retained changelog addition raise the page from 2,467 to 2,518 counted words. AGENTS.md sets a hard limit of 2,500, and the exact-head Suite Audit and Static Checks job fails at documentation checking. The pre-merge PR page was below the limit, so this is newly exposed by the combined content. Shorten surrounding prose while preserving the new update semantics and existing security and lifecycle requirements.

Findings

  • [P2] Trim the flow page below the documentation word limit — docs/flows/workspace-files.md:87-90
Agent review details

How this fits together

CLI and Console requests enter the Agent PATCH route, which invokes OCC authorization, topology admission, transactional storage, and audit recording.

flowchart LR
  A[CLI or Console] --> B[Agent PATCH route]
  B --> C[OCC updateAgent]
  C --> D[Native IAM authorization]
  C --> E[Compute topology admission]
  C --> F[Agent storage and audit]
Loading

Technical review

Best possible solution:

Keep the resolved-ID repair and regression, and trim the existing flow page below 2,500 words without removing its admission boundaries.

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

Current-main source establishes the false topology change, and supplied parent CLI traces show both omitted-ID failures; this review ran no application behavior or tests.

Is this the best way to solve the issue?

Using the already resolved ID is the smallest complete repair and preserves pending-setup checks, actual topology-change checks, deployment admission, IAM, and audit.

Full review comments:

  • [P2] Trim the flow page below the documentation word limit — docs/flows/workspace-files.md:87-90
    On the reviewed merged head, this paragraph and the retained changelog addition raise the page from 2,467 to 2,518 counted words. AGENTS.md sets a hard limit of 2,500, and the exact-head Suite Audit and Static Checks job fails at documentation checking. The pre-merge PR page was below the limit, so this is newly exposed by the combined content. Shorten surrounding prose while preserving the new update semantics and existing security and lifecycle requirements.
    Confidence: 0.99

Overall correctness: patch is incorrect
Overall confidence: 0.98

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against 09e9cb6e4a45.

Provenance checked

  • Completed workspace topology admission keeps the original intent (ba0baf0: Reject actual Configuration or execution-mode changes that deployment would refuse while leaving unrelated Agent edits possible.)
  • Optional Configuration ID during Agent updates keeps the original intent (110aea3: Support managed-mode-only requests by resolving an omitted Configuration ID to the Agent's saved ID.)

Testing

Proof path: shipped entry point.

Security

None.

Evidence

Acceptance criteria:

  • pnpm docs:check
  • pnpm format:check
  • git diff --check

What I checked:

Likely related people:

  • Free Wortley: Raw commit ba0baf0 adds packages/occ/src/index.ts:9110 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: ba0baf089734; files: packages/occ/src/index.ts)
  • kevinlin-openai: Raw commit cee299c adds docs/flows/workspace-files.md:84 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: medium; commits: cee299ce8147; files: docs/flows/workspace-files.md)

Review metrics

Metric Value Why it matters
Patch scope Production +1/-1; tests +84/-0; documentation +8/-2 The regression covers omitted and explicit identities plus genuine topology changes without adding production machinery.

Labels

Label changes:

  • add P2: The repair addresses a supported administrative update rejected under a bounded completed-workspace and edited-Configuration condition.
  • add proof: sufficient: Contributor real behavior proof is sufficient.
  • add rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦞 diamond lobster and patch quality is 🦐 gold shrimp.
  • add status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action.

Label justifications:

  • P2: The repair addresses a supported administrative update rejected under a bounded completed-workspace and edited-Configuration condition.
  • rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦞 diamond lobster and patch quality is 🦐 gold shrimp.
  • status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action.
  • 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.

Reviewed October 26, 2026, 8:32 PM ET / October 27, 2026, 00:32 UTC.

…history page

The merged flow doc reached 2,516 words, over the 2,500-word limit. The repo keeps older
dated entries on the history page, so the two oldest move there (2,495 words).
@freeqaz

freeqaz commented Oct 27, 2026

Copy link
Copy Markdown
Collaborator

Free's clanker here (an AI agent working on Free's behalf). After the main merge, docs/flows/workspace-files.md came to 2,516 words, over the 2,500-word limit, and Suite Audit and Static Checks failed on it. I pushed one docs-only commit (20de9e7) that moves the two 10-10 changelog entries to workspace-files/history.md, the repo's place for older entries. Your paragraph is unchanged and the page is now 2,495 words. docs:check and Prettier pass locally.

@freeqaz
freeqaz merged commit 7f29917 into openclaw:main Oct 27, 2026
38 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

P2 Normal priority bug or improvement with limited blast radius. proof: sufficient Contributor real behavior proof is sufficient. rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Mode-only Agent updates mistake an omitted Configuration ID for a topology change

2 participants