Merge branch 'main' into dashboard-v2-views-refactor

.github/workflows/auto-response.yml

@@ -393,6 +393,7 @@ jobs:
             }
 
             const invalidLabel = "invalid";
+            const spamLabel = "r: spam";
             const dirtyLabel = "dirty";
             const noisyPrMessage =
               "Closing this PR because it looks dirty (too many unrelated or unexpected changes). This usually happens when a branch picks up unrelated commits or a merge went sideways. Please recreate the PR from a clean branch.";
@@ -429,6 +430,21 @@ jobs:
                 });
                 return;
               }
+              if (labelSet.has(spamLabel)) {
+                await github.rest.issues.update({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number: pullRequest.number,
+                  state: "closed",
+                });
+                await github.rest.issues.lock({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number: pullRequest.number,
+                  lock_reason: "spam",
+                });
+                return;
+              }
               if (labelSet.has(invalidLabel)) {
                 await github.rest.issues.update({
                   owner: context.repo.owner,
@@ -440,6 +456,23 @@ jobs:
               }
             }
 
+            if (issue && labelSet.has(spamLabel)) {
+              await github.rest.issues.update({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: issue.number,
+                state: "closed",
+                state_reason: "not_planned",
+              });
+              await github.rest.issues.lock({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: issue.number,
+                lock_reason: "spam",
+              });
+              return;
+            }
+
             if (issue && labelSet.has(invalidLabel)) {
               await github.rest.issues.update({
                 owner: context.repo.owner,

.github/workflows/ci.yml

@@ -302,34 +302,6 @@ jobs:
           python -m pip install --upgrade pip
           python -m pip install pre-commit
 
-      - name: Detect secrets
-        run: |
-          set -euo pipefail
-
-          if [ "${{ github.event_name }}" = "push" ]; then
-            echo "Running full detect-secrets scan on push."
-            pre-commit run --all-files detect-secrets
-            exit 0
-          fi
-
-          BASE="${{ github.event.pull_request.base.sha }}"
-          changed_files=()
-          if git rev-parse --verify "$BASE^{commit}" >/dev/null 2>&1; then
-            while IFS= read -r path; do
-              [ -n "$path" ] || continue
-              [ -f "$path" ] || continue
-              changed_files+=("$path")
-            done < <(git diff --name-only --diff-filter=ACMR "$BASE" HEAD)
-          fi
-
-          if [ "${#changed_files[@]}" -gt 0 ]; then
-            echo "Running detect-secrets on ${#changed_files[@]} changed file(s)."
-            pre-commit run detect-secrets --files "${changed_files[@]}"
-          else
-            echo "Falling back to full detect-secrets scan."
-            pre-commit run --all-files detect-secrets
-          fi
-
       - name: Detect committed private keys
         run: pre-commit run --all-files detect-private-key
 

.github/workflows/install-smoke.yml

@@ -43,6 +43,8 @@ jobs:
       - name: Set up Docker Builder
         uses: useblacksmith/setup-docker-builder@v1
 
+      # Blacksmith can fall back to the local docker driver, which rejects gha
+      # cache export/import. Keep smoke builds driver-agnostic.
       - name: Build root Dockerfile smoke image
         uses: useblacksmith/build-push-action@v2
         with:
@@ -52,8 +54,6 @@ jobs:
           load: true
           push: false
           provenance: false
-          cache-from: type=gha,scope=install-smoke-root-dockerfile
-          cache-to: type=gha,mode=max,scope=install-smoke-root-dockerfile
 
       - name: Run root Dockerfile CLI smoke
         run: |
@@ -73,8 +73,6 @@ jobs:
           load: true
           push: false
           provenance: false
-          cache-from: type=gha,scope=install-smoke-root-dockerfile-ext
-          cache-to: type=gha,mode=max,scope=install-smoke-root-dockerfile-ext
 
       - name: Smoke test Dockerfile with extension build arg
         run: |
@@ -89,8 +87,6 @@ jobs:
           load: true
           push: false
           provenance: false
-          cache-from: type=gha,scope=install-smoke-installer-root
-          cache-to: type=gha,mode=max,scope=install-smoke-installer-root
 
       - name: Build installer non-root image
         if: github.event_name != 'pull_request'
@@ -102,8 +98,6 @@ jobs:
           load: true
           push: false
           provenance: false
-          cache-from: type=gha,scope=install-smoke-installer-nonroot
-          cache-to: type=gha,mode=max,scope=install-smoke-installer-nonroot
 
       - name: Run installer docker tests
         env:

.github/workflows/openclaw-npm-release.yml

@@ -0,0 +1,79 @@
+name: OpenClaw NPM Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+concurrency:
+  group: openclaw-npm-release-${{ github.ref }}
+  cancel-in-progress: false
+
+env:
+  NODE_VERSION: "22.x"
+  PNPM_VERSION: "10.23.0"
+
+jobs:
+  publish_openclaw_npm:
+    # npm trusted publishing + provenance requires a GitHub-hosted runner.
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node environment
+        uses: ./.github/actions/setup-node-env
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          pnpm-version: ${{ env.PNPM_VERSION }}
+          install-bun: "false"
+          use-sticky-disk: "false"
+
+      - name: Validate release tag and package metadata
+        env:
+          RELEASE_SHA: ${{ github.sha }}
+          RELEASE_TAG: ${{ github.ref_name }}
+          RELEASE_MAIN_REF: origin/main
+        run: |
+          set -euo pipefail
+          # Fetch the full main ref so merge-base ancestry checks keep working
+          # for older tagged commits that are still contained in main.
+          git fetch --no-tags origin +refs/heads/main:refs/remotes/origin/main
+          pnpm release:openclaw:npm:check
+
+      - name: Ensure version is not already published
+        run: |
+          set -euo pipefail
+          PACKAGE_VERSION=$(node -p "require('./package.json').version")
+
+          if npm view "openclaw@${PACKAGE_VERSION}" version >/dev/null 2>&1; then
+            echo "openclaw@${PACKAGE_VERSION} is already published on npm."
+            exit 1
+          fi
+
+          echo "Publishing openclaw@${PACKAGE_VERSION}"
+
+      - name: Check
+        run: pnpm check
+
+      - name: Build
+        run: pnpm build
+
+      - name: Verify release contents
+        run: pnpm release:check
+
+      - name: Publish
+        run: |
+          set -euo pipefail
+          PACKAGE_VERSION=$(node -p "require('./package.json').version")
+
+          if [[ "$PACKAGE_VERSION" == *-beta.* ]]; then
+            npm publish --access public --tag beta --provenance
+          else
+            npm publish --access public --provenance
+          fi

.gitignore

@@ -81,6 +81,7 @@ apps/ios/*.mobileprovision
 # Local untracked files
 .local/
 docs/.local/
+tmp/
 IDENTITY.md
 USER.md
 .tgz

AGENTS.md

@@ -24,6 +24,7 @@
 - `r: testflight`: close requests asking for TestFlight access/builds. OpenClaw does not provide TestFlight distribution yet, so use the standard response (“Not available, build from source.”) instead of ad-hoc replies.
 - `r: third-party-extension`: close with guidance to ship as third-party plugin.
 - `r: moltbook`: close + lock as off-topic (not affiliated).
+- `r: spam`: close + lock as spam (`lock_reason: spam`).
 - `invalid`: close invalid items (issues are closed as `not_planned`; PRs are closed).
 - `dirty`: close PRs with too many unrelated/unexpected changes (PR-only label).
 

CHANGELOG.md

@@ -10,6 +10,8 @@ Docs: https://docs.openclaw.ai
 - Git/runtime state: ignore the gateway-generated `.dev-state` file so local runtime state does not show up as untracked repo noise. (#41848) Thanks @smysle.
 - ACP/sessions_spawn: add optional `resumeSessionId` for `runtime: "acp"` so spawned ACP sessions can resume an existing ACPX/Codex conversation instead of always starting fresh. (#41847) Thanks @pejmanjohn.
 - Exec/child commands: mark child command environments with `OPENCLAW_CLI` so subprocesses can detect when they were launched from the OpenClaw CLI. (#41411) Thanks @vincentkoc.
+- iOS/Home canvas: add a bundled welcome screen with a live agent overview that refreshes on connect, reconnect, and foreground return, and move the compact connection pill off the top-left canvas overlay. (#42456) Thanks @ngutman.
+- iOS/Home canvas: replace floating controls with a docked toolbar, make the bundled home scaffold adapt to smaller phones, and open chat in the resolved main session instead of a synthetic `ios` session. (#42456) Thanks @ngutman.
 
 ### Breaking
 
@@ -17,6 +19,7 @@ Docs: https://docs.openclaw.ai
 
 ### Fixes
 
+- Agents/text sanitization: strip leaked model control tokens (`<|...|>` and full-width `<｜...｜>` variants) from user-facing assistant text, preventing GLM-5 and DeepSeek internal delimiters from reaching end users. (#42173) Thanks @imwyvern.
 - Resolve web tool SecretRefs atomically at runtime. (#41599) Thanks @joshavant.
 - Feishu/local image auto-convert: pass `mediaLocalRoots` through the `sendText` local-image shim so allowed local image paths upload as Feishu images again instead of falling back to raw path text. (#40623) Thanks @ayanesakura.
 - ACP/ACPX plugin: bump the bundled `acpx` pin to `0.1.16` so plugin-local installs and strict version checks match the latest published CLI. (#41975) Thanks @dutifulbob.
@@ -64,6 +67,16 @@ Docs: https://docs.openclaw.ai
 - Agents/fallback cooldown probing: cap cooldown-bypass probing to one attempt per provider per fallback run so multi-model same-provider cooldown chains can continue to cross-provider fallbacks instead of repeatedly stalling on duplicate cooldown probes. (#41711) Thanks @cgdusek.
 - Telegram/direct delivery: bridge direct delivery sends to internal `message:sent` hooks so internal hook listeners observe successful Telegram deliveries. (#40185) Thanks @vincentkoc.
 - Plugins/global hook runner: harden singleton state handling so shared global hook runner reuse does not leak or corrupt runner state across executions. (#40184) Thanks @vincentkoc.
+- Agents/fallback: recognize Poe `402 You've used up your points!` billing errors so configured model fallbacks trigger instead of surfacing the raw provider error. (#42278) Thanks @CryUshio.
+- Telegram/outbound HTML sends: chunk long HTML-mode messages, preserve plain-text fallback and silent-delivery params across retries, and cut over to plain text when HTML chunk planning cannot safely preserve the full message. (#42240) thanks @obviyus.
+- Agents/embedded overload logs: include the failing model and provider in error-path console output, with lifecycle regression coverage for the rendered and sanitized `consoleMessage`. (#41236) thanks @jiarung.
+- Agents/failover: treat Gemini `MALFORMED_RESPONSE` stop reasons as retryable timeouts so preview-model enum drift falls back cleanly instead of crashing the run, without also reclassifying malformed function-call errors. (#42292) Thanks @jnMetaCode.
+- Discord/Telegram outbound runtime config: thread runtime-resolved config through Discord and Telegram send paths so SecretRef-based credentials stay resolved during message delivery. (#42352) Thanks @joshavant.
+- Secrets/SecretRef: reject exec SecretRef traversal ids across schema, runtime, and gateway. (#42370) Thanks @joshavant.
+- Telegram/docs: clarify that `channels.telegram.groups` allowlists chats while `groupAllowFrom` allowlists users inside those chats, and point invalid negative chat IDs at the right config key. (#42451) Thanks @altaywtf.
+- Models/Alibaba Cloud Model Studio: wire `MODELSTUDIO_API_KEY` through shared env auth, implicit provider discovery, and shell-env fallback so onboarding works outside the wizard too. (#40634) Thanks @pomelo-nwu.
+- ACP/sessions_spawn: implicitly stream `mode="run"` ACP spawns to parent only for eligible subagent orchestrator sessions (heartbeat `target: "last"` with a usable session-local route), restoring parent progress relays without thread binding. (#42404) Thanks @davidguttman.
+- Sessions/reset model recompute: clear stale runtime model, context-token, and system-prompt metadata before session resets recompute the replacement session, so resets pick up current defaults and explicit overrides instead of reusing old runtime model state. (#41173) thanks @PonyX-lab.
 
 ## 2026.3.8
 
@@ -130,6 +143,7 @@ Docs: https://docs.openclaw.ai
 - Security/system.run: bind approved `bun` and `deno run` script operands to on-disk file snapshots so post-approval script rewrites are denied before execution.
 - Skills/download installs: pin the validated per-skill tools root before writing downloaded archives, so rebinding the lexical tools path cannot redirect download writes outside the intended tools directory. Thanks @tdjackey.
 - Control UI/Debug: replace the Manual RPC free-text method field with a sorted dropdown sourced from gateway-advertised methods, and stack the form vertically for narrower layouts. (#14967) thanks @rixau.
+- Auth/profile resolution: log debug details when auto-discovered auth profiles fail during provider API-key resolution, so `--debug` output surfaces the real refresh/keychain/credential-store failure instead of only the generic missing-key message. (#41271) thanks @he-yufeng.
 
 ## 2026.3.7
 

CONTRIBUTING.md

@@ -86,6 +86,7 @@ Welcome to the lobster tank! 🦞
 
 - Test locally with your OpenClaw instance
 - Run tests: `pnpm build && pnpm check && pnpm test`
+- If you have access to Codex, run `codex review --base origin/main` locally before opening or updating your PR. Treat this as the current highest standard of AI review, even if GitHub Codex review also runs.
 - Ensure CI checks pass
 - Keep PRs focused (one thing per PR; do not mix unrelated concerns)
 - Describe what & why
@@ -99,6 +100,8 @@ If a review bot leaves review conversations on your PR, you are expected to hand
 - Resolve the conversation yourself once the code or explanation fully addresses the bot's concern
 - Reply and leave it open only when you need maintainer or reviewer judgment
 - Do not leave "fixed" bot review conversations for maintainers to clean up for you
+- If Codex leaves comments, address every relevant one or resolve it with a short explanation when it is not applicable to your change
+- If GitHub Codex review does not trigger for some reason, run `codex review --base origin/main` locally anyway and treat that output as required review work
 
 This applies to both human-authored and AI-assisted PRs.
 
@@ -127,6 +130,7 @@ Please include in your PR:
 - [ ] Note the degree of testing (untested / lightly tested / fully tested)
 - [ ] Include prompts or session logs if possible (super helpful!)
 - [ ] Confirm you understand what the code does
+- [ ] If you have access to Codex, run `codex review --base origin/main` locally and address the findings before asking for review
 - [ ] Resolve or reply to bot review conversations after you address them
 
 AI PRs are first-class citizens here. We just want transparency so reviewers know what to look for. If you are using an LLM coding agent, instruct it to resolve bot review conversations it has addressed instead of leaving them for maintainers.

apps/ios/Sources/HomeToolbar.swift

@@ -0,0 +1,223 @@
+import SwiftUI
+
+struct HomeToolbar: View {
+    var gateway: StatusPill.GatewayState
+    var voiceWakeEnabled: Bool
+    var activity: StatusPill.Activity?
+    var brighten: Bool
+    var talkButtonEnabled: Bool
+    var talkActive: Bool
+    var talkTint: Color
+    var onStatusTap: () -> Void
+    var onChatTap: () -> Void
+    var onTalkTap: () -> Void
+    var onSettingsTap: () -> Void
+
+    @Environment(\.colorSchemeContrast) private var contrast
+
+    var body: some View {
+        VStack(spacing: 0) {
+            Rectangle()
+                .fill(.white.opacity(self.contrast == .increased ? 0.46 : (self.brighten ? 0.18 : 0.12)))
+                .frame(height: self.contrast == .increased ? 1.0 : 0.6)
+                .allowsHitTesting(false)
+
+            HStack(spacing: 12) {
+                HomeToolbarStatusButton(
+                    gateway: self.gateway,
+                    voiceWakeEnabled: self.voiceWakeEnabled,
+                    activity: self.activity,
+                    brighten: self.brighten,
+                    onTap: self.onStatusTap)
+
+                Spacer(minLength: 0)
+
+                HStack(spacing: 8) {
+                    HomeToolbarActionButton(
+                        systemImage: "text.bubble.fill",
+                        accessibilityLabel: "Chat",
+                        brighten: self.brighten,
+                        action: self.onChatTap)
+
+                    if self.talkButtonEnabled {
+                        HomeToolbarActionButton(
+                            systemImage: self.talkActive ? "waveform.circle.fill" : "waveform.circle",
+                            accessibilityLabel: self.talkActive ? "Talk Mode On" : "Talk Mode Off",
+                            brighten: self.brighten,
+                            tint: self.talkTint,
+                            isActive: self.talkActive,
+                            action: self.onTalkTap)
+                    }
+
+                    HomeToolbarActionButton(
+                        systemImage: "gearshape.fill",
+                        accessibilityLabel: "Settings",
+                        brighten: self.brighten,
+                        action: self.onSettingsTap)
+                }
+            }
+            .padding(.horizontal, 12)
+            .padding(.top, 10)
+            .padding(.bottom, 8)
+        }
+        .frame(maxWidth: .infinity)
+        .background(.ultraThinMaterial)
+        .overlay(alignment: .top) {
+            LinearGradient(
+                colors: [
+                    .white.opacity(self.brighten ? 0.10 : 0.06),
+                    .clear,
+                ],
+                startPoint: .top,
+                endPoint: .bottom)
+                .allowsHitTesting(false)
+        }
+    }
+}
+
+private struct HomeToolbarStatusButton: View {
+    @Environment(\.scenePhase) private var scenePhase
+    @Environment(\.accessibilityReduceMotion) private var reduceMotion
+    @Environment(\.colorSchemeContrast) private var contrast
+
+    var gateway: StatusPill.GatewayState
+    var voiceWakeEnabled: Bool
+    var activity: StatusPill.Activity?
+    var brighten: Bool
+    var onTap: () -> Void
+
+    @State private var pulse: Bool = false
+
+    var body: some View {
+        Button(action: self.onTap) {
+            HStack(spacing: 8) {
+                HStack(spacing: 6) {
+                    Circle()
+                        .fill(self.gateway.color)
+                        .frame(width: 8, height: 8)
+                        .scaleEffect(
+                            self.gateway == .connecting && !self.reduceMotion
+                                ? (self.pulse ? 1.15 : 0.85)
+                                : 1.0
+                        )
+                        .opacity(self.gateway == .connecting && !self.reduceMotion ? (self.pulse ? 1.0 : 0.6) : 1.0)
+
+                    Text(self.gateway.title)
+                        .font(.footnote.weight(.semibold))
+                        .foregroundStyle(.primary)
+                        .lineLimit(1)
+                }
+
+                if let activity {
+                    Image(systemName: activity.systemImage)
+                        .font(.footnote.weight(.semibold))
+                        .foregroundStyle(activity.tint ?? .primary)
+                        .transition(.opacity.combined(with: .move(edge: .top)))
+                } else {
+                    Image(systemName: self.voiceWakeEnabled ? "mic.fill" : "mic.slash")
+                        .font(.footnote.weight(.semibold))
+                        .foregroundStyle(self.voiceWakeEnabled ? .primary : .secondary)
+                        .transition(.opacity.combined(with: .move(edge: .top)))
+                }
+            }
+            .padding(.horizontal, 12)
+            .padding(.vertical, 8)
+            .background {
+                RoundedRectangle(cornerRadius: 14, style: .continuous)
+                    .fill(Color.black.opacity(self.brighten ? 0.12 : 0.18))
+                    .overlay {
+                        RoundedRectangle(cornerRadius: 14, style: .continuous)
+                            .strokeBorder(
+                                .white.opacity(self.contrast == .increased ? 0.46 : (self.brighten ? 0.22 : 0.16)),
+                                lineWidth: self.contrast == .increased ? 1.0 : 0.6)
+                    }
+            }
+        }
+        .buttonStyle(.plain)
+        .accessibilityLabel("Connection Status")
+        .accessibilityValue(self.accessibilityValue)
+        .accessibilityHint(self.gateway == .connected ? "Double tap for gateway actions" : "Double tap to open settings")
+        .onAppear { self.updatePulse(for: self.gateway, scenePhase: self.scenePhase, reduceMotion: self.reduceMotion) }
+        .onDisappear { self.pulse = false }
+        .onChange(of: self.gateway) { _, newValue in
+            self.updatePulse(for: newValue, scenePhase: self.scenePhase, reduceMotion: self.reduceMotion)
+        }
+        .onChange(of: self.scenePhase) { _, newValue in
+            self.updatePulse(for: self.gateway, scenePhase: newValue, reduceMotion: self.reduceMotion)
+        }
+        .onChange(of: self.reduceMotion) { _, newValue in
+            self.updatePulse(for: self.gateway, scenePhase: self.scenePhase, reduceMotion: newValue)
+        }
+        .animation(.easeInOut(duration: 0.18), value: self.activity?.title)
+    }
+
+    private var accessibilityValue: String {
+        if let activity {
+            return "\(self.gateway.title), \(activity.title)"
+        }
+        return "\(self.gateway.title), Voice Wake \(self.voiceWakeEnabled ? "enabled" : "disabled")"
+    }
+
+    private func updatePulse(for gateway: StatusPill.GatewayState, scenePhase: ScenePhase, reduceMotion: Bool) {
+        guard gateway == .connecting, scenePhase == .active, !reduceMotion else {
+            withAnimation(reduceMotion ? .none : .easeOut(duration: 0.2)) { self.pulse = false }
+            return
+        }
+
+        guard !self.pulse else { return }
+        withAnimation(.easeInOut(duration: 0.9).repeatForever(autoreverses: true)) {
+            self.pulse = true
+        }
+    }
+}
+
+private struct HomeToolbarActionButton: View {
+    @Environment(\.colorSchemeContrast) private var contrast
+
+    let systemImage: String
+    let accessibilityLabel: String
+    let brighten: Bool
+    var tint: Color?
+    var isActive: Bool = false
+    let action: () -> Void
+
+    var body: some View {
+        Button(action: self.action) {
+            Image(systemName: self.systemImage)
+                .font(.system(size: 16, weight: .semibold))
+                .foregroundStyle(self.isActive ? (self.tint ?? .primary) : .primary)
+                .frame(width: 40, height: 40)
+                .background {
+                    RoundedRectangle(cornerRadius: 12, style: .continuous)
+                        .fill(Color.black.opacity(self.brighten ? 0.12 : 0.18))
+                        .overlay {
+                            if let tint {
+                                RoundedRectangle(cornerRadius: 12, style: .continuous)
+                                    .fill(
+                                        LinearGradient(
+                                            colors: [
+                                                tint.opacity(self.isActive ? 0.22 : 0.14),
+                                                tint.opacity(self.isActive ? 0.08 : 0.04),
+                                                .clear,
+                                            ],
+                                            startPoint: .topLeading,
+                                            endPoint: .bottomTrailing))
+                                    .blendMode(.overlay)
+                            }
+                        }
+                        .overlay {
+                            RoundedRectangle(cornerRadius: 12, style: .continuous)
+                                .strokeBorder(
+                                    (self.tint ?? .white).opacity(
+                                        self.isActive
+                                            ? 0.34
+                                            : (self.contrast == .increased ? 0.4 : (self.brighten ? 0.22 : 0.16))
+                                    ),
+                                    lineWidth: self.contrast == .increased ? 1.0 : (self.isActive ? 0.8 : 0.6))
+                        }
+                }
+        }
+        .buttonStyle(.plain)
+        .accessibilityLabel(self.accessibilityLabel)
+    }
+}

apps/ios/Sources/Model/NodeAppModel+Canvas.swift

@@ -34,18 +34,11 @@ extension NodeAppModel {
     }
 
     func showA2UIOnConnectIfNeeded() async {
-        let current = self.screen.urlString.trimmingCharacters(in: .whitespacesAndNewlines)
-        if current.isEmpty || current == self.lastAutoA2uiURL {
-            if let canvasUrl = await self.resolveCanvasHostURLWithCapabilityRefresh(),
-               let url = URL(string: canvasUrl),
-               await Self.probeTCP(url: url, timeoutSeconds: 2.5)
-            {
-                self.screen.navigate(to: canvasUrl)
-                self.lastAutoA2uiURL = canvasUrl
-            } else {
-                self.lastAutoA2uiURL = nil
-                self.screen.showDefaultCanvas()
-            }
+        await MainActor.run {
+            // Keep the bundled home canvas as the default connected view.
+            // Agents can still explicitly present a remote or local canvas later.
+            self.lastAutoA2uiURL = nil
+            self.screen.showDefaultCanvas()
         }
     }
 

apps/ios/Sources/Model/NodeAppModel.swift

@@ -88,6 +88,7 @@ final class NodeAppModel {
     var selectedAgentId: String?
     var gatewayDefaultAgentId: String?
     var gatewayAgents: [AgentSummary] = []
+    var homeCanvasRevision: Int = 0
     var lastShareEventText: String = "No share events yet."
     var openChatRequestID: Int = 0
     private(set) var pendingAgentDeepLinkPrompt: AgentDeepLinkPrompt?
@@ -548,6 +549,7 @@ final class NodeAppModel {
                 self.seamColorHex = raw.isEmpty ? nil : raw
                 self.mainSessionBaseKey = mainKey
                 self.talkMode.updateMainSessionKey(self.mainSessionKey)
+                self.homeCanvasRevision &+= 1
             }
         } catch {
             if let gatewayError = error as? GatewayResponseError {
@@ -574,12 +576,19 @@ final class NodeAppModel {
                     self.selectedAgentId = nil
                 }
                 self.talkMode.updateMainSessionKey(self.mainSessionKey)
+                self.homeCanvasRevision &+= 1
             }
         } catch {
             // Best-effort only.
         }
     }
 
+    func refreshGatewayOverviewIfConnected() async {
+        guard await self.isOperatorConnected() else { return }
+        await self.refreshBrandingFromGateway()
+        await self.refreshAgentsFromGateway()
+    }
+
     func setSelectedAgentId(_ agentId: String?) {
         let trimmed = (agentId ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
         let stableID = (self.connectedGatewayID ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
@@ -590,6 +599,7 @@ final class NodeAppModel {
             GatewaySettingsStore.saveGatewaySelectedAgentId(stableID: stableID, agentId: self.selectedAgentId)
         }
         self.talkMode.updateMainSessionKey(self.mainSessionKey)
+        self.homeCanvasRevision &+= 1
         if let relay = ShareGatewayRelaySettings.loadConfig() {
             ShareGatewayRelaySettings.saveConfig(
                 ShareGatewayRelayConfig(
@@ -1629,11 +1639,9 @@ extension NodeAppModel {
     }
 
     var chatSessionKey: String {
-        let base = "ios"
-        let agentId = (self.selectedAgentId ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
-        let defaultId = (self.gatewayDefaultAgentId ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
-        if agentId.isEmpty || (!defaultId.isEmpty && agentId == defaultId) { return base }
-        return SessionKey.makeAgentSessionKey(agentId: agentId, baseKey: base)
+        // Keep chat aligned with the gateway's resolved main session key.
+        // A hardcoded "ios" base creates synthetic placeholder sessions in the chat UI.
+        self.mainSessionKey
     }
 
     var activeAgentName: String {
@@ -1749,6 +1757,7 @@ private extension NodeAppModel {
         self.gatewayDefaultAgentId = nil
         self.gatewayAgents = []
         self.selectedAgentId = GatewaySettingsStore.loadGatewaySelectedAgentId(stableID: stableID)
+        self.homeCanvasRevision &+= 1
         self.apnsLastRegisteredTokenHex = nil
     }
 

apps/ios/Sources/Onboarding/OnboardingWizardView.swift

@@ -536,7 +536,7 @@ struct OnboardingWizardView: View {
                     Text(
                         "Approve this device on the gateway.\n"
                             + "1) `openclaw devices approve` (or `openclaw devices approve <requestId>`)\n"
-                            + "2) `/pair approve` in Telegram\n"
+                            + "2) `/pair approve` in your OpenClaw chat\n"
                             + "\(requestLine)\n"
                             + "OpenClaw will also retry automatically when you return to this app.")
                 }

apps/ios/Sources/RootCanvas.swift

@@ -1,5 +1,6 @@
 import SwiftUI
 import UIKit
+import OpenClawProtocol
 
 struct RootCanvas: View {
     @Environment(NodeAppModel.self) private var appModel
@@ -137,16 +138,33 @@ struct RootCanvas: View {
                 .environment(self.gatewayController)
         }
         .onAppear { self.updateIdleTimer() }
+        .onAppear { self.updateHomeCanvasState() }
         .onAppear { self.evaluateOnboardingPresentation(force: false) }
         .onAppear { self.maybeAutoOpenSettings() }
         .onChange(of: self.preventSleep) { _, _ in self.updateIdleTimer() }
-        .onChange(of: self.scenePhase) { _, _ in self.updateIdleTimer() }
+        .onChange(of: self.scenePhase) { _, newValue in
+            self.updateIdleTimer()
+            self.updateHomeCanvasState()
+            guard newValue == .active else { return }
+            Task {
+                await self.appModel.refreshGatewayOverviewIfConnected()
+                await MainActor.run {
+                    self.updateHomeCanvasState()
+                }
+            }
+        }
         .onAppear { self.maybeShowQuickSetup() }
         .onChange(of: self.gatewayController.gateways.count) { _, _ in self.maybeShowQuickSetup() }
         .onAppear { self.updateCanvasDebugStatus() }
         .onChange(of: self.canvasDebugStatusEnabled) { _, _ in self.updateCanvasDebugStatus() }
-        .onChange(of: self.appModel.gatewayStatusText) { _, _ in self.updateCanvasDebugStatus() }
-        .onChange(of: self.appModel.gatewayServerName) { _, _ in self.updateCanvasDebugStatus() }
+        .onChange(of: self.appModel.gatewayStatusText) { _, _ in
+            self.updateCanvasDebugStatus()
+            self.updateHomeCanvasState()
+        }
+        .onChange(of: self.appModel.gatewayServerName) { _, _ in
+            self.updateCanvasDebugStatus()
+            self.updateHomeCanvasState()
+        }
         .onChange(of: self.appModel.gatewayServerName) { _, newValue in
             if newValue != nil {
                 self.showOnboarding = false
@@ -155,7 +173,13 @@ struct RootCanvas: View {
         .onChange(of: self.onboardingRequestID) { _, _ in
             self.evaluateOnboardingPresentation(force: true)
         }
-        .onChange(of: self.appModel.gatewayRemoteAddress) { _, _ in self.updateCanvasDebugStatus() }
+        .onChange(of: self.appModel.gatewayRemoteAddress) { _, _ in
+            self.updateCanvasDebugStatus()
+            self.updateHomeCanvasState()
+        }
+        .onChange(of: self.appModel.homeCanvasRevision) { _, _ in
+            self.updateHomeCanvasState()
+        }
         .onChange(of: self.appModel.gatewayServerName) { _, newValue in
             if newValue != nil {
                 self.onboardingComplete = true
@@ -209,6 +233,134 @@ struct RootCanvas: View {
         self.appModel.screen.updateDebugStatus(title: title, subtitle: subtitle)
     }
 
+    private func updateHomeCanvasState() {
+        let payload = self.makeHomeCanvasPayload()
+        guard let data = try? JSONEncoder().encode(payload),
+              let json = String(data: data, encoding: .utf8)
+        else {
+            self.appModel.screen.updateHomeCanvasState(json: nil)
+            return
+        }
+        self.appModel.screen.updateHomeCanvasState(json: json)
+    }
+
+    private func makeHomeCanvasPayload() -> HomeCanvasPayload {
+        let gatewayName = self.normalized(self.appModel.gatewayServerName)
+        let gatewayAddress = self.normalized(self.appModel.gatewayRemoteAddress)
+        let gatewayLabel = gatewayName ?? gatewayAddress ?? "Gateway"
+        let activeAgentID = self.resolveActiveAgentID()
+        let agents = self.homeCanvasAgents(activeAgentID: activeAgentID)
+
+        switch self.gatewayStatus {
+        case .connected:
+            return HomeCanvasPayload(
+                gatewayState: "connected",
+                eyebrow: "Connected to \(gatewayLabel)",
+                title: "Your agents are ready",
+                subtitle:
+                    "This phone stays dormant until the gateway needs it, then wakes, syncs, and goes back to sleep.",
+                gatewayLabel: gatewayLabel,
+                activeAgentName: self.appModel.activeAgentName,
+                activeAgentBadge: agents.first(where: { $0.isActive })?.badge ?? "OC",
+                activeAgentCaption: "Selected on this phone",
+                agentCount: agents.count,
+                agents: Array(agents.prefix(6)),
+                footer: "The overview refreshes on reconnect and when the app returns to foreground.")
+        case .connecting:
+            return HomeCanvasPayload(
+                gatewayState: "connecting",
+                eyebrow: "Reconnecting",
+                title: "OpenClaw is syncing back up",
+                subtitle:
+                    "The gateway session is coming back online. "
+                    + "Agent shortcuts should settle automatically in a moment.",
+                gatewayLabel: gatewayLabel,
+                activeAgentName: self.appModel.activeAgentName,
+                activeAgentBadge: "OC",
+                activeAgentCaption: "Gateway session in progress",
+                agentCount: agents.count,
+                agents: Array(agents.prefix(4)),
+                footer: "If the gateway is reachable, reconnect should complete without intervention.")
+        case .error, .disconnected:
+            return HomeCanvasPayload(
+                gatewayState: self.gatewayStatus == .error ? "error" : "offline",
+                eyebrow: "Welcome to OpenClaw",
+                title: "Your phone stays quiet until it is needed",
+                subtitle:
+                    "Pair this device to your gateway to wake it only for real work, "
+                    + "keep a live agent overview handy, and avoid battery-draining background loops.",
+                gatewayLabel: gatewayLabel,
+                activeAgentName: "Main",
+                activeAgentBadge: "OC",
+                activeAgentCaption: "Connect to load your agents",
+                agentCount: agents.count,
+                agents: Array(agents.prefix(4)),
+                footer:
+                    "When connected, the gateway can wake the phone with a silent push "
+                    + "instead of holding an always-on session.")
+        }
+    }
+
+    private func resolveActiveAgentID() -> String {
+        let selected = self.normalized(self.appModel.selectedAgentId) ?? ""
+        if !selected.isEmpty {
+            return selected
+        }
+        return self.resolveDefaultAgentID()
+    }
+
+    private func resolveDefaultAgentID() -> String {
+        self.normalized(self.appModel.gatewayDefaultAgentId) ?? ""
+    }
+
+    private func homeCanvasAgents(activeAgentID: String) -> [HomeCanvasAgentCard] {
+        let defaultAgentID = self.resolveDefaultAgentID()
+        let cards = self.appModel.gatewayAgents.map { agent -> HomeCanvasAgentCard in
+            let isActive = !activeAgentID.isEmpty && agent.id == activeAgentID
+            let isDefault = !defaultAgentID.isEmpty && agent.id == defaultAgentID
+            return HomeCanvasAgentCard(
+                id: agent.id,
+                name: self.homeCanvasName(for: agent),
+                badge: self.homeCanvasBadge(for: agent),
+                caption: isActive ? "Active on this phone" : (isDefault ? "Default agent" : "Ready"),
+                isActive: isActive)
+        }
+
+        return cards.sorted { lhs, rhs in
+            if lhs.isActive != rhs.isActive {
+                return lhs.isActive
+            }
+            return lhs.name.localizedCaseInsensitiveCompare(rhs.name) == .orderedAscending
+        }
+    }
+
+    private func homeCanvasName(for agent: AgentSummary) -> String {
+        self.normalized(agent.name) ?? agent.id
+    }
+
+    private func homeCanvasBadge(for agent: AgentSummary) -> String {
+        if let identity = agent.identity,
+           let emoji = identity["emoji"]?.value as? String,
+           let normalizedEmoji = self.normalized(emoji)
+        {
+            return normalizedEmoji
+        }
+        let words = self.homeCanvasName(for: agent)
+            .split(whereSeparator: { $0.isWhitespace || $0 == "-" || $0 == "_" })
+            .prefix(2)
+        let initials = words.compactMap { $0.first }.map(String.init).joined()
+        if !initials.isEmpty {
+            return initials.uppercased()
+        }
+        return "OC"
+    }
+
+    private func normalized(_ value: String?) -> String? {
+        guard let value else { return nil }
+        let trimmed = value.trimmingCharacters(in: .whitespacesAndNewlines)
+        return trimmed.isEmpty ? nil : trimmed
+    }
+
     private func evaluateOnboardingPresentation(force: Bool) {
         if force {
             self.onboardingAllowSkip = true
@@ -274,6 +426,28 @@ struct RootCanvas: View {
     }
 }
 
+private struct HomeCanvasPayload: Codable {
+    var gatewayState: String
+    var eyebrow: String
+    var title: String
+    var subtitle: String
+    var gatewayLabel: String
+    var activeAgentName: String
+    var activeAgentBadge: String
+    var activeAgentCaption: String
+    var agentCount: Int
+    var agents: [HomeCanvasAgentCard]
+    var footer: String
+}
+
+private struct HomeCanvasAgentCard: Codable {
+    var id: String
+    var name: String
+    var badge: String
+    var caption: String
+    var isActive: Bool
+}
+
 private struct CanvasContent: View {
     @Environment(NodeAppModel.self) private var appModel
     @AppStorage("talk.enabled") private var talkEnabled: Bool = false
@@ -301,53 +475,33 @@ private struct CanvasContent: View {
                     .transition(.opacity)
             }
         }
-        .overlay(alignment: .topLeading) {
-            HStack(alignment: .top, spacing: 8) {
-                StatusPill(
-                    gateway: self.gatewayStatus,
-                    voiceWakeEnabled: self.voiceWakeEnabled,
-                    activity: self.statusActivity,
-                    brighten: self.brightenButtons,
-                    onTap: {
-                        if self.gatewayStatus == .connected {
-                            self.showGatewayActions = true
-                        } else {
-                            self.openSettings()
-                        }
-                    })
-                    .layoutPriority(1)
-
-                Spacer(minLength: 8)
-
-                HStack(spacing: 8) {
-                    OverlayButton(systemImage: "text.bubble.fill", brighten: self.brightenButtons) {
-                        self.openChat()
-                    }
-                    .accessibilityLabel("Chat")
-
-                    if self.talkButtonEnabled {
-                        // Keep Talk mode near status controls while freeing right-side screen real estate.
-                        OverlayButton(
-                            systemImage: self.talkActive ? "waveform.circle.fill" : "waveform.circle",
-                            brighten: self.brightenButtons,
-                            tint: self.appModel.seamColor,
-                            isActive: self.talkActive)
-                        {
-                            let next = !self.talkActive
-                            self.talkEnabled = next
-                            self.appModel.setTalkEnabled(next)
-                        }
-                        .accessibilityLabel("Talk Mode")
-                    }
-
-                    OverlayButton(systemImage: "gearshape.fill", brighten: self.brightenButtons) {
+        .safeAreaInset(edge: .bottom, spacing: 0) {
+            HomeToolbar(
+                gateway: self.gatewayStatus,
+                voiceWakeEnabled: self.voiceWakeEnabled,
+                activity: self.statusActivity,
+                brighten: self.brightenButtons,
+                talkButtonEnabled: self.talkButtonEnabled,
+                talkActive: self.talkActive,
+                talkTint: self.appModel.seamColor,
+                onStatusTap: {
+                    if self.gatewayStatus == .connected {
+                        self.showGatewayActions = true
+                    } else {
                         self.openSettings()
                     }
-                    .accessibilityLabel("Settings")
-                }
-            }
-            .padding(.horizontal, 10)
-            .safeAreaPadding(.top, 10)
+                },
+                onChatTap: {
+                    self.openChat()
+                },
+                onTalkTap: {
+                    let next = !self.talkActive
+                    self.talkEnabled = next
+                    self.appModel.setTalkEnabled(next)
+                },
+                onSettingsTap: {
+                    self.openSettings()
+                })
         }
         .overlay(alignment: .topLeading) {
             if let voiceWakeToastText, !voiceWakeToastText.isEmpty {
@@ -380,63 +534,6 @@ private struct CanvasContent: View {
     }
 }
 
-private struct OverlayButton: View {
-    let systemImage: String
-    let brighten: Bool
-    var tint: Color?
-    var isActive: Bool = false
-    let action: () -> Void
-
-    var body: some View {
-        Button(action: self.action) {
-            Image(systemName: self.systemImage)
-                .font(.system(size: 16, weight: .semibold))
-                .foregroundStyle(self.isActive ? (self.tint ?? .primary) : .primary)
-                .padding(10)
-                .background {
-                    RoundedRectangle(cornerRadius: 12, style: .continuous)
-                        .fill(.ultraThinMaterial)
-                        .overlay {
-                            RoundedRectangle(cornerRadius: 12, style: .continuous)
-                                .fill(
-                                    LinearGradient(
-                                        colors: [
-                                            .white.opacity(self.brighten ? 0.26 : 0.18),
-                                            .white.opacity(self.brighten ? 0.08 : 0.04),
-                                            .clear,
-                                        ],
-                                        startPoint: .topLeading,
-                                        endPoint: .bottomTrailing))
-                                .blendMode(.overlay)
-                        }
-                        .overlay {
-                            if let tint {
-                                RoundedRectangle(cornerRadius: 12, style: .continuous)
-                                    .fill(
-                                        LinearGradient(
-                                            colors: [
-                                                tint.opacity(self.isActive ? 0.22 : 0.14),
-                                                tint.opacity(self.isActive ? 0.10 : 0.06),
-                                                .clear,
-                                            ],
-                                            startPoint: .topLeading,
-                                            endPoint: .bottomTrailing))
-                                    .blendMode(.overlay)
-                            }
-                        }
-                        .overlay {
-                            RoundedRectangle(cornerRadius: 12, style: .continuous)
-                                .strokeBorder(
-                                    (self.tint ?? .white).opacity(self.isActive ? 0.34 : (self.brighten ? 0.24 : 0.18)),
-                                    lineWidth: self.isActive ? 0.7 : 0.5)
-                        }
-                        .shadow(color: .black.opacity(0.35), radius: 12, y: 6)
-                }
-        }
-        .buttonStyle(.plain)
-    }
-}
-
 private struct CameraFlashOverlay: View {
     var nonce: Int
 

apps/ios/Sources/Screen/ScreenController.swift

@@ -20,6 +20,7 @@ final class ScreenController {
     private var debugStatusEnabled: Bool = false
     private var debugStatusTitle: String?
     private var debugStatusSubtitle: String?
+    private var homeCanvasStateJSON: String?
 
     init() {
         self.reload()
@@ -94,6 +95,26 @@ final class ScreenController {
             subtitle: self.debugStatusSubtitle)
     }
 
+    func updateHomeCanvasState(json: String?) {
+        self.homeCanvasStateJSON = json
+        self.applyHomeCanvasStateIfNeeded()
+    }
+
+    func applyHomeCanvasStateIfNeeded() {
+        guard let webView = self.activeWebView else { return }
+        let payload = self.homeCanvasStateJSON ?? "null"
+        let js = """
+        (() => {
+          try {
+            const api = globalThis.__openclaw;
+            if (!api || typeof api.renderHome !== 'function') return;
+            api.renderHome(\(payload));
+          } catch (_) {}
+        })()
+        """
+        webView.evaluateJavaScript(js) { _, _ in }
+    }
+
     func waitForA2UIReady(timeoutMs: Int) async -> Bool {
         let clock = ContinuousClock()
         let deadline = clock.now.advanced(by: .milliseconds(timeoutMs))
@@ -191,6 +212,7 @@ final class ScreenController {
         self.activeWebView = webView
         self.reload()
         self.applyDebugStatusIfNeeded()
+        self.applyHomeCanvasStateIfNeeded()
     }
 
     func detachWebView(_ webView: WKWebView) {

apps/ios/Sources/Screen/ScreenTab.swift

@@ -7,7 +7,7 @@ struct ScreenTab: View {
     var body: some View {
         ZStack(alignment: .top) {
             ScreenWebView(controller: self.appModel.screen)
-                .ignoresSafeArea()
+                .ignoresSafeArea(.container, edges: [.top, .leading, .trailing])
                 .overlay(alignment: .top) {
                     if let errorText = self.appModel.screen.errorText,
                        self.appModel.gatewayServerName == nil

apps/ios/Sources/Screen/ScreenWebView.swift

@@ -161,6 +161,7 @@ private final class ScreenNavigationDelegate: NSObject, WKNavigationDelegate {
     func webView(_: WKWebView, didFinish _: WKNavigation?) {
         self.controller?.errorText = nil
         self.controller?.applyDebugStatusIfNeeded()
+        self.controller?.applyHomeCanvasStateIfNeeded()
     }
 
     func webView(_: WKWebView, didFail _: WKNavigation?, withError error: any Error) {

apps/ios/Sources/Settings/SettingsTab.swift

@@ -65,10 +65,10 @@ struct SettingsTab: View {
                     DisclosureGroup(isExpanded: self.$gatewayExpanded) {
                         if !self.isGatewayConnected {
                             Text(
-                                "1. Open Telegram and message your bot: /pair\n"
+                                "1. Open a chat with your OpenClaw agent and send /pair\n"
                                     + "2. Copy the setup code it returns\n"
                                     + "3. Paste here and tap Connect\n"
-                                    + "4. Back in Telegram, run /pair approve")
+                                    + "4. Back in that chat, run /pair approve")
                                 .font(.footnote)
                                 .foregroundStyle(.secondary)
 
@@ -340,9 +340,9 @@ struct SettingsTab: View {
                                     .foregroundStyle(.secondary)
                             }
                             self.featureToggle(
-                                "Show Talk Button",
+                                "Show Talk Control",
                                 isOn: self.$talkButtonEnabled,
-                                help: "Shows the floating Talk button in the main interface.")
+                                help: "Shows the Talk control in the main toolbar.")
                             TextField("Default Share Instruction", text: self.$defaultShareInstruction, axis: .vertical)
                                 .lineLimit(2 ... 6)
                                 .textInputAutocapitalization(.sentences)
@@ -896,7 +896,7 @@ struct SettingsTab: View {
         guard !trimmed.isEmpty else { return nil }
         let lower = trimmed.lowercased()
         if lower.contains("pairing required") {
-            return "Pairing required. Go back to Telegram and run /pair approve, then tap Connect again."
+            return "Pairing required. Go back to your OpenClaw chat and run /pair approve, then tap Connect again."
         }
         if lower.contains("device nonce required") || lower.contains("device nonce mismatch") {
             return "Secure handshake failed. Make sure Tailscale is connected, then tap Connect again."

apps/ios/Sources/Status/StatusPill.swift

@@ -38,6 +38,7 @@ struct StatusPill: View {
     var gateway: GatewayState
     var voiceWakeEnabled: Bool
     var activity: Activity?
+    var compact: Bool = false
     var brighten: Bool = false
     var onTap: () -> Void
 
@@ -45,11 +46,11 @@ struct StatusPill: View {
 
     var body: some View {
         Button(action: self.onTap) {
-            HStack(spacing: 10) {
-                HStack(spacing: 8) {
+            HStack(spacing: self.compact ? 8 : 10) {
+                HStack(spacing: self.compact ? 6 : 8) {
                     Circle()
                         .fill(self.gateway.color)
-                        .frame(width: 9, height: 9)
+                        .frame(width: self.compact ? 8 : 9, height: self.compact ? 8 : 9)
                         .scaleEffect(
                             self.gateway == .connecting && !self.reduceMotion
                                 ? (self.pulse ? 1.15 : 0.85)
@@ -58,34 +59,38 @@ struct StatusPill: View {
                         .opacity(self.gateway == .connecting && !self.reduceMotion ? (self.pulse ? 1.0 : 0.6) : 1.0)
 
                     Text(self.gateway.title)
-                        .font(.subheadline.weight(.semibold))
+                        .font((self.compact ? Font.footnote : Font.subheadline).weight(.semibold))
                         .foregroundStyle(.primary)
                 }
 
-                Divider()
-                    .frame(height: 14)
-                    .opacity(0.35)
-
                 if let activity {
-                    HStack(spacing: 6) {
+                    if !self.compact {
+                        Divider()
+                            .frame(height: 14)
+                            .opacity(0.35)
+                    }
+
+                    HStack(spacing: self.compact ? 4 : 6) {
                         Image(systemName: activity.systemImage)
-                            .font(.subheadline.weight(.semibold))
+                            .font((self.compact ? Font.footnote : Font.subheadline).weight(.semibold))
                             .foregroundStyle(activity.tint ?? .primary)
-                        Text(activity.title)
-                            .font(.subheadline.weight(.semibold))
-                            .foregroundStyle(.primary)
-                            .lineLimit(1)
+                        if !self.compact {
+                            Text(activity.title)
+                                .font(.subheadline.weight(.semibold))
+                                .foregroundStyle(.primary)
+                                .lineLimit(1)
+                        }
                     }
                     .transition(.opacity.combined(with: .move(edge: .top)))
                 } else {
                     Image(systemName: self.voiceWakeEnabled ? "mic.fill" : "mic.slash")
-                        .font(.subheadline.weight(.semibold))
+                        .font((self.compact ? Font.footnote : Font.subheadline).weight(.semibold))
                         .foregroundStyle(self.voiceWakeEnabled ? .primary : .secondary)
                         .accessibilityLabel(self.voiceWakeEnabled ? "Voice Wake enabled" : "Voice Wake disabled")
                         .transition(.opacity.combined(with: .move(edge: .top)))
                 }
             }
-            .statusGlassCard(brighten: self.brighten, verticalPadding: 8)
+            .statusGlassCard(brighten: self.brighten, verticalPadding: self.compact ? 6 : 8)
         }
         .buttonStyle(.plain)
         .accessibilityLabel("Connection Status")

apps/ios/Tests/NodeAppModelInvokeTests.swift

@@ -83,16 +83,16 @@ private final class MockWatchMessagingService: @preconcurrency WatchMessagingSer
         #expect(json.contains("\"value\""))
     }
 
-    @Test @MainActor func chatSessionKeyDefaultsToIOSBase() {
+    @Test @MainActor func chatSessionKeyDefaultsToMainBase() {
         let appModel = NodeAppModel()
-        #expect(appModel.chatSessionKey == "ios")
+        #expect(appModel.chatSessionKey == "main")
     }
 
     @Test @MainActor func chatSessionKeyUsesAgentScopedKeyForNonDefaultAgent() {
         let appModel = NodeAppModel()
         appModel.gatewayDefaultAgentId = "main"
         appModel.setSelectedAgentId("agent-123")
-        #expect(appModel.chatSessionKey == SessionKey.makeAgentSessionKey(agentId: "agent-123", baseKey: "ios"))
+        #expect(appModel.chatSessionKey == SessionKey.makeAgentSessionKey(agentId: "agent-123", baseKey: "main"))
         #expect(appModel.mainSessionKey == "agent:agent-123:main")
     }
 

apps/shared/OpenClawKit/Sources/OpenClawKit/Resources/CanvasScaffold/scaffold.html

@@ -3,7 +3,7 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
-    <title>Canvas</title>
+    <title>OpenClaw</title>
     <script>
       (() => {
         try {
@@ -15,99 +15,358 @@
           }
           if (/android/i.test(navigator.userAgent || '')) {
             document.documentElement.dataset.platform = 'android';
+          } else {
+            document.documentElement.dataset.platform = 'ios';
           }
         } catch (_) {}
       })();
     </script>
     <style>
-      :root { color-scheme: dark; }
-      @media (prefers-reduced-motion: reduce) {
-        body::before, body::after { animation: none !important; }
+      :root {
+        color-scheme: dark;
+        --bg: #06070b;
+        --panel: rgba(14, 17, 24, 0.74);
+        --panel-strong: rgba(18, 23, 32, 0.86);
+        --line: rgba(255, 255, 255, 0.1);
+        --line-strong: rgba(255, 255, 255, 0.18);
+        --text: rgba(255, 255, 255, 0.96);
+        --muted: rgba(222, 229, 239, 0.72);
+        --soft: rgba(222, 229, 239, 0.5);
+        --accent: #8ec5ff;
+        --accent-strong: #5b9dff;
+        --accent-warm: #ff9159;
+        --accent-rose: #ff5fa2;
+        --state: #7d8ca3;
+        --safe-top: env(safe-area-inset-top, 0px);
+        --safe-bottom: env(safe-area-inset-bottom, 0px);
       }
-      html,body { height:100%; margin:0; }
+
+      html, body {
+        height: 100%;
+        margin: 0;
+      }
+
       body {
+        font-family: -apple-system, BlinkMacSystemFont, "SF Pro Display", "SF Pro Text", system-ui, sans-serif;
         background:
-          radial-gradient(1200px 900px at 15% 20%, rgba(42, 113, 255, 0.18), rgba(0,0,0,0) 55%),
-          radial-gradient(900px 700px at 85% 30%, rgba(255, 0, 138, 0.14), rgba(0,0,0,0) 60%),
-          radial-gradient(1000px 900px at 60% 90%, rgba(0, 209, 255, 0.10), rgba(0,0,0,0) 60%),
-          #000;
+          radial-gradient(900px 640px at 12% 10%, rgba(91, 157, 255, 0.36), rgba(0, 0, 0, 0) 58%),
+          radial-gradient(840px 600px at 88% 16%, rgba(255, 95, 162, 0.24), rgba(0, 0, 0, 0) 62%),
+          radial-gradient(960px 720px at 50% 100%, rgba(255, 145, 89, 0.18), rgba(0, 0, 0, 0) 60%),
+          linear-gradient(180deg, #090b11 0%, #05060a 100%);
+        color: var(--text);
         overflow: hidden;
       }
-      :root[data-platform="android"] body {
-        background:
-          radial-gradient(1200px 900px at 15% 20%, rgba(42, 113, 255, 0.62), rgba(0,0,0,0) 55%),
-          radial-gradient(900px 700px at 85% 30%, rgba(255, 0, 138, 0.52), rgba(0,0,0,0) 60%),
-          radial-gradient(1000px 900px at 60% 90%, rgba(0, 209, 255, 0.48), rgba(0,0,0,0) 60%),
-          #0b1328;
-      }
-      body::before {
-        content:"";
-        position: fixed;
-        inset: -20%;
-        background:
-          repeating-linear-gradient(0deg, rgba(255,255,255,0.03) 0, rgba(255,255,255,0.03) 1px,
-                                 transparent 1px, transparent 48px),
-          repeating-linear-gradient(90deg, rgba(255,255,255,0.03) 0, rgba(255,255,255,0.03) 1px,
-                                 transparent 1px, transparent 48px);
-        transform: translate3d(0,0,0) rotate(-7deg);
-        will-change: transform, opacity;
-        -webkit-backface-visibility: hidden;
-        backface-visibility: hidden;
-        opacity: 0.45;
-        pointer-events: none;
-        animation: openclaw-grid-drift 140s ease-in-out infinite alternate;
-      }
-      :root[data-platform="android"] body::before { opacity: 0.80; }
+
+      body::before,
       body::after {
-        content:"";
+        content: "";
         position: fixed;
-        inset: -35%;
-        background:
-          radial-gradient(900px 700px at 30% 30%, rgba(42,113,255,0.16), rgba(0,0,0,0) 60%),
-          radial-gradient(800px 650px at 70% 35%, rgba(255,0,138,0.12), rgba(0,0,0,0) 62%),
-          radial-gradient(900px 800px at 55% 75%, rgba(0,209,255,0.10), rgba(0,0,0,0) 62%);
-        filter: blur(28px);
-        opacity: 0.52;
-        will-change: transform, opacity;
-        -webkit-backface-visibility: hidden;
-        backface-visibility: hidden;
-        transform: translate3d(0,0,0);
+        inset: -10%;
         pointer-events: none;
-        animation: openclaw-glow-drift 110s ease-in-out infinite alternate;
       }
-      :root[data-platform="android"] body::after { opacity: 0.85; }
-      @supports (mix-blend-mode: screen) {
-        body::after { mix-blend-mode: screen; }
+
+      body::before {
+        background:
+          repeating-linear-gradient(
+            90deg,
+            rgba(255, 255, 255, 0.025) 0,
+            rgba(255, 255, 255, 0.025) 1px,
+            transparent 1px,
+            transparent 52px
+          ),
+          repeating-linear-gradient(
+            0deg,
+            rgba(255, 255, 255, 0.025) 0,
+            rgba(255, 255, 255, 0.025) 1px,
+            transparent 1px,
+            transparent 52px
+          );
+        opacity: 0.42;
+        transform: rotate(-7deg);
       }
-      @supports not (mix-blend-mode: screen) {
-        body::after { opacity: 0.70; }
-      }
-      @keyframes openclaw-grid-drift {
-        0%   { transform: translate3d(-12px, 8px, 0) rotate(-7deg); opacity: 0.40; }
-        50%  { transform: translate3d( 10px,-7px, 0) rotate(-6.6deg); opacity: 0.56; }
-        100% { transform: translate3d(-8px,  6px, 0) rotate(-7.2deg); opacity: 0.42; }
-      }
-      @keyframes openclaw-glow-drift {
-        0%   { transform: translate3d(-18px, 12px, 0) scale(1.02); opacity: 0.40; }
-        50%  { transform: translate3d( 14px,-10px, 0) scale(1.05); opacity: 0.52; }
-        100% { transform: translate3d(-10px,  8px, 0) scale(1.03); opacity: 0.43; }
+
+      body::after {
+        background:
+          radial-gradient(700px 460px at 20% 18%, rgba(142, 197, 255, 0.18), rgba(0, 0, 0, 0) 62%),
+          radial-gradient(720px 520px at 84% 20%, rgba(255, 95, 162, 0.14), rgba(0, 0, 0, 0) 66%),
+          radial-gradient(860px 620px at 52% 88%, rgba(255, 145, 89, 0.14), rgba(0, 0, 0, 0) 64%);
+        filter: blur(28px);
+        opacity: 0.95;
       }
+
+      body[data-state="connected"] { --state: #61d58b; }
+      body[data-state="connecting"] { --state: #ffd05f; }
+      body[data-state="error"] { --state: #ff6d6d; }
+      body[data-state="offline"] { --state: #95a3b9; }
+
       canvas {
         position: fixed;
         inset: 0;
-        display:block;
-        width:100vw;
-        height:100vh;
-        touch-action: none;
+        width: 100vw;
+        height: 100vh;
+        display: block;
         z-index: 1;
       }
-      :root[data-platform="android"] #openclaw-canvas {
-        background:
-          radial-gradient(1100px 800px at 20% 15%, rgba(42, 113, 255, 0.78), rgba(0,0,0,0) 58%),
-          radial-gradient(900px 650px at 82% 28%, rgba(255, 0, 138, 0.66), rgba(0,0,0,0) 62%),
-          radial-gradient(1000px 900px at 60% 88%, rgba(0, 209, 255, 0.58), rgba(0,0,0,0) 62%),
-          #141c33;
+
+      #openclaw-home {
+        position: fixed;
+        inset: 0;
+        z-index: 2;
+        display: flex;
+        align-items: flex-start;
+        justify-content: center;
+        padding: calc(var(--safe-top) + 18px) 16px calc(var(--safe-bottom) + 18px);
+        box-sizing: border-box;
+        overflow-y: auto;
+        overflow-x: hidden;
+        -webkit-overflow-scrolling: touch;
       }
+
+      .shell {
+        width: min(100%, 760px);
+        display: flex;
+        flex-direction: column;
+        justify-content: flex-start;
+        gap: 16px;
+        min-height: 100%;
+        box-sizing: border-box;
+      }
+
+      .hero {
+        position: relative;
+        overflow: hidden;
+        border-radius: 28px;
+        background: linear-gradient(180deg, rgba(18, 24, 34, 0.86), rgba(10, 13, 19, 0.94));
+        border: 1px solid var(--line);
+        box-shadow: 0 28px 90px rgba(0, 0, 0, 0.42);
+        padding: 22px 22px 18px;
+      }
+
+      .hero::before {
+        content: "";
+        position: absolute;
+        inset: -30% auto auto -20%;
+        width: 240px;
+        height: 240px;
+        border-radius: 999px;
+        background: radial-gradient(circle, rgba(142, 197, 255, 0.18), rgba(0, 0, 0, 0));
+        pointer-events: none;
+      }
+
+      .eyebrow {
+        display: inline-flex;
+        align-items: center;
+        gap: 9px;
+        padding: 8px 12px;
+        border-radius: 999px;
+        background: rgba(255, 255, 255, 0.04);
+        border: 1px solid rgba(255, 255, 255, 0.08);
+        color: var(--muted);
+        font-size: 12px;
+        font-weight: 700;
+        letter-spacing: 0.06em;
+        text-transform: uppercase;
+        max-width: 100%;
+        box-sizing: border-box;
+      }
+
+      .eyebrow-dot {
+        flex: 0 0 auto;
+        width: 9px;
+        height: 9px;
+        border-radius: 999px;
+        background: var(--state);
+        box-shadow: 0 0 18px color-mix(in srgb, var(--state) 68%, transparent);
+      }
+
+      #openclaw-home-eyebrow {
+        min-width: 0;
+        overflow: hidden;
+        text-overflow: ellipsis;
+        white-space: nowrap;
+      }
+
+      .hero h1 {
+        margin: 18px 0 0;
+        font-size: clamp(32px, 7vw, 52px);
+        line-height: 0.98;
+        letter-spacing: -0.04em;
+      }
+
+      .hero p {
+        margin: 14px 0 0;
+        font-size: 16px;
+        line-height: 1.5;
+        color: var(--muted);
+        max-width: 32rem;
+      }
+
+      .hero-grid {
+        display: grid;
+        grid-template-columns: 1.2fr 1fr;
+        gap: 12px;
+        margin-top: 22px;
+      }
+
+      .meta-card,
+      .agent-card {
+        border-radius: 22px;
+        background: var(--panel);
+        border: 1px solid var(--line);
+        backdrop-filter: blur(18px);
+        -webkit-backdrop-filter: blur(18px);
+      }
+
+      .meta-card {
+        padding: 16px 16px 15px;
+      }
+
+      .meta-label {
+        font-size: 11px;
+        letter-spacing: 0.08em;
+        text-transform: uppercase;
+        color: var(--soft);
+      }
+
+      .meta-value {
+        margin-top: 8px;
+        font-size: 24px;
+        font-weight: 700;
+        letter-spacing: -0.03em;
+        overflow-wrap: anywhere;
+      }
+
+      .meta-subtitle {
+        margin-top: 6px;
+        color: var(--muted);
+        font-size: 13px;
+        line-height: 1.4;
+      }
+
+      .agent-focus {
+        display: flex;
+        align-items: flex-start;
+        gap: 14px;
+        margin-top: 8px;
+      }
+
+      .agent-badge {
+        width: 56px;
+        height: 56px;
+        border-radius: 18px;
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        background:
+          linear-gradient(135deg, rgba(142, 197, 255, 0.22), rgba(91, 157, 255, 0.1)),
+          rgba(255, 255, 255, 0.04);
+        border: 1px solid rgba(255, 255, 255, 0.12);
+        font-size: 24px;
+        font-weight: 700;
+      }
+
+      .agent-focus .name {
+        font-size: 22px;
+        font-weight: 700;
+        letter-spacing: -0.03em;
+        overflow-wrap: anywhere;
+      }
+
+      .agent-focus .caption {
+        margin-top: 4px;
+        font-size: 13px;
+        color: var(--muted);
+      }
+
+      .section {
+        padding: 16px 16px 14px;
+      }
+
+      .section-header {
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        gap: 12px;
+        margin-bottom: 12px;
+      }
+
+      .section-title {
+        font-size: 14px;
+        font-weight: 700;
+        color: var(--muted);
+      }
+
+      .section-count {
+        font-size: 12px;
+        font-weight: 700;
+        color: var(--soft);
+      }
+
+      .agent-grid {
+        display: grid;
+        grid-template-columns: repeat(2, minmax(0, 1fr));
+        gap: 10px;
+      }
+
+      .agent-card {
+        padding: 13px 13px 12px;
+      }
+
+      .agent-card.active {
+        background: var(--panel-strong);
+        border-color: var(--line-strong);
+        box-shadow: inset 0 0 0 1px rgba(142, 197, 255, 0.12);
+      }
+
+      .agent-row {
+        display: flex;
+        align-items: center;
+        gap: 10px;
+      }
+
+      .agent-row .badge {
+        width: 38px;
+        height: 38px;
+        border-radius: 14px;
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        background: rgba(255, 255, 255, 0.05);
+        border: 1px solid rgba(255, 255, 255, 0.08);
+        font-size: 16px;
+        font-weight: 700;
+      }
+
+      .agent-row .name {
+        font-size: 15px;
+        font-weight: 700;
+        line-height: 1.2;
+        overflow-wrap: anywhere;
+      }
+
+      .agent-row .caption {
+        margin-top: 3px;
+        font-size: 12px;
+        color: var(--muted);
+      }
+
+      .empty-state {
+        padding: 18px;
+        border-radius: 18px;
+        background: rgba(255, 255, 255, 0.03);
+        border: 1px dashed rgba(255, 255, 255, 0.12);
+        color: var(--muted);
+        font-size: 14px;
+        line-height: 1.45;
+      }
+
+      .footer-note {
+        margin-top: 12px;
+        color: var(--soft);
+        font-size: 12px;
+        line-height: 1.45;
+      }
+
       #openclaw-status {
         position: fixed;
         inset: 0;
@@ -115,41 +374,174 @@
         align-items: center;
         justify-content: flex-start;
         flex-direction: column;
-        padding-top: calc(20px + env(safe-area-inset-top, 0px));
+        padding-top: calc(var(--safe-top) + 18px);
         pointer-events: none;
         z-index: 3;
       }
+
       #openclaw-status .card {
         text-align: center;
         padding: 16px 18px;
         border-radius: 14px;
-        background: rgba(18, 18, 22, 0.42);
-        border: 1px solid rgba(255,255,255,0.08);
-        box-shadow: 0 18px 60px rgba(0,0,0,0.55);
+        background: rgba(18, 18, 22, 0.46);
+        border: 1px solid rgba(255, 255, 255, 0.08);
+        box-shadow: 0 18px 60px rgba(0, 0, 0, 0.55);
         -webkit-backdrop-filter: blur(14px);
         backdrop-filter: blur(14px);
       }
+
       #openclaw-status .title {
         font: 600 20px -apple-system, BlinkMacSystemFont, "SF Pro Display", "SF Pro Text", system-ui, sans-serif;
-        letter-spacing: 0.2px;
-        color: rgba(255,255,255,0.92);
-        text-shadow: 0 0 22px rgba(42, 113, 255, 0.35);
+        color: rgba(255, 255, 255, 0.92);
       }
+
       #openclaw-status .subtitle {
         margin-top: 6px;
         font: 500 12px -apple-system, BlinkMacSystemFont, "SF Pro Text", system-ui, sans-serif;
-        color: rgba(255,255,255,0.58);
+        color: rgba(255, 255, 255, 0.58);
+      }
+
+      @media (max-width: 640px) {
+        #openclaw-home {
+          padding-left: 12px;
+          padding-right: 12px;
+        }
+
+        .hero {
+          border-radius: 24px;
+          padding: 18px 16px 16px;
+        }
+
+        .hero-grid,
+        .agent-grid {
+          grid-template-columns: 1fr;
+        }
+
+        .hero h1 {
+          font-size: 34px;
+        }
+      }
+
+      @media (max-height: 760px) {
+        #openclaw-home {
+          padding-top: calc(var(--safe-top) + 14px);
+          padding-bottom: calc(var(--safe-bottom) + 12px);
+        }
+
+        .shell {
+          gap: 12px;
+        }
+
+        .hero {
+          border-radius: 24px;
+          padding: 16px 15px 15px;
+        }
+
+        .hero h1 {
+          margin-top: 14px;
+          font-size: clamp(28px, 8vw, 38px);
+        }
+
+        .hero p {
+          margin-top: 10px;
+          font-size: 15px;
+          line-height: 1.42;
+        }
+
+        .hero-grid {
+          margin-top: 18px;
+        }
+
+        .meta-card {
+          padding: 14px 14px 13px;
+        }
+
+        .meta-value {
+          font-size: 22px;
+        }
+
+        .agent-badge {
+          width: 50px;
+          height: 50px;
+          border-radius: 16px;
+          font-size: 22px;
+        }
+
+        .agent-focus .name {
+          font-size: 20px;
+        }
+
+        .section {
+          padding: 14px 14px 12px;
+        }
+
+        .section-header {
+          margin-bottom: 10px;
+        }
+      }
+
+      @media (prefers-reduced-motion: reduce) {
+        body::before,
+        body::after {
+          animation: none !important;
+        }
       }
     </style>
   </head>
-  <body>
+  <body data-state="offline">
     <canvas id="openclaw-canvas"></canvas>
+    <div id="openclaw-home">
+      <div class="shell">
+        <div class="hero">
+          <div class="eyebrow">
+            <span class="eyebrow-dot"></span>
+            <span id="openclaw-home-eyebrow">Welcome to OpenClaw</span>
+          </div>
+          <h1 id="openclaw-home-title">Your phone stays quiet until it is needed</h1>
+          <p id="openclaw-home-subtitle">
+            Pair this device to your gateway to wake it only for real work, keep a live agent overview handy, and avoid battery-draining background loops.
+          </p>
+
+          <div class="hero-grid">
+            <div class="meta-card">
+              <div class="meta-label">Gateway</div>
+              <div class="meta-value" id="openclaw-home-gateway">Gateway</div>
+              <div class="meta-subtitle" id="openclaw-home-gateway-caption">Connect to load your agents</div>
+            </div>
+
+            <div class="meta-card">
+              <div class="meta-label">Active Agent</div>
+              <div class="agent-focus">
+                <div class="agent-badge" id="openclaw-home-active-badge">OC</div>
+                <div>
+                  <div class="name" id="openclaw-home-active-name">Main</div>
+                  <div class="caption" id="openclaw-home-active-caption">Connect to load your agents</div>
+                </div>
+              </div>
+            </div>
+          </div>
+        </div>
+
+        <div class="meta-card section">
+          <div class="section-header">
+            <div class="section-title">Live agents</div>
+            <div class="section-count" id="openclaw-home-agent-count">0 agents</div>
+          </div>
+          <div class="agent-grid" id="openclaw-home-agent-grid"></div>
+          <div class="footer-note" id="openclaw-home-footer">
+            When connected, the gateway can wake the phone with a silent push instead of holding an always-on session.
+          </div>
+        </div>
+      </div>
+    </div>
+
     <div id="openclaw-status">
       <div class="card">
         <div class="title" id="openclaw-status-title">Ready</div>
         <div class="subtitle" id="openclaw-status-subtitle">Waiting for agent</div>
       </div>
     </div>
+
     <script>
       (() => {
         const canvas = document.getElementById('openclaw-canvas');
@@ -157,6 +549,20 @@
         const statusEl = document.getElementById('openclaw-status');
         const titleEl = document.getElementById('openclaw-status-title');
         const subtitleEl = document.getElementById('openclaw-status-subtitle');
+        const home = {
+          root: document.getElementById('openclaw-home'),
+          eyebrow: document.getElementById('openclaw-home-eyebrow'),
+          title: document.getElementById('openclaw-home-title'),
+          subtitle: document.getElementById('openclaw-home-subtitle'),
+          gateway: document.getElementById('openclaw-home-gateway'),
+          gatewayCaption: document.getElementById('openclaw-home-gateway-caption'),
+          activeBadge: document.getElementById('openclaw-home-active-badge'),
+          activeName: document.getElementById('openclaw-home-active-name'),
+          activeCaption: document.getElementById('openclaw-home-active-caption'),
+          agentCount: document.getElementById('openclaw-home-agent-count'),
+          agentGrid: document.getElementById('openclaw-home-agent-grid'),
+          footer: document.getElementById('openclaw-home-footer')
+        };
         const debugStatusEnabledByQuery = (() => {
           try {
             const params = new URLSearchParams(window.location.search);
@@ -172,54 +578,114 @@
 
         function resize() {
           const dpr = window.devicePixelRatio || 1;
-          const w = Math.max(1, Math.floor(window.innerWidth * dpr));
-          const h = Math.max(1, Math.floor(window.innerHeight * dpr));
-          canvas.width = w;
-          canvas.height = h;
+          const width = Math.max(1, Math.floor(window.innerWidth * dpr));
+          const height = Math.max(1, Math.floor(window.innerHeight * dpr));
+          canvas.width = width;
+          canvas.height = height;
           ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
         }
 
+        function setDebugStatusEnabled(enabled) {
+          debugStatusEnabled = !!enabled;
+          if (!debugStatusEnabled) {
+            statusEl.style.display = 'none';
+          }
+        }
+
+        function setStatus(title, subtitle) {
+          if (!debugStatusEnabled) return;
+          if (!title && !subtitle) {
+            statusEl.style.display = 'none';
+            return;
+          }
+          statusEl.style.display = 'flex';
+          if (typeof title === 'string') titleEl.textContent = title;
+          if (typeof subtitle === 'string') subtitleEl.textContent = subtitle;
+        }
+
+        function clearChildren(node) {
+          while (node.firstChild) node.removeChild(node.firstChild);
+        }
+
+        function createAgentCard(agent) {
+          const card = document.createElement('div');
+          card.className = `agent-card${agent.isActive ? ' active' : ''}`;
+
+          const row = document.createElement('div');
+          row.className = 'agent-row';
+
+          const badge = document.createElement('div');
+          badge.className = 'badge';
+          badge.textContent = agent.badge || 'OC';
+
+          const text = document.createElement('div');
+
+          const name = document.createElement('div');
+          name.className = 'name';
+          name.textContent = agent.name || agent.id || 'Agent';
+
+          const caption = document.createElement('div');
+          caption.className = 'caption';
+          caption.textContent = agent.caption || 'Ready';
+
+          text.appendChild(name);
+          text.appendChild(caption);
+          row.appendChild(badge);
+          row.appendChild(text);
+          card.appendChild(row);
+          return card;
+        }
+
+        function renderHome(state) {
+          if (!state || typeof state !== 'object') return;
+
+          document.body.dataset.state = state.gatewayState || 'offline';
+          home.root.style.display = 'flex';
+          home.eyebrow.textContent = state.eyebrow || 'Welcome to OpenClaw';
+          home.title.textContent = state.title || 'OpenClaw';
+          home.subtitle.textContent = state.subtitle || '';
+          home.gateway.textContent = state.gatewayLabel || 'Gateway';
+          home.gatewayCaption.textContent = state.gatewayState === 'connected'
+            ? `${state.agentCount || 0} agent${state.agentCount === 1 ? '' : 's'} available`
+            : (state.activeAgentCaption || 'Connect to load your agents');
+          home.activeBadge.textContent = state.activeAgentBadge || 'OC';
+          home.activeName.textContent = state.activeAgentName || 'Main';
+          home.activeCaption.textContent = state.activeAgentCaption || '';
+          home.agentCount.textContent = `${state.agentCount || 0} agent${state.agentCount === 1 ? '' : 's'}`;
+          home.footer.textContent = state.footer || '';
+
+          clearChildren(home.agentGrid);
+          const agents = Array.isArray(state.agents) ? state.agents : [];
+          if (!agents.length) {
+            const empty = document.createElement('div');
+            empty.className = 'empty-state';
+            empty.textContent = state.gatewayState === 'connected'
+              ? 'Your gateway is online. Agents will appear here as soon as the current scope reports them.'
+              : 'Connect this phone to your gateway and the live agent overview will appear here.';
+            home.agentGrid.appendChild(empty);
+            return;
+          }
+
+          agents.forEach((agent) => {
+            home.agentGrid.appendChild(createAgentCard(agent));
+          });
+        }
+
         window.addEventListener('resize', resize);
         resize();
 
-        const setDebugStatusEnabled = (enabled) => {
-          debugStatusEnabled = !!enabled;
-          if (!statusEl) return;
-          if (!debugStatusEnabled) {
-            statusEl.style.display = 'none';
-          }
-        };
-
-        if (statusEl && !debugStatusEnabled) {
+        if (!debugStatusEnabled) {
           statusEl.style.display = 'none';
         }
 
-        const api = {
+        window.__openclaw = {
           canvas,
           ctx,
           setDebugStatusEnabled,
-          setStatus: (title, subtitle) => {
-            if (!statusEl || !debugStatusEnabled) return;
-            if (!title && !subtitle) {
-              statusEl.style.display = 'none';
-              return;
-            }
-            statusEl.style.display = 'flex';
-            if (titleEl && typeof title === 'string') titleEl.textContent = title;
-            if (subtitleEl && typeof subtitle === 'string') subtitleEl.textContent = subtitle;
-            if (!debugStatusEnabled) {
-              clearTimeout(window.__statusTimeout);
-              window.__statusTimeout = setTimeout(() => {
-                statusEl.style.display = 'none';
-              }, 3000);
-            } else {
-              clearTimeout(window.__statusTimeout);
-            }
-          }
+          setStatus,
+          renderHome
         };
-        window.__openclaw = api;
       })();
-
     </script>
   </body>
 </html>

docs/channels/discord.md

@@ -168,6 +168,7 @@ openclaw pairing approve discord <CODE>
 
 <Note>
 Token resolution is account-aware. Config token values win over env fallback. `DISCORD_BOT_TOKEN` is only used for the default account.
+For advanced outbound calls (message tool/channel actions), an explicit per-call `token` is used for that call. Account policy/retry settings still come from the selected account in the active runtime snapshot.
 </Note>
 
 ## Recommended: Set up a guild workspace

docs/channels/telegram.md

@@ -155,6 +155,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
 
     `groupAllowFrom` is used for group sender filtering. If not set, Telegram falls back to `allowFrom`.
     `groupAllowFrom` entries should be numeric Telegram user IDs (`telegram:` / `tg:` prefixes are normalized).
+    Do not put Telegram group or supergroup chat IDs in `groupAllowFrom`. Negative chat IDs belong under `channels.telegram.groups`.
     Non-numeric entries are ignored for sender authorization.
     Security boundary (`2026.2.25+`): group sender auth does **not** inherit DM pairing-store approvals.
     Pairing stays DM-only. For groups, set `groupAllowFrom` or per-group/per-topic `allowFrom`.
@@ -177,6 +178,31 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
 }
 ```
 
+    Example: allow only specific users inside one specific group:
+
+```json5
+{
+  channels: {
+    telegram: {
+      groups: {
+        "-1001234567890": {
+          requireMention: true,
+          allowFrom: ["8734062810", "745123456"],
+        },
+      },
+    },
+  },
+}
+```
+
+    <Warning>
+      Common mistake: `groupAllowFrom` is not a Telegram group allowlist.
+
+      - Put negative Telegram group or supergroup chat IDs like `-1001234567890` under `channels.telegram.groups`.
+      - Put Telegram user IDs like `8734062810` under `groupAllowFrom` when you want to limit which people inside an allowed group can trigger the bot.
+      - Use `groupAllowFrom: ["*"]` only when you want any member of an allowed group to be able to talk to the bot.
+    </Warning>
+
   </Tab>
 
   <Tab title="Mention behavior">
@@ -410,6 +436,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
     - `channels.telegram.actions.sticker` (default: disabled)
 
     Note: `edit` and `topic-create` are currently enabled by default and do not have separate `channels.telegram.actions.*` toggles.
+    Runtime sends use the active config/secrets snapshot (startup/reload), so action paths do not perform ad-hoc SecretRef re-resolution per send.
 
     Reaction removal semantics: [/tools/reactions](/tools/reactions)
 

docs/gateway/configuration-reference.md

@@ -304,6 +304,7 @@ WhatsApp runs through the gateway's web channel (Baileys Web). It starts automat
 ```
 
 - Token: `channels.discord.token`, with `DISCORD_BOT_TOKEN` as fallback for the default account.
+- Direct outbound calls that provide an explicit Discord `token` use that token for the call; account retry/policy settings still come from the selected account in the active runtime snapshot.
 - Optional `channels.discord.defaultAccount` overrides default account selection when it matches a configured account id.
 - Use `user:<id>` (DM) or `channel:<id>` (guild channel) for delivery targets; bare numeric IDs are rejected.
 - Guild slugs are lowercase with spaces replaced by `-`; channel keys use the slugged name (no `#`). Prefer guild IDs.
@@ -2712,6 +2713,7 @@ Validation:
 - `source: "env"` id pattern: `^[A-Z][A-Z0-9_]{0,127}$`
 - `source: "file"` id: absolute JSON pointer (for example `"/providers/openai/apiKey"`)
 - `source: "exec"` id pattern: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$`
+- `source: "exec"` ids must not contain `.` or `..` slash-delimited path segments (for example `a/../b` is rejected)
 
 ### Supported credential surface
 

docs/gateway/secrets.md

@@ -21,6 +21,7 @@ Secrets are resolved into an in-memory runtime snapshot.
 - Startup fails fast when an effectively active SecretRef cannot be resolved.
 - Reload uses atomic swap: full success, or keep the last-known-good snapshot.
 - Runtime requests read from the active in-memory snapshot only.
+- Outbound delivery paths also read from that active snapshot (for example Discord reply/thread delivery and Telegram action sends); they do not re-resolve SecretRefs on each send.
 
 This keeps secret-provider outages off hot request paths.
 
@@ -113,6 +114,7 @@ Validation:
 
 - `provider` must match `^[a-z][a-z0-9_-]{0,63}$`
 - `id` must match `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$`
+- `id` must not contain `.` or `..` as slash-delimited path segments (for example `a/../b` is rejected)
 
 ## Provider config
 
@@ -321,6 +323,7 @@ Activation contract:
 - Success swaps the snapshot atomically.
 - Startup failure aborts gateway startup.
 - Runtime reload failure keeps the last-known-good snapshot.
+- Providing an explicit per-call channel token to an outbound helper/tool call does not trigger SecretRef activation; activation points remain startup, reload, and explicit `secrets.reload`.
 
 ## Degraded and recovered signals
 

docs/help/testing.md

@@ -409,3 +409,6 @@ When you fix a provider/model issue discovered in live:
 - Prefer targeting the smallest layer that catches the bug:
   - provider request conversion/replay bug → direct models test
   - gateway session/history/tool pipeline bug → gateway live smoke or CI-safe gateway mock test
+- SecretRef traversal guardrail:
+  - `src/secrets/exec-secret-ref-id-parity.test.ts` derives one sampled target per SecretRef class from registry metadata (`listSecretTargetRegistryEntries()`), then asserts traversal-segment exec ids are rejected.
+  - If you add a new `includeInPlan` SecretRef target family in `src/secrets/target-registry-data.ts`, update `classifyTargetClass` in that test. The test intentionally fails on unclassified target ids so new classes cannot be skipped silently.

docs/reference/RELEASING.md

@@ -19,6 +19,32 @@ When the operator says “release”, immediately do this preflight (no extra qu
 - Load env from `~/.profile` and confirm `SPARKLE_PRIVATE_KEY_FILE` + App Store Connect vars are set (SPARKLE_PRIVATE_KEY_FILE should live in `~/.profile`).
 - Use Sparkle keys from `~/Library/CloudStorage/Dropbox/Backup/Sparkle` if needed.
 
+## Versioning
+
+Current OpenClaw releases use date-based versioning.
+
+- Stable release version: `YYYY.M.D`
+  - Git tag: `vYYYY.M.D`
+  - Examples from repo history: `v2026.2.26`, `v2026.3.8`
+- Beta prerelease version: `YYYY.M.D-beta.N`
+  - Git tag: `vYYYY.M.D-beta.N`
+  - Examples from repo history: `v2026.2.15-beta.1`, `v2026.3.8-beta.1`
+- Use the same version string everywhere, minus the leading `v` where Git tags are not used:
+  - `package.json`: `2026.3.8`
+  - Git tag: `v2026.3.8`
+  - GitHub release title: `openclaw 2026.3.8`
+- Do not zero-pad month or day. Use `2026.3.8`, not `2026.03.08`.
+- Stable and beta are npm dist-tags, not separate release lines:
+  - `latest` = stable
+  - `beta` = prerelease/testing
+- Dev is the moving head of `main`, not a normal git-tagged release.
+- The release workflow enforces the current stable/beta tag formats and rejects versions whose CalVer date is more than 2 UTC calendar days away from the release date.
+
+Historical note:
+
+- Older tags such as `v2026.1.11-1`, `v2026.2.6-3`, and `v2.0.0-beta2` exist in repo history.
+- Treat those as legacy tag patterns. New releases should use `vYYYY.M.D` for stable and `vYYYY.M.D-beta.N` for beta.
+
 1. **Version & metadata**
 
 - [ ] Bump `package.json` version (e.g., `2026.1.29`).
@@ -67,8 +93,11 @@ When the operator says “release”, immediately do this preflight (no extra qu
 6. **Publish (npm)**
 
 - [ ] Confirm git status is clean; commit and push as needed.
-- [ ] `npm login` (verify 2FA) if needed.
-- [ ] `npm publish --access public` (use `--tag beta` for pre-releases).
+- [ ] Confirm npm trusted publishing is configured for the `openclaw` package.
+- [ ] Push the matching git tag to trigger `.github/workflows/openclaw-npm-release.yml`.
+  - Stable tags publish to npm `latest`.
+  - Beta tags publish to npm `beta`.
+  - The workflow rejects tags that do not match `package.json`, are not on `main`, or whose CalVer date is more than 2 UTC calendar days away from the release date.
 - [ ] Verify the registry: `npm view openclaw version`, `npm view openclaw dist-tags`, and `npx -y openclaw@X.Y.Z --version` (or `--help`).
 
 ### Troubleshooting (notes from 2.0.0-beta2 release)
@@ -84,6 +113,7 @@ When the operator says “release”, immediately do this preflight (no extra qu
 7. **GitHub release + appcast**
 
 - [ ] Tag and push: `git tag vX.Y.Z && git push origin vX.Y.Z` (or `git push --tags`).
+  - Pushing the tag also triggers the npm release workflow.
 - [ ] Create/refresh the GitHub release for `vX.Y.Z` with **title `openclaw X.Y.Z`** (not just the tag); body should include the **full** changelog section for that version (Highlights + Changes + Fixes), inline (no bare links), and **must not repeat the title inside the body**.
 - [ ] Attach artifacts: `npm pack` tarball (optional), `OpenClaw-X.Y.Z.zip`, and `OpenClaw-X.Y.Z.dSYM.zip` (if generated).
 - [ ] Commit the updated `appcast.xml` and push it (Sparkle feeds from main).

docs/tools/acp-agents.md

@@ -243,9 +243,36 @@ Interface details:
   - `mode: "session"` requires `thread: true`
 - `cwd` (optional): requested runtime working directory (validated by backend/runtime policy).
 - `label` (optional): operator-facing label used in session/banner text.
+- `resumeSessionId` (optional): resume an existing ACP session instead of creating a new one. The agent replays its conversation history via `session/load`. Requires `runtime: "acp"`.
 - `streamTo` (optional): `"parent"` streams initial ACP run progress summaries back to the requester session as system events.
   - When available, accepted responses include `streamLogPath` pointing to a session-scoped JSONL log (`<sessionId>.acp-stream.jsonl`) you can tail for full relay history.
 
+### Resume an existing session
+
+Use `resumeSessionId` to continue a previous ACP session instead of starting fresh. The agent replays its conversation history via `session/load`, so it picks up with full context of what came before.
+
+```json
+{
+  "task": "Continue where we left off — fix the remaining test failures",
+  "runtime": "acp",
+  "agentId": "codex",
+  "resumeSessionId": "<previous-session-id>"
+}
+```
+
+Common use cases:
+
+- Hand off a Codex session from your laptop to your phone — tell your agent to pick up where you left off
+- Continue a coding session you started interactively in the CLI, now headlessly through your agent
+- Pick up work that was interrupted by a gateway restart or idle timeout
+
+Notes:
+
+- `resumeSessionId` requires `runtime: "acp"` — returns an error if used with the sub-agent runtime.
+- `resumeSessionId` restores the upstream ACP conversation history; `thread` and `mode` still apply normally to the new OpenClaw session you are creating, so `mode: "session"` still requires `thread: true`.
+- The target agent must support `session/load` (Codex and Claude Code do).
+- If the session ID isn't found, the spawn fails with a clear error — no silent fallback to a new session.
+
 ### Operator smoke test
 
 Use this after a gateway deploy when you want a quick live check that ACP spawn

extensions/diffs/src/browser.test.ts

@@ -1,8 +1,8 @@
 import fs from "node:fs/promises";
-import os from "node:os";
 import path from "node:path";
 import type { OpenClawConfig } from "openclaw/plugin-sdk/diffs";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createTempDiffRoot } from "./test-helpers.js";
 
 const { launchMock } = vi.hoisted(() => ({
   launchMock: vi.fn(),
@@ -17,10 +17,11 @@ vi.mock("playwright-core", () => ({
 describe("PlaywrightDiffScreenshotter", () => {
   let rootDir: string;
   let outputPath: string;
+  let cleanupRootDir: () => Promise<void>;
 
   beforeEach(async () => {
     vi.useFakeTimers();
-    rootDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-diffs-browser-"));
+    ({ rootDir, cleanup: cleanupRootDir } = await createTempDiffRoot("openclaw-diffs-browser-"));
     outputPath = path.join(rootDir, "preview.png");
     launchMock.mockReset();
     const browserModule = await import("./browser.js");
@@ -31,7 +32,7 @@ describe("PlaywrightDiffScreenshotter", () => {
     const browserModule = await import("./browser.js");
     await browserModule.resetSharedBrowserStateForTests();
     vi.useRealTimers();
-    await fs.rm(rootDir, { recursive: true, force: true });
+    await cleanupRootDir();
   });
 
   it("reuses the same browser across renders and closes it after the idle window", async () => {

extensions/diffs/src/http.test.ts

@@ -1,32 +1,24 @@
-import fs from "node:fs/promises";
 import type { IncomingMessage } from "node:http";
-import os from "node:os";
-import path from "node:path";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import { createMockServerResponse } from "../../../src/test-utils/mock-http-response.js";
 import { createDiffsHttpHandler } from "./http.js";
 import { DiffArtifactStore } from "./store.js";
+import { createDiffStoreHarness } from "./test-helpers.js";
 
 describe("createDiffsHttpHandler", () => {
-  let rootDir: string;
   let store: DiffArtifactStore;
+  let cleanupRootDir: () => Promise<void>;
 
   beforeEach(async () => {
-    rootDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-diffs-http-"));
-    store = new DiffArtifactStore({ rootDir });
+    ({ store, cleanup: cleanupRootDir } = await createDiffStoreHarness("openclaw-diffs-http-"));
   });
 
   afterEach(async () => {
-    await fs.rm(rootDir, { recursive: true, force: true });
+    await cleanupRootDir();
   });
 
   it("serves a stored diff document", async () => {
-    const artifact = await store.createArtifact({
-      html: "<html>viewer</html>",
-      title: "Demo",
-      inputKind: "before_after",
-      fileCount: 1,
-    });
+    const artifact = await createViewerArtifact(store);
 
     const handler = createDiffsHttpHandler({ store });
     const res = createMockServerResponse();
@@ -45,12 +37,7 @@ describe("createDiffsHttpHandler", () => {
   });
 
   it("rejects invalid tokens", async () => {
-    const artifact = await store.createArtifact({
-      html: "<html>viewer</html>",
-      title: "Demo",
-      inputKind: "before_after",
-      fileCount: 1,
-    });
+    const artifact = await createViewerArtifact(store);
 
     const handler = createDiffsHttpHandler({ store });
     const res = createMockServerResponse();
@@ -113,96 +100,52 @@ describe("createDiffsHttpHandler", () => {
     expect(String(res.body)).toContain("openclawDiffsReady");
   });
 
-  it("blocks non-loopback viewer access by default", async () => {
-    const artifact = await store.createArtifact({
-      html: "<html>viewer</html>",
-      title: "Demo",
-      inputKind: "before_after",
-      fileCount: 1,
-    });
+  it.each([
+    {
+      name: "blocks non-loopback viewer access by default",
+      request: remoteReq,
+      allowRemoteViewer: false,
+      expectedStatusCode: 404,
+    },
+    {
+      name: "blocks loopback requests that carry proxy forwarding headers by default",
+      request: localReq,
+      headers: { "x-forwarded-for": "203.0.113.10" },
+      allowRemoteViewer: false,
+      expectedStatusCode: 404,
+    },
+    {
+      name: "allows remote access when allowRemoteViewer is enabled",
+      request: remoteReq,
+      allowRemoteViewer: true,
+      expectedStatusCode: 200,
+    },
+    {
+      name: "allows proxied loopback requests when allowRemoteViewer is enabled",
+      request: localReq,
+      headers: { "x-forwarded-for": "203.0.113.10" },
+      allowRemoteViewer: true,
+      expectedStatusCode: 200,
+    },
+  ])("$name", async ({ request, headers, allowRemoteViewer, expectedStatusCode }) => {
+    const artifact = await createViewerArtifact(store);
 
-    const handler = createDiffsHttpHandler({ store });
+    const handler = createDiffsHttpHandler({ store, allowRemoteViewer });
     const res = createMockServerResponse();
     const handled = await handler(
-      remoteReq({
+      request({
         method: "GET",
         url: artifact.viewerPath,
+        headers,
       }),
       res,
     );
 
     expect(handled).toBe(true);
-    expect(res.statusCode).toBe(404);
-  });
-
-  it("blocks loopback requests that carry proxy forwarding headers by default", async () => {
-    const artifact = await store.createArtifact({
-      html: "<html>viewer</html>",
-      title: "Demo",
-      inputKind: "before_after",
-      fileCount: 1,
-    });
-
-    const handler = createDiffsHttpHandler({ store });
-    const res = createMockServerResponse();
-    const handled = await handler(
-      localReq({
-        method: "GET",
-        url: artifact.viewerPath,
-        headers: { "x-forwarded-for": "203.0.113.10" },
-      }),
-      res,
-    );
-
-    expect(handled).toBe(true);
-    expect(res.statusCode).toBe(404);
-  });
-
-  it("allows remote access when allowRemoteViewer is enabled", async () => {
-    const artifact = await store.createArtifact({
-      html: "<html>viewer</html>",
-      title: "Demo",
-      inputKind: "before_after",
-      fileCount: 1,
-    });
-
-    const handler = createDiffsHttpHandler({ store, allowRemoteViewer: true });
-    const res = createMockServerResponse();
-    const handled = await handler(
-      remoteReq({
-        method: "GET",
-        url: artifact.viewerPath,
-      }),
-      res,
-    );
-
-    expect(handled).toBe(true);
-    expect(res.statusCode).toBe(200);
-    expect(res.body).toBe("<html>viewer</html>");
-  });
-
-  it("allows proxied loopback requests when allowRemoteViewer is enabled", async () => {
-    const artifact = await store.createArtifact({
-      html: "<html>viewer</html>",
-      title: "Demo",
-      inputKind: "before_after",
-      fileCount: 1,
-    });
-
-    const handler = createDiffsHttpHandler({ store, allowRemoteViewer: true });
-    const res = createMockServerResponse();
-    const handled = await handler(
-      localReq({
-        method: "GET",
-        url: artifact.viewerPath,
-        headers: { "x-forwarded-for": "203.0.113.10" },
-      }),
-      res,
-    );
-
-    expect(handled).toBe(true);
-    expect(res.statusCode).toBe(200);
-    expect(res.body).toBe("<html>viewer</html>");
+    expect(res.statusCode).toBe(expectedStatusCode);
+    if (expectedStatusCode === 200) {
+      expect(res.body).toBe("<html>viewer</html>");
+    }
   });
 
   it("rate-limits repeated remote misses", async () => {
@@ -232,6 +175,15 @@ describe("createDiffsHttpHandler", () => {
   });
 });
 
+async function createViewerArtifact(store: DiffArtifactStore) {
+  return await store.createArtifact({
+    html: "<html>viewer</html>",
+    title: "Demo",
+    inputKind: "before_after",
+    fileCount: 1,
+  });
+}
+
 function localReq(input: {
   method: string;
   url: string;

extensions/diffs/src/store.test.ts

@@ -1,21 +1,25 @@
 import fs from "node:fs/promises";
-import os from "node:os";
 import path from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { DiffArtifactStore } from "./store.js";
+import { createDiffStoreHarness } from "./test-helpers.js";
 
 describe("DiffArtifactStore", () => {
   let rootDir: string;
   let store: DiffArtifactStore;
+  let cleanupRootDir: () => Promise<void>;
 
   beforeEach(async () => {
-    rootDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-diffs-store-"));
-    store = new DiffArtifactStore({ rootDir });
+    ({
+      rootDir,
+      store,
+      cleanup: cleanupRootDir,
+    } = await createDiffStoreHarness("openclaw-diffs-store-"));
   });
 
   afterEach(async () => {
     vi.useRealTimers();
-    await fs.rm(rootDir, { recursive: true, force: true });
+    await cleanupRootDir();
   });
 
   it("creates and retrieves an artifact", async () => {

extensions/diffs/src/test-helpers.ts

@@ -0,0 +1,30 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { DiffArtifactStore } from "./store.js";
+
+export async function createTempDiffRoot(prefix: string): Promise<{
+  rootDir: string;
+  cleanup: () => Promise<void>;
+}> {
+  const rootDir = await fs.mkdtemp(path.join(os.tmpdir(), prefix));
+  return {
+    rootDir,
+    cleanup: async () => {
+      await fs.rm(rootDir, { recursive: true, force: true });
+    },
+  };
+}
+
+export async function createDiffStoreHarness(prefix: string): Promise<{
+  rootDir: string;
+  store: DiffArtifactStore;
+  cleanup: () => Promise<void>;
+}> {
+  const { rootDir, cleanup } = await createTempDiffRoot(prefix);
+  return {
+    rootDir,
+    store: new DiffArtifactStore({ rootDir }),
+    cleanup,
+  };
+}

extensions/diffs/src/tool.test.ts

@@ -1,25 +1,24 @@
 import fs from "node:fs/promises";
-import os from "node:os";
 import path from "node:path";
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk/diffs";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { DiffScreenshotter } from "./browser.js";
 import { DEFAULT_DIFFS_TOOL_DEFAULTS } from "./config.js";
 import { DiffArtifactStore } from "./store.js";
+import { createDiffStoreHarness } from "./test-helpers.js";
 import { createDiffsTool } from "./tool.js";
 import type { DiffRenderOptions } from "./types.js";
 
 describe("diffs tool", () => {
-  let rootDir: string;
   let store: DiffArtifactStore;
+  let cleanupRootDir: () => Promise<void>;
 
   beforeEach(async () => {
-    rootDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-diffs-tool-"));
-    store = new DiffArtifactStore({ rootDir });
+    ({ store, cleanup: cleanupRootDir } = await createDiffStoreHarness("openclaw-diffs-tool-"));
   });
 
   afterEach(async () => {
-    await fs.rm(rootDir, { recursive: true, force: true });
+    await cleanupRootDir();
   });
 
   it("returns a viewer URL in view mode", async () => {

extensions/zalo/src/channel.sendpayload.test.ts

@@ -1,5 +1,9 @@
 import type { ReplyPayload } from "openclaw/plugin-sdk/zalo";
 import { beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  installSendPayloadContractSuite,
+  primeSendMock,
+} from "../../../src/test-utils/send-payload-contract.js";
 import { zaloPlugin } from "./channel.js";
 
 vi.mock("./send.js", () => ({
@@ -25,78 +29,16 @@ describe("zaloPlugin outbound sendPayload", () => {
     mockedSend.mockResolvedValue({ ok: true, messageId: "zl-1" });
   });
 
-  it("text-only delegates to sendText", async () => {
-    mockedSend.mockResolvedValue({ ok: true, messageId: "zl-t1" });
-
-    const result = await zaloPlugin.outbound!.sendPayload!(baseCtx({ text: "hello" }));
-
-    expect(mockedSend).toHaveBeenCalledWith("123456789", "hello", expect.any(Object));
-    expect(result).toMatchObject({ channel: "zalo", messageId: "zl-t1" });
-  });
-
-  it("single media delegates to sendMedia", async () => {
-    mockedSend.mockResolvedValue({ ok: true, messageId: "zl-m1" });
-
-    const result = await zaloPlugin.outbound!.sendPayload!(
-      baseCtx({ text: "cap", mediaUrl: "https://example.com/a.jpg" }),
-    );
-
-    expect(mockedSend).toHaveBeenCalledWith(
-      "123456789",
-      "cap",
-      expect.objectContaining({ mediaUrl: "https://example.com/a.jpg" }),
-    );
-    expect(result).toMatchObject({ channel: "zalo" });
-  });
-
-  it("multi-media iterates URLs with caption on first", async () => {
-    mockedSend
-      .mockResolvedValueOnce({ ok: true, messageId: "zl-1" })
-      .mockResolvedValueOnce({ ok: true, messageId: "zl-2" });
-
-    const result = await zaloPlugin.outbound!.sendPayload!(
-      baseCtx({
-        text: "caption",
-        mediaUrls: ["https://example.com/1.jpg", "https://example.com/2.jpg"],
-      }),
-    );
-
-    expect(mockedSend).toHaveBeenCalledTimes(2);
-    expect(mockedSend).toHaveBeenNthCalledWith(
-      1,
-      "123456789",
-      "caption",
-      expect.objectContaining({ mediaUrl: "https://example.com/1.jpg" }),
-    );
-    expect(mockedSend).toHaveBeenNthCalledWith(
-      2,
-      "123456789",
-      "",
-      expect.objectContaining({ mediaUrl: "https://example.com/2.jpg" }),
-    );
-    expect(result).toMatchObject({ channel: "zalo", messageId: "zl-2" });
-  });
-
-  it("empty payload returns no-op", async () => {
-    const result = await zaloPlugin.outbound!.sendPayload!(baseCtx({}));
-
-    expect(mockedSend).not.toHaveBeenCalled();
-    expect(result).toEqual({ channel: "zalo", messageId: "" });
-  });
-
-  it("chunking splits long text", async () => {
-    mockedSend
-      .mockResolvedValueOnce({ ok: true, messageId: "zl-c1" })
-      .mockResolvedValueOnce({ ok: true, messageId: "zl-c2" });
-
-    const longText = "a".repeat(3000);
-    const result = await zaloPlugin.outbound!.sendPayload!(baseCtx({ text: longText }));
-
-    // textChunkLimit is 2000 with chunkTextForOutbound, so it should split
-    expect(mockedSend.mock.calls.length).toBeGreaterThanOrEqual(2);
-    for (const call of mockedSend.mock.calls) {
-      expect((call[1] as string).length).toBeLessThanOrEqual(2000);
-    }
-    expect(result).toMatchObject({ channel: "zalo" });
+  installSendPayloadContractSuite({
+    channel: "zalo",
+    chunking: { mode: "split", longTextLength: 3000, maxChunkLength: 2000 },
+    createHarness: ({ payload, sendResults }) => {
+      primeSendMock(mockedSend, { ok: true, messageId: "zl-1" }, sendResults);
+      return {
+        run: async () => await zaloPlugin.outbound!.sendPayload!(baseCtx(payload)),
+        sendMock: mockedSend,
+        to: "123456789",
+      };
+    },
   });
 });

extensions/zalouser/src/channel.sendpayload.test.ts

@@ -1,5 +1,9 @@
 import type { ReplyPayload } from "openclaw/plugin-sdk/zalouser";
 import { beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  installSendPayloadContractSuite,
+  primeSendMock,
+} from "../../../src/test-utils/send-payload-contract.js";
 import { zalouserPlugin } from "./channel.js";
 
 vi.mock("./send.js", () => ({
@@ -40,15 +44,6 @@ describe("zalouserPlugin outbound sendPayload", () => {
     mockedSend.mockResolvedValue({ ok: true, messageId: "zlu-1" });
   });
 
-  it("text-only delegates to sendText", async () => {
-    mockedSend.mockResolvedValue({ ok: true, messageId: "zlu-t1" });
-
-    const result = await zalouserPlugin.outbound!.sendPayload!(baseCtx({ text: "hello" }));
-
-    expect(mockedSend).toHaveBeenCalledWith("987654321", "hello", expect.any(Object));
-    expect(result).toMatchObject({ channel: "zalouser", messageId: "zlu-t1" });
-  });
-
   it("group target delegates with isGroup=true and stripped threadId", async () => {
     mockedSend.mockResolvedValue({ ok: true, messageId: "zlu-g1" });
 
@@ -65,21 +60,6 @@ describe("zalouserPlugin outbound sendPayload", () => {
     expect(result).toMatchObject({ channel: "zalouser", messageId: "zlu-g1" });
   });
 
-  it("single media delegates to sendMedia", async () => {
-    mockedSend.mockResolvedValue({ ok: true, messageId: "zlu-m1" });
-
-    const result = await zalouserPlugin.outbound!.sendPayload!(
-      baseCtx({ text: "cap", mediaUrl: "https://example.com/a.jpg" }),
-    );
-
-    expect(mockedSend).toHaveBeenCalledWith(
-      "987654321",
-      "cap",
-      expect.objectContaining({ mediaUrl: "https://example.com/a.jpg" }),
-    );
-    expect(result).toMatchObject({ channel: "zalouser" });
-  });
-
   it("treats bare numeric targets as direct chats for backward compatibility", async () => {
     mockedSend.mockResolvedValue({ ok: true, messageId: "zlu-d1" });
 
@@ -112,55 +92,17 @@ describe("zalouserPlugin outbound sendPayload", () => {
     expect(result).toMatchObject({ channel: "zalouser", messageId: "zlu-g-native" });
   });
 
-  it("multi-media iterates URLs with caption on first", async () => {
-    mockedSend
-      .mockResolvedValueOnce({ ok: true, messageId: "zlu-1" })
-      .mockResolvedValueOnce({ ok: true, messageId: "zlu-2" });
-
-    const result = await zalouserPlugin.outbound!.sendPayload!(
-      baseCtx({
-        text: "caption",
-        mediaUrls: ["https://example.com/1.jpg", "https://example.com/2.jpg"],
-      }),
-    );
-
-    expect(mockedSend).toHaveBeenCalledTimes(2);
-    expect(mockedSend).toHaveBeenNthCalledWith(
-      1,
-      "987654321",
-      "caption",
-      expect.objectContaining({ mediaUrl: "https://example.com/1.jpg" }),
-    );
-    expect(mockedSend).toHaveBeenNthCalledWith(
-      2,
-      "987654321",
-      "",
-      expect.objectContaining({ mediaUrl: "https://example.com/2.jpg" }),
-    );
-    expect(result).toMatchObject({ channel: "zalouser", messageId: "zlu-2" });
-  });
-
-  it("empty payload returns no-op", async () => {
-    const result = await zalouserPlugin.outbound!.sendPayload!(baseCtx({}));
-
-    expect(mockedSend).not.toHaveBeenCalled();
-    expect(result).toEqual({ channel: "zalouser", messageId: "" });
-  });
-
-  it("chunking splits long text", async () => {
-    mockedSend
-      .mockResolvedValueOnce({ ok: true, messageId: "zlu-c1" })
-      .mockResolvedValueOnce({ ok: true, messageId: "zlu-c2" });
-
-    const longText = "a".repeat(3000);
-    const result = await zalouserPlugin.outbound!.sendPayload!(baseCtx({ text: longText }));
-
-    // textChunkLimit is 2000 with chunkTextForOutbound, so it should split
-    expect(mockedSend.mock.calls.length).toBeGreaterThanOrEqual(2);
-    for (const call of mockedSend.mock.calls) {
-      expect((call[1] as string).length).toBeLessThanOrEqual(2000);
-    }
-    expect(result).toMatchObject({ channel: "zalouser" });
+  installSendPayloadContractSuite({
+    channel: "zalouser",
+    chunking: { mode: "split", longTextLength: 3000, maxChunkLength: 2000 },
+    createHarness: ({ payload, sendResults }) => {
+      primeSendMock(mockedSend, { ok: true, messageId: "zlu-1" }, sendResults);
+      return {
+        run: async () => await zalouserPlugin.outbound!.sendPayload!(baseCtx(payload)),
+        sendMock: mockedSend,
+        to: "987654321",
+      };
+    },
   });
 });
 

package.json

@@ -295,6 +295,7 @@
     "protocol:gen": "node --import tsx scripts/protocol-gen.ts",
     "protocol:gen:swift": "node --import tsx scripts/protocol-gen-swift.ts",
     "release:check": "node --import tsx scripts/release-check.ts",
+    "release:openclaw:npm:check": "node --import tsx scripts/openclaw-npm-release-check.ts",
     "start": "node scripts/run-node.mjs",
     "test": "node scripts/test-parallel.mjs",
     "test:all": "pnpm lint && pnpm build && pnpm test && pnpm test:e2e && pnpm test:live && pnpm test:docker:all",

scripts/openclaw-npm-release-check.ts

@@ -0,0 +1,251 @@
+#!/usr/bin/env -S node --import tsx
+
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+
+type PackageJson = {
+  name?: string;
+  version?: string;
+  description?: string;
+  license?: string;
+  repository?: { url?: string } | string;
+  bin?: Record<string, string>;
+};
+
+export type ParsedReleaseVersion = {
+  version: string;
+  channel: "stable" | "beta";
+  year: number;
+  month: number;
+  day: number;
+  betaNumber?: number;
+  date: Date;
+};
+
+const STABLE_VERSION_REGEX = /^(?<year>\d{4})\.(?<month>[1-9]\d?)\.(?<day>[1-9]\d?)$/;
+const BETA_VERSION_REGEX =
+  /^(?<year>\d{4})\.(?<month>[1-9]\d?)\.(?<day>[1-9]\d?)-beta\.(?<beta>[1-9]\d*)$/;
+const EXPECTED_REPOSITORY_URL = "https://github.com/openclaw/openclaw";
+const MAX_CALVER_DISTANCE_DAYS = 2;
+
+function normalizeRepoUrl(value: unknown): string {
+  if (typeof value !== "string") {
+    return "";
+  }
+
+  return value
+    .trim()
+    .replace(/^git\+/, "")
+    .replace(/\.git$/i, "")
+    .replace(/\/+$/, "");
+}
+
+function parseDateParts(
+  version: string,
+  groups: Record<string, string | undefined>,
+  channel: "stable" | "beta",
+): ParsedReleaseVersion | null {
+  const year = Number.parseInt(groups.year ?? "", 10);
+  const month = Number.parseInt(groups.month ?? "", 10);
+  const day = Number.parseInt(groups.day ?? "", 10);
+  const betaNumber = channel === "beta" ? Number.parseInt(groups.beta ?? "", 10) : undefined;
+
+  if (
+    !Number.isInteger(year) ||
+    !Number.isInteger(month) ||
+    !Number.isInteger(day) ||
+    month < 1 ||
+    month > 12 ||
+    day < 1 ||
+    day > 31
+  ) {
+    return null;
+  }
+  if (channel === "beta" && (!Number.isInteger(betaNumber) || (betaNumber ?? 0) < 1)) {
+    return null;
+  }
+
+  const date = new Date(Date.UTC(year, month - 1, day));
+  if (
+    date.getUTCFullYear() !== year ||
+    date.getUTCMonth() !== month - 1 ||
+    date.getUTCDate() !== day
+  ) {
+    return null;
+  }
+
+  return {
+    version,
+    channel,
+    year,
+    month,
+    day,
+    betaNumber,
+    date,
+  };
+}
+
+export function parseReleaseVersion(version: string): ParsedReleaseVersion | null {
+  const trimmed = version.trim();
+  if (!trimmed) {
+    return null;
+  }
+
+  const stableMatch = STABLE_VERSION_REGEX.exec(trimmed);
+  if (stableMatch?.groups) {
+    return parseDateParts(trimmed, stableMatch.groups, "stable");
+  }
+
+  const betaMatch = BETA_VERSION_REGEX.exec(trimmed);
+  if (betaMatch?.groups) {
+    return parseDateParts(trimmed, betaMatch.groups, "beta");
+  }
+
+  return null;
+}
+
+function startOfUtcDay(date: Date): number {
+  return Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate());
+}
+
+export function utcCalendarDayDistance(left: Date, right: Date): number {
+  return Math.round(Math.abs(startOfUtcDay(left) - startOfUtcDay(right)) / 86_400_000);
+}
+
+export function collectReleasePackageMetadataErrors(pkg: PackageJson): string[] {
+  const actualRepositoryUrl = normalizeRepoUrl(
+    typeof pkg.repository === "string" ? pkg.repository : pkg.repository?.url,
+  );
+  const errors: string[] = [];
+
+  if (pkg.name !== "openclaw") {
+    errors.push(`package.json name must be "openclaw"; found "${pkg.name ?? ""}".`);
+  }
+  if (!pkg.description?.trim()) {
+    errors.push("package.json description must be non-empty.");
+  }
+  if (pkg.license !== "MIT") {
+    errors.push(`package.json license must be "MIT"; found "${pkg.license ?? ""}".`);
+  }
+  if (actualRepositoryUrl !== EXPECTED_REPOSITORY_URL) {
+    errors.push(
+      `package.json repository.url must resolve to ${EXPECTED_REPOSITORY_URL}; found ${
+        actualRepositoryUrl || "<missing>"
+      }.`,
+    );
+  }
+  if (pkg.bin?.openclaw !== "openclaw.mjs") {
+    errors.push(
+      `package.json bin.openclaw must be "openclaw.mjs"; found "${pkg.bin?.openclaw ?? ""}".`,
+    );
+  }
+
+  return errors;
+}
+
+export function collectReleaseTagErrors(params: {
+  packageVersion: string;
+  releaseTag: string;
+  releaseSha?: string;
+  releaseMainRef?: string;
+  now?: Date;
+}): string[] {
+  const errors: string[] = [];
+  const releaseTag = params.releaseTag.trim();
+  const packageVersion = params.packageVersion.trim();
+  const now = params.now ?? new Date();
+
+  const parsedVersion = parseReleaseVersion(packageVersion);
+  if (parsedVersion === null) {
+    errors.push(
+      `package.json version must match YYYY.M.D or YYYY.M.D-beta.N; found "${packageVersion || "<missing>"}".`,
+    );
+  }
+
+  if (!releaseTag.startsWith("v")) {
+    errors.push(`Release tag must start with "v"; found "${releaseTag || "<missing>"}".`);
+  }
+
+  const tagVersion = releaseTag.startsWith("v") ? releaseTag.slice(1) : releaseTag;
+  const parsedTag = parseReleaseVersion(tagVersion);
+  if (parsedTag === null) {
+    errors.push(
+      `Release tag must match vYYYY.M.D or vYYYY.M.D-beta.N; found "${releaseTag || "<missing>"}".`,
+    );
+  }
+
+  const expectedTag = packageVersion ? `v${packageVersion}` : "";
+  if (releaseTag !== expectedTag) {
+    errors.push(
+      `Release tag ${releaseTag || "<missing>"} does not match package.json version ${
+        packageVersion || "<missing>"
+      }; expected ${expectedTag || "<missing>"}.`,
+    );
+  }
+
+  if (parsedVersion !== null) {
+    const dayDistance = utcCalendarDayDistance(parsedVersion.date, now);
+    if (dayDistance > MAX_CALVER_DISTANCE_DAYS) {
+      const nowLabel = now.toISOString().slice(0, 10);
+      const versionDate = parsedVersion.date.toISOString().slice(0, 10);
+      errors.push(
+        `Release version ${packageVersion} is ${dayDistance} days away from current UTC date ${nowLabel}; release CalVer date ${versionDate} must be within ${MAX_CALVER_DISTANCE_DAYS} days.`,
+      );
+    }
+  }
+
+  if (params.releaseSha?.trim() && params.releaseMainRef?.trim()) {
+    try {
+      execFileSync(
+        "git",
+        ["merge-base", "--is-ancestor", params.releaseSha, params.releaseMainRef],
+        { stdio: "ignore" },
+      );
+    } catch {
+      errors.push(
+        `Tagged commit ${params.releaseSha} is not contained in ${params.releaseMainRef}.`,
+      );
+    }
+  }
+
+  return errors;
+}
+
+function loadPackageJson(): PackageJson {
+  return JSON.parse(readFileSync("package.json", "utf8")) as PackageJson;
+}
+
+function main(): number {
+  const pkg = loadPackageJson();
+  const metadataErrors = collectReleasePackageMetadataErrors(pkg);
+  const tagErrors = collectReleaseTagErrors({
+    packageVersion: pkg.version ?? "",
+    releaseTag: process.env.RELEASE_TAG ?? "",
+    releaseSha: process.env.RELEASE_SHA,
+    releaseMainRef: process.env.RELEASE_MAIN_REF,
+  });
+  const errors = [...metadataErrors, ...tagErrors];
+
+  if (errors.length > 0) {
+    for (const error of errors) {
+      console.error(`openclaw-npm-release-check: ${error}`);
+    }
+    return 1;
+  }
+
+  const parsedVersion = parseReleaseVersion(pkg.version ?? "");
+  const channel = parsedVersion?.channel ?? "unknown";
+  const dayDistance =
+    parsedVersion === null
+      ? "unknown"
+      : String(utcCalendarDayDistance(parsedVersion.date, new Date()));
+  console.log(
+    `openclaw-npm-release-check: validated ${channel} release ${pkg.version} (${dayDistance} day UTC delta).`,
+  );
+  return 0;
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+  process.exit(main());
+}

src/agents/acp-spawn-parent-stream.ts

@@ -180,7 +180,9 @@ export function startAcpSpawnParentStreamRelay(params: {
   };
   const wake = () => {
     requestHeartbeatNow(
-      scopedHeartbeatWakeOptions(parentSessionKey, { reason: "acp:spawn:stream" }),
+      scopedHeartbeatWakeOptions(parentSessionKey, {
+        reason: "acp:spawn:stream",
+      }),
     );
   };
   const emit = (text: string, contextKey: string) => {

src/agents/acp-spawn.test.ts

@@ -38,6 +38,7 @@ const hoisted = vi.hoisted(() => {
   const loadSessionStoreMock = vi.fn();
   const resolveStorePathMock = vi.fn();
   const resolveSessionTranscriptFileMock = vi.fn();
+  const areHeartbeatsEnabledMock = vi.fn();
   const state = {
     cfg: createDefaultSpawnConfig(),
   };
@@ -55,6 +56,7 @@ const hoisted = vi.hoisted(() => {
     loadSessionStoreMock,
     resolveStorePathMock,
     resolveSessionTranscriptFileMock,
+    areHeartbeatsEnabledMock,
     state,
   };
 });
@@ -128,6 +130,14 @@ vi.mock("../infra/outbound/session-binding-service.js", async (importOriginal) =
   };
 });
 
+vi.mock("../infra/heartbeat-wake.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../infra/heartbeat-wake.js")>();
+  return {
+    ...actual,
+    areHeartbeatsEnabled: () => hoisted.areHeartbeatsEnabledMock(),
+  };
+});
+
 vi.mock("./acp-spawn-parent-stream.js", () => ({
   startAcpSpawnParentStreamRelay: (...args: unknown[]) =>
     hoisted.startAcpSpawnParentStreamRelayMock(...args),
@@ -192,6 +202,7 @@ function expectResolvedIntroTextInBindMetadata(): void {
 describe("spawnAcpDirect", () => {
   beforeEach(() => {
     hoisted.state.cfg = createDefaultSpawnConfig();
+    hoisted.areHeartbeatsEnabledMock.mockReset().mockReturnValue(true);
 
     hoisted.callGatewayMock.mockReset().mockImplementation(async (argsUnknown: unknown) => {
       const args = argsUnknown as { method?: string };
@@ -393,6 +404,8 @@ describe("spawnAcpDirect", () => {
 
     expect(result.status).toBe("accepted");
     expect(result.mode).toBe("run");
+    expect(result.streamLogPath).toBeUndefined();
+    expect(hoisted.startAcpSpawnParentStreamRelayMock).not.toHaveBeenCalled();
     expect(hoisted.resolveSessionTranscriptFileMock).toHaveBeenCalledWith(
       expect.objectContaining({
         sessionId: "sess-123",
@@ -633,6 +646,290 @@ describe("spawnAcpDirect", () => {
     expect(secondHandle.notifyStarted).toHaveBeenCalledTimes(1);
   });
 
+  it("implicitly streams mode=run ACP spawns for subagent requester sessions", async () => {
+    hoisted.state.cfg = {
+      ...hoisted.state.cfg,
+      agents: {
+        defaults: {
+          heartbeat: {
+            every: "30m",
+            target: "last",
+          },
+        },
+      },
+    };
+    const firstHandle = createRelayHandle();
+    const secondHandle = createRelayHandle();
+    hoisted.startAcpSpawnParentStreamRelayMock
+      .mockReset()
+      .mockReturnValueOnce(firstHandle)
+      .mockReturnValueOnce(secondHandle);
+    hoisted.loadSessionStoreMock.mockReset().mockImplementation(() => {
+      const store: Record<
+        string,
+        { sessionId: string; updatedAt: number; deliveryContext?: unknown }
+      > = {
+        "agent:main:subagent:parent": {
+          sessionId: "parent-sess-1",
+          updatedAt: Date.now(),
+          deliveryContext: {
+            channel: "discord",
+            to: "channel:parent-channel",
+            accountId: "default",
+          },
+        },
+      };
+      return new Proxy(store, {
+        get(target, prop) {
+          if (typeof prop === "string" && prop.startsWith("agent:codex:acp:")) {
+            return { sessionId: "sess-123", updatedAt: Date.now() };
+          }
+          return target[prop as keyof typeof target];
+        },
+      });
+    });
+
+    const result = await spawnAcpDirect(
+      {
+        task: "Investigate flaky tests",
+        agentId: "codex",
+      },
+      {
+        agentSessionKey: "agent:main:subagent:parent",
+        agentChannel: "discord",
+        agentAccountId: "default",
+        agentTo: "channel:parent-channel",
+      },
+    );
+
+    expect(result.status).toBe("accepted");
+    expect(result.mode).toBe("run");
+    expect(result.streamLogPath).toBe("/tmp/sess-main.acp-stream.jsonl");
+    const agentCall = hoisted.callGatewayMock.mock.calls
+      .map((call: unknown[]) => call[0] as { method?: string; params?: Record<string, unknown> })
+      .find((request) => request.method === "agent");
+    expect(agentCall?.params?.deliver).toBe(false);
+    expect(agentCall?.params?.channel).toBeUndefined();
+    expect(agentCall?.params?.to).toBeUndefined();
+    expect(agentCall?.params?.threadId).toBeUndefined();
+    expect(hoisted.startAcpSpawnParentStreamRelayMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        parentSessionKey: "agent:main:subagent:parent",
+        agentId: "codex",
+        logPath: "/tmp/sess-main.acp-stream.jsonl",
+        emitStartNotice: false,
+      }),
+    );
+    expect(firstHandle.dispose).toHaveBeenCalledTimes(1);
+    expect(secondHandle.notifyStarted).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not implicitly stream when heartbeat target is not session-local", async () => {
+    hoisted.state.cfg = {
+      ...hoisted.state.cfg,
+      agents: {
+        defaults: {
+          heartbeat: {
+            every: "30m",
+            target: "discord",
+            to: "channel:ops-room",
+          },
+        },
+      },
+    };
+
+    const result = await spawnAcpDirect(
+      {
+        task: "Investigate flaky tests",
+        agentId: "codex",
+      },
+      {
+        agentSessionKey: "agent:main:subagent:fixed-target",
+      },
+    );
+
+    expect(result.status).toBe("accepted");
+    expect(result.mode).toBe("run");
+    expect(result.streamLogPath).toBeUndefined();
+    expect(hoisted.startAcpSpawnParentStreamRelayMock).not.toHaveBeenCalled();
+  });
+
+  it("does not implicitly stream when session scope is global", async () => {
+    hoisted.state.cfg = {
+      ...hoisted.state.cfg,
+      session: {
+        ...hoisted.state.cfg.session,
+        scope: "global",
+      },
+      agents: {
+        defaults: {
+          heartbeat: {
+            every: "30m",
+            target: "last",
+          },
+        },
+      },
+    };
+
+    const result = await spawnAcpDirect(
+      {
+        task: "Investigate flaky tests",
+        agentId: "codex",
+      },
+      {
+        agentSessionKey: "agent:main:subagent:global-scope",
+      },
+    );
+
+    expect(result.status).toBe("accepted");
+    expect(result.mode).toBe("run");
+    expect(result.streamLogPath).toBeUndefined();
+    expect(hoisted.startAcpSpawnParentStreamRelayMock).not.toHaveBeenCalled();
+  });
+
+  it("does not implicitly stream for subagent requester sessions when heartbeat is disabled", async () => {
+    hoisted.state.cfg = {
+      ...hoisted.state.cfg,
+      agents: {
+        list: [{ id: "main", heartbeat: { every: "30m" } }, { id: "research" }],
+      },
+    };
+
+    const result = await spawnAcpDirect(
+      {
+        task: "Investigate flaky tests",
+        agentId: "codex",
+      },
+      {
+        agentSessionKey: "agent:research:subagent:orchestrator",
+      },
+    );
+
+    expect(result.status).toBe("accepted");
+    expect(result.mode).toBe("run");
+    expect(result.streamLogPath).toBeUndefined();
+    expect(hoisted.startAcpSpawnParentStreamRelayMock).not.toHaveBeenCalled();
+  });
+
+  it("does not implicitly stream for subagent requester sessions when heartbeat cadence is invalid", async () => {
+    hoisted.state.cfg = {
+      ...hoisted.state.cfg,
+      agents: {
+        list: [
+          {
+            id: "research",
+            heartbeat: { every: "0m" },
+          },
+        ],
+      },
+    };
+
+    const result = await spawnAcpDirect(
+      {
+        task: "Investigate flaky tests",
+        agentId: "codex",
+      },
+      {
+        agentSessionKey: "agent:research:subagent:invalid-heartbeat",
+      },
+    );
+
+    expect(result.status).toBe("accepted");
+    expect(result.mode).toBe("run");
+    expect(result.streamLogPath).toBeUndefined();
+    expect(hoisted.startAcpSpawnParentStreamRelayMock).not.toHaveBeenCalled();
+  });
+
+  it("does not implicitly stream when heartbeats are runtime-disabled", async () => {
+    hoisted.areHeartbeatsEnabledMock.mockReturnValue(false);
+
+    const result = await spawnAcpDirect(
+      {
+        task: "Investigate flaky tests",
+        agentId: "codex",
+      },
+      {
+        agentSessionKey: "agent:main:subagent:runtime-disabled",
+      },
+    );
+
+    expect(result.status).toBe("accepted");
+    expect(result.mode).toBe("run");
+    expect(result.streamLogPath).toBeUndefined();
+    expect(hoisted.startAcpSpawnParentStreamRelayMock).not.toHaveBeenCalled();
+  });
+
+  it("does not implicitly stream for legacy subagent requester session keys", async () => {
+    const result = await spawnAcpDirect(
+      {
+        task: "Investigate flaky tests",
+        agentId: "codex",
+      },
+      {
+        agentSessionKey: "subagent:legacy-worker",
+      },
+    );
+
+    expect(result.status).toBe("accepted");
+    expect(result.mode).toBe("run");
+    expect(result.streamLogPath).toBeUndefined();
+    expect(hoisted.startAcpSpawnParentStreamRelayMock).not.toHaveBeenCalled();
+  });
+
+  it("does not implicitly stream for subagent requester sessions with thread context", async () => {
+    const result = await spawnAcpDirect(
+      {
+        task: "Investigate flaky tests",
+        agentId: "codex",
+      },
+      {
+        agentSessionKey: "agent:main:subagent:thread-context",
+        agentChannel: "discord",
+        agentAccountId: "default",
+        agentTo: "channel:parent-channel",
+        agentThreadId: "requester-thread",
+      },
+    );
+
+    expect(result.status).toBe("accepted");
+    expect(result.mode).toBe("run");
+    expect(result.streamLogPath).toBeUndefined();
+    expect(hoisted.startAcpSpawnParentStreamRelayMock).not.toHaveBeenCalled();
+  });
+
+  it("does not implicitly stream for thread-bound subagent requester sessions", async () => {
+    hoisted.sessionBindingListBySessionMock.mockImplementation((targetSessionKey: string) => {
+      if (targetSessionKey === "agent:main:subagent:thread-bound") {
+        return [
+          createSessionBinding({
+            targetSessionKey,
+            targetKind: "subagent",
+            status: "active",
+          }),
+        ];
+      }
+      return [];
+    });
+
+    const result = await spawnAcpDirect(
+      {
+        task: "Investigate flaky tests",
+        agentId: "codex",
+      },
+      {
+        agentSessionKey: "agent:main:subagent:thread-bound",
+        agentChannel: "discord",
+        agentAccountId: "default",
+        agentTo: "channel:parent-channel",
+      },
+    );
+
+    expect(result.status).toBe("accepted");
+    expect(result.mode).toBe("run");
+    expect(result.streamLogPath).toBeUndefined();
+    expect(hoisted.startAcpSpawnParentStreamRelayMock).not.toHaveBeenCalled();
+  });
+
   it("announces parent relay start only after successful child dispatch", async () => {
     const firstHandle = createRelayHandle();
     const secondHandle = createRelayHandle();

src/agents/acp-spawn.ts

@@ -10,6 +10,7 @@ import {
   resolveAcpThreadSessionDetailLines,
 } from "../acp/runtime/session-identifiers.js";
 import type { AcpRuntimeSessionMode } from "../acp/runtime/types.js";
+import { DEFAULT_HEARTBEAT_EVERY } from "../auto-reply/heartbeat.js";
 import {
   resolveThreadBindingIntroText,
   resolveThreadBindingThreadName,
@@ -21,11 +22,13 @@ import {
   resolveThreadBindingMaxAgeMsForChannel,
   resolveThreadBindingSpawnPolicy,
 } from "../channels/thread-bindings-policy.js";
+import { parseDurationMs } from "../cli/parse-duration.js";
 import { loadConfig } from "../config/config.js";
 import type { OpenClawConfig } from "../config/config.js";
 import { loadSessionStore, resolveStorePath, type SessionEntry } from "../config/sessions.js";
 import { resolveSessionTranscriptFile } from "../config/sessions/transcript.js";
 import { callGateway } from "../gateway/call.js";
+import { areHeartbeatsEnabled } from "../infra/heartbeat-wake.js";
 import { resolveConversationIdFromTargets } from "../infra/outbound/conversation-id.js";
 import {
   getSessionBindingService,
@@ -33,13 +36,18 @@ import {
   type SessionBindingRecord,
 } from "../infra/outbound/session-binding-service.js";
 import { createSubsystemLogger } from "../logging/subsystem.js";
-import { normalizeAgentId } from "../routing/session-key.js";
-import { normalizeDeliveryContext } from "../utils/delivery-context.js";
+import {
+  isSubagentSessionKey,
+  normalizeAgentId,
+  parseAgentSessionKey,
+} from "../routing/session-key.js";
+import { deliveryContextFromSession, normalizeDeliveryContext } from "../utils/delivery-context.js";
 import {
   type AcpSpawnParentRelayHandle,
   resolveAcpSpawnStreamLogPath,
   startAcpSpawnParentStreamRelay,
 } from "./acp-spawn-parent-stream.js";
+import { resolveAgentConfig, resolveDefaultAgentId } from "./agent-scope.js";
 import { resolveSandboxRuntimeStatus } from "./sandbox/runtime-status.js";
 import { resolveInternalSessionKey, resolveMainSessionAlias } from "./tools/sessions-helpers.js";
 
@@ -130,6 +138,95 @@ function resolveAcpSessionMode(mode: SpawnAcpMode): AcpRuntimeSessionMode {
   return mode === "session" ? "persistent" : "oneshot";
 }
 
+function isHeartbeatEnabledForSessionAgent(params: {
+  cfg: OpenClawConfig;
+  sessionKey?: string;
+}): boolean {
+  if (!areHeartbeatsEnabled()) {
+    return false;
+  }
+  const requesterAgentId = parseAgentSessionKey(params.sessionKey)?.agentId;
+  if (!requesterAgentId) {
+    return true;
+  }
+
+  const agentEntries = params.cfg.agents?.list ?? [];
+  const hasExplicitHeartbeatAgents = agentEntries.some((entry) => Boolean(entry?.heartbeat));
+  const enabledByPolicy = hasExplicitHeartbeatAgents
+    ? agentEntries.some(
+        (entry) => Boolean(entry?.heartbeat) && normalizeAgentId(entry?.id) === requesterAgentId,
+      )
+    : requesterAgentId === resolveDefaultAgentId(params.cfg);
+  if (!enabledByPolicy) {
+    return false;
+  }
+
+  const heartbeatEvery =
+    resolveAgentConfig(params.cfg, requesterAgentId)?.heartbeat?.every ??
+    params.cfg.agents?.defaults?.heartbeat?.every ??
+    DEFAULT_HEARTBEAT_EVERY;
+  const trimmedEvery = typeof heartbeatEvery === "string" ? heartbeatEvery.trim() : "";
+  if (!trimmedEvery) {
+    return false;
+  }
+  try {
+    return parseDurationMs(trimmedEvery, { defaultUnit: "m" }) > 0;
+  } catch {
+    return false;
+  }
+}
+
+function resolveHeartbeatConfigForAgent(params: {
+  cfg: OpenClawConfig;
+  agentId: string;
+}): NonNullable<NonNullable<OpenClawConfig["agents"]>["defaults"]>["heartbeat"] {
+  const defaults = params.cfg.agents?.defaults?.heartbeat;
+  const overrides = resolveAgentConfig(params.cfg, params.agentId)?.heartbeat;
+  if (!defaults && !overrides) {
+    return undefined;
+  }
+  return {
+    ...defaults,
+    ...overrides,
+  };
+}
+
+function hasSessionLocalHeartbeatRelayRoute(params: {
+  cfg: OpenClawConfig;
+  parentSessionKey: string;
+  requesterAgentId: string;
+}): boolean {
+  const scope = params.cfg.session?.scope ?? "per-sender";
+  if (scope === "global") {
+    return false;
+  }
+
+  const heartbeat = resolveHeartbeatConfigForAgent({
+    cfg: params.cfg,
+    agentId: params.requesterAgentId,
+  });
+  if ((heartbeat?.target ?? "none") !== "last") {
+    return false;
+  }
+
+  // Explicit delivery overrides are not session-local and can route updates
+  // to unrelated destinations (for example a pinned ops channel).
+  if (typeof heartbeat?.to === "string" && heartbeat.to.trim().length > 0) {
+    return false;
+  }
+  if (typeof heartbeat?.accountId === "string" && heartbeat.accountId.trim().length > 0) {
+    return false;
+  }
+
+  const storePath = resolveStorePath(params.cfg.session?.store, {
+    agentId: params.requesterAgentId,
+  });
+  const sessionStore = loadSessionStore(storePath);
+  const parentEntry = sessionStore[params.parentSessionKey];
+  const parentDeliveryContext = deliveryContextFromSession(parentEntry);
+  return Boolean(parentDeliveryContext?.channel && parentDeliveryContext.to);
+}
+
 function resolveTargetAcpAgentId(params: {
   requestedAgentId?: string;
   cfg: OpenClawConfig;
@@ -326,6 +423,8 @@ export async function spawnAcpDirect(
       error: 'sessions_spawn streamTo="parent" requires an active requester session context.',
     };
   }
+
+  const requestThreadBinding = params.thread === true;
   const runtimePolicyError = resolveAcpSpawnRuntimePolicyError({
     cfg,
     requesterSessionKey: ctx.agentSessionKey,
@@ -339,7 +438,6 @@ export async function spawnAcpDirect(
     };
   }
 
-  const requestThreadBinding = params.thread === true;
   const spawnMode = resolveSpawnMode({
     requestedMode: params.mode,
     threadRequested: requestThreadBinding,
@@ -351,6 +449,52 @@ export async function spawnAcpDirect(
     };
   }
 
+  const bindingService = getSessionBindingService();
+  const requesterParsedSession = parseAgentSessionKey(parentSessionKey);
+  const requesterIsSubagentSession =
+    Boolean(requesterParsedSession) && isSubagentSessionKey(parentSessionKey);
+  const requesterHasActiveSubagentBinding =
+    requesterIsSubagentSession && parentSessionKey
+      ? bindingService
+          .listBySession(parentSessionKey)
+          .some((record) => record.targetKind === "subagent" && record.status !== "ended")
+      : false;
+  const requesterHasThreadContext =
+    typeof ctx.agentThreadId === "string"
+      ? ctx.agentThreadId.trim().length > 0
+      : ctx.agentThreadId != null;
+  const requesterHeartbeatEnabled = isHeartbeatEnabledForSessionAgent({
+    cfg,
+    sessionKey: parentSessionKey,
+  });
+  const requesterAgentId = requesterParsedSession?.agentId;
+  const requesterHeartbeatRelayRouteUsable =
+    parentSessionKey && requesterAgentId
+      ? hasSessionLocalHeartbeatRelayRoute({
+          cfg,
+          parentSessionKey,
+          requesterAgentId,
+        })
+      : false;
+
+  // For mode=run without thread binding, implicitly route output to parent
+  // only for spawned subagent orchestrator sessions with heartbeat enabled
+  // AND a session-local heartbeat delivery route (target=last + usable last route).
+  // Skip requester sessions that are thread-bound (or carrying thread context)
+  // so user-facing threads do not receive unsolicited ACP progress chatter
+  // unless streamTo="parent" is explicitly requested. Use resolved spawnMode
+  // (not params.mode) so default mode selection works.
+  const implicitStreamToParent =
+    !streamToParentRequested &&
+    spawnMode === "run" &&
+    !requestThreadBinding &&
+    requesterIsSubagentSession &&
+    !requesterHasActiveSubagentBinding &&
+    !requesterHasThreadContext &&
+    requesterHeartbeatEnabled &&
+    requesterHeartbeatRelayRouteUsable;
+  const effectiveStreamToParent = streamToParentRequested || implicitStreamToParent;
+
   const targetAgentResult = resolveTargetAcpAgentId({
     requestedAgentId: params.agentId,
     cfg,
@@ -392,7 +536,6 @@ export async function spawnAcpDirect(
   }
 
   const acpManager = getAcpSessionManager();
-  const bindingService = getSessionBindingService();
   let binding: SessionBindingRecord | null = null;
   let sessionCreated = false;
   let initializedRuntime: AcpSpawnRuntimeCloseHandle | undefined;
@@ -530,17 +673,17 @@ export async function spawnAcpDirect(
   // Fresh one-shot ACP runs should bootstrap the worker first, then let higher layers
   // decide how to relay status. Inline delivery is reserved for thread-bound sessions.
   const useInlineDelivery =
-    hasDeliveryTarget && spawnMode === "session" && !streamToParentRequested;
+    hasDeliveryTarget && spawnMode === "session" && !effectiveStreamToParent;
   const childIdem = crypto.randomUUID();
   let childRunId: string = childIdem;
   const streamLogPath =
-    streamToParentRequested && parentSessionKey
+    effectiveStreamToParent && parentSessionKey
       ? resolveAcpSpawnStreamLogPath({
           childSessionKey: sessionKey,
         })
       : undefined;
   let parentRelay: AcpSpawnParentRelayHandle | undefined;
-  if (streamToParentRequested && parentSessionKey) {
+  if (effectiveStreamToParent && parentSessionKey) {
     // Register relay before dispatch so fast lifecycle failures are not missed.
     parentRelay = startAcpSpawnParentStreamRelay({
       runId: childIdem,
@@ -585,7 +728,7 @@ export async function spawnAcpDirect(
     };
   }
 
-  if (streamToParentRequested && parentSessionKey) {
+  if (effectiveStreamToParent && parentSessionKey) {
     if (parentRelay && childRunId !== childIdem) {
       parentRelay.dispose();
       // Defensive fallback if gateway returns a runId that differs from idempotency key.

src/agents/anthropic-payload-log.test.ts

@@ -29,7 +29,7 @@ describe("createAnthropicPayloadLogger", () => {
       ],
     };
     const streamFn: StreamFn = ((model, __, options) => {
-      options?.onPayload?.(payload);
+      options?.onPayload?.(payload, model);
       return {} as never;
     }) as StreamFn;
 

src/agents/anthropic-payload-log.ts

@@ -145,7 +145,7 @@ export function createAnthropicPayloadLogger(params: {
           payload: redactedPayload,
           payloadDigest: digest(redactedPayload),
         });
-        return options?.onPayload?.(payload);
+        return options?.onPayload?.(payload, model);
       };
       return streamFn(model, context, {
         ...options,

src/agents/auth-profiles/oauth.openai-codex-refresh-fallback.test.ts

@@ -17,17 +17,13 @@ const { getOAuthApiKeyMock } = vi.hoisted(() => ({
   }),
 }));
 
-vi.mock("@mariozechner/pi-ai", async () => {
-  const actual = await vi.importActual<typeof import("@mariozechner/pi-ai")>("@mariozechner/pi-ai");
-  return {
-    ...actual,
-    getOAuthApiKey: getOAuthApiKeyMock,
-    getOAuthProviders: () => [
-      { id: "openai-codex", envApiKey: "OPENAI_API_KEY", oauthTokenEnv: "OPENAI_OAUTH_TOKEN" }, // pragma: allowlist secret
-      { id: "anthropic", envApiKey: "ANTHROPIC_API_KEY", oauthTokenEnv: "ANTHROPIC_OAUTH_TOKEN" }, // pragma: allowlist secret
-    ],
-  };
-});
+vi.mock("@mariozechner/pi-ai/oauth", () => ({
+  getOAuthApiKey: getOAuthApiKeyMock,
+  getOAuthProviders: () => [
+    { id: "openai-codex", envApiKey: "OPENAI_API_KEY", oauthTokenEnv: "OPENAI_OAUTH_TOKEN" }, // pragma: allowlist secret
+    { id: "anthropic", envApiKey: "ANTHROPIC_API_KEY", oauthTokenEnv: "ANTHROPIC_OAUTH_TOKEN" }, // pragma: allowlist secret
+  ],
+}));
 
 function createExpiredOauthStore(params: {
   profileId: string;

src/agents/auth-profiles/oauth.ts

@@ -1,5 +1,5 @@
 import type { OAuthCredentials, OAuthProvider } from "@mariozechner/pi-ai";
-import { getOAuthApiKey, getOAuthProviders } from "@mariozechner/pi-ai";
+import { getOAuthApiKey, getOAuthProviders } from "@mariozechner/pi-ai/oauth";
 import { loadConfig, type OpenClawConfig } from "../../config/config.js";
 import { coerceSecretRef } from "../../config/types.secrets.js";
 import { withFileLock } from "../../infra/file-lock.js";

src/agents/model-auth-env-vars.ts

@@ -32,6 +32,7 @@ export const PROVIDER_ENV_API_KEY_CANDIDATES: Record<string, string[]> = {
   mistral: ["MISTRAL_API_KEY"],
   together: ["TOGETHER_API_KEY"],
   qianfan: ["QIANFAN_API_KEY"],
+  modelstudio: ["MODELSTUDIO_API_KEY"],
   ollama: ["OLLAMA_API_KEY"],
   vllm: ["VLLM_API_KEY"],
   kilocode: ["KILOCODE_API_KEY"],

src/agents/model-auth.profiles.test.ts

@@ -230,6 +230,21 @@ describe("getApiKeyForModel", () => {
     });
   });
 
+  it("resolves Model Studio API key from env", async () => {
+    await withEnvAsync(
+      { [envVar("MODELSTUDIO", "API", "KEY")]: "modelstudio-test-key" },
+      async () => {
+        // pragma: allowlist secret
+        const resolved = await resolveApiKeyForProvider({
+          provider: "modelstudio",
+          store: { version: 1, profiles: {} },
+        });
+        expect(resolved.apiKey).toBe("modelstudio-test-key");
+        expect(resolved.source).toContain("MODELSTUDIO_API_KEY");
+      },
+    );
+  });
+
   it("resolves synthetic local auth key for configured ollama provider without apiKey", async () => {
     await withEnvAsync({ OLLAMA_API_KEY: undefined }, async () => {
       const resolved = await resolveApiKeyForProvider({

src/agents/model-auth.ts

@@ -4,6 +4,7 @@ import { formatCliCommand } from "../cli/command-format.js";
 import type { OpenClawConfig } from "../config/config.js";
 import type { ModelProviderAuthMode, ModelProviderConfig } from "../config/types.js";
 import { getShellEnvAppliedKeys } from "../infra/shell-env.js";
+import { createSubsystemLogger } from "../logging/subsystem.js";
 import {
   normalizeOptionalSecretInput,
   normalizeSecretInput,
@@ -22,6 +23,8 @@ import { normalizeProviderId } from "./model-selection.js";
 
 export { ensureAuthProfileStore, resolveAuthProfileOrder } from "./auth-profiles.js";
 
+const log = createSubsystemLogger("model-auth");
+
 const AWS_BEARER_ENV = "AWS_BEARER_TOKEN_BEDROCK";
 const AWS_ACCESS_KEY_ENV = "AWS_ACCESS_KEY_ID";
 const AWS_SECRET_KEY_ENV = "AWS_SECRET_ACCESS_KEY";
@@ -221,7 +224,9 @@ export async function resolveApiKeyForProvider(params: {
           mode: mode === "oauth" ? "oauth" : mode === "token" ? "token" : "api-key",
         };
       }
-    } catch {}
+    } catch (err) {
+      log.debug?.(`auth profile "${candidate}" failed for provider "${provider}": ${String(err)}`);
+    }
   }
 
   const envResolved = resolveEnvApiKey(provider);

src/agents/models-config.e2e-harness.ts

@@ -101,6 +101,7 @@ export const MODELS_CONFIG_IMPLICIT_ENV_VARS = [
   "OPENROUTER_API_KEY",
   "PI_CODING_AGENT_DIR",
   "QIANFAN_API_KEY",
+  "MODELSTUDIO_API_KEY",
   "QWEN_OAUTH_TOKEN",
   "QWEN_PORTAL_API_KEY",
   "SYNTHETIC_API_KEY",

src/agents/models-config.providers.modelstudio.test.ts

@@ -0,0 +1,32 @@
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { withEnvAsync } from "../test-utils/env.js";
+import { resolveImplicitProvidersForTest } from "./models-config.e2e-harness.js";
+import { buildModelStudioProvider } from "./models-config.providers.js";
+
+const modelStudioApiKeyEnv = ["MODELSTUDIO_API", "KEY"].join("_");
+
+describe("Model Studio implicit provider", () => {
+  it("should include modelstudio when MODELSTUDIO_API_KEY is configured", async () => {
+    const agentDir = mkdtempSync(join(tmpdir(), "openclaw-test-"));
+    const modelStudioApiKey = "test-key"; // pragma: allowlist secret
+    await withEnvAsync({ [modelStudioApiKeyEnv]: modelStudioApiKey }, async () => {
+      const providers = await resolveImplicitProvidersForTest({ agentDir });
+      expect(providers?.modelstudio).toBeDefined();
+      expect(providers?.modelstudio?.apiKey).toBe("MODELSTUDIO_API_KEY");
+      expect(providers?.modelstudio?.baseUrl).toBe("https://coding-intl.dashscope.aliyuncs.com/v1");
+    });
+  });
+
+  it("should build the static Model Studio provider catalog", () => {
+    const provider = buildModelStudioProvider();
+    const modelIds = provider.models.map((model) => model.id);
+    expect(provider.api).toBe("openai-completions");
+    expect(provider.baseUrl).toBe("https://coding-intl.dashscope.aliyuncs.com/v1");
+    expect(modelIds).toContain("qwen3.5-plus");
+    expect(modelIds).toContain("qwen3-coder-plus");
+    expect(modelIds).toContain("kimi-k2.5");
+  });
+});

src/agents/models-config.providers.static.ts

@@ -137,6 +137,90 @@ const QIANFAN_DEFAULT_COST = {
   cacheWrite: 0,
 };
 
+export const MODELSTUDIO_BASE_URL = "https://coding-intl.dashscope.aliyuncs.com/v1";
+export const MODELSTUDIO_DEFAULT_MODEL_ID = "qwen3.5-plus";
+const MODELSTUDIO_DEFAULT_COST = {
+  input: 0,
+  output: 0,
+  cacheRead: 0,
+  cacheWrite: 0,
+};
+
+const MODELSTUDIO_MODEL_CATALOG: ReadonlyArray<ProviderModelConfig> = [
+  {
+    id: "qwen3.5-plus",
+    name: "qwen3.5-plus",
+    reasoning: false,
+    input: ["text", "image"],
+    cost: MODELSTUDIO_DEFAULT_COST,
+    contextWindow: 1_000_000,
+    maxTokens: 65_536,
+  },
+  {
+    id: "qwen3-max-2026-01-23",
+    name: "qwen3-max-2026-01-23",
+    reasoning: false,
+    input: ["text"],
+    cost: MODELSTUDIO_DEFAULT_COST,
+    contextWindow: 262_144,
+    maxTokens: 65_536,
+  },
+  {
+    id: "qwen3-coder-next",
+    name: "qwen3-coder-next",
+    reasoning: false,
+    input: ["text"],
+    cost: MODELSTUDIO_DEFAULT_COST,
+    contextWindow: 262_144,
+    maxTokens: 65_536,
+  },
+  {
+    id: "qwen3-coder-plus",
+    name: "qwen3-coder-plus",
+    reasoning: false,
+    input: ["text"],
+    cost: MODELSTUDIO_DEFAULT_COST,
+    contextWindow: 1_000_000,
+    maxTokens: 65_536,
+  },
+  {
+    id: "MiniMax-M2.5",
+    name: "MiniMax-M2.5",
+    reasoning: false,
+    input: ["text"],
+    cost: MODELSTUDIO_DEFAULT_COST,
+    contextWindow: 1_000_000,
+    maxTokens: 65_536,
+  },
+  {
+    id: "glm-5",
+    name: "glm-5",
+    reasoning: false,
+    input: ["text"],
+    cost: MODELSTUDIO_DEFAULT_COST,
+    contextWindow: 202_752,
+    maxTokens: 16_384,
+  },
+  {
+    id: "glm-4.7",
+    name: "glm-4.7",
+    reasoning: false,
+    input: ["text"],
+    cost: MODELSTUDIO_DEFAULT_COST,
+    contextWindow: 202_752,
+    maxTokens: 16_384,
+  },
+  {
+    id: "kimi-k2.5",
+    name: "kimi-k2.5",
+    reasoning: false,
+    input: ["text", "image"],
+    cost: MODELSTUDIO_DEFAULT_COST,
+    contextWindow: 262_144,
+    maxTokens: 32_768,
+  },
+];
+
 const NVIDIA_BASE_URL = "https://integrate.api.nvidia.com/v1";
 const NVIDIA_DEFAULT_MODEL_ID = "nvidia/llama-3.1-nemotron-70b-instruct";
 const NVIDIA_DEFAULT_CONTEXT_WINDOW = 131072;
@@ -384,6 +468,14 @@ export function buildQianfanProvider(): ProviderConfig {
   };
 }
 
+export function buildModelStudioProvider(): ProviderConfig {
+  return {
+    baseUrl: MODELSTUDIO_BASE_URL,
+    api: "openai-completions",
+    models: MODELSTUDIO_MODEL_CATALOG.map((model) => ({ ...model })),
+  };
+}
+
 export function buildNvidiaProvider(): ProviderConfig {
   return {
     baseUrl: NVIDIA_BASE_URL,

src/agents/models-config.providers.ts

@@ -29,6 +29,7 @@ import {
   buildKilocodeProvider,
   buildMinimaxPortalProvider,
   buildMinimaxProvider,
+  buildModelStudioProvider,
   buildMoonshotProvider,
   buildNvidiaProvider,
   buildOpenAICodexProvider,
@@ -46,8 +47,11 @@ export {
   buildKimiCodingProvider,
   buildKilocodeProvider,
   buildNvidiaProvider,
+  buildModelStudioProvider,
   buildQianfanProvider,
   buildXiaomiProvider,
+  MODELSTUDIO_BASE_URL,
+  MODELSTUDIO_DEFAULT_MODEL_ID,
   QIANFAN_BASE_URL,
   QIANFAN_DEFAULT_MODEL_ID,
   XIAOMI_DEFAULT_MODEL_ID,
@@ -512,6 +516,7 @@ const SIMPLE_IMPLICIT_PROVIDER_LOADERS: ImplicitProviderLoader[] = [
     apiKey,
   })),
   withApiKey("qianfan", async ({ apiKey }) => ({ ...buildQianfanProvider(), apiKey })),
+  withApiKey("modelstudio", async ({ apiKey }) => ({ ...buildModelStudioProvider(), apiKey })),
   withApiKey("openrouter", async ({ apiKey }) => ({ ...buildOpenrouterProvider(), apiKey })),
   withApiKey("nvidia", async ({ apiKey }) => ({ ...buildNvidiaProvider(), apiKey })),
   withApiKey("kilocode", async ({ apiKey }) => ({

src/agents/openai-ws-stream.ts

@@ -604,10 +604,14 @@ export function createOpenAIWebSocketStreamFn(
         ...(prevResponseId ? { previous_response_id: prevResponseId } : {}),
         ...extraParams,
       };
-      options?.onPayload?.(payload);
+      const nextPayload = await options?.onPayload?.(payload, model);
+      const requestPayload =
+        nextPayload && typeof nextPayload === "object"
+          ? (nextPayload as Parameters<OpenAIWebSocketManager["send"]>[0])
+          : (payload as Parameters<OpenAIWebSocketManager["send"]>[0]);
 
       try {
-        session.manager.send(payload as Parameters<OpenAIWebSocketManager["send"]>[0]);
+        session.manager.send(requestPayload);
       } catch (sendErr) {
         if (transport === "websocket") {
           throw sendErr instanceof Error ? sendErr : new Error(String(sendErr));

src/agents/pi-embedded-helpers.isbillingerrormessage.test.ts

@@ -501,6 +501,26 @@ describe("isFailoverErrorMessage", () => {
       expect(isFailoverErrorMessage(sample)).toBe(true);
     }
   });
+
+  it("matches Gemini MALFORMED_RESPONSE stop reason as timeout (#42149)", () => {
+    const samples = [
+      "Unhandled stop reason: MALFORMED_RESPONSE",
+      "Unhandled stop reason: malformed_response",
+      "stop reason: MALFORMED_RESPONSE",
+    ];
+    for (const sample of samples) {
+      expect(isTimeoutErrorMessage(sample)).toBe(true);
+      expect(classifyFailoverReason(sample)).toBe("timeout");
+      expect(isFailoverErrorMessage(sample)).toBe(true);
+    }
+  });
+
+  it("does not classify MALFORMED_FUNCTION_CALL as timeout", () => {
+    const sample = "Unhandled stop reason: MALFORMED_FUNCTION_CALL";
+    expect(isTimeoutErrorMessage(sample)).toBe(false);
+    expect(classifyFailoverReason(sample)).toBe(null);
+    expect(isFailoverErrorMessage(sample)).toBe(false);
+  });
 });
 
 describe("parseImageSizeError", () => {
@@ -646,6 +666,12 @@ describe("classifyFailoverReason", () => {
     expect(classifyFailoverReason("402 Payment Required: Weekly/Monthly Limit Exhausted")).toBe(
       "billing",
     );
+    // Poe returns 402 without "payment required"; must be recognized for fallback
+    expect(
+      classifyFailoverReason(
+        "402 You've used up your points! Visit https://poe.com/api/keys to get more.",
+      ),
+    ).toBe("billing");
     expect(classifyFailoverReason(INSUFFICIENT_QUOTA_PAYLOAD)).toBe("billing");
     expect(classifyFailoverReason("deadline exceeded")).toBe("timeout");
     expect(classifyFailoverReason("request ended without sending any chunks")).toBe("timeout");

src/agents/pi-embedded-helpers/errors.ts

@@ -237,7 +237,7 @@ const RETRYABLE_402_SCOPED_RESULT_HINTS = [
   "exhausted",
 ] as const;
 const RAW_402_MARKER_RE =
-  /["']?(?:status|code)["']?\s*[:=]\s*402\b|\bhttp\s*402\b|\berror(?:\s+code)?\s*[:=]?\s*402\b|\b(?:got|returned|received)\s+(?:a\s+)?402\b|^\s*402\s+payment required\b/i;
+  /["']?(?:status|code)["']?\s*[:=]\s*402\b|\bhttp\s*402\b|\berror(?:\s+code)?\s*[:=]?\s*402\b|\b(?:got|returned|received)\s+(?:a\s+)?402\b|^\s*402\s+payment required\b|^\s*402\s+.*used up your points\b/i;
 const LEADING_402_WRAPPER_RE =
   /^(?:error[:\s-]+)?(?:(?:http\s*)?402(?:\s+payment required)?|payment required)(?:[:\s-]+|$)/i;
 

src/agents/pi-embedded-helpers/failover-matches.ts

@@ -40,9 +40,9 @@ const ERROR_PATTERNS = {
     /\benotfound\b/i,
     /\beai_again\b/i,
     /without sending (?:any )?chunks?/i,
-    /\bstop reason:\s*(?:abort|error)\b/i,
-    /\breason:\s*(?:abort|error)\b/i,
-    /\bunhandled stop reason:\s*(?:abort|error)\b/i,
+    /\bstop reason:\s*(?:abort|error|malformed_response)\b/i,
+    /\breason:\s*(?:abort|error|malformed_response)\b/i,
+    /\bunhandled stop reason:\s*(?:abort|error|malformed_response)\b/i,
   ],
   billing: [
     /["']?(?:status|code)["']?\s*[:=]\s*402\b|\bhttp\s*402\b|\berror(?:\s+code)?\s*[:=]?\s*402\b|\b(?:got|returned|received)\s+(?:a\s+)?402\b|^\s*402\s+payment/i,

src/agents/pi-embedded-runner-extraparams.test.ts

@@ -208,7 +208,7 @@ describe("applyExtraParamsToAgent", () => {
   }) {
     const payload = params.payload ?? { store: false };
     const baseStreamFn: StreamFn = (model, _context, options) => {
-      options?.onPayload?.(payload);
+      options?.onPayload?.(payload, model);
       return {} as ReturnType<StreamFn>;
     };
     const agent = { streamFn: baseStreamFn };
@@ -233,7 +233,7 @@ describe("applyExtraParamsToAgent", () => {
   }) {
     const payload = params.payload ?? {};
     const baseStreamFn: StreamFn = (model, _context, options) => {
-      options?.onPayload?.(payload);
+      options?.onPayload?.(payload, model);
       return {} as ReturnType<StreamFn>;
     };
     const agent = { streamFn: baseStreamFn };
@@ -276,7 +276,7 @@ describe("applyExtraParamsToAgent", () => {
     const payloads: Record<string, unknown>[] = [];
     const baseStreamFn: StreamFn = (_model, _context, options) => {
       const payload: Record<string, unknown> = { model: "deepseek/deepseek-r1" };
-      options?.onPayload?.(payload);
+      options?.onPayload?.(payload, _model);
       payloads.push(payload);
       return {} as ReturnType<StreamFn>;
     };
@@ -308,7 +308,7 @@ describe("applyExtraParamsToAgent", () => {
     const payloads: Record<string, unknown>[] = [];
     const baseStreamFn: StreamFn = (_model, _context, options) => {
       const payload: Record<string, unknown> = {};
-      options?.onPayload?.(payload);
+      options?.onPayload?.(payload, _model);
       payloads.push(payload);
       return {} as ReturnType<StreamFn>;
     };
@@ -332,7 +332,7 @@ describe("applyExtraParamsToAgent", () => {
     const payloads: Record<string, unknown>[] = [];
     const baseStreamFn: StreamFn = (_model, _context, options) => {
       const payload: Record<string, unknown> = { reasoning_effort: "high" };
-      options?.onPayload?.(payload);
+      options?.onPayload?.(payload, _model);
       payloads.push(payload);
       return {} as ReturnType<StreamFn>;
     };
@@ -357,7 +357,7 @@ describe("applyExtraParamsToAgent", () => {
     const payloads: Record<string, unknown>[] = [];
     const baseStreamFn: StreamFn = (_model, _context, options) => {
       const payload: Record<string, unknown> = { reasoning: { max_tokens: 256 } };
-      options?.onPayload?.(payload);
+      options?.onPayload?.(payload, _model);
       payloads.push(payload);
       return {} as ReturnType<StreamFn>;
     };
@@ -381,7 +381,7 @@ describe("applyExtraParamsToAgent", () => {
     const payloads: Record<string, unknown>[] = [];
     const baseStreamFn: StreamFn = (_model, _context, options) => {
       const payload: Record<string, unknown> = { reasoning_effort: "medium" };
-      options?.onPayload?.(payload);
+      options?.onPayload?.(payload, _model);
       payloads.push(payload);
       return {} as ReturnType<StreamFn>;
     };
@@ -588,7 +588,7 @@ describe("applyExtraParamsToAgent", () => {
     const payloads: Record<string, unknown>[] = [];
     const baseStreamFn: StreamFn = (_model, _context, options) => {
       const payload: Record<string, unknown> = { thinking: "off" };
-      options?.onPayload?.(payload);
+      options?.onPayload?.(payload, _model);
       payloads.push(payload);
       return {} as ReturnType<StreamFn>;
     };
@@ -619,7 +619,7 @@ describe("applyExtraParamsToAgent", () => {
     const payloads: Record<string, unknown>[] = [];
     const baseStreamFn: StreamFn = (_model, _context, options) => {
       const payload: Record<string, unknown> = { thinking: "off" };
-      options?.onPayload?.(payload);
+      options?.onPayload?.(payload, _model);
       payloads.push(payload);
       return {} as ReturnType<StreamFn>;
     };
@@ -650,7 +650,7 @@ describe("applyExtraParamsToAgent", () => {
     const payloads: Record<string, unknown>[] = [];
     const baseStreamFn: StreamFn = (_model, _context, options) => {
       const payload: Record<string, unknown> = {};
-      options?.onPayload?.(payload);
+      options?.onPayload?.(payload, _model);
       payloads.push(payload);
       return {} as ReturnType<StreamFn>;
     };
@@ -674,7 +674,7 @@ describe("applyExtraParamsToAgent", () => {
     const payloads: Record<string, unknown>[] = [];
     const baseStreamFn: StreamFn = (_model, _context, options) => {
       const payload: Record<string, unknown> = { tool_choice: "required" };
-      options?.onPayload?.(payload);
+      options?.onPayload?.(payload, _model);
       payloads.push(payload);
       return {} as ReturnType<StreamFn>;
     };
@@ -699,7 +699,7 @@ describe("applyExtraParamsToAgent", () => {
     const payloads: Record<string, unknown>[] = [];
     const baseStreamFn: StreamFn = (_model, _context, options) => {
       const payload: Record<string, unknown> = {};
-      options?.onPayload?.(payload);
+      options?.onPayload?.(payload, _model);
       payloads.push(payload);
       return {} as ReturnType<StreamFn>;
     };
@@ -749,7 +749,7 @@ describe("applyExtraParamsToAgent", () => {
         ],
         tool_choice: { type: "tool", name: "read" },
       };
-      options?.onPayload?.(payload);
+      options?.onPayload?.(payload, _model);
       payloads.push(payload);
       return {} as ReturnType<StreamFn>;
     };
@@ -793,7 +793,7 @@ describe("applyExtraParamsToAgent", () => {
           },
         ],
       };
-      options?.onPayload?.(payload);
+      options?.onPayload?.(payload, _model);
       payloads.push(payload);
       return {} as ReturnType<StreamFn>;
     };
@@ -832,7 +832,7 @@ describe("applyExtraParamsToAgent", () => {
           },
         ],
       };
-      options?.onPayload?.(payload);
+      options?.onPayload?.(payload, _model);
       payloads.push(payload);
       return {} as ReturnType<StreamFn>;
     };
@@ -896,7 +896,7 @@ describe("applyExtraParamsToAgent", () => {
           },
         },
       };
-      options?.onPayload?.(payload);
+      options?.onPayload?.(payload, _model);
       payloads.push(payload);
       return {} as ReturnType<StreamFn>;
     };
@@ -943,7 +943,7 @@ describe("applyExtraParamsToAgent", () => {
           },
         },
       };
-      options?.onPayload?.(payload);
+      options?.onPayload?.(payload, _model);
       payloads.push(payload);
       return {} as ReturnType<StreamFn>;
     };

src/agents/pi-embedded-runner/anthropic-stream-wrappers.ts

@@ -298,7 +298,7 @@ export function createAnthropicToolPayloadCompatibilityWrapper(
             );
           }
         }
-        return originalOnPayload?.(payload);
+        return originalOnPayload?.(payload, model);
       },
     });
   };

src/agents/pi-embedded-runner/extra-params.kilocode.test.ts

@@ -19,7 +19,7 @@ function applyAndCapture(params: {
 
   const baseStreamFn: StreamFn = (_model, _context, options) => {
     captured.headers = options?.headers;
-    options?.onPayload?.({});
+    options?.onPayload?.({}, _model);
     return createAssistantMessageEventStream();
   };
   const agent = { streamFn: baseStreamFn };
@@ -97,7 +97,7 @@ describe("extra-params: Kilocode kilo/auto reasoning", () => {
 
     const baseStreamFn: StreamFn = (_model, _context, options) => {
       const payload: Record<string, unknown> = { reasoning_effort: "high" };
-      options?.onPayload?.(payload);
+      options?.onPayload?.(payload, _model);
       capturedPayload = payload;
       return createAssistantMessageEventStream();
     };
@@ -125,7 +125,7 @@ describe("extra-params: Kilocode kilo/auto reasoning", () => {
 
     const baseStreamFn: StreamFn = (_model, _context, options) => {
       const payload: Record<string, unknown> = {};
-      options?.onPayload?.(payload);
+      options?.onPayload?.(payload, _model);
       capturedPayload = payload;
       return createAssistantMessageEventStream();
     };
@@ -158,7 +158,7 @@ describe("extra-params: Kilocode kilo/auto reasoning", () => {
 
     const baseStreamFn: StreamFn = (_model, _context, options) => {
       const payload: Record<string, unknown> = { reasoning_effort: "high" };
-      options?.onPayload?.(payload);
+      options?.onPayload?.(payload, _model);
       capturedPayload = payload;
       return createAssistantMessageEventStream();
     };

src/agents/pi-embedded-runner/extra-params.openrouter-cache-control.test.ts

@@ -13,7 +13,7 @@ type StreamPayload = {
 
 function runOpenRouterPayload(payload: StreamPayload, modelId: string) {
   const baseStreamFn: StreamFn = (_model, _context, options) => {
-    options?.onPayload?.(payload);
+    options?.onPayload?.(payload, _model);
     return createAssistantMessageEventStream();
   };
   const agent = { streamFn: baseStreamFn };

src/agents/pi-embedded-runner/extra-params.ts

@@ -230,7 +230,7 @@ function createGoogleThinkingPayloadWrapper(
             thinkingLevel,
           });
         }
-        return onPayload?.(payload);
+        return onPayload?.(payload, model);
       },
     });
   };
@@ -263,7 +263,7 @@ function createZaiToolStreamWrapper(
           // Inject tool_stream: true for Z.AI API
           (payload as Record<string, unknown>).tool_stream = true;
         }
-        return originalOnPayload?.(payload);
+        return originalOnPayload?.(payload, model);
       },
     });
   };
@@ -310,7 +310,7 @@ function createParallelToolCallsWrapper(
         if (payload && typeof payload === "object") {
           (payload as Record<string, unknown>).parallel_tool_calls = enabled;
         }
-        return originalOnPayload?.(payload);
+        return originalOnPayload?.(payload, model);
       },
     });
   };

src/agents/pi-embedded-runner/extra-params.zai-tool-stream.test.ts

@@ -22,7 +22,7 @@ type ToolStreamCase = {
 function runToolStreamCase(params: ToolStreamCase) {
   const payload: Record<string, unknown> = { model: params.model.id, messages: [] };
   const baseStreamFn: StreamFn = (model, _context, options) => {
-    options?.onPayload?.(payload);
+    options?.onPayload?.(payload, model);
     return {} as ReturnType<StreamFn>;
   };
   const agent = { streamFn: baseStreamFn };

src/agents/pi-embedded-runner/model.provider-normalization.ts

@@ -54,9 +54,33 @@ function normalizeOpenAICodexTransport(params: {
   } as Model<Api>;
 }
 
+function normalizeOpenAITransport(params: { provider: string; model: Model<Api> }): Model<Api> {
+  if (normalizeProviderId(params.provider) !== "openai") {
+    return params.model;
+  }
+
+  const useResponsesTransport =
+    params.model.api === "openai-completions" &&
+    (!params.model.baseUrl || isOpenAIApiBaseUrl(params.model.baseUrl));
+
+  if (!useResponsesTransport) {
+    return params.model;
+  }
+
+  return {
+    ...params.model,
+    api: "openai-responses",
+  } as Model<Api>;
+}
+
 export function normalizeResolvedProviderModel(params: {
   provider: string;
   model: Model<Api>;
 }): Model<Api> {
-  return normalizeModelCompat(normalizeOpenAICodexTransport(params));
+  const normalizedOpenAI = normalizeOpenAITransport(params);
+  const normalizedCodex = normalizeOpenAICodexTransport({
+    provider: params.provider,
+    model: normalizedOpenAI,
+  });
+  return normalizeModelCompat(normalizedCodex);
 }

src/agents/pi-embedded-runner/model.test.ts

@@ -518,6 +518,54 @@ describe("resolveModel", () => {
     });
   });
 
+  it("normalizes stale native openai gpt-5.4 completions transport to responses", () => {
+    mockDiscoveredModel({
+      provider: "openai",
+      modelId: "gpt-5.4",
+      templateModel: buildForwardCompatTemplate({
+        id: "gpt-5.4",
+        name: "GPT-5.4",
+        provider: "openai",
+        api: "openai-completions",
+        baseUrl: "https://api.openai.com/v1",
+      }),
+    });
+
+    const result = resolveModel("openai", "gpt-5.4", "/tmp/agent");
+
+    expect(result.error).toBeUndefined();
+    expect(result.model).toMatchObject({
+      provider: "openai",
+      id: "gpt-5.4",
+      api: "openai-responses",
+      baseUrl: "https://api.openai.com/v1",
+    });
+  });
+
+  it("keeps proxied openai completions transport untouched", () => {
+    mockDiscoveredModel({
+      provider: "openai",
+      modelId: "gpt-5.4",
+      templateModel: buildForwardCompatTemplate({
+        id: "gpt-5.4",
+        name: "GPT-5.4",
+        provider: "openai",
+        api: "openai-completions",
+        baseUrl: "https://proxy.example.com/v1",
+      }),
+    });
+
+    const result = resolveModel("openai", "gpt-5.4", "/tmp/agent");
+
+    expect(result.error).toBeUndefined();
+    expect(result.model).toMatchObject({
+      provider: "openai",
+      id: "gpt-5.4",
+      api: "openai-completions",
+      baseUrl: "https://proxy.example.com/v1",
+    });
+  });
+
   it("builds an anthropic forward-compat fallback for claude-opus-4-6", () => {
     mockDiscoveredModel({
       provider: "anthropic",

src/agents/pi-embedded-runner/moonshot-stream-wrappers.ts

@@ -60,7 +60,7 @@ export function createSiliconFlowThinkingWrapper(baseStreamFn: StreamFn | undefi
             payloadObj.thinking = null;
           }
         }
-        return originalOnPayload?.(payload);
+        return originalOnPayload?.(payload, model);
       },
     });
   };
@@ -106,7 +106,7 @@ export function createMoonshotThinkingWrapper(
             payloadObj.tool_choice = "auto";
           }
         }
-        return originalOnPayload?.(payload);
+        return originalOnPayload?.(payload, model);
       },
     });
   };

src/agents/pi-embedded-runner/openai-stream-wrappers.ts

@@ -197,7 +197,7 @@ export function createOpenAIResponsesContextManagementWrapper(
             compactThreshold,
           });
         }
-        return originalOnPayload?.(payload);
+        return originalOnPayload?.(payload, model);
       },
     });
   };
@@ -226,7 +226,7 @@ export function createOpenAIServiceTierWrapper(
             payloadObj.service_tier = serviceTier;
           }
         }
-        return originalOnPayload?.(payload);
+        return originalOnPayload?.(payload, model);
       },
     });
   };

src/agents/pi-embedded-runner/proxy-stream-wrappers.ts

@@ -92,7 +92,7 @@ export function createOpenRouterSystemCacheWrapper(baseStreamFn: StreamFn | unde
             }
           }
         }
-        return originalOnPayload?.(payload);
+        return originalOnPayload?.(payload, model);
       },
     });
   };
@@ -113,7 +113,7 @@ export function createOpenRouterWrapper(
       },
       onPayload: (payload) => {
         normalizeProxyReasoningPayload(payload, thinkingLevel);
-        return onPayload?.(payload);
+        return onPayload?.(payload, model);
       },
     });
   };
@@ -138,7 +138,7 @@ export function createKilocodeWrapper(
       },
       onPayload: (payload) => {
         normalizeProxyReasoningPayload(payload, thinkingLevel);
-        return onPayload?.(payload);
+        return onPayload?.(payload, model);
       },
     });
   };

src/agents/pi-embedded-runner/run/attempt.test.ts

@@ -520,7 +520,7 @@ describe("wrapOllamaCompatNumCtx", () => {
     let payloadSeen: Record<string, unknown> | undefined;
     const baseFn = vi.fn((_model, _context, options) => {
       const payload: Record<string, unknown> = { options: { temperature: 0.1 } };
-      options?.onPayload?.(payload);
+      options?.onPayload?.(payload, _model);
       payloadSeen = payload;
       return {} as never;
     });

src/agents/pi-embedded-runner/run/attempt.ts

@@ -230,14 +230,14 @@ export function wrapOllamaCompatNumCtx(baseFn: StreamFn | undefined, numCtx: num
       ...options,
       onPayload: (payload: unknown) => {
         if (!payload || typeof payload !== "object") {
-          return options?.onPayload?.(payload);
+          return options?.onPayload?.(payload, model);
         }
         const payloadRecord = payload as Record<string, unknown>;
         if (!payloadRecord.options || typeof payloadRecord.options !== "object") {
           payloadRecord.options = {};
         }
         (payloadRecord.options as Record<string, unknown>).num_ctx = numCtx;
-        return options?.onPayload?.(payload);
+        return options?.onPayload?.(payload, model);
       },
     });
 }

src/agents/pi-embedded-subscribe.handlers.lifecycle.test.ts

@@ -70,7 +70,7 @@ describe("handleAgentEnd", () => {
     });
   });
 
-  it("attaches raw provider error metadata without changing the console message", () => {
+  it("attaches raw provider error metadata and includes model/provider in console output", () => {
     const ctx = createContext({
       role: "assistant",
       stopReason: "error",
@@ -91,9 +91,35 @@ describe("handleAgentEnd", () => {
       error: "The AI service is temporarily overloaded. Please try again in a moment.",
       failoverReason: "overloaded",
       providerErrorType: "overloaded_error",
+      consoleMessage:
+        "embedded run agent end: runId=run-1 isError=true model=claude-test provider=anthropic error=The AI service is temporarily overloaded. Please try again in a moment.",
     });
   });
 
+  it("sanitizes model and provider before writing consoleMessage", () => {
+    const ctx = createContext({
+      role: "assistant",
+      stopReason: "error",
+      provider: "anthropic\u001b]8;;https://evil.test\u0007",
+      model: "claude\tsonnet\n4",
+      errorMessage: "connection refused",
+      content: [{ type: "text", text: "" }],
+    });
+
+    handleAgentEnd(ctx);
+
+    const warn = vi.mocked(ctx.log.warn);
+    const meta = warn.mock.calls[0]?.[1];
+    expect(meta).toMatchObject({
+      consoleMessage:
+        "embedded run agent end: runId=run-1 isError=true model=claude sonnet 4 provider=anthropic]8;;https://evil.test error=connection refused",
+    });
+    expect(meta?.consoleMessage).not.toContain("\n");
+    expect(meta?.consoleMessage).not.toContain("\r");
+    expect(meta?.consoleMessage).not.toContain("\t");
+    expect(meta?.consoleMessage).not.toContain("\u001b");
+  });
+
   it("redacts logged error text before emitting lifecycle events", () => {
     const onAgentEvent = vi.fn();
     const ctx = createContext(

src/agents/pi-embedded-subscribe.handlers.lifecycle.ts

@@ -48,6 +48,8 @@ export function handleAgentEnd(ctx: EmbeddedPiSubscribeContext) {
     const safeErrorText =
       buildTextObservationFields(errorText).textPreview ?? "LLM request failed.";
     const safeRunId = sanitizeForConsole(ctx.params.runId) ?? "-";
+    const safeModel = sanitizeForConsole(lastAssistant.model) ?? "unknown";
+    const safeProvider = sanitizeForConsole(lastAssistant.provider) ?? "unknown";
     ctx.log.warn("embedded run agent end", {
       event: "embedded_run_agent_end",
       tags: ["error_handling", "lifecycle", "agent_end", "assistant_error"],
@@ -55,10 +57,10 @@ export function handleAgentEnd(ctx: EmbeddedPiSubscribeContext) {
       isError: true,
       error: safeErrorText,
       failoverReason,
-      provider: lastAssistant.provider,
       model: lastAssistant.model,
+      provider: lastAssistant.provider,
       ...observedError,
-      consoleMessage: `embedded run agent end: runId=${safeRunId} isError=true error=${safeErrorText}`,
+      consoleMessage: `embedded run agent end: runId=${safeRunId} isError=true model=${safeModel} provider=${safeProvider} error=${safeErrorText}`,
     });
     emitAgentEvent({
       runId: ctx.params.runId,

src/agents/tools/pdf-native-providers.ts

@@ -137,10 +137,9 @@ export async function geminiAnalyzePdf(params: {
   }
   parts.push({ text: params.prompt });
 
-  const baseUrl = (params.baseUrl ?? "https://generativelanguage.googleapis.com").replace(
-    /\/+$/,
-    "",
-  );
+  const baseUrl = (params.baseUrl ?? "https://generativelanguage.googleapis.com")
+    .replace(/\/+$/, "")
+    .replace(/\/v1beta$/, "");
   const url = `${baseUrl}/v1beta/models/${encodeURIComponent(params.modelId)}:generateContent?key=${encodeURIComponent(apiKey)}`;
 
   const res = await fetch(url, {

src/agents/tools/pdf-tool.test.ts

@@ -711,6 +711,26 @@ describe("native PDF provider API calls", () => {
       "apiKey required",
     );
   });
+
+  it("geminiAnalyzePdf does not duplicate /v1beta when baseUrl already includes it", async () => {
+    const { geminiAnalyzePdf } = await import("./pdf-native-providers.js");
+    const fetchMock = mockFetchResponse({
+      ok: true,
+      json: async () => ({
+        candidates: [{ content: { parts: [{ text: "ok" }] } }],
+      }),
+    });
+
+    await geminiAnalyzePdf(
+      makeGeminiAnalyzeParams({
+        baseUrl: "https://generativelanguage.googleapis.com/v1beta",
+      }),
+    );
+
+    const [url] = fetchMock.mock.calls[0];
+    expect(url).toContain("/v1beta/models/");
+    expect(url).not.toContain("/v1beta/v1beta");
+  });
 });
 
 // ---------------------------------------------------------------------------

src/agents/tools/telegram-actions.test.ts

@@ -18,6 +18,16 @@ const sendStickerTelegram = vi.fn(async () => ({
   chatId: "123",
 }));
 const deleteMessageTelegram = vi.fn(async () => ({ ok: true }));
+const editMessageTelegram = vi.fn(async () => ({
+  ok: true,
+  messageId: "456",
+  chatId: "123",
+}));
+const createForumTopicTelegram = vi.fn(async () => ({
+  topicId: 99,
+  name: "Topic",
+  chatId: "123",
+}));
 let envSnapshot: ReturnType<typeof captureEnv>;
 
 vi.mock("../../telegram/send.js", () => ({
@@ -30,6 +40,10 @@ vi.mock("../../telegram/send.js", () => ({
     sendStickerTelegram(...args),
   deleteMessageTelegram: (...args: Parameters<typeof deleteMessageTelegram>) =>
     deleteMessageTelegram(...args),
+  editMessageTelegram: (...args: Parameters<typeof editMessageTelegram>) =>
+    editMessageTelegram(...args),
+  createForumTopicTelegram: (...args: Parameters<typeof createForumTopicTelegram>) =>
+    createForumTopicTelegram(...args),
 }));
 
 describe("handleTelegramAction", () => {
@@ -90,6 +104,8 @@ describe("handleTelegramAction", () => {
     sendPollTelegram.mockClear();
     sendStickerTelegram.mockClear();
     deleteMessageTelegram.mockClear();
+    editMessageTelegram.mockClear();
+    createForumTopicTelegram.mockClear();
     process.env.TELEGRAM_BOT_TOKEN = "tok";
   });
 
@@ -379,6 +395,85 @@ describe("handleTelegramAction", () => {
     );
   });
 
+  it.each([
+    {
+      name: "react",
+      params: { action: "react", chatId: "123", messageId: 456, emoji: "✅" },
+      cfg: reactionConfig("minimal"),
+      assertCall: (
+        readCallOpts: (calls: unknown[][], argIndex: number) => Record<string, unknown>,
+      ) => readCallOpts(reactMessageTelegram.mock.calls as unknown[][], 3),
+    },
+    {
+      name: "sendMessage",
+      params: { action: "sendMessage", to: "123", content: "hello" },
+      cfg: telegramConfig(),
+      assertCall: (
+        readCallOpts: (calls: unknown[][], argIndex: number) => Record<string, unknown>,
+      ) => readCallOpts(sendMessageTelegram.mock.calls as unknown[][], 2),
+    },
+    {
+      name: "poll",
+      params: {
+        action: "poll",
+        to: "123",
+        question: "Q?",
+        answers: ["A", "B"],
+      },
+      cfg: telegramConfig(),
+      assertCall: (
+        readCallOpts: (calls: unknown[][], argIndex: number) => Record<string, unknown>,
+      ) => readCallOpts(sendPollTelegram.mock.calls as unknown[][], 2),
+    },
+    {
+      name: "deleteMessage",
+      params: { action: "deleteMessage", chatId: "123", messageId: 1 },
+      cfg: telegramConfig(),
+      assertCall: (
+        readCallOpts: (calls: unknown[][], argIndex: number) => Record<string, unknown>,
+      ) => readCallOpts(deleteMessageTelegram.mock.calls as unknown[][], 2),
+    },
+    {
+      name: "editMessage",
+      params: { action: "editMessage", chatId: "123", messageId: 1, content: "updated" },
+      cfg: telegramConfig(),
+      assertCall: (
+        readCallOpts: (calls: unknown[][], argIndex: number) => Record<string, unknown>,
+      ) => readCallOpts(editMessageTelegram.mock.calls as unknown[][], 3),
+    },
+    {
+      name: "sendSticker",
+      params: { action: "sendSticker", to: "123", fileId: "sticker-1" },
+      cfg: telegramConfig({ actions: { sticker: true } }),
+      assertCall: (
+        readCallOpts: (calls: unknown[][], argIndex: number) => Record<string, unknown>,
+      ) => readCallOpts(sendStickerTelegram.mock.calls as unknown[][], 2),
+    },
+    {
+      name: "createForumTopic",
+      params: { action: "createForumTopic", chatId: "123", name: "Topic" },
+      cfg: telegramConfig({ actions: { createForumTopic: true } }),
+      assertCall: (
+        readCallOpts: (calls: unknown[][], argIndex: number) => Record<string, unknown>,
+      ) => readCallOpts(createForumTopicTelegram.mock.calls as unknown[][], 2),
+    },
+  ])("forwards resolved cfg for $name action", async ({ params, cfg, assertCall }) => {
+    const readCallOpts = (calls: unknown[][], argIndex: number): Record<string, unknown> => {
+      const args = calls[0];
+      if (!Array.isArray(args)) {
+        throw new Error("Expected Telegram action call args");
+      }
+      const opts = args[argIndex];
+      if (!opts || typeof opts !== "object") {
+        throw new Error("Expected Telegram action options object");
+      }
+      return opts as Record<string, unknown>;
+    };
+    await handleTelegramAction(params as Record<string, unknown>, cfg);
+    const opts = assertCall(readCallOpts);
+    expect(opts.cfg).toBe(cfg);
+  });
+
   it.each([
     {
       name: "media",

src/agents/tools/telegram-actions.ts

@@ -154,6 +154,7 @@ export async function handleTelegramAction(
     let reactionResult: Awaited<ReturnType<typeof reactMessageTelegram>>;
     try {
       reactionResult = await reactMessageTelegram(chatId ?? "", messageId ?? 0, emoji ?? "", {
+        cfg,
         token,
         remove,
         accountId: accountId ?? undefined,
@@ -237,6 +238,7 @@ export async function handleTelegramAction(
       );
     }
     const result = await sendMessageTelegram(to, content, {
+      cfg,
       token,
       accountId: accountId ?? undefined,
       mediaUrl: mediaUrl || undefined,
@@ -293,6 +295,7 @@ export async function handleTelegramAction(
         durationHours: durationHours ?? undefined,
       },
       {
+        cfg,
         token,
         accountId: accountId ?? undefined,
         replyToMessageId: replyToMessageId ?? undefined,
@@ -327,6 +330,7 @@ export async function handleTelegramAction(
       );
     }
     await deleteMessageTelegram(chatId ?? "", messageId ?? 0, {
+      cfg,
       token,
       accountId: accountId ?? undefined,
     });
@@ -367,6 +371,7 @@ export async function handleTelegramAction(
       );
     }
     const result = await editMessageTelegram(chatId ?? "", messageId ?? 0, content, {
+      cfg,
       token,
       accountId: accountId ?? undefined,
       buttons,
@@ -399,6 +404,7 @@ export async function handleTelegramAction(
       );
     }
     const result = await sendStickerTelegram(to, fileId, {
+      cfg,
       token,
       accountId: accountId ?? undefined,
       replyToMessageId: replyToMessageId ?? undefined,
@@ -454,6 +460,7 @@ export async function handleTelegramAction(
       );
     }
     const result = await createForumTopicTelegram(chatId ?? "", name, {
+      cfg,
       token,
       accountId: accountId ?? undefined,
       iconColor: iconColor ?? undefined,

src/auto-reply/reply/agent-runner.runreplyagent.e2e.test.ts

@@ -1255,6 +1255,79 @@ describe("runReplyAgent typing (heartbeat)", () => {
     });
   });
 
+  it("clears stale runtime model fields when resetSession retries after compaction failure", async () => {
+    await withTempStateDir(async (stateDir) => {
+      const sessionId = "session-stale-model";
+      const storePath = path.join(stateDir, "sessions", "sessions.json");
+      const transcriptPath = sessions.resolveSessionTranscriptPath(sessionId);
+      const sessionEntry: SessionEntry = {
+        sessionId,
+        updatedAt: Date.now(),
+        sessionFile: transcriptPath,
+        modelProvider: "qwencode",
+        model: "qwen3.5-plus-2026-02-15",
+        contextTokens: 123456,
+        systemPromptReport: {
+          source: "run",
+          generatedAt: Date.now(),
+          sessionId,
+          sessionKey: "main",
+          provider: "qwencode",
+          model: "qwen3.5-plus-2026-02-15",
+          workspaceDir: stateDir,
+          bootstrapMaxChars: 1000,
+          bootstrapTotalMaxChars: 2000,
+          systemPrompt: {
+            chars: 10,
+            projectContextChars: 5,
+            nonProjectContextChars: 5,
+          },
+          injectedWorkspaceFiles: [],
+          skills: {
+            promptChars: 0,
+            entries: [],
+          },
+          tools: {
+            listChars: 0,
+            schemaChars: 0,
+            entries: [],
+          },
+        },
+      };
+      const sessionStore = { main: sessionEntry };
+
+      await fs.mkdir(path.dirname(storePath), { recursive: true });
+      await fs.writeFile(storePath, JSON.stringify(sessionStore), "utf-8");
+      await fs.mkdir(path.dirname(transcriptPath), { recursive: true });
+      await fs.writeFile(transcriptPath, "ok", "utf-8");
+
+      state.runEmbeddedPiAgentMock.mockImplementationOnce(async () => {
+        throw new Error(
+          'Context overflow: Summarization failed: 400 {"message":"prompt is too long"}',
+        );
+      });
+
+      const { run } = createMinimalRun({
+        sessionEntry,
+        sessionStore,
+        sessionKey: "main",
+        storePath,
+      });
+      await run();
+
+      expect(sessionStore.main.modelProvider).toBeUndefined();
+      expect(sessionStore.main.model).toBeUndefined();
+      expect(sessionStore.main.contextTokens).toBeUndefined();
+      expect(sessionStore.main.systemPromptReport).toBeUndefined();
+
+      const persisted = JSON.parse(await fs.readFile(storePath, "utf-8"));
+      expect(persisted.main.modelProvider).toBeUndefined();
+      expect(persisted.main.model).toBeUndefined();
+      expect(persisted.main.contextTokens).toBeUndefined();
+      expect(persisted.main.systemPromptReport).toBeUndefined();
+    });
+  });
+
   it("surfaces overflow fallback when embedded run returns empty payloads", async () => {
     state.runEmbeddedPiAgentMock.mockImplementationOnce(async () => ({
       payloads: [],

src/auto-reply/reply/agent-runner.ts

@@ -278,6 +278,10 @@ export async function runReplyAgent(params: {
       updatedAt: Date.now(),
       systemSent: false,
       abortedLastRun: false,
+      modelProvider: undefined,
+      model: undefined,
+      contextTokens: undefined,
+      systemPromptReport: undefined,
       fallbackNoticeSelectedModel: undefined,
       fallbackNoticeActiveModel: undefined,
       fallbackNoticeReason: undefined,

src/channels/plugins/outbound/direct-text-media.sendpayload.test.ts

@@ -1,9 +1,17 @@
-import { describe, expect, it, vi } from "vitest";
+import { describe, vi } from "vitest";
 import type { ReplyPayload } from "../../../auto-reply/types.js";
+import {
+  installSendPayloadContractSuite,
+  primeSendMock,
+} from "../../../test-utils/send-payload-contract.js";
 import { createDirectTextMediaOutbound } from "./direct-text-media.js";
 
-function makeOutbound() {
-  const sendFn = vi.fn().mockResolvedValue({ messageId: "m1" });
+function createDirectHarness(params: {
+  payload: ReplyPayload;
+  sendResults?: Array<{ messageId: string }>;
+}) {
+  const sendFn = vi.fn();
+  primeSendMock(sendFn, { messageId: "m1" }, params.sendResults);
   const outbound = createDirectTextMediaOutbound({
     channel: "imessage",
     resolveSender: () => sendFn,
@@ -24,94 +32,16 @@ function baseCtx(payload: ReplyPayload) {
 }
 
 describe("createDirectTextMediaOutbound sendPayload", () => {
-  it("text-only delegates to sendText", async () => {
-    const { outbound, sendFn } = makeOutbound();
-    const result = await outbound.sendPayload!(baseCtx({ text: "hello" }));
-
-    expect(sendFn).toHaveBeenCalledTimes(1);
-    expect(sendFn).toHaveBeenCalledWith("user1", "hello", expect.any(Object));
-    expect(result).toMatchObject({ channel: "imessage", messageId: "m1" });
-  });
-
-  it("single media delegates to sendMedia", async () => {
-    const { outbound, sendFn } = makeOutbound();
-    const result = await outbound.sendPayload!(
-      baseCtx({ text: "cap", mediaUrl: "https://example.com/a.jpg" }),
-    );
-
-    expect(sendFn).toHaveBeenCalledTimes(1);
-    expect(sendFn).toHaveBeenCalledWith(
-      "user1",
-      "cap",
-      expect.objectContaining({ mediaUrl: "https://example.com/a.jpg" }),
-    );
-    expect(result).toMatchObject({ channel: "imessage", messageId: "m1" });
-  });
-
-  it("multi-media iterates URLs with caption on first", async () => {
-    const sendFn = vi
-      .fn()
-      .mockResolvedValueOnce({ messageId: "m1" })
-      .mockResolvedValueOnce({ messageId: "m2" });
-    const outbound = createDirectTextMediaOutbound({
-      channel: "imessage",
-      resolveSender: () => sendFn,
-      resolveMaxBytes: () => undefined,
-      buildTextOptions: (opts) => opts as never,
-      buildMediaOptions: (opts) => opts as never,
-    });
-    const result = await outbound.sendPayload!(
-      baseCtx({
-        text: "caption",
-        mediaUrls: ["https://example.com/1.jpg", "https://example.com/2.jpg"],
-      }),
-    );
-
-    expect(sendFn).toHaveBeenCalledTimes(2);
-    expect(sendFn).toHaveBeenNthCalledWith(
-      1,
-      "user1",
-      "caption",
-      expect.objectContaining({ mediaUrl: "https://example.com/1.jpg" }),
-    );
-    expect(sendFn).toHaveBeenNthCalledWith(
-      2,
-      "user1",
-      "",
-      expect.objectContaining({ mediaUrl: "https://example.com/2.jpg" }),
-    );
-    expect(result).toMatchObject({ channel: "imessage", messageId: "m2" });
-  });
-
-  it("empty payload returns no-op", async () => {
-    const { outbound, sendFn } = makeOutbound();
-    const result = await outbound.sendPayload!(baseCtx({}));
-
-    expect(sendFn).not.toHaveBeenCalled();
-    expect(result).toEqual({ channel: "imessage", messageId: "" });
-  });
-
-  it("chunking splits long text", async () => {
-    const sendFn = vi
-      .fn()
-      .mockResolvedValueOnce({ messageId: "c1" })
-      .mockResolvedValueOnce({ messageId: "c2" });
-    const outbound = createDirectTextMediaOutbound({
-      channel: "signal",
-      resolveSender: () => sendFn,
-      resolveMaxBytes: () => undefined,
-      buildTextOptions: (opts) => opts as never,
-      buildMediaOptions: (opts) => opts as never,
-    });
-    // textChunkLimit is 4000; generate text exceeding that
-    const longText = "a".repeat(5000);
-    const result = await outbound.sendPayload!(baseCtx({ text: longText }));
-
-    expect(sendFn.mock.calls.length).toBeGreaterThanOrEqual(2);
-    // Each chunk should be within the limit
-    for (const call of sendFn.mock.calls) {
-      expect((call[1] as string).length).toBeLessThanOrEqual(4000);
-    }
-    expect(result).toMatchObject({ channel: "signal" });
+  installSendPayloadContractSuite({
+    channel: "imessage",
+    chunking: { mode: "split", longTextLength: 5000, maxChunkLength: 4000 },
+    createHarness: ({ payload, sendResults }) => {
+      const { outbound, sendFn } = createDirectHarness({ payload, sendResults });
+      return {
+        run: async () => await outbound.sendPayload!(baseCtx(payload)),
+        sendMock: sendFn,
+        to: "user1",
+      };
+    },
   });
 });

src/channels/plugins/outbound/discord.sendpayload.test.ts

@@ -1,98 +1,37 @@
-import { describe, expect, it, vi } from "vitest";
+import { describe, vi } from "vitest";
 import type { ReplyPayload } from "../../../auto-reply/types.js";
+import {
+  installSendPayloadContractSuite,
+  primeSendMock,
+} from "../../../test-utils/send-payload-contract.js";
 import { discordOutbound } from "./discord.js";
 
-function baseCtx(payload: ReplyPayload) {
-  return {
+function createHarness(params: {
+  payload: ReplyPayload;
+  sendResults?: Array<{ messageId: string }>;
+}) {
+  const sendDiscord = vi.fn();
+  primeSendMock(sendDiscord, { messageId: "dc-1", channelId: "123456" }, params.sendResults);
+  const ctx = {
     cfg: {},
     to: "channel:123456",
     text: "",
-    payload,
+    payload: params.payload,
     deps: {
-      sendDiscord: vi.fn().mockResolvedValue({ messageId: "dc-1", channelId: "123456" }),
+      sendDiscord,
     },
   };
+  return {
+    run: async () => await discordOutbound.sendPayload!(ctx),
+    sendMock: sendDiscord,
+    to: ctx.to,
+  };
 }
 
 describe("discordOutbound sendPayload", () => {
-  it("text-only delegates to sendText", async () => {
-    const ctx = baseCtx({ text: "hello" });
-    const result = await discordOutbound.sendPayload!(ctx);
-
-    expect(ctx.deps.sendDiscord).toHaveBeenCalledTimes(1);
-    expect(ctx.deps.sendDiscord).toHaveBeenCalledWith(
-      "channel:123456",
-      "hello",
-      expect.any(Object),
-    );
-    expect(result).toMatchObject({ channel: "discord" });
-  });
-
-  it("single media delegates to sendMedia", async () => {
-    const ctx = baseCtx({ text: "cap", mediaUrl: "https://example.com/a.jpg" });
-    const result = await discordOutbound.sendPayload!(ctx);
-
-    expect(ctx.deps.sendDiscord).toHaveBeenCalledTimes(1);
-    expect(ctx.deps.sendDiscord).toHaveBeenCalledWith(
-      "channel:123456",
-      "cap",
-      expect.objectContaining({ mediaUrl: "https://example.com/a.jpg" }),
-    );
-    expect(result).toMatchObject({ channel: "discord" });
-  });
-
-  it("multi-media iterates URLs with caption on first", async () => {
-    const sendDiscord = vi
-      .fn()
-      .mockResolvedValueOnce({ messageId: "dc-1", channelId: "123456" })
-      .mockResolvedValueOnce({ messageId: "dc-2", channelId: "123456" });
-    const ctx = {
-      cfg: {},
-      to: "channel:123456",
-      text: "",
-      payload: {
-        text: "caption",
-        mediaUrls: ["https://example.com/1.jpg", "https://example.com/2.jpg"],
-      } as ReplyPayload,
-      deps: { sendDiscord },
-    };
-    const result = await discordOutbound.sendPayload!(ctx);
-
-    expect(sendDiscord).toHaveBeenCalledTimes(2);
-    expect(sendDiscord).toHaveBeenNthCalledWith(
-      1,
-      "channel:123456",
-      "caption",
-      expect.objectContaining({ mediaUrl: "https://example.com/1.jpg" }),
-    );
-    expect(sendDiscord).toHaveBeenNthCalledWith(
-      2,
-      "channel:123456",
-      "",
-      expect.objectContaining({ mediaUrl: "https://example.com/2.jpg" }),
-    );
-    expect(result).toMatchObject({ channel: "discord", messageId: "dc-2" });
-  });
-
-  it("empty payload returns no-op", async () => {
-    const ctx = baseCtx({});
-    const result = await discordOutbound.sendPayload!(ctx);
-
-    expect(ctx.deps.sendDiscord).not.toHaveBeenCalled();
-    expect(result).toEqual({ channel: "discord", messageId: "" });
-  });
-
-  it("text exceeding chunk limit is sent as-is when chunker is null", async () => {
-    // Discord has chunker: null, so long text should be sent as a single message
-    const ctx = baseCtx({ text: "a".repeat(3000) });
-    const result = await discordOutbound.sendPayload!(ctx);
-
-    expect(ctx.deps.sendDiscord).toHaveBeenCalledTimes(1);
-    expect(ctx.deps.sendDiscord).toHaveBeenCalledWith(
-      "channel:123456",
-      "a".repeat(3000),
-      expect.any(Object),
-    );
-    expect(result).toMatchObject({ channel: "discord" });
+  installSendPayloadContractSuite({
+    channel: "discord",
+    chunking: { mode: "passthrough", longTextLength: 3000 },
+    createHarness,
   });
 });

src/channels/plugins/outbound/slack.sendpayload.test.ts

@@ -1,92 +1,41 @@
-import { describe, expect, it, vi } from "vitest";
+import { describe, vi } from "vitest";
 import type { ReplyPayload } from "../../../auto-reply/types.js";
+import {
+  installSendPayloadContractSuite,
+  primeSendMock,
+} from "../../../test-utils/send-payload-contract.js";
 import { slackOutbound } from "./slack.js";
 
-function baseCtx(payload: ReplyPayload) {
-  return {
+function createHarness(params: {
+  payload: ReplyPayload;
+  sendResults?: Array<{ messageId: string }>;
+}) {
+  const sendSlack = vi.fn();
+  primeSendMock(
+    sendSlack,
+    { messageId: "sl-1", channelId: "C12345", ts: "1234.5678" },
+    params.sendResults,
+  );
+  const ctx = {
     cfg: {},
     to: "C12345",
     text: "",
-    payload,
+    payload: params.payload,
     deps: {
-      sendSlack: vi
-        .fn()
-        .mockResolvedValue({ messageId: "sl-1", channelId: "C12345", ts: "1234.5678" }),
+      sendSlack,
     },
   };
+  return {
+    run: async () => await slackOutbound.sendPayload!(ctx),
+    sendMock: sendSlack,
+    to: ctx.to,
+  };
 }
 
 describe("slackOutbound sendPayload", () => {
-  it("text-only delegates to sendText", async () => {
-    const ctx = baseCtx({ text: "hello" });
-    const result = await slackOutbound.sendPayload!(ctx);
-
-    expect(ctx.deps.sendSlack).toHaveBeenCalledTimes(1);
-    expect(ctx.deps.sendSlack).toHaveBeenCalledWith("C12345", "hello", expect.any(Object));
-    expect(result).toMatchObject({ channel: "slack" });
-  });
-
-  it("single media delegates to sendMedia", async () => {
-    const ctx = baseCtx({ text: "cap", mediaUrl: "https://example.com/a.jpg" });
-    const result = await slackOutbound.sendPayload!(ctx);
-
-    expect(ctx.deps.sendSlack).toHaveBeenCalledTimes(1);
-    expect(ctx.deps.sendSlack).toHaveBeenCalledWith(
-      "C12345",
-      "cap",
-      expect.objectContaining({ mediaUrl: "https://example.com/a.jpg" }),
-    );
-    expect(result).toMatchObject({ channel: "slack" });
-  });
-
-  it("multi-media iterates URLs with caption on first", async () => {
-    const sendSlack = vi
-      .fn()
-      .mockResolvedValueOnce({ messageId: "sl-1", channelId: "C12345" })
-      .mockResolvedValueOnce({ messageId: "sl-2", channelId: "C12345" });
-    const ctx = {
-      cfg: {},
-      to: "C12345",
-      text: "",
-      payload: {
-        text: "caption",
-        mediaUrls: ["https://example.com/1.jpg", "https://example.com/2.jpg"],
-      } as ReplyPayload,
-      deps: { sendSlack },
-    };
-    const result = await slackOutbound.sendPayload!(ctx);
-
-    expect(sendSlack).toHaveBeenCalledTimes(2);
-    expect(sendSlack).toHaveBeenNthCalledWith(
-      1,
-      "C12345",
-      "caption",
-      expect.objectContaining({ mediaUrl: "https://example.com/1.jpg" }),
-    );
-    expect(sendSlack).toHaveBeenNthCalledWith(
-      2,
-      "C12345",
-      "",
-      expect.objectContaining({ mediaUrl: "https://example.com/2.jpg" }),
-    );
-    expect(result).toMatchObject({ channel: "slack", messageId: "sl-2" });
-  });
-
-  it("empty payload returns no-op", async () => {
-    const ctx = baseCtx({});
-    const result = await slackOutbound.sendPayload!(ctx);
-
-    expect(ctx.deps.sendSlack).not.toHaveBeenCalled();
-    expect(result).toEqual({ channel: "slack", messageId: "" });
-  });
-
-  it("text exceeding chunk limit is sent as-is when chunker is null", async () => {
-    // Slack has chunker: null, so long text should be sent as a single message
-    const ctx = baseCtx({ text: "a".repeat(5000) });
-    const result = await slackOutbound.sendPayload!(ctx);
-
-    expect(ctx.deps.sendSlack).toHaveBeenCalledTimes(1);
-    expect(ctx.deps.sendSlack).toHaveBeenCalledWith("C12345", "a".repeat(5000), expect.any(Object));
-    expect(result).toMatchObject({ channel: "slack" });
+  installSendPayloadContractSuite({
+    channel: "slack",
+    chunking: { mode: "passthrough", longTextLength: 5000 },
+    createHarness,
   });
 });

src/channels/plugins/outbound/whatsapp.sendpayload.test.ts

@@ -1,106 +1,37 @@
-import { describe, expect, it, vi } from "vitest";
+import { describe, vi } from "vitest";
 import type { ReplyPayload } from "../../../auto-reply/types.js";
+import {
+  installSendPayloadContractSuite,
+  primeSendMock,
+} from "../../../test-utils/send-payload-contract.js";
 import { whatsappOutbound } from "./whatsapp.js";
 
-function baseCtx(payload: ReplyPayload) {
-  return {
+function createHarness(params: {
+  payload: ReplyPayload;
+  sendResults?: Array<{ messageId: string }>;
+}) {
+  const sendWhatsApp = vi.fn();
+  primeSendMock(sendWhatsApp, { messageId: "wa-1" }, params.sendResults);
+  const ctx = {
     cfg: {},
     to: "5511999999999@c.us",
     text: "",
-    payload,
+    payload: params.payload,
     deps: {
-      sendWhatsApp: vi.fn().mockResolvedValue({ messageId: "wa-1" }),
+      sendWhatsApp,
     },
   };
+  return {
+    run: async () => await whatsappOutbound.sendPayload!(ctx),
+    sendMock: sendWhatsApp,
+    to: ctx.to,
+  };
 }
 
 describe("whatsappOutbound sendPayload", () => {
-  it("text-only delegates to sendText", async () => {
-    const ctx = baseCtx({ text: "hello" });
-    const result = await whatsappOutbound.sendPayload!(ctx);
-
-    expect(ctx.deps.sendWhatsApp).toHaveBeenCalledTimes(1);
-    expect(ctx.deps.sendWhatsApp).toHaveBeenCalledWith(
-      "5511999999999@c.us",
-      "hello",
-      expect.any(Object),
-    );
-    expect(result).toMatchObject({ channel: "whatsapp", messageId: "wa-1" });
-  });
-
-  it("single media delegates to sendMedia", async () => {
-    const ctx = baseCtx({ text: "cap", mediaUrl: "https://example.com/a.jpg" });
-    const result = await whatsappOutbound.sendPayload!(ctx);
-
-    expect(ctx.deps.sendWhatsApp).toHaveBeenCalledTimes(1);
-    expect(ctx.deps.sendWhatsApp).toHaveBeenCalledWith(
-      "5511999999999@c.us",
-      "cap",
-      expect.objectContaining({ mediaUrl: "https://example.com/a.jpg" }),
-    );
-    expect(result).toMatchObject({ channel: "whatsapp" });
-  });
-
-  it("multi-media iterates URLs with caption on first", async () => {
-    const sendWhatsApp = vi
-      .fn()
-      .mockResolvedValueOnce({ messageId: "wa-1" })
-      .mockResolvedValueOnce({ messageId: "wa-2" });
-    const ctx = {
-      cfg: {},
-      to: "5511999999999@c.us",
-      text: "",
-      payload: {
-        text: "caption",
-        mediaUrls: ["https://example.com/1.jpg", "https://example.com/2.jpg"],
-      } as ReplyPayload,
-      deps: { sendWhatsApp },
-    };
-    const result = await whatsappOutbound.sendPayload!(ctx);
-
-    expect(sendWhatsApp).toHaveBeenCalledTimes(2);
-    expect(sendWhatsApp).toHaveBeenNthCalledWith(
-      1,
-      "5511999999999@c.us",
-      "caption",
-      expect.objectContaining({ mediaUrl: "https://example.com/1.jpg" }),
-    );
-    expect(sendWhatsApp).toHaveBeenNthCalledWith(
-      2,
-      "5511999999999@c.us",
-      "",
-      expect.objectContaining({ mediaUrl: "https://example.com/2.jpg" }),
-    );
-    expect(result).toMatchObject({ channel: "whatsapp", messageId: "wa-2" });
-  });
-
-  it("empty payload returns no-op", async () => {
-    const ctx = baseCtx({});
-    const result = await whatsappOutbound.sendPayload!(ctx);
-
-    expect(ctx.deps.sendWhatsApp).not.toHaveBeenCalled();
-    expect(result).toEqual({ channel: "whatsapp", messageId: "" });
-  });
-
-  it("chunking splits long text", async () => {
-    const sendWhatsApp = vi
-      .fn()
-      .mockResolvedValueOnce({ messageId: "wa-c1" })
-      .mockResolvedValueOnce({ messageId: "wa-c2" });
-    const longText = "a".repeat(5000);
-    const ctx = {
-      cfg: {},
-      to: "5511999999999@c.us",
-      text: "",
-      payload: { text: longText } as ReplyPayload,
-      deps: { sendWhatsApp },
-    };
-    const result = await whatsappOutbound.sendPayload!(ctx);
-
-    expect(sendWhatsApp.mock.calls.length).toBeGreaterThanOrEqual(2);
-    for (const call of sendWhatsApp.mock.calls) {
-      expect((call[1] as string).length).toBeLessThanOrEqual(4000);
-    }
-    expect(result).toMatchObject({ channel: "whatsapp" });
+  installSendPayloadContractSuite({
+    channel: "whatsapp",
+    chunking: { mode: "split", longTextLength: 5000, maxChunkLength: 4000 },
+    createHarness,
   });
 });

src/cli/acp-cli.option-collisions.test.ts

@@ -1,9 +1,7 @@
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
 import { Command } from "commander";
 import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import { runRegisteredCli } from "../test-utils/command-runner.js";
+import { withTempSecretFiles } from "../test-utils/secret-file-fixture.js";
 
 const runAcpClientInteractive = vi.fn(async (_opts: unknown) => {});
 const serveAcpGateway = vi.fn(async (_opts: unknown) => {});
@@ -30,27 +28,6 @@ vi.mock("../runtime.js", () => ({
 describe("acp cli option collisions", () => {
   let registerAcpCli: typeof import("./acp-cli.js").registerAcpCli;
 
-  async function withSecretFiles<T>(
-    secrets: { token?: string; password?: string },
-    run: (files: { tokenFile?: string; passwordFile?: string }) => Promise<T>,
-  ): Promise<T> {
-    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-acp-cli-"));
-    try {
-      const files: { tokenFile?: string; passwordFile?: string } = {};
-      if (secrets.token !== undefined) {
-        files.tokenFile = path.join(dir, "token.txt");
-        await fs.writeFile(files.tokenFile, secrets.token, "utf8");
-      }
-      if (secrets.password !== undefined) {
-        files.passwordFile = path.join(dir, "password.txt");
-        await fs.writeFile(files.passwordFile, secrets.password, "utf8");
-      }
-      return await run(files);
-    } finally {
-      await fs.rm(dir, { recursive: true, force: true });
-    }
-  }
-
   function createAcpProgram() {
     const program = new Command();
     registerAcpCli(program);
@@ -93,15 +70,19 @@ describe("acp cli option collisions", () => {
   });
 
   it("loads gateway token/password from files", async () => {
-    await withSecretFiles({ token: "tok_file\n", [passwordKey()]: "pw_file\n" }, async (files) => {
-      // pragma: allowlist secret
-      await parseAcp([
-        "--token-file",
-        files.tokenFile ?? "",
-        "--password-file",
-        files.passwordFile ?? "",
-      ]);
-    });
+    await withTempSecretFiles(
+      "openclaw-acp-cli-",
+      { token: "tok_file\n", [passwordKey()]: "pw_file\n" },
+      async (files) => {
+        // pragma: allowlist secret
+        await parseAcp([
+          "--token-file",
+          files.tokenFile ?? "",
+          "--password-file",
+          files.passwordFile ?? "",
+        ]);
+      },
+    );
 
     expect(serveAcpGateway).toHaveBeenCalledWith(
       expect.objectContaining({
@@ -111,21 +92,30 @@ describe("acp cli option collisions", () => {
     );
   });
 
-  it("rejects mixed secret flags and file flags", async () => {
-    await withSecretFiles({ token: "tok_file\n" }, async (files) => {
-      await parseAcp(["--token", "tok_inline", "--token-file", files.tokenFile ?? ""]);
+  it.each([
+    {
+      name: "rejects mixed secret flags and file flags",
+      files: { token: "tok_file\n" },
+      args: (tokenFile: string) => ["--token", "tok_inline", "--token-file", tokenFile],
+      expected: /Use either --token or --token-file/,
+    },
+    {
+      name: "rejects mixed password flags and file flags",
+      files: { password: "pw_file\n" }, // pragma: allowlist secret
+      args: (_tokenFile: string, passwordFile: string) => [
+        "--password",
+        "pw_inline",
+        "--password-file",
+        passwordFile,
+      ],
+      expected: /Use either --password or --password-file/,
+    },
+  ])("$name", async ({ files, args, expected }) => {
+    await withTempSecretFiles("openclaw-acp-cli-", files, async ({ tokenFile, passwordFile }) => {
+      await parseAcp(args(tokenFile ?? "", passwordFile ?? ""));
     });
 
-    expectCliError(/Use either --token or --token-file/);
-  });
-
-  it("rejects mixed password flags and file flags", async () => {
-    const passwordFileValue = "pw_file\n"; // pragma: allowlist secret
-    await withSecretFiles({ password: passwordFileValue }, async (files) => {
-      await parseAcp(["--password", "pw_inline", "--password-file", files.passwordFile ?? ""]);
-    });
-
-    expectCliError(/Use either --password or --password-file/);
+    expectCliError(expected);
   });
 
   it("warns when inline secret flags are used", async () => {
@@ -140,7 +130,7 @@ describe("acp cli option collisions", () => {
   });
 
   it("trims token file path before reading", async () => {
-    await withSecretFiles({ token: "tok_file\n" }, async (files) => {
+    await withTempSecretFiles("openclaw-acp-cli-", { token: "tok_file\n" }, async (files) => {
       await parseAcp(["--token-file", `  ${files.tokenFile ?? ""}  `]);
     });
 

src/cli/daemon-cli/register-service-commands.test.ts

@@ -39,34 +39,37 @@ describe("addGatewayServiceCommands", () => {
     runDaemonUninstall.mockClear();
   });
 
-  it("forwards install option collisions from parent gateway command", async () => {
+  it.each([
+    {
+      name: "forwards install option collisions from parent gateway command",
+      argv: ["install", "--force", "--port", "19000", "--token", "tok_test"],
+      assert: () => {
+        expect(runDaemonInstall).toHaveBeenCalledWith(
+          expect.objectContaining({
+            force: true,
+            port: "19000",
+            token: "tok_test",
+          }),
+        );
+      },
+    },
+    {
+      name: "forwards status auth collisions from parent gateway command",
+      argv: ["status", "--token", "tok_status", "--password", "pw_status"],
+      assert: () => {
+        expect(runDaemonStatus).toHaveBeenCalledWith(
+          expect.objectContaining({
+            rpc: expect.objectContaining({
+              token: "tok_status",
+              password: "pw_status", // pragma: allowlist secret
+            }),
+          }),
+        );
+      },
+    },
+  ])("$name", async ({ argv, assert }) => {
     const gateway = createGatewayParentLikeCommand();
-    await gateway.parseAsync(["install", "--force", "--port", "19000", "--token", "tok_test"], {
-      from: "user",
-    });
-
-    expect(runDaemonInstall).toHaveBeenCalledWith(
-      expect.objectContaining({
-        force: true,
-        port: "19000",
-        token: "tok_test",
-      }),
-    );
-  });
-
-  it("forwards status auth collisions from parent gateway command", async () => {
-    const gateway = createGatewayParentLikeCommand();
-    await gateway.parseAsync(["status", "--token", "tok_status", "--password", "pw_status"], {
-      from: "user",
-    });
-
-    expect(runDaemonStatus).toHaveBeenCalledWith(
-      expect.objectContaining({
-        rpc: expect.objectContaining({
-          token: "tok_status",
-          password: "pw_status", // pragma: allowlist secret
-        }),
-      }),
-    );
+    await gateway.parseAsync(argv, { from: "user" });
+    assert();
   });
 });

src/cli/gateway-cli/register.option-collisions.test.ts

@@ -128,30 +128,34 @@ describe("gateway register option collisions", () => {
     gatewayStatusCommand.mockClear();
   });
 
-  it("forwards --token to gateway call when parent and child option names collide", async () => {
-    await sharedProgram.parseAsync(["gateway", "call", "health", "--token", "tok_call", "--json"], {
-      from: "user",
-    });
-
-    expect(callGatewayCli).toHaveBeenCalledWith(
-      "health",
-      expect.objectContaining({
-        token: "tok_call",
-      }),
-      {},
-    );
-  });
-
-  it("forwards --token to gateway probe when parent and child option names collide", async () => {
-    await sharedProgram.parseAsync(["gateway", "probe", "--token", "tok_probe", "--json"], {
-      from: "user",
-    });
-
-    expect(gatewayStatusCommand).toHaveBeenCalledWith(
-      expect.objectContaining({
-        token: "tok_probe",
-      }),
-      defaultRuntime,
-    );
+  it.each([
+    {
+      name: "forwards --token to gateway call when parent and child option names collide",
+      argv: ["gateway", "call", "health", "--token", "tok_call", "--json"],
+      assert: () => {
+        expect(callGatewayCli).toHaveBeenCalledWith(
+          "health",
+          expect.objectContaining({
+            token: "tok_call",
+          }),
+          {},
+        );
+      },
+    },
+    {
+      name: "forwards --token to gateway probe when parent and child option names collide",
+      argv: ["gateway", "probe", "--token", "tok_probe", "--json"],
+      assert: () => {
+        expect(gatewayStatusCommand).toHaveBeenCalledWith(
+          expect.objectContaining({
+            token: "tok_probe",
+          }),
+          defaultRuntime,
+        );
+      },
+    },
+  ])("$name", async ({ argv, assert }) => {
+    await sharedProgram.parseAsync(argv, { from: "user" });
+    assert();
   });
 });

src/cli/gateway-cli/run.option-collisions.test.ts

@@ -1,8 +1,6 @@
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
 import { Command } from "commander";
 import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { withTempSecretFiles } from "../../test-utils/secret-file-fixture.js";
 import { createCliRuntimeCapture } from "../test-runtime-capture.js";
 
 const startGatewayServer = vi.fn(async (_port: number, _opts?: unknown) => ({
@@ -195,16 +193,10 @@ describe("gateway run option collisions", () => {
     );
   });
 
-  it("accepts --auth none override", async () => {
-    await runGatewayCli(["gateway", "run", "--auth", "none", "--allow-unconfigured"]);
+  it.each(["none", "trusted-proxy"] as const)("accepts --auth %s override", async (mode) => {
+    await runGatewayCli(["gateway", "run", "--auth", mode, "--allow-unconfigured"]);
 
-    expectAuthOverrideMode("none");
-  });
-
-  it("accepts --auth trusted-proxy override", async () => {
-    await runGatewayCli(["gateway", "run", "--auth", "trusted-proxy", "--allow-unconfigured"]);
-
-    expectAuthOverrideMode("trusted-proxy");
+    expectAuthOverrideMode(mode);
   });
 
   it("prints all supported modes on invalid --auth value", async () => {
@@ -244,36 +236,34 @@ describe("gateway run option collisions", () => {
   });
 
   it("reads gateway password from --password-file", async () => {
-    const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-gateway-run-"));
-    try {
-      const passwordFile = path.join(tempDir, "gateway-password.txt");
-      await fs.writeFile(passwordFile, "pw_from_file\n", "utf8");
+    await withTempSecretFiles(
+      "openclaw-gateway-run-",
+      { password: "pw_from_file\n" },
+      async ({ passwordFile }) => {
+        await runGatewayCli([
+          "gateway",
+          "run",
+          "--auth",
+          "password",
+          "--password-file",
+          passwordFile ?? "",
+          "--allow-unconfigured",
+        ]);
+      },
+    );
 
-      await runGatewayCli([
-        "gateway",
-        "run",
-        "--auth",
-        "password",
-        "--password-file",
-        passwordFile,
-        "--allow-unconfigured",
-      ]);
-
-      expect(startGatewayServer).toHaveBeenCalledWith(
-        18789,
-        expect.objectContaining({
-          auth: expect.objectContaining({
-            mode: "password",
-            password: "pw_from_file", // pragma: allowlist secret
-          }),
+    expect(startGatewayServer).toHaveBeenCalledWith(
+      18789,
+      expect.objectContaining({
+        auth: expect.objectContaining({
+          mode: "password",
+          password: "pw_from_file", // pragma: allowlist secret
         }),
-      );
-      expect(runtimeErrors).not.toContain(
-        "Warning: --password can be exposed via process listings. Prefer --password-file or OPENCLAW_GATEWAY_PASSWORD.",
-      );
-    } finally {
-      await fs.rm(tempDir, { recursive: true, force: true });
-    }
+      }),
+    );
+    expect(runtimeErrors).not.toContain(
+      "Warning: --password can be exposed via process listings. Prefer --password-file or OPENCLAW_GATEWAY_PASSWORD.",
+    );
   });
 
   it("warns when gateway password is passed inline", async () => {
@@ -293,26 +283,24 @@ describe("gateway run option collisions", () => {
   });
 
   it("rejects using both --password and --password-file", async () => {
-    const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-gateway-run-"));
-    try {
-      const passwordFile = path.join(tempDir, "gateway-password.txt");
-      await fs.writeFile(passwordFile, "pw_from_file\n", "utf8");
+    await withTempSecretFiles(
+      "openclaw-gateway-run-",
+      { password: "pw_from_file\n" },
+      async ({ passwordFile }) => {
+        await expect(
+          runGatewayCli([
+            "gateway",
+            "run",
+            "--password",
+            "pw_inline",
+            "--password-file",
+            passwordFile ?? "",
+            "--allow-unconfigured",
+          ]),
+        ).rejects.toThrow("__exit__:1");
+      },
+    );
 
-      await expect(
-        runGatewayCli([
-          "gateway",
-          "run",
-          "--password",
-          "pw_inline",
-          "--password-file",
-          passwordFile,
-          "--allow-unconfigured",
-        ]),
-      ).rejects.toThrow("__exit__:1");
-
-      expect(runtimeErrors).toContain("Use either --password or --password-file.");
-    } finally {
-      await fs.rm(tempDir, { recursive: true, force: true });
-    }
+    expect(runtimeErrors).toContain("Use either --password or --password-file.");
   });
 });

src/cli/program/register.onboard.ts

@@ -160,6 +160,8 @@ export function registerOnboardCommand(program: Command) {
           zaiApiKey: opts.zaiApiKey as string | undefined,
           xiaomiApiKey: opts.xiaomiApiKey as string | undefined,
           qianfanApiKey: opts.qianfanApiKey as string | undefined,
+          modelstudioApiKeyCn: opts.modelstudioApiKeyCn as string | undefined,
+          modelstudioApiKey: opts.modelstudioApiKey as string | undefined,
           minimaxApiKey: opts.minimaxApiKey as string | undefined,
           syntheticApiKey: opts.syntheticApiKey as string | undefined,
           veniceApiKey: opts.veniceApiKey as string | undefined,

src/cli/update-cli.option-collisions.test.ts

@@ -44,30 +44,36 @@ describe("update cli option collisions", () => {
     defaultRuntime.exit.mockClear();
   });
 
-  it("forwards parent-captured --json/--timeout to `update status`", async () => {
-    await runRegisteredCli({
-      register: registerUpdateCli as (program: Command) => void,
+  it.each([
+    {
+      name: "forwards parent-captured --json/--timeout to `update status`",
       argv: ["update", "status", "--json", "--timeout", "9"],
-    });
-
-    expect(updateStatusCommand).toHaveBeenCalledWith(
-      expect.objectContaining({
-        json: true,
-        timeout: "9",
-      }),
-    );
-  });
-
-  it("forwards parent-captured --timeout to `update wizard`", async () => {
+      assert: () => {
+        expect(updateStatusCommand).toHaveBeenCalledWith(
+          expect.objectContaining({
+            json: true,
+            timeout: "9",
+          }),
+        );
+      },
+    },
+    {
+      name: "forwards parent-captured --timeout to `update wizard`",
+      argv: ["update", "wizard", "--timeout", "13"],
+      assert: () => {
+        expect(updateWizardCommand).toHaveBeenCalledWith(
+          expect.objectContaining({
+            timeout: "13",
+          }),
+        );
+      },
+    },
+  ])("$name", async ({ argv, assert }) => {
     await runRegisteredCli({
       register: registerUpdateCli as (program: Command) => void,
-      argv: ["update", "wizard", "--timeout", "13"],
+      argv,
     });
 
-    expect(updateWizardCommand).toHaveBeenCalledWith(
-      expect.objectContaining({
-        timeout: "13",
-      }),
-    );
+    assert();
   });
 });

src/commands/auth-choice-options.ts

@@ -119,6 +119,12 @@ const AUTH_CHOICE_GROUP_DEFS: {
     hint: "API key",
     choices: ["qianfan-api-key"],
   },
+  {
+    value: "modelstudio",
+    label: "Alibaba Cloud Model Studio",
+    hint: "Coding Plan API key (CN / Global)",
+    choices: ["modelstudio-api-key-cn", "modelstudio-api-key"],
+  },
   {
     value: "copilot",
     label: "Copilot",
@@ -297,6 +303,17 @@ const BASE_AUTH_CHOICE_OPTIONS: ReadonlyArray<AuthChoiceOption> = [
     label: "MiniMax M2.5 Highspeed",
     hint: "Official fast tier",
   },
+  { value: "qianfan-api-key", label: "Qianfan API key" },
+  {
+    value: "modelstudio-api-key-cn",
+    label: "Coding Plan API Key for China (subscription)",
+    hint: "Endpoint: coding.dashscope.aliyuncs.com",
+  },
+  {
+    value: "modelstudio-api-key",
+    label: "Coding Plan API Key for Global/Intl (subscription)",
+    hint: "Endpoint: coding-intl.dashscope.aliyuncs.com",
+  },
   { value: "custom-api-key", label: "Custom Provider" },
 ];
 

src/commands/auth-choice.apply-helpers.ts

@@ -8,6 +8,8 @@ import {
 import { encodeJsonPointerToken } from "../secrets/json-pointer.js";
 import { PROVIDER_ENV_VARS } from "../secrets/provider-env-vars.js";
 import {
+  formatExecSecretRefIdValidationMessage,
+  isValidExecSecretRefId,
   isValidFileSecretRefId,
   resolveDefaultSecretProviderAlias,
 } from "../secrets/ref-contract.js";
@@ -238,6 +240,9 @@ export async function promptSecretRefForOnboarding(params: {
         ) {
           return 'singleValue mode expects id "value".';
         }
+        if (providerEntry.source === "exec" && !isValidExecSecretRefId(candidate)) {
+          return formatExecSecretRefIdValidationMessage();
+        }
         return undefined;
       },
     });

src/commands/auth-choice.apply.api-providers.ts

@@ -76,6 +76,12 @@ import {
   setXiaomiApiKey,
   setZaiApiKey,
   ZAI_DEFAULT_MODEL_REF,
+  MODELSTUDIO_DEFAULT_MODEL_REF,
+  applyModelStudioConfig,
+  applyModelStudioConfigCn,
+  applyModelStudioProviderConfig,
+  applyModelStudioProviderConfigCn,
+  setModelStudioApiKey,
 } from "./onboard-auth.js";
 import type { AuthChoice, SecretInputMode } from "./onboard-types.js";
 import { OPENCODE_ZEN_DEFAULT_MODEL } from "./opencode-zen-model-default.js";
@@ -295,6 +301,46 @@ const SIMPLE_API_KEY_PROVIDER_FLOWS: Partial<Record<AuthChoice, SimpleApiKeyProv
     applyProviderConfig: applyKilocodeProviderConfig,
     noteDefault: KILOCODE_DEFAULT_MODEL_REF,
   },
+  "modelstudio-api-key-cn": {
+    provider: "modelstudio",
+    profileId: "modelstudio:default",
+    expectedProviders: ["modelstudio"],
+    envLabel: "MODELSTUDIO_API_KEY",
+    promptMessage: "Enter Alibaba Cloud Model Studio Coding Plan API key (China)",
+    setCredential: setModelStudioApiKey,
+    defaultModel: MODELSTUDIO_DEFAULT_MODEL_REF,
+    applyDefaultConfig: applyModelStudioConfigCn,
+    applyProviderConfig: applyModelStudioProviderConfigCn,
+    noteDefault: MODELSTUDIO_DEFAULT_MODEL_REF,
+    noteMessage: [
+      "Get your API key at: https://bailian.console.aliyun.com/",
+      "Endpoint: coding.dashscope.aliyuncs.com",
+      "Models: qwen3.5-plus, glm-4.7, kimi-k2.5, MiniMax-M2.5, etc.",
+    ].join("\n"),
+    noteTitle: "Alibaba Cloud Model Studio Coding Plan (China)",
+    normalize: (value) => String(value ?? "").trim(),
+    validate: (value) => (String(value ?? "").trim() ? undefined : "Required"),
+  },
+  "modelstudio-api-key": {
+    provider: "modelstudio",
+    profileId: "modelstudio:default",
+    expectedProviders: ["modelstudio"],
+    envLabel: "MODELSTUDIO_API_KEY",
+    promptMessage: "Enter Alibaba Cloud Model Studio Coding Plan API key (Global/Intl)",
+    setCredential: setModelStudioApiKey,
+    defaultModel: MODELSTUDIO_DEFAULT_MODEL_REF,
+    applyDefaultConfig: applyModelStudioConfig,
+    applyProviderConfig: applyModelStudioProviderConfig,
+    noteDefault: MODELSTUDIO_DEFAULT_MODEL_REF,
+    noteMessage: [
+      "Get your API key at: https://bailian.console.aliyun.com/",
+      "Endpoint: coding-intl.dashscope.aliyuncs.com",
+      "Models: qwen3.5-plus, glm-4.7, kimi-k2.5, MiniMax-M2.5, etc.",
+    ].join("\n"),
+    noteTitle: "Alibaba Cloud Model Studio Coding Plan (Global/Intl)",
+    normalize: (value) => String(value ?? "").trim(),
+    validate: (value) => (String(value ?? "").trim() ? undefined : "Required"),
+  },
   "synthetic-api-key": {
     provider: "synthetic",
     profileId: "synthetic:default",

src/commands/onboard-auth.config-core.ts

@@ -65,6 +65,7 @@ import {
   buildZaiModelDefinition,
   buildMoonshotModelDefinition,
   buildXaiModelDefinition,
+  buildModelStudioModelDefinition,
   MISTRAL_BASE_URL,
   MISTRAL_DEFAULT_MODEL_ID,
   QIANFAN_BASE_URL,
@@ -79,6 +80,9 @@ import {
   resolveZaiBaseUrl,
   XAI_BASE_URL,
   XAI_DEFAULT_MODEL_ID,
+  MODELSTUDIO_CN_BASE_URL,
+  MODELSTUDIO_GLOBAL_BASE_URL,
+  MODELSTUDIO_DEFAULT_MODEL_REF,
 } from "./onboard-auth.models.js";
 
 export function applyZaiProviderConfig(
@@ -573,3 +577,92 @@ export function applyQianfanConfig(cfg: OpenClawConfig): OpenClawConfig {
   const next = applyQianfanProviderConfig(cfg);
   return applyAgentDefaultModelPrimary(next, QIANFAN_DEFAULT_MODEL_REF);
 }
+
+// Alibaba Cloud Model Studio Coding Plan
+
+function applyModelStudioProviderConfigWithBaseUrl(
+  cfg: OpenClawConfig,
+  baseUrl: string,
+): OpenClawConfig {
+  const models = { ...cfg.agents?.defaults?.models };
+
+  const modelStudioModelIds = [
+    "qwen3.5-plus",
+    "qwen3-max-2026-01-23",
+    "qwen3-coder-next",
+    "qwen3-coder-plus",
+    "MiniMax-M2.5",
+    "glm-5",
+    "glm-4.7",
+    "kimi-k2.5",
+  ];
+  for (const modelId of modelStudioModelIds) {
+    const modelRef = `modelstudio/${modelId}`;
+    if (!models[modelRef]) {
+      models[modelRef] = {};
+    }
+  }
+  models[MODELSTUDIO_DEFAULT_MODEL_REF] = {
+    ...models[MODELSTUDIO_DEFAULT_MODEL_REF],
+    alias: models[MODELSTUDIO_DEFAULT_MODEL_REF]?.alias ?? "Qwen",
+  };
+
+  const providers = { ...cfg.models?.providers };
+  const existingProvider = providers.modelstudio;
+  const existingModels = Array.isArray(existingProvider?.models) ? existingProvider.models : [];
+
+  const defaultModels = [
+    buildModelStudioModelDefinition({ id: "qwen3.5-plus" }),
+    buildModelStudioModelDefinition({ id: "qwen3-max-2026-01-23" }),
+    buildModelStudioModelDefinition({ id: "qwen3-coder-next" }),
+    buildModelStudioModelDefinition({ id: "qwen3-coder-plus" }),
+    buildModelStudioModelDefinition({ id: "MiniMax-M2.5" }),
+    buildModelStudioModelDefinition({ id: "glm-5" }),
+    buildModelStudioModelDefinition({ id: "glm-4.7" }),
+    buildModelStudioModelDefinition({ id: "kimi-k2.5" }),
+  ];
+
+  const mergedModels = [...existingModels];
+  const seen = new Set(existingModels.map((m) => m.id));
+  for (const model of defaultModels) {
+    if (!seen.has(model.id)) {
+      mergedModels.push(model);
+      seen.add(model.id);
+    }
+  }
+
+  const { apiKey: existingApiKey, ...existingProviderRest } = (existingProvider ?? {}) as Record<
+    string,
+    unknown
+  > as { apiKey?: string };
+  const resolvedApiKey = typeof existingApiKey === "string" ? existingApiKey : undefined;
+  const normalizedApiKey = resolvedApiKey?.trim();
+
+  providers.modelstudio = {
+    ...existingProviderRest,
+    baseUrl,
+    api: "openai-completions",
+    ...(normalizedApiKey ? { apiKey: normalizedApiKey } : {}),
+    models: mergedModels.length > 0 ? mergedModels : defaultModels,
+  };
+
+  return applyOnboardAuthAgentModelsAndProviders(cfg, { agentModels: models, providers });
+}
+
+export function applyModelStudioProviderConfig(cfg: OpenClawConfig): OpenClawConfig {
+  return applyModelStudioProviderConfigWithBaseUrl(cfg, MODELSTUDIO_GLOBAL_BASE_URL);
+}
+
+export function applyModelStudioProviderConfigCn(cfg: OpenClawConfig): OpenClawConfig {
+  return applyModelStudioProviderConfigWithBaseUrl(cfg, MODELSTUDIO_CN_BASE_URL);
+}
+
+export function applyModelStudioConfig(cfg: OpenClawConfig): OpenClawConfig {
+  const next = applyModelStudioProviderConfig(cfg);
+  return applyAgentDefaultModelPrimary(next, MODELSTUDIO_DEFAULT_MODEL_REF);
+}
+
+export function applyModelStudioConfigCn(cfg: OpenClawConfig): OpenClawConfig {
+  const next = applyModelStudioProviderConfigCn(cfg);
+  return applyAgentDefaultModelPrimary(next, MODELSTUDIO_DEFAULT_MODEL_REF);
+}

src/commands/onboard-auth.credentials.ts

@@ -15,7 +15,11 @@ import { PROVIDER_ENV_VARS } from "../secrets/provider-env-vars.js";
 import { normalizeSecretInput } from "../utils/normalize-secret-input.js";
 import type { SecretInputMode } from "./onboard-types.js";
 export { CLOUDFLARE_AI_GATEWAY_DEFAULT_MODEL_REF } from "../agents/cloudflare-ai-gateway.js";
-export { MISTRAL_DEFAULT_MODEL_REF, XAI_DEFAULT_MODEL_REF } from "./onboard-auth.models.js";
+export {
+  MISTRAL_DEFAULT_MODEL_REF,
+  XAI_DEFAULT_MODEL_REF,
+  MODELSTUDIO_DEFAULT_MODEL_REF,
+} from "./onboard-auth.models.js";
 export { KILOCODE_DEFAULT_MODEL_REF };
 
 const resolveAuthAgentDir = (agentDir?: string) => agentDir ?? resolveOpenClawAgentDir();
@@ -472,6 +476,18 @@ export function setQianfanApiKey(
   });
 }
 
+export function setModelStudioApiKey(
+  key: SecretInput,
+  agentDir?: string,
+  options?: ApiKeyStorageOptions,
+) {
+  upsertAuthProfile({
+    profileId: "modelstudio:default",
+    credential: buildApiKeyCredential("modelstudio", key, undefined, options),
+    agentDir: resolveAuthAgentDir(agentDir),
+  });
+}
+
 export function setXaiApiKey(key: SecretInput, agentDir?: string, options?: ApiKeyStorageOptions) {
   upsertAuthProfile({
     profileId: "xai:default",

src/commands/onboard-auth.models.ts

@@ -224,3 +224,105 @@ export function buildKilocodeModelDefinition(): ModelDefinitionConfig {
     maxTokens: KILOCODE_DEFAULT_MAX_TOKENS,
   };
 }
+
+// Alibaba Cloud Model Studio Coding Plan
+export const MODELSTUDIO_CN_BASE_URL = "https://coding.dashscope.aliyuncs.com/v1";
+export const MODELSTUDIO_GLOBAL_BASE_URL = "https://coding-intl.dashscope.aliyuncs.com/v1";
+export const MODELSTUDIO_DEFAULT_MODEL_ID = "qwen3.5-plus";
+export const MODELSTUDIO_DEFAULT_MODEL_REF = `modelstudio/${MODELSTUDIO_DEFAULT_MODEL_ID}`;
+export const MODELSTUDIO_DEFAULT_COST = {
+  input: 0,
+  output: 0,
+  cacheRead: 0,
+  cacheWrite: 0,
+};
+
+const MODELSTUDIO_MODEL_CATALOG = {
+  "qwen3.5-plus": {
+    name: "qwen3.5-plus",
+    reasoning: false,
+    input: ["text", "image"],
+    contextWindow: 1000000,
+    maxTokens: 65536,
+  },
+  "qwen3-max-2026-01-23": {
+    name: "qwen3-max-2026-01-23",
+    reasoning: false,
+    input: ["text"],
+    contextWindow: 262144,
+    maxTokens: 65536,
+  },
+  "qwen3-coder-next": {
+    name: "qwen3-coder-next",
+    reasoning: false,
+    input: ["text"],
+    contextWindow: 262144,
+    maxTokens: 65536,
+  },
+  "qwen3-coder-plus": {
+    name: "qwen3-coder-plus",
+    reasoning: false,
+    input: ["text"],
+    contextWindow: 1000000,
+    maxTokens: 65536,
+  },
+  "MiniMax-M2.5": {
+    name: "MiniMax-M2.5",
+    reasoning: false,
+    input: ["text"],
+    contextWindow: 1000000,
+    maxTokens: 65536,
+  },
+  "glm-5": {
+    name: "glm-5",
+    reasoning: false,
+    input: ["text"],
+    contextWindow: 202752,
+    maxTokens: 16384,
+  },
+  "glm-4.7": {
+    name: "glm-4.7",
+    reasoning: false,
+    input: ["text"],
+    contextWindow: 202752,
+    maxTokens: 16384,
+  },
+  "kimi-k2.5": {
+    name: "kimi-k2.5",
+    reasoning: false,
+    input: ["text", "image"],
+    contextWindow: 262144,
+    maxTokens: 32768,
+  },
+} as const;
+
+type ModelStudioCatalogId = keyof typeof MODELSTUDIO_MODEL_CATALOG;
+
+export function buildModelStudioModelDefinition(params: {
+  id: string;
+  name?: string;
+  reasoning?: boolean;
+  input?: string[];
+  cost?: ModelDefinitionConfig["cost"];
+  contextWindow?: number;
+  maxTokens?: number;
+}): ModelDefinitionConfig {
+  const catalog = MODELSTUDIO_MODEL_CATALOG[params.id as ModelStudioCatalogId];
+  return {
+    id: params.id,
+    name: params.name ?? catalog?.name ?? params.id,
+    reasoning: params.reasoning ?? catalog?.reasoning ?? false,
+    input:
+      (params.input as ("text" | "image")[]) ??
+      ([...(catalog?.input ?? ["text"])] as ("text" | "image")[]),
+    cost: params.cost ?? MODELSTUDIO_DEFAULT_COST,
+    contextWindow: params.contextWindow ?? catalog?.contextWindow ?? 262144,
+    maxTokens: params.maxTokens ?? catalog?.maxTokens ?? 65536,
+  };
+}
+
+export function buildModelStudioDefaultModelDefinition(): ModelDefinitionConfig {
+  return buildModelStudioModelDefinition({
+    id: MODELSTUDIO_DEFAULT_MODEL_ID,
+  });
+}

src/commands/onboard-auth.ts

@@ -39,6 +39,10 @@ export {
   applyXiaomiProviderConfig,
   applyZaiConfig,
   applyZaiProviderConfig,
+  applyModelStudioConfig,
+  applyModelStudioConfigCn,
+  applyModelStudioProviderConfig,
+  applyModelStudioProviderConfigCn,
   KILOCODE_BASE_URL,
 } from "./onboard-auth.config-core.js";
 export {
@@ -84,6 +88,7 @@ export {
   setVolcengineApiKey,
   setZaiApiKey,
   setXaiApiKey,
+  setModelStudioApiKey,
   writeOAuthCredentials,
   HUGGINGFACE_DEFAULT_MODEL_REF,
   VERCEL_AI_GATEWAY_DEFAULT_MODEL_REF,
@@ -92,6 +97,7 @@ export {
   TOGETHER_DEFAULT_MODEL_REF,
   MISTRAL_DEFAULT_MODEL_REF,
   XAI_DEFAULT_MODEL_REF,
+  MODELSTUDIO_DEFAULT_MODEL_REF,
 } from "./onboard-auth.credentials.js";
 export {
   buildKilocodeModelDefinition,

src/commands/onboard-non-interactive.provider-auth.test.ts

@@ -611,6 +611,26 @@ describe("onboard (non-interactive): provider auth", () => {
     });
   });
 
+  it("infers Model Studio auth choice from --modelstudio-api-key and sets default model", async () => {
+    await withOnboardEnv("openclaw-onboard-modelstudio-infer-", async (env) => {
+      const cfg = await runOnboardingAndReadConfig(env, {
+        modelstudioApiKey: "modelstudio-test-key", // pragma: allowlist secret
+      });
+
+      expect(cfg.auth?.profiles?.["modelstudio:default"]?.provider).toBe("modelstudio");
+      expect(cfg.auth?.profiles?.["modelstudio:default"]?.mode).toBe("api_key");
+      expect(cfg.models?.providers?.modelstudio?.baseUrl).toBe(
+        "https://coding-intl.dashscope.aliyuncs.com/v1",
+      );
+      expect(cfg.agents?.defaults?.model?.primary).toBe("modelstudio/qwen3.5-plus");
+      await expectApiKeyProfile({
+        profileId: "modelstudio:default",
+        provider: "modelstudio",
+        key: "modelstudio-test-key",
+      });
+    });
+  });
+
   it("configures a custom provider from non-interactive flags", async () => {
     await withOnboardEnv("openclaw-onboard-custom-provider-", async ({ configPath, runtime }) => {
       await runNonInteractiveOnboardingWithDefaults(runtime, {

src/commands/onboard-non-interactive/local/auth-choice-inference.ts

@@ -30,6 +30,8 @@ type AuthChoiceFlagOptions = Pick<
   | "xaiApiKey"
   | "litellmApiKey"
   | "qianfanApiKey"
+  | "modelstudioApiKeyCn"
+  | "modelstudioApiKey"
   | "volcengineApiKey"
   | "byteplusApiKey"
   | "customBaseUrl"

src/commands/onboard-non-interactive/local/auth-choice.ts

@@ -15,6 +15,8 @@ import {
   applyCloudflareAiGatewayConfig,
   applyKilocodeConfig,
   applyQianfanConfig,
+  applyModelStudioConfig,
+  applyModelStudioConfigCn,
   applyKimiCodeConfig,
   applyMinimaxApiConfig,
   applyMinimaxApiConfigCn,
@@ -37,6 +39,7 @@ import {
   setCloudflareAiGatewayConfig,
   setByteplusApiKey,
   setQianfanApiKey,
+  setModelStudioApiKey,
   setGeminiApiKey,
   setKilocodeApiKey,
   setKimiCodingApiKey,
@@ -498,6 +501,60 @@ export async function applyNonInteractiveAuthChoice(params: {
     return applyQianfanConfig(nextConfig);
   }
 
+  if (authChoice === "modelstudio-api-key-cn") {
+    const resolved = await resolveApiKey({
+      provider: "modelstudio",
+      cfg: baseConfig,
+      flagValue: opts.modelstudioApiKeyCn,
+      flagName: "--modelstudio-api-key-cn",
+      envVar: "MODELSTUDIO_API_KEY",
+      runtime,
+    });
+    if (!resolved) {
+      return null;
+    }
+    if (
+      !(await maybeSetResolvedApiKey(resolved, (value) =>
+        setModelStudioApiKey(value, undefined, apiKeyStorageOptions),
+      ))
+    ) {
+      return null;
+    }
+    nextConfig = applyAuthProfileConfig(nextConfig, {
+      profileId: "modelstudio:default",
+      provider: "modelstudio",
+      mode: "api_key",
+    });
+    return applyModelStudioConfigCn(nextConfig);
+  }
+
+  if (authChoice === "modelstudio-api-key") {
+    const resolved = await resolveApiKey({
+      provider: "modelstudio",
+      cfg: baseConfig,
+      flagValue: opts.modelstudioApiKey,
+      flagName: "--modelstudio-api-key",
+      envVar: "MODELSTUDIO_API_KEY",
+      runtime,
+    });
+    if (!resolved) {
+      return null;
+    }
+    if (
+      !(await maybeSetResolvedApiKey(resolved, (value) =>
+        setModelStudioApiKey(value, undefined, apiKeyStorageOptions),
+      ))
+    ) {
+      return null;
+    }
+    nextConfig = applyAuthProfileConfig(nextConfig, {
+      profileId: "modelstudio:default",
+      provider: "modelstudio",
+      mode: "api_key",
+    });
+    return applyModelStudioConfig(nextConfig);
+  }
+
   if (authChoice === "openai-api-key") {
     const resolved = await resolveApiKey({
       provider: "openai",

src/commands/onboard-provider-auth-flags.ts

@@ -23,6 +23,8 @@ type OnboardProviderAuthOptionKey = keyof Pick<
   | "xaiApiKey"
   | "litellmApiKey"
   | "qianfanApiKey"
+  | "modelstudioApiKeyCn"
+  | "modelstudioApiKey"
   | "volcengineApiKey"
   | "byteplusApiKey"
 >;
@@ -184,6 +186,20 @@ export const ONBOARD_PROVIDER_AUTH_FLAGS: ReadonlyArray<OnboardProviderAuthFlag>
     cliOption: "--qianfan-api-key <key>",
     description: "QIANFAN API key",
   },
+  {
+    optionKey: "modelstudioApiKeyCn",
+    authChoice: "modelstudio-api-key-cn",
+    cliFlag: "--modelstudio-api-key-cn",
+    cliOption: "--modelstudio-api-key-cn <key>",
+    description: "Alibaba Cloud Model Studio Coding Plan API key (China)",
+  },
+  {
+    optionKey: "modelstudioApiKey",
+    authChoice: "modelstudio-api-key",
+    cliFlag: "--modelstudio-api-key",
+    cliOption: "--modelstudio-api-key <key>",
+    description: "Alibaba Cloud Model Studio Coding Plan API key (Global/Intl)",
+  },
   {
     optionKey: "volcengineApiKey",
     authChoice: "volcengine-api-key",

src/commands/onboard-types.ts

@@ -49,6 +49,8 @@ export type AuthChoice =
   | "volcengine-api-key"
   | "byteplus-api-key"
   | "qianfan-api-key"
+  | "modelstudio-api-key-cn"
+  | "modelstudio-api-key"
   | "custom-api-key"
   | "skip";
 export type AuthChoiceGroupId =
@@ -75,6 +77,7 @@ export type AuthChoiceGroupId =
   | "together"
   | "huggingface"
   | "qianfan"
+  | "modelstudio"
   | "xai"
   | "volcengine"
   | "byteplus"
@@ -135,6 +138,8 @@ export type OnboardOptions = {
   volcengineApiKey?: string;
   byteplusApiKey?: string;
   qianfanApiKey?: string;
+  modelstudioApiKeyCn?: string;
+  modelstudioApiKey?: string;
   customBaseUrl?: string;
   customApiKey?: string;
   customModelId?: string;

src/commands/openai-codex-oauth.test.ts

@@ -9,7 +9,7 @@ const mocks = vi.hoisted(() => ({
   formatOpenAIOAuthTlsPreflightFix: vi.fn(),
 }));
 
-vi.mock("@mariozechner/pi-ai", () => ({
+vi.mock("@mariozechner/pi-ai/oauth", () => ({
   loginOpenAICodex: mocks.loginOpenAICodex,
 }));
 

src/commands/openai-codex-oauth.ts

@@ -1,5 +1,5 @@
 import type { OAuthCredentials } from "@mariozechner/pi-ai";
-import { loginOpenAICodex } from "@mariozechner/pi-ai";
+import { loginOpenAICodex } from "@mariozechner/pi-ai/oauth";
 import type { RuntimeEnv } from "../runtime.js";
 import type { WizardPrompter } from "../wizard/prompts.js";
 import { createVpsAwareOAuthHandlers } from "./oauth-flow.js";

src/config/config.secrets-schema.test.ts

@@ -1,4 +1,8 @@
 import { describe, expect, it } from "vitest";
+import {
+  INVALID_EXEC_SECRET_REF_IDS,
+  VALID_EXEC_SECRET_REF_IDS,
+} from "../test-utils/secret-ref-test-vectors.js";
 import { validateConfigObjectRaw } from "./validation.js";
 
 function validateOpenAiApiKeyRef(apiKey: unknown) {
@@ -173,4 +177,31 @@ describe("config secret refs schema", () => {
       ).toBe(true);
     }
   });
+
+  it("accepts valid exec secret reference ids", () => {
+    for (const id of VALID_EXEC_SECRET_REF_IDS) {
+      const result = validateOpenAiApiKeyRef({
+        source: "exec",
+        provider: "vault",
+        id,
+      });
+      expect(result.ok, `expected valid exec ref id: ${id}`).toBe(true);
+    }
+  });
+
+  it("rejects invalid exec secret reference ids", () => {
+    for (const id of INVALID_EXEC_SECRET_REF_IDS) {
+      const result = validateOpenAiApiKeyRef({
+        source: "exec",
+        provider: "vault",
+        id,
+      });
+      expect(result.ok, `expected invalid exec ref id: ${id}`).toBe(false);
+      if (!result.ok) {
+        expect(
+          result.issues.some((issue) => issue.path.includes("models.providers.openai.apiKey")),
+        ).toBe(true);
+      }
+    }
+  });
 });