feat(signal): add setup wizard#100906
Conversation
Dependency graph guard clearedThis PR no longer has blocked dependency graph changes. A future dependency graph change requires a fresh
|
There was a problem hiding this comment.
Pull request overview
Adds a guided Signal channel setup wizard (with a recommended Docker/container path) and updates core channel setup flow to support “setup not applied” results so failed setup won’t persist misleading partial configuration.
Changes:
- Update
setupChannelsto supportsetupApplied: falseresults and roll back selection-time/config mutations instead of recording partial selections/accounts. - Extend Signal plugin setup with Docker container creation/reuse, readiness probing (daemon vs linked account vs receive), and account-scoped
apiMode. - Add a narrow plugin SDK QR-terminal subpath to let setup flows render QR codes without pulling broader media runtime surfaces; update docs/catalog metadata accordingly.
Reviewed changes
Copilot reviewed 42 out of 43 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| src/wizard/i18n/locales/en.ts | Tweaks Signal wizard prompt strings for clearer wording. |
| src/plugins/official-external-plugin-catalog.test.ts | Updates expected Signal catalog install metadata (min host version, default choice). |
| src/plugin-sdk/qr-terminal-runtime.ts | Adds narrow QR terminal rendering export for setup surfaces. |
| src/flows/channel-setup.ts | Honors setupApplied and introduces rollback behavior; adds brief progress paint delay around registry snapshot load. |
| src/flows/channel-setup.test.ts | Adds coverage for setupApplied/rollback semantics and progress rendering behavior. |
| src/config/zod-schema.providers-core.ts | Moves apiMode into the Signal account base schema to allow per-account overrides. |
| src/config/types.signal.ts | Adds account-scoped apiMode typing and clarifies channel-level apiMode semantics. |
| src/commands/channels/status.ts | Surfaces Signal probe readiness in text output and suppresses misleading “works” when not ready. |
| src/commands/channels.surfaces-signal-runtime-errors-channels-status-output.test.ts | Tests readiness bits and suppression of “works” for non-ready Signal probes. |
| src/channels/plugins/setup-wizard.ts | Plumbs setupApplied through setup-wizard finalize -> setup result. |
| src/channels/plugins/setup-wizard-types.ts | Extends finalize/result types with optional setupApplied. |
| src/channels/plugins/setup-wizard-helpers.ts | Renames “account” wording to “configuration” and improves prompt labels/placeholders. |
| src/channels/plugins/setup-wizard-helpers.test.ts | Updates tests for new “configuration” wording and adds new-account-name prompt coverage. |
| scripts/lib/plugin-sdk-entrypoints.json | Registers new qr-terminal-runtime plugin SDK entrypoint. |
| scripts/lib/plugin-sdk-doc-metadata.ts | Categorizes the new SDK subpath for docs. |
| scripts/lib/official-external-channel-catalog.json | Bumps Signal minHostVersion to match new surfaces. |
| package.json | Exposes ./plugin-sdk/qr-terminal-runtime in package exports. |
| extensions/signal/src/setup-surface.ts | Refactors Signal setup wizard status/prompting to support transport selection and delegated prepare/finalize. |
| extensions/signal/src/setup-core.ts | Implements transport choice, Docker/existing-server probing, rollback-on-cancel, per-account apiMode, and richer setup prompts/help. |
| extensions/signal/src/setup-container.ts | New Docker container setup runner: create/start container, QR/link flow, linked-account validation, and bounded fetch parsing. |
| extensions/signal/src/send.ts | Uses account-scoped apiMode (merged per-account config) and adds tests for apiMode fallback in typing/receipts overrides. |
| extensions/signal/src/send.test.ts | Adds tests for typing/read receipt apiMode fallback behavior. |
| extensions/signal/src/send-reactions.ts | Uses account-scoped apiMode for reaction sends. |
| extensions/signal/src/probe.ts | Adds readiness classification and container linked-account validation for probes. |
| extensions/signal/src/monitor.ts | Uses account-scoped apiMode and updates container/autoStart incompatibility error text. |
| extensions/signal/src/install-signal-cli.ts | Improves Homebrew install failure messaging with command echo + bounded stderr/stdout output. |
| extensions/signal/src/install-signal-cli.test.ts | Tests improved Homebrew failure messaging. |
| extensions/signal/src/core.test.ts | Adds broad coverage for setup wizard transports, probe readiness, container setup helpers, and new prompt/help behaviors. |
| extensions/signal/src/config-schema.test.ts | Updates schema test to accept per-account apiMode. |
| extensions/signal/src/client.ts | Adds native receive readiness check via SSE open/cleanup. |
| extensions/signal/src/client.test.ts | Tests native receive readiness behavior and failure modes. |
| extensions/signal/src/client-adapter.ts | Enhances auto mode detection/checking to include receive readiness and preserve receive-specific errors. |
| extensions/signal/src/client-adapter.test.ts | Adds coverage for receive-aware detection/checking behavior and error preservation. |
| extensions/signal/src/channel.ts | Surfaces readiness in capability probe formatting and passes account into probe. |
| extensions/signal/src/channel.setup.ts | Splits/defines a narrower setup-only plugin surface (vs full runtime plugin). |
| extensions/signal/setup-plugin-api.ts | New narrow setup entrypoint export. |
| extensions/signal/setup-entry.ts | Points bundled setup entry at the new setup-only API module. |
| extensions/signal/setup-entry.test.ts | Tests bundled setup entry loading and account-scoped config mutation helpers. |
| extensions/signal/package.json | Bumps Signal plugin minHostVersion to >=2026.6.11. |
| docs/plugins/sdk-subpaths.md | Documents the new plugin-sdk/qr-terminal-runtime subpath. |
| docs/channels/signal.md | Updates Signal channel docs for the new guided setup, Docker flow, and readiness states. |
| docs/.generated/plugin-sdk-api-baseline.sha256 | Updates SDK API baseline hashes due to new exported surface. |
|
Codex review: needs maintainer review before merge. Reviewed July 13, 2026, 6:45 PM ET / 22:45 UTC. Summary PR surface: Source +1635, Tests +3468, Docs +19, Generated 0. Total +5122 across 54 files. Reproducibility: not applicable. this is a feature and compatibility review rather than a report of one reproducible current-main failure. The changed paths are source-verifiable and have extensive exact-head automated coverage. Review metrics: 2 noteworthy metrics.
Stored data model Merge readiness Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch. Rank-up moves:
Risk before merge
Maintainer options:
Next step before merge
Maintainer decision needed
Security Review detailsBest possible solution: Land this as rebased, independently reviewable changes—shared cancellation/status plumbing, Signal setup/config scoping, then transport probing and routing—with fresh-install, upgrade, and live mixed-account send/receive/status evidence before the final merge. Do we have a high-confidence way to reproduce the issue? Not applicable: this is a feature and compatibility review rather than a report of one reproducible current-main failure. The changed paths are source-verifiable and have extensive exact-head automated coverage. Is this the best way to solve the issue? The plugin-owned architecture and additive cancellation contract are maintainable, but the combined conflicted landing shape is not the safest solution; the proposed stacked split with refreshed upgrade and live delivery proof is better. AGENTS.md: found and applied where relevant. Codex review notes: model internal, reasoning high; reviewed against 0b96300fc675. Label changesLabel changes:
Label justifications:
Evidence reviewedPR surface: Source +1635, Tests +3468, Docs +19, Generated 0. Total +5122 across 54 files. View PR surface stats
What I checked:
Likely related people:
What the crustacean ranks mean
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. How this review workflow works
Review history (30 earlier review cycles; latest 8 shown)
|
b29755e to
bc2f512
Compare
72899d7 to
37ea225
Compare
37ea225 to
7f68911
Compare
|
/clawsweeper re-review |
|
🦞🧹 I asked ClawSweeper to review this item again. |
7f68911 to
4c9acd8
Compare
|
🦞🧹 I asked ClawSweeper to review this item again. |
e07a22d to
86c2afa
Compare
|
/clawsweeper re-review |
|
🦞🧹 I asked ClawSweeper to review this item again. Re-review progress:
|
86c2afa to
7ff67ab
Compare
|
/clawsweeper re-review |
|
🦞🧹 I asked ClawSweeper to review this item again. Re-review progress:
|
7ff67ab to
949888f
Compare
949888f to
e3e20ca
Compare
e3e20ca to
a668bf0
Compare
40c76bc to
f5791bb
Compare
What Problem This Solves
Signal setup needed a guided path that proves a usable receive transport before users rely on the channel, without OpenClaw creating or managing a Signal Docker container. Existing setup and status paths could also leave stale native/container transport fields ambiguous, miss account-specific API-mode behavior, or report a Signal daemon as generically working when the configured account was missing or receive was unavailable.
Why This Change Was Made
The Signal plugin now owns a setup wizard for two supported transports: local
signal-cliand an existing Signal server managed by the operator. The same change tightens native/container/auto probing so setup and status distinguish transport reachability from account and receive readiness, and it lets multi-account Signal configs usechannels.signal.apiModeas a channel default with per-account overrides.The shared setup contract gains one additive cancellation result so a plugin can refuse to persist an unusable setup. Cancellation discards wizard-local channel changes and skips later hooks and completion notes while preserving accepted external-plugin installation metadata. This contract is documented in the plugin SDK setup guide.
Setup also materializes inherited root Signal transport fields into an account entry when that account is edited. This is migration-like config normalization, but it preserves the effective behavior while making the account's transport choice explicit; runtime still accepts the channel-level fields as defaults for untouched accounts.
User Impact
Users can run Signal setup, choose local
signal-clior an existing server URL, and save config only after the selected transport is reachable for the intended account. Operators get cleareropenclaw channels status --probeand health output for ready, account-missing, receive-unavailable, and unreachable Signal states.Existing/manual
bbernhard/signal-cli-rest-apideployments remain supported throughapiMode: "container". OpenClaw no longer offers an OpenClaw-managed Signal Docker setup path. Multi-account installations can mix native and container transports by overridingapiModeper account.Evidence
Behavioral proof:
httpUrl,autoStart: false, andapiMode: "auto".listAccounts; bound single-account daemons remain supported through the upstream JSON-RPC method-not-found contract./v1/receive/{account}, and linked-account validation uses bounded/v1/accountsreads.apiModebefore the channel default.cliPathandconfigPath, including home-relative paths containing spaces.Exact-head automated proof on
ec905c1f8d3e2803b180dfae17d5f7b071617ea4:tbx_01kxer8crr7n983esdnvhtehxr, Actions run29288747237.src/channels/plugins/setup-wizard.test.ts(1),src/flows/channel-setup.test.ts(19),src/commands/health.test.ts(24), andsrc/commands/onboard-channels.e2e.test.ts(17).git diff --checkpassed.Broader repair-loop proof:
src/config/sessions/store.tsmissing-symbol errors stopped the aggregate gate.Review proof:
CI:
mainbranch; the branch was reviewed and proven against frozen base1ecef82da8a80bb46682279cc2e2157d1ee04aa1.