refactor(cli): unify agent installation lifecycle by PsiACE · Pull Request #2052 · oceanbase/powercontext

PsiACE · 2026-10-18T07:06:36Z

Which issue or RFC does this PR close?

Related to #1713 (setup usability).

Rationale for this change

Agent installers duplicate lifecycle orchestration. Share the flow and keep native behavior in thin adapters, removing 2,579 lines of runtime code overall.

What changes are included in this PR?

Adapters expose four operations:

install(source: PluginSource) -> dict: install the native package.
configure(connection: SetupTransport) -> dict: update its connection settings.
Optional enable(): initialize native activation while preserving explicit preferences.
verify(**native_options) -> dict[str, Diagnostic]: collect host checks; doctor owns final diagnostics.

setup [agents...] -> select + validate
                     |
                     `-> per agent: install -> configure -> [enable] -> doctor
                                                                        |
                                                               verify + Server checks

config agent [agents...] ----------> configure
doctor [agents...] ---------------> verify + Server checks

Failures stay isolated per agent, with completed stages reported. Connection files and credentials share one rollback boundary, with atomic replacement for readers. Setup rejects replacing missing targets with unresolved recovery backups and reports where to restore them. Pi restores the previous package if native installation fails; repeated setup removes replaced user-level registrations. Desktop diagnostics use the new doctor contract. Unused installation prediction, duplicate writers and internal-only assertions are removed. Affected CLI guides use the new commands. Shared Skills/MCP distribution is separate from this PR.

Are there any user-facing changes?

setup codex claude-code completes installation, configuration and diagnostics in one command; interactive setup offers agent selection.
config agent updates installed connections without reinstalling or enabling plugins. doctor checks selected or saved agents, falling back to Server diagnostics when none are saved.
Breaking: removes setup select, doctor integrations and legacy Skill hash migrations. Unsupported installed diagnostic probes require rerunning setup; unrecognized existing content is preserved and rejected explicitly.

How was this change tested?

Focused lifecycle, connection, credential and adapter behavior checks: 324 passed, 1 skipped.
make check and make docs-test passed; 942 public pages and internal links verified.
Native DSH: 11 runtime workflows and 8 setup workflows passed against a real fixture Server. Configuration checks also passed against the installed CLI and pinned native API.
Native Pi 0.82.1: replaced checkout registration removed; repeated setup leaves one package. Native Codex: explicit disablement preserved.
Desktop frontend checks and isolated Rust diagnostics passed; Windows acceptance runs in CI.

AI usage statement

Codex assisted implementation; GPT-6 Astra (xhigh) assisted design and review.

Copilot

🟡 Changes recommended

Pi upgrade recovery and shared publication safeguards remain unresolved.

3 open issues

What changed in this PR

Unifies agent installation, configuration, and diagnostics behind a shared CLI lifecycle, supporting the setup-usability work in #1713.

Changes:

Adds multi-agent setup and configuration with isolated per-agent results.
Centralizes publication, transport settings, credentials, and source handling.
Updates diagnostics, guidance manifests, tests, and bilingual documentation.

File	Description
tests/test_setup_rollback.py	Tests publication rollback.
tests/test_pi_cli.py	Updates Pi lifecycle tests.
tests/test_opencode_installation.py	Uses shared installation flow.
tests/test_native_transport_diagnostics.py	Removes obsolete Codex cache tests.
tests/test_integration_manifest.py	Checks installer catalog coverage.
tests/test_installation.py	Adds lifecycle recovery tests.
tests/test_hermes_cli.py	Tests activation preferences and retries.
tests/test_guidance_installation.py	Uses shared installation entry point.
tests/test_guidance_generation.py	Updates guidance compatibility tests.
tests/test_dsh_transport.py	Updates native transport tests.
tests/test_dsh_profiles.py	Tests saved target reuse.
tests/test_dsh_cli.py	Updates DSH diagnostic assertions.
tests/test_doctor_integrations.py	Removes retired command tests.
tests/test_config_wizard_agents.py	Removes obsolete catalog assertion.
tests/test_cli_kimi_code.py	Tests configuration and readiness behavior.
tests/test_authorization.py	Updates authorization API tests.
tests/test_agent_lifecycle_cli.py	Adds multi-agent CLI tests.
tests/install_support.py	Adds installer test helpers.
tests/e2e/zcode_acceptance/runner.py	Uses shared setup entry point.
tests/e2e/test_workbuddy_service_chain.py	Exercises setup, configuration, and doctor.
tests/e2e/test_kimi_code_host.py	Uses installer adapter APIs.
tests/e2e/test_codex_native_mcp_live.py	Uses Codex verification adapter.
tests/e2e/atomic_memory_models.py	Handles readiness inference probes.
tests/conftest.py	Adds lifecycle test fixtures.
src/powercontext/client/transport_policy.py	Loads saved DSH target settings.
src/powercontext/cli/transport.py	Combines connection and credential publication.
src/powercontext/cli/pi.py	Introduces Pi lifecycle adapter.
src/powercontext/cli/native_transport.py	Updates native endpoint discovery.
src/powercontext/cli/installation.py	Adds shared lifecycle and publication helpers.
src/powercontext/cli/guidance.py	Simplifies package recognition and guidance ownership.
src/powercontext/cli/git_source.py	Centralizes plugin source resolution.
src/powercontext/cli/dsh_transport.py	Removes candidate installation prediction.
src/powercontext/cli/dsh_runtime.py	Reuses saved native targets.
src/powercontext/cli/dsh_config.mjs	Simplifies native configuration inspection.
src/powercontext/cli/config.py	Adds `config agent`.
src/powercontext/cli/config_wizard_agents.py	Uses its own metadata catalog.
src/powercontext/cli/authorization.py	Prepares credentials for shared publication.
src/powercontext/cli/app.py	Registers callback-only command applications.
scripts/integration_guidance_skills.py	Generates manifests without legacy hashes.
scripts/guidance_templates/legacy.json	Removes legacy migration hashes.
integrations/zcode/plugins/powercontext/tests/observations.test.mjs	Updates readiness fixture.
integrations/zcode/plugins/powercontext/skills/powercontext-project-context/.powercontext-guidance.json	Removes legacy hashes.
integrations/zcode/plugins/powercontext/scripts/doctor.mjs	Validates readiness and emits v2 diagnostics.
integrations/workbuddy/plugins/powercontext/skills/powercontext-project-context/.powercontext-guidance.json	Removes legacy hashes.
integrations/pi/plugins/powercontext/skills/powercontext-project-context/.powercontext-guidance.json	Removes legacy hashes.
integrations/opencode/plugins/powercontext/skills/powercontext-project-context/.powercontext-guidance.json	Removes legacy hashes.
integrations/openclaw/plugins/memory-powercontext/skills/powercontext-project-context/.powercontext-guidance.json	Removes legacy hashes.
integrations/minimax/plugins/powercontext/skills/powercontext-project-context/.powercontext-guidance.json	Removes legacy hashes.
integrations/kimi-code/plugins/powercontext/tests/plugin.test.mjs	Updates readiness fixture.
integrations/kimi-code/plugins/powercontext/skills/powercontext-project-context/.powercontext-guidance.json	Removes legacy hashes.
integrations/kimi-code/plugins/powercontext/scripts/doctor.mjs	Preserves degraded readiness in v2 diagnostics.
integrations/hermes/plugins/powercontext/skills/powercontext-project-context/.powercontext-guidance.json	Removes legacy hashes.
integrations/dsh/plugins/powercontext/tests/runtime/setup.test.mjs	Updates native setup scenarios.
integrations/dsh/plugins/powercontext/tests/runtime/setup-fixture.mjs	Supplies Server URL and unwraps host results.
integrations/dsh/plugins/powercontext/tests/runtime/runtime.test.mjs	Uses updated setup fixture.
integrations/codex/plugins/powercontext/skills/powercontext-project-context/.powercontext-guidance.json	Removes legacy hashes.
integrations/claude-code/plugins/powercontext/skills/powercontext-project-context/.powercontext-guidance.json	Removes legacy hashes.
integrations/agent-plugin/powercontext/skills/powercontext-project-context/.powercontext-guidance.json	Removes legacy hashes.
evaluation/zcode_guidance/skill-lock.json	Refreshes guidance lock metadata.
evaluation/zcode_guidance/run.py	Uses shared setup entry point.
evaluation/skills/skill-up/vendor/powercontext-project-context/.powercontext-guidance.json	Removes vendored legacy hashes.
evaluation/skills/skill-up/skill-lock.json	Refreshes guidance lock metadata.
docs/zh/docs/operate/troubleshoot.md	Documents updated diagnostics.
docs/zh/docs/operate/connect-remote-server.md	Documents multi-agent connection commands.
docs/zh/docs/integrations/workbuddy.md	Documents shared lifecycle support.
docs/zh/docs/integrations/index.md	Updates setup and configuration guidance.
docs/zh/docs/integrations/codex.md	Clarifies setup diagnostic results.
docs/zh/docs/develop/interfaces.md	Documents new CLI contract.
docs/en/docs/operate/troubleshoot.md	Documents updated diagnostics.
docs/en/docs/operate/connect-remote-server.md	Documents multi-agent connection commands.
docs/en/docs/integrations/workbuddy.md	Documents shared lifecycle support.
docs/en/docs/integrations/index.md	Updates setup and configuration guidance.
docs/en/docs/integrations/codex.md	Clarifies setup diagnostic results.
docs/en/docs/develop/interfaces.md	Documents new CLI contract.
desktop/ui/src/generated/ipc.ts	Replaces host presence with status.
desktop/ui/src/app/Diagnostics.tsx	Displays host diagnostic status.
desktop/src-tauri/tests/diagnostics.rs	Tests updated diagnostic projection.
desktop/src-tauri/src/diagnostics.rs	Adopts multi-agent doctor output.
desktop/src-tauri/examples/diagnostic_cli_probe.rs	Expects ten host results.
desktop/README.zh.md	Documents updated diagnostic invocation.
desktop/README.md	Documents updated diagnostic invocation.
.github/workflows/master.yml	Removes obsolete test selection.

_{Review effort: Balanced}

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.

hireview001

CI failed: windows-unit-portability (failure).
CI failed: Main (failure). Failed steps: windows-unit-portability / Verify managed guidance and exact rollback bytes on Windows.

Reject unsupported ZCode paths before publishing plugins. Preserve fresh and existing installations on invalid connection input, and decode rollback errors before matching Windows recovery paths.

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.

hidb4ai

The CLI-only setup/doctor regression needs fixing. Inline comments also cover a lower-priority Hermes documentation mismatch.

hidb4ai · 2026-10-19T10:00:12Z

please update & resolve conflicts

Merge master and retain Kimi workspace Scope support in the shared lifecycle. Skip unavailable optional service inspection so HTTP health checks can run, and correct Hermes provider selection guidance.

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.

hidb4ai

LGTM

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.

hireview001

Resolve merge conflicts with the target branch.

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.

PsiACE added the 1.5.0 v1.5.0 release tracking label Oct 18, 2026

PsiACE force-pushed the refactor/agent-install-lifecycle branch 3 times, most recently from 9f9629d to ccff14a Compare October 18, 2026 07:55

PsiACE added 2 commits October 18, 2026 16:27

refactor(cli): unify agent setup through thin native adapters

2da90ac

refactor(cli): remove legacy migrations and implementation-only tests

1ff19cc

PsiACE force-pushed the refactor/agent-install-lifecycle branch from ccff14a to 1226e01 Compare October 18, 2026 08:28

PsiACE marked this pull request as ready for review October 18, 2026 08:46

Copilot AI balanced review requested due to automatic review settings October 18, 2026 08:46

PsiACE requested review from Alanxtl, AlexStocks, Zxf-xufeng, frf12, frostming, knqiufan, yihong0618 and zhanghuidinah as code owners October 18, 2026 08:46

Copilot started reviewing on behalf of PsiACE October 18, 2026 08:47

View session

Copilot AI reviewed Oct 18, 2026

View reviewed changes

Comment thread src/powercontext/cli/pi.py Outdated

Comment thread src/powercontext/cli/installation.py

Comment thread src/powercontext/cli/installation.py Outdated

fix(cli): preserve setup state and align acceptance checks

d492cab

Copilot AI balanced review requested due to automatic review settings October 18, 2026 09:30

PsiACE force-pushed the refactor/agent-install-lifecycle branch from 1226e01 to d492cab Compare October 18, 2026 09:30

Copilot AI reviewed Oct 18, 2026

AlexStocks reviewed Oct 18, 2026

View reviewed changes

Comment thread scripts/integration_guidance_skills.py

fix(cli): preserve recovery backups before setup retries

e5b9ba0

Copilot AI balanced review requested due to automatic review settings October 18, 2026 19:38

Copilot AI reviewed Oct 18, 2026

hireview001 reviewed Oct 19, 2026

View reviewed changes

Comment thread src/powercontext/cli/zcode.py Outdated

PsiACE added 2 commits October 19, 2026 11:57

chore: merge master into agent lifecycle branch

ff4b0a2

fix(cli): validate ZCode origins before installation

e2b35ea

Reject unsupported ZCode paths before publishing plugins. Preserve fresh and existing installations on invalid connection input, and decode rollback errors before matching Windows recovery paths.

Copilot AI reviewed Oct 19, 2026

hireview001 reviewed Oct 19, 2026

View reviewed changes

Comment thread src/powercontext/cli/system.py Outdated

fix(cli): preserve agent lifecycle state during setup

5ecdbc4

Copilot AI balanced review requested due to automatic review settings October 19, 2026 06:29

Copilot AI reviewed Oct 19, 2026

PsiACE mentioned this pull request Oct 19, 2026

bug: flaky trace assertion in scheduler activation test #2071

Closed

1 task

hidb4ai reviewed Oct 19, 2026

View reviewed changes

Comment thread src/powercontext/cli/hosts.py

Comment thread src/powercontext/cli/hermes.py

fix(cli): keep agent diagnostics usable with CLI-only installs

62f2bac

Merge master and retain Kimi workspace Scope support in the shared lifecycle. Skip unavailable optional service inspection so HTTP health checks can run, and correct Hermes provider selection guidance.

Copilot AI balanced review requested due to automatic review settings October 19, 2026 10:11

Copilot AI reviewed Oct 19, 2026

hidb4ai approved these changes Oct 19, 2026

View reviewed changes

AlexStocks reviewed Oct 19, 2026

View reviewed changes

Comment thread src/powercontext/cli/kimi_code.py

fix(e2e): align Kimi harness setup with agent lifecycle

42069c5

Copilot AI balanced review requested due to automatic review settings October 19, 2026 11:53

Copilot AI reviewed Oct 19, 2026

PsiACE mentioned this pull request Oct 19, 2026

bug: flaky ZCode pending boundary timeout assertion #2080

Closed

1 task

PsiACE requested a review from AlexStocks October 19, 2026 13:19

hireview001 reviewed Oct 20, 2026

View reviewed changes

Comment thread src/powercontext/cli/zcode.py Outdated

Comment thread src/powercontext/cli/config.py

fix(cli): validate and rebind ZCode authorization

b077ba2

Copilot AI balanced review requested due to automatic review settings October 20, 2026 04:22

Copilot AI reviewed Oct 20, 2026

hireview001 reviewed Oct 20, 2026

View reviewed changes

Comment thread src/powercontext/cli/kimi_code.py Outdated

PsiACE added 2 commits October 20, 2026 14:05

merge: sync master into agent lifecycle branch

4a4055e

fix(cli): respect MCP endpoints and managed guidance

6f13640

Copilot AI balanced review requested due to automatic review settings October 20, 2026 06:07

Copilot AI reviewed Oct 20, 2026

AlexStocks approved these changes Oct 20, 2026

View reviewed changes

AlexStocks merged commit 6159efa into master Oct 20, 2026
44 checks passed

PsiACE deleted the refactor/agent-install-lifecycle branch October 20, 2026 07:52

Conversation

PsiACE commented Oct 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Which issue or RFC does this PR close?

Rationale for this change

What changes are included in this PR?

Are there any user-facing changes?

How was this change tested?

AI usage statement

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

hireview001 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

hidb4ai left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

hidb4ai commented Oct 19, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

hidb4ai left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

hireview001 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

PsiACE commented Oct 18, 2026 •

edited

Loading