perf(cli): lazy-load agents actions for help by frankekn · Pull Request #84483 · openclaw/openclaw

frankekn · 2026-05-20T07:10:04Z

Summary

Problem: openclaw agents --help imported the full agents action barrel and paid heavy startup cost on a help-only path.
Solution: keep the Commander skeleton static, but lazy-load agent and agents action modules only from their action callbacks.
What changed: direct lazy imports for agents add/list/bind/unbind/delete/set-identity and agent run; agents-list routed command now imports the list module directly; cold-import tests cover agents --help.
What did NOT change (scope boundary): no agents command behavior, docs link, option, routing, or generic subcommand help changes.

Motivation

Before this patch, agents --help measured at ~1.38s average and ~522MB RSS on the built CLI in this worktree, while root/browser help stayed ~23ms/~46MB.
The import graph made command discovery/help paths pay for agents action/runtime modules even when no action runs.

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

Related #
This PR fixes a bug or regression

Real behavior proof (required for external PRs)

Behavior or issue addressed: openclaw agents --help cold-start import/runtime cost.
Real environment tested: local macOS worktree, Node v24.14.0, built openclaw.mjs entry.
Exact steps or command run after this patch: pnpm build; node dist/entry.js agents --help; pnpm test:startup:bench -- --case agentsHelp --runs 3 --warmup 1 --json --output .artifacts/perf-agents-help-after.json.
Evidence after fix: benchmark after patch averaged 361.2ms, p95 433.4ms, RSS avg 321.7MB.
Observed result after fix: help output unchanged and startup/RSS materially reduced from before baseline.
What was not tested: full pnpm test suite.
Before evidence: before benchmark averaged 1382.0ms, p95 1423.1ms, RSS avg 522.4MB.

Root Cause (if applicable)

Root cause: register.agent.ts statically imported agent-via-gateway and the commands/agents.ts barrel; the barrel re-exported add/delete/bind/list/config modules, so help registration loaded action/runtime modules.
Missing detection / guardrail: no cold-import test covered agents --help.
Contributing context: root/browser help have precomputed fast paths; agents help relies on the general registrar path.

Regression Test Plan (if applicable)

Coverage level that should have caught this:
- Unit test
- Seam / integration test
- End-to-end test
- Existing coverage already sufficient
Target test or file: src/cli/help-cold-imports.test.ts, src/cli/program/register.agent.test.ts.
Scenario the test should lock in: agents --help does not import agent/agents action modules, while action paths still call the same command functions.
Why this is the smallest reliable guardrail: it tests the registrar import boundary directly without process-level timing noise.
Existing test that already covers this (if any): none for agents help cold imports.
If no new test is added, why not: N/A.

User-visible / Behavior Changes

openclaw agents --help starts faster and uses less memory. Help text and command behavior are unchanged.

Diagram (if applicable)

Before:
agents --help -> register.agent.ts -> commands/agents.ts barrel -> action modules loaded

After:
agents --help -> register.agent.ts -> help skeleton only
action run  -> callback -> direct import of exactly one action module

Security Impact (required)

New permissions/capabilities? No
Secrets/tokens handling changed? No
New/changed network calls? No
Command/tool execution surface changed? No
Data access scope changed? No
If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

OS: macOS
Runtime/container: Node v24.14.0, local pnpm workspace
Model/provider: N/A
Integration/channel (if any): N/A
Relevant config (redacted): N/A

Steps

pnpm build
node dist/entry.js agents --help > .artifacts/agents-help-after.txt
diff -u .artifacts/agents-help-before.txt .artifacts/agents-help-after.txt
pnpm test:startup:bench -- --case agentsHelp --runs 3 --warmup 1 --json --output .artifacts/perf-agents-help-after.json

Expected

Help output unchanged.
agents --help avoids loading heavy agents action modules.
Startup time/RSS materially drop.

Actual

Help output diff was empty.
agents --help benchmark improved from 1382.0ms avg / 522.4MB RSS avg to 361.2ms avg / 321.7MB RSS avg.
Cold-import tests pass.

Evidence

Failing test/log before + passing after
Trace/log snippets
Screenshot/recording
Perf numbers (if relevant)

Human Verification (required)

Verified scenarios:
- pnpm test src/cli/help-cold-imports.test.ts src/cli/program/register.agent.test.ts src/cli/run-main.exit.test.ts -- --reporter=default
- pnpm build
- diff -u .artifacts/agents-help-before.txt .artifacts/agents-help-after.txt
- pnpm test:startup:bench -- --case agentsHelp --runs 3 --warmup 1 --json --output .artifacts/perf-agents-help-after.json
- pnpm tsgo
- pnpm check:changed
Edge cases checked: parent agents default action still calls list; lazy-loaded action failures still route through runtime error handling; routed agents-list avoids the barrel.
What you did not verify: full test suite and CI.

Review Conversations

I replied to or resolved every bot review conversation I addressed in this PR.
I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

Backward compatible? Yes
Config/env changes? No
Migration needed? No
If yes, exact upgrade steps: N/A

Risks and Mitigations

Risk: lazy imports could accidentally route an action to the wrong module.
- Mitigation: existing registrar tests now mock direct module paths and verify each action still calls the expected command function.

clawsweeper · 2026-05-20T07:11:45Z

Codex review: needs maintainer review before merge.

Workflow note: Future ClawSweeper reviews update this same comment in place.

How this review workflow works

ClawSweeper keeps one durable marker-backed review comment per issue or PR.
Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
Maintainers can also comment @clawsweeper review to request a fresh review only.
Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

Summary
The branch lazy-loads agents CLI action modules from callbacks, routes agents-list to the list command module, removes the internal agents command barrel, and updates cold-import/routing tests plus the changelog.

Reproducibility: yes. Current main source shows agents --help registration loads the agents action barrel, and the PR body gives before/after built-CLI benchmark commands and numbers; I did not rerun commands in this read-only review.

PR rating
Overall: 🦞 diamond lobster
Proof: 🌊 off-meta tidepool
Patch quality: 🦞 diamond lobster
Summary: Focused performance refactor with current-main root-cause evidence, strong reported benchmark proof, targeted regression coverage, and no blocking findings.

What the crustacean ranks mean

🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Real behavior proof
Not applicable: The external-contributor proof gate does not apply to this MEMBER, maintainer-labeled PR, though the body includes useful built-CLI benchmark commands and after-fix numbers.

Risk before merge

Required checks and explicit maintainer review remain the merge gate because this protected PR changes CLI command dispatch even though the added tests cover the action mappings.

Maintainer options:

Decide the mitigation before merge
Land the lazy-load refactor after maintainer review and required checks, keeping the direct import tests as the regression guardrail.
Pause or close
Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge
The PR is protected and review-clean, so the remaining action is maintainer review and required-check completion rather than automated repair.

Security
Cleared: The diff only changes CLI import timing, route wiring, tests, and changelog text; no security or supply-chain surface was added.

Review details

Best possible solution:

Land the lazy-load refactor after maintainer review and required checks, keeping the direct import tests as the regression guardrail.

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

Yes. Current main source shows agents --help registration loads the agents action barrel, and the PR body gives before/after built-CLI benchmark commands and numbers; I did not rerun commands in this read-only review.

Is this the best way to solve the issue?

Yes. Callback-time direct imports are a narrow maintainable fix because they preserve the Commander help skeleton and existing command behavior while avoiding help-time action module loading.

Label justifications:

P2: This is a normal-priority CLI performance improvement with limited blast radius and targeted regression coverage.
rating: 🦞 diamond lobster: Current PR rating is 🦞 diamond lobster because proof is 🌊 off-meta tidepool, patch quality is 🦞 diamond lobster, and Focused performance refactor with current-main root-cause evidence, strong reported benchmark proof, targeted regression coverage, and no blocking findings.
status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The external-contributor proof gate does not apply to this MEMBER, maintainer-labeled PR, though the body includes useful built-CLI benchmark commands and after-fix numbers.

What I checked:

Protected PR state: Provided GitHub context shows this PR is open, author association is MEMBER, and labels include maintainer, so cleanup policy keeps it open for explicit maintainer handling. (113a23575e2f)
Current main import-cost path: Current main statically imports agent-via-gateway and the commands/agents.js barrel at module load time in the agents registrar, so registering agents --help loads action modules before any action runs. (src/cli/program/register.agent.ts:2, a30ac3f8d7cb)
PR lazy-load implementation: The PR head replaces static action imports with typed dynamic import helpers and calls them from command callbacks, preserving the Commander skeleton for help output. (src/cli/program/register.agent.ts:11, 113a23575e2f)
Cold-import guardrail: The PR adds mocks for every agents action module and a agents --help test that asserts none of those action modules load on the help-only path. (src/cli/help-cold-imports.test.ts:153, 113a23575e2f)
Routed command fix: The agents-list routed command uses a lazy loader for agents.commands.list.js instead of importing the removed barrel. (src/cli/program/routed-command-definitions.ts:45, 113a23575e2f)
Barrel removal consistency: A PR-tree grep for remaining commands/agents.js imports returned no matches, supporting that the deleted internal barrel is not still referenced in the branch. (src/commands/agents.ts:1, 113a23575e2f)

Likely related people:

steipete: Blame shows the current agents registrar was added in d1470360c4, and history shows the earlier agents command split in a58ff1ac63. (role: current file introducer and CLI command-split contributor; confidence: high; commits: d1470360c4, a58ff1ac63, 4ee41cc6f3; files: src/cli/program/register.agent.ts, src/commands/agents.commands.list.ts, src/commands/agents.config.ts)
frankekn: Merged commit 2c0c9c92 added the same lazy-import/cold-import pattern for setup, onboard, and configure help startup immediately before this PR branch. (role: recent adjacent CLI help-performance contributor; confidence: high; commits: 2c0c9c92, 31de4f43, 113a23575; files: src/cli/help-cold-imports.test.ts, src/cli/program/register.setup.ts, src/cli/program/register.onboard.ts)
Bob: Commit 6a705a37f2 changed the agents command/list/bind surfaces for persistent Discord channel and Telegram topic bindings, which are among the action paths preserved by this PR. (role: agent bindings feature contributor; confidence: medium; commits: 6a705a37f2; files: src/commands/agents.commands.bind.ts, src/commands/agents.commands.list.ts, src/commands/agents.bindings.ts)

Codex review notes: model gpt-5.5, reasoning high; reviewed against a30ac3f8d7cb.

clawsweeper · 2026-05-20T07:16:40Z

ClawSweeper PR egg

✨ Hatched: 🥚 common Neon Signal Puff

Hatch command

Comment @clawsweeper hatch when this PR is hatchable.

Hatchability rules:

Merged PRs are hatchable.
Open PRs are hatchable when they are status: 👀 ready for maintainer look, status: 🚀 automerge armed, or labeled clawsweeper:automerge.
Closed unmerged PRs are hatchable only when one of those hatchable labels is still present in the durable record.

Rarity: 🥚 common.
Trait: stacks clean commits.
Image traits: location artifact grotto; accessory commit compass; palette amber, ink, and glacier blue; mood determined; pose nestled inside a glowing shell; shell matte ceramic shell; lighting soft studio lighting; background quiet workflow signs.
Share on X: post this hatch
Copy: My PR egg hatched a 🥚 common Neon Signal Puff in ClawSweeper.

What is this egg doing here?

Eggs appear after the PR passes real-behavior proof. It is here for vibes, not verdicts: it does not change labels, ratings, merge decisions, or automation.
The shell reacts to review momentum: open follow-up work warms it up, re-review makes it wobble, and a clean final review lets it hatch.
Hatchability usually comes from sufficient real-behavior proof, no blocking P0/P1/P2 findings, no security attention needed, and clean correctness. A merged PR is already final, so merge makes the egg hatchable independently.
The hatch is seeded from this repository and PR number, so the same PR keeps the same creature; the reviewed head SHA can only change safe visual details.
Rarity is just collectible sparkle: 🥚 common, 🌱 uncommon, 💎 rare, ✨ glimmer, and 🌈 legendary.

