* fix(agents): allow model fallback when takeover wrapper holds classifiable promptError
When EmbeddedAttemptPromptErrorWithCleanupTakeoverError wraps a real
provider-level failure (e.g. timeout, rate_limit) inside .promptError but
inherits the name "EmbeddedAttemptSessionTakeoverError", the fallback
classifier isNonProviderRuntimeCoordinationError aborts the fallback chain
without checking whether the underlying cause is a retryable provider error.
Fix: in isNonProviderRuntimeCoordinationError, check err.promptError before
returning true for takeover-named errors. If promptError is a classifiable
provider failure (timeout, rate_limit, etc.), let fallback proceed — the
takeover is a cleanup side-effect, not the root cause.
Tests:
- Unit tests for the classifier: timeout, rate_limit, unclassifiable,
and pure takeover (regression)
- Integration tests for the runWithModelFallback pipeline: timeout
and rate_limit promptError both produce correct fallback and reason;
pure takeover still aborts
Related to #99963
* fix(agents): carry preserved prompt failures
* fix(agents): keep pure takeovers fatal
---------
Co-authored-by: Peter Steinberger <steipete@gmail.com>
* fix(agents): use truncateUtf16Safe for runner error text truncation
One .slice(0, 200) truncation site in the embedded agent runner
may cut UTF-16 surrogate pairs in half when the error text contains
multi-byte characters such as emoji. Replace it with
truncateUtf16Safe to keep the truncated output valid Unicode.
* test(agents): cover UTF-16 overflow diagnostics
---------
Co-authored-by: Peter Steinberger <steipete@gmail.com>
* feat(onboard): guided CLI onboarding with live AI verification and classic fallback
Interactive `openclaw onboard` (and bare `openclaw` on a fresh install) now
runs a guided flow with macOS-app parity: detect existing AI access, live-test
candidates with a real completion before persisting anything, walk down the
ladder on failure with mapped reasons, and offer verified manual API-key entry
from installed provider manifests (masked input). In-flow escapes: classic
wizard, Crestodian chat, skip-AI. Classic wizard gains an optional post-auth
live verification step. `--classic`, `--modern`, and `--non-interactive`
contracts unchanged. Docs corrected for post-#99935 routing.
Closes#101851
* improve(onboard): quiet probe diagnostics in wizard TTY, carry risk ack into classic escape
Candidate live-tests during guided setup are probes: rename their run id and
lane to the existing probe conventions (logging/subsystem.ts console
suppression, command-queue quiet probe lanes) so expected failures stop
leaking raw diagnostics into the Clack UI; file diagnostics unchanged. The
classic-wizard escape now passes the already-collected risk acknowledgement
through instead of re-prompting in the same session.
* fix(onboard): quiet the session-derived setup-inference probe lane too
The live-test run enqueues on two lanes: the explicit probe lane and one
derived from its temp session key. Extend the shared quiet-probe predicate to
cover the derived lane so a failing candidate cannot leak lane-task
diagnostics into the wizard TTY.
* improve(onboard): suppress subsystem console output during wizard live tests
Provider-transport subsystem loggers (model-fetch start/response, transport
errors) carry no run id, so probe suppression cannot catch them and a failing
candidate printed raw log lines into the Clack TTY. Reuse the TUI console
subsystem-filter seam via a finally-safe scoped helper around guided
activation and the classic live-verify; file logging is unchanged and the
gateway (macOS app) surface is unaffected.
* fix(onboard): never auto-replace a configured model when its live check fails
The re-run verification probe executes outside the configured workspace (setup
never runs workspace plugins), so a workspace-backed current model can fail
the check while working fine in the agent. Stop the auto ladder on an
existing-model failure and hand the decision to the manual stage instead of
silently persisting a different candidate as the default. Docs note the
fail-safe and the workspace caveat.
* feat(onboard): two-way switching between Crestodian chat and the menu wizards
From the chat, `open setup wizard`, `open classic wizard`, and `open channel
wizard for <channel>` hand off to the guided flow, the classic wizard, or the
masked `channels add` wizard after the chat TUI tears down (mirrors the
open-tui handoff; gateway surface gets a text pointer instead). The hosted
channel wizard no longer dead-ends at sensitive steps — it offers the switch
and remembers the channel. New read-only `channel info <channel>` operation
and ring-zero action surface label, blurb, configured state, and the real
docs URL from channel-setup discovery so the assistant can explain Slack or
Telegram prerequisites instead of guessing; both prompts instruct it to use
them. `channels add --channel <id>` now preselects the channel. Docs cover
the interchangeable flows.
* fix(onboard): avoid param reassignment in open-setup handoff
* improve(onboard): separate ask-about vs connect intent in channel prompt guidance
Live test showed the agent detouring an explicit connect request through
channel_info because the guidance said to consult it first. Both prompts now
distinguish asking about a channel (channel info + docs link) from asking to
connect (connect right away).
* fix(channels): mark channel token entry as sensitive input
The shared single-token prompt lacked sensitive:true, so terminal wizards
echoed pasted channel tokens and the Crestodian chat bridge (which refuses
plain-text secrets based on this flag) hosted the Telegram token step in
visible chat. Found live-testing the chat-to-wizard switch; pre-existing on
main but load-bearing for the masked-wizard contract this PR documents.
* fix(onboard): restore terminal state around the guided flow's TUI launch
Mirror the classic finalize handoff so the chat TUI never inherits the wizard
prompter's raw/paused terminal state on the default first-run path.
* fix(channels): type the token prompter mock for the sensitive-flag assertion
* fix(gateway): map the TUI-only open-setup action to none for app clients
Engine-side surface gating already prevents open-setup replies on the gateway
surface; this keeps the client-visible action enum stable even if that gate
ever regresses. (Reviewed with the switching round; missed in its commit.)
* docs: regenerate docs map for onboarding page changes
* fix(nodes): defer and back off remote bin probes
* chore: leave release changelog ownership centralized
* fix(nodes): probe the live post-pairing surface
* fix(nodes): retry probes after reconnect
* fix(nodes): bind probes to live connections
* test(skills): isolate remote bin signature configs
* test(skills): place remote skills under workspace root
* style(skills): satisfy probe delay lint
---------
Co-authored-by: Peter Steinberger <steipete@gmail.com>
Adds client-capability-gated tool availability: gateway clients declare
capabilities at connect (new inline-widgets cap), chat.send stamps them into
the run context, and every tool assembly path (embedded runner, queued
followups, Codex app-server harness, plugin-only construction plans) drops
tools whose requiredClientCaps the originating client did not declare. The
Canvas plugin ships the first such tool, show_widget: agents pass SVG or an
HTML fragment plus a title; the plugin hosts it as a bounded, retention-scoped
Canvas document and returns the existing canvas preview handle, which web chat
renders as a sandboxed iframe fitted to the widget's reported content height.
Widget frames never get allow-same-origin (per-preview sandbox ceiling,
including the sidebar path) and the Canvas host serves widget documents with a
CSP sandbox header so direct navigation runs in an opaque origin. Verified
live end-to-end on a Testbox with gpt-5.5 (screenshots on the PR). CLI-backed
model backends do not carry client caps yet and stay fail-closed (#102577).
Closes#101790
* fix(plugin-sdk): update ssrf-runtime import path in cdp-proxy-bypass.ts
The import path `openclaw/plugin-sdk/ssrf-runtime-internal` was renamed
to `openclaw/plugin-sdk/ssrf-runtime` in a previous version, but
cdp-proxy-bypass.ts still referenced the old path. The neighbouring
cdp.helpers.ts already uses the correct path. This caused the browser
plugin to fail to load with "Package subpath is not defined by exports".
Fixes#96639
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
* fix(plugin-sdk): update ssrf-runtime import path in cdp-proxy-bypass
The import path `openclaw/plugin-sdk/ssrf-runtime-internal` was renamed
to `openclaw/plugin-sdk/ssrf-runtime` in a previous version, but
cdp-proxy-bypass.ts still referenced the old path. The neighbouring
cdp.helpers.ts already uses the correct path. This caused the browser
plugin to fail to load with "Package subpath is not defined by exports".
Update the corresponding vi.mock path in the test file to match.
Fixes#96639
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
* fix(plugin-sdk): promote managed-proxy bypass exports to public ssrf-runtime
Export registerManagedProxyBrowserCdpBypass and fetchConfiguredLocalOriginWithSsrFGuard
from the public ssrf-runtime path so that the browser plugin and ollama embedding
provider can lazy-load without hitting the private ssrf-runtime-internal subpath
that is excluded from package.json exports.
Fixes#96639
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
* fix(build): bundle private SSRF runtime for packaged plugins
---------
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
Co-authored-by: Peter Steinberger <steipete@gmail.com>
Reset reconnect attempts only after a provider-ready connection stays stable, and cover both flap exhaustion and stable recovery.
Co-authored-by: Peter Steinberger <steipete@gmail.com>
* fix(plugins): terminate git clone args so git: specs cannot inject options
A git: install spec whose base ends in .git or is scp-form was passed to
git clone as a bare positional. A spec beginning with a dash, such as
git:--upload-pack=/path/pwn.git, was parsed by git as an option rather than
a repository, reaching a command-execution primitive. The sibling
git switch --detach -- <ref> in the same files was already hardened; the
clone sites were missed.
Add a -- option terminator before the URL at both clone call sites
(installPluginFromGitSpec and installSkillFromSource) and reject a
leading-dash URL in isGitUrl as defense in depth.
* test(plugins): prove git option rejection boundary
Co-authored-by: yetval <yetvald@gmail.com>
---------
Co-authored-by: Peter Steinberger <steipete@gmail.com>
* fix(backup): write backup archive with owner-only 0o600 permissions
The published openclaw backup .tar.gz was created via createWriteStream
with no mode, so it landed at 0644 and world-readable. The archive
bundles auth.json OAuth access and refresh tokens, openclaw.json provider
API keys, and the state database, exposing all of them to any local user.
The intermediate SQLite snapshot is already chmod 0o600, but that
mitigation never reached the final artifact that actually matters. Create
the archive stream with mode 0o600 so the published backup is owner-only.
publishTempArchive preserves the source mode: fs.link shares the inode and
fs.copyFile copies the source mode, so the single write-site fix reaches
both publish paths.
* fix(backup): create archives owner-only
Co-authored-by: yetval <yetvald@gmail.com>
---------
Co-authored-by: Peter Steinberger <steipete@gmail.com>
* fix(plugins): fall back to os.homedir() when HOME/OPENCLAW_HOME is empty
manifest-metadata-scan resolved the home directory with
`env.OPENCLAW_HOME ?? env.HOME ?? env.USERPROFILE ?? os.homedir()`. The nullish
coalescing operator only catches null/undefined, so an empty or whitespace home
variable (e.g. HOME="" in a stripped-down container/sandbox env) was kept as ""
and path.join("", ".openclaw") resolved to a RELATIVE ".openclaw" under the cwd.
Plugin discovery then read global extensions from the wrong directory.
Normalize each candidate with the already-imported normalizeOptionalString (which
returns undefined for empty/whitespace) so an empty value falls through to
os.homedir(), matching the canonical home resolver in src/infra/home-dir.ts.
Co-Authored-By: Claude <noreply@anthropic.com>
* refactor(plugins): reuse canonical manifest paths
Co-authored-by: liyuanbin <li.yuanbin1@xydigit.com>
---------
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Peter Steinberger <steipete@gmail.com>
* [AI] fix(agents): emit model.failover diagnostic on normal model fallback transitions
Restructure observeFailedCandidate to emit the existing model.failover
diagnostic event for candidate run failures when an actual next fallback
candidate exists.
Previously emitFailoverEvent was only called in the cooldown lane-suspension
branch. Normal fallback transitions only reached the trajectory recorder
(onFallbackStep) and were invisible in OTel traces.
Key design decisions:
- Emit inside observeFailedCandidate so both LiveSessionModelSwitchError
and generic error paths are covered automatically
- Guard emission on nextCandidate to avoid false telemetry for single-model
runs or terminal candidate exhaustion (the cooldown suspension branch
already handles that case with suspended=true)
- Extract error reason via existing describeFailoverError helper
Related to #102015
Co-Authored-By: claude-4.6 <noreply@anthropic.com>
* [AI] test(agents): add regression tests for model.failover diagnostic emission
Covers three scenarios:
- Primary fails, fallback succeeds: verifies model.failover event payload
(from/to provider/model, reason, cascadeDepth, suspended)
- Single-model run: verifies no false event emission
- Exhausted chain: verifies only real transition emits, terminal does not
Related to #102015
Co-Authored-By: claude-4.6 <noreply@anthropic.com>
* test(agents): consolidate failover diagnostics coverage
* test(agents): satisfy fallback diagnostic gates
---------
Co-authored-by: claude-4.6 <noreply@anthropic.com>
Co-authored-by: Peter Steinberger <steipete@gmail.com>
Session-scoped tool-result projection freeze (shrink-only, stable
fallback identities for ambiguous tool ids) and a sent-watermark so
late-resolving inbound media appends a new user turn instead of
rewriting an already-sent slot. Stops Anthropic prompt-cache tail
invalidation on busy/media-heavy embedded sessions.
* fix(logging): use truncateUtf16Safe in diagnostic log text clamp
Replace naive .slice(0, maxChars) with truncateUtf16Safe() in
clampDiagnosticLogText() — the core helper used by all diagnostic
log output (sanitizeDiagnosticLogText, formatDiagnosticAttributes,
etc.). This prevents surrogate pair splitting across the entire
diagnostic logging subsystem.
Co-Authored-By: Claude <noreply@anthropic.com>
* fix(logging): preserve UTF-16 in bounded log text
---------
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Peter Steinberger <steipete@gmail.com>