frankekn · 2026-05-20T07:40:47Z

@codex review

Addressed the stale route-test mock finding:

src/cli/program/routes.test.ts now mocks ../../commands/agents.commands.list.js.
The old ../../commands/agents.js mock now throws if the routed agents-list path imports the barrel again.

Local verification after the repair:

pnpm test src/cli/program/routes.test.ts src/cli/help-cold-imports.test.ts src/cli/program/register.agent.test.ts src/cli/run-main.exit.test.ts -- --reporter=default
# 4 files passed, 132 tests passed

pnpm check:changed
# passed

hxy91819

LGTM overall. This is a typical and appropriate Node/ESM CLI cold-start optimization: moving the heavy command implementations from static registration-time imports to action-time dynamic imports keeps the help path light, while preserving the existing command behavior and not changing any public SDK contract.

One thing I would recommend fixing before merge: the refactor appears to leave src/commands/agents.ts as a production-dead barrel. The direct lazy imports now target the individual agents.commands.* modules, so this aggregate re-export file no longer seems to be used by the production graph, and CI is flagging it as an unexpected unused file. Please either remove that barrel and update the remaining tests/mocks to use the direct modules, or restore an intentional production use if the barrel is meant to remain.

Lazy-load agents CLI action modules from command callbacks so agents --help avoids importing the full agents runtime. Validated by GitHub required checks and local focused CLI gates.

openclaw-barnacle Bot added cli CLI command changes size: M maintainer Maintainer-authored PR labels May 20, 2026

clawsweeper Bot added 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. P2 Normal backlog priority with limited blast radius. labels May 20, 2026

hxy91819 reviewed May 20, 2026

View reviewed changes

frankekn self-assigned this May 20, 2026

openclaw-barnacle Bot added the commands Command implementations label May 20, 2026

frankekn force-pushed the perf-01-agents-help branch from 45d260b to ce19662 Compare May 21, 2026 03:08

frankekn added 3 commits May 21, 2026 11:28

perf(cli): lazy-load agents actions for help

31de4f4

test(cli): update agents route mock

03b521a

chore(cli): remove unused agents barrel

364a8b3

frankekn force-pushed the perf-01-agents-help branch from ce19662 to 364a8b3 Compare May 21, 2026 03:32

docs(changelog): credit agents help perf fix

113a235

frankekn merged commit 168f8a7 into main May 21, 2026
99 checks passed

frankekn deleted the perf-01-agents-help branch May 21, 2026 04:35

github-actions Bot mentioned this pull request May 21, 2026

📡 Upstream Digest — 2026-05-21 07:42 UTC curtismercier/openclaw-mods#906

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

perf(cli): lazy-load agents actions for help#84483

perf(cli): lazy-load agents actions for help#84483
frankekn merged 4 commits into
mainfrom
perf-01-agents-help

frankekn commented May 20, 2026

Uh oh!

clawsweeper Bot commented May 20, 2026 •

edited

Loading

Uh oh!

clawsweeper Bot commented May 20, 2026 •

edited

Loading

Uh oh!

frankekn commented May 20, 2026

Uh oh!

hxy91819 left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Uh oh!

Conversation

frankekn commented May 20, 2026

Summary

Motivation

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

Real behavior proof (required for external PRs)

Root Cause (if applicable)

Regression Test Plan (if applicable)

User-visible / Behavior Changes

Diagram (if applicable)

Security Impact (required)

Repro + Verification

Environment

Steps

Expected

Actual

Evidence

Human Verification (required)

Review Conversations

Compatibility / Migration

Risks and Mitigations

Uh oh!

clawsweeper Bot commented May 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

clawsweeper Bot commented May 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Hatch command

Uh oh!

frankekn commented May 20, 2026

Uh oh!

hxy91819 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

clawsweeper Bot commented May 20, 2026 •

edited

Loading

clawsweeper Bot commented May 20, 2026 •

edited

Loading